feat: /gpr-settings + cross-platform discoverability

README.md

@@ -8,6 +8,7 @@ A CLI that drives a coding agent through an audit-verified Plan.
 [![Tests](https://img.shields.io/badge/tests-76_passing-emerald?style=flat-square)](tests/)
 [![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)](CHANGELOG.md)
 [![Python](https://img.shields.io/badge/python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)](pyproject.toml)
+[![Platforms](https://img.shields.io/badge/platforms-macOS_%7C_Linux_%7C_Windows-9cf?style=flat-square)](#quickstart)
 [![Ko-fi](https://img.shields.io/badge/ko--fi-support-FF5E5B?style=flat-square&logo=kofi&logoColor=white)](https://ko-fi.com/adityavg13)
 
 ![demo](docs/demo.gif)
@@ -20,6 +21,8 @@ What test-driven development is to code, gpr is to LLM coding agents: every clai
 
 ## Quickstart
 
+**Runs on macOS, Linux, and Windows.** CI exercises all three on every PR (`ubuntu-latest`, `macos-latest`, `windows-latest`). The shell scripts target bash; on Windows that means **WSL** or **Git Bash** — native `cmd` / PowerShell is not supported.
+
 ```bash
 git clone https://github.com/AdityaVG13/GPR ~/.local/share/gpr
 ln -sf ~/.local/share/gpr/bin/gpr ~/.local/bin/gpr
@@ -35,11 +38,12 @@ gpr run --agent claude --max-cost-usd 5
 
 **Linux** — works as shown. `apt install jq` / `dnf install jq` / `pacman -S jq` if missing.
 
-**Windows** — three paths:
+**Windows** — two supported paths:
 
 1. **WSL** (recommended). Inside `wsl`, follow the Linux steps. `claude` CLI runs inside WSL and uses your subscription session normally.
 2. **Git Bash** (MinGW). The same shell commands work; `~/.local/share/gpr` resolves under your Windows user profile. Install [Git for Windows](https://git-scm.com/download/win) for bash + jq, then run the quickstart in Git Bash.
-3. **Native PowerShell / cmd** is not supported. Use WSL or Git Bash.
+
+Native PowerShell / cmd is not supported — gpr's loop driver is bash. See [issue tracker](https://github.com/AdityaVG13/GPR/issues) if you want native PowerShell support.
 
 Desktop notifications use `osascript` on macOS, `notify-send` on Linux, and `powershell.exe` toast on Windows / WSL. Set `GPR_NO_NOTIFY=1` to disable.
 
@@ -51,7 +55,7 @@ Or, if you're already in a Claude Code TUI session inside a project:
 /gpr Build a TODO REST API with auth
 ```
 
-That bootstraps the Plan via an interactive interview (`gpr-grill`), runs the loop one iteration at a time, and yields back to you between rounds. Type `/gpr` again to advance, `/gpr-steer ...` to redirect.
+That bootstraps the Plan via an interactive interview (`gpr-grill`), runs the loop one iteration at a time, and yields back to you between rounds. Type `/gpr` again to advance, `/gpr-steer ...` to redirect, `/gpr-status` to see progress, `/gpr-settings` to browse or edit gpr's config (run defaults, viewer style, env-var hints).
 
 > **Auth.** gpr never handles credentials. It spawns whichever agent CLI you point it at (`claude`, `codex`, `opencode`, `gemini`) as a subprocess; that CLI uses its own auth. So `claude` running on your Claude Code subscription session works exactly as well as one configured with `ANTHROPIC_API_KEY`.
 

install/commands/gpr-settings.md

@@ -0,0 +1,13 @@
+---
+description: Browse and edit gpr config (run defaults, viewer style, budget caps, env hints).
+---
+
+Activate the `gpr-settings` skill (defined in `~/.claude/skills/gpr-settings/SKILL.md`).
+
+The skill wraps `gpr config` — the deterministic CLI surface for run defaults (`run.agent`, `run.max_iters`, `run.deep_audit`, …) and viewer preferences (`viewer.style`, `viewer.theme`, …). It also surfaces the runtime env vars (`GPR_AGENT_EXTRA_ARGS`, `GPR_NO_NOTIFY`, `GPR_BUDGET_MAX_COST_USD`) and points the user at `.gpr/Plan.json` for per-project budget caps.
+
+`$ARGUMENTS` is forwarded as a hint:
+- empty → present the full settings menu
+- `list` / `show` → just dump current config and exit
+- `<key>` (e.g. `run.agent`) → jump straight to that key
+- `reset` → walk the user through reset confirmation

install/install.sh

@@ -23,6 +23,11 @@ mkdir -p "$GRILL_TARGET"
 cp "$INSTALL_SRC/skill/gpr-grill/SKILL.md" "$GRILL_TARGET/SKILL.md"
 log_ok "skill: $GRILL_TARGET/SKILL.md"
 
+SETTINGS_TARGET="${HOME}/.claude/skills/gpr-settings"
+mkdir -p "$SETTINGS_TARGET"
+cp "$INSTALL_SRC/skill/gpr-settings/SKILL.md" "$SETTINGS_TARGET/SKILL.md"
+log_ok "skill: $SETTINGS_TARGET/SKILL.md"
+
 for f in "$INSTALL_SRC"/commands/*.md; do
   cp "$f" "$TARGET_CMD_DIR/"
   log_ok "command: $TARGET_CMD_DIR/$(basename "$f")"
@@ -38,6 +43,7 @@ fi
 hr
 log_ok "installed"
 log_info "from any Claude Code session in a gpr-initialized project, type:"
-printf '    %s/gpr%s            run one iteration\n' "$C_BOLD" "$C_RESET"
-printf '    %s/gpr-status%s     show progress\n' "$C_BOLD" "$C_RESET"
-printf '    %s/gpr-steer%s ...  write a human steer\n' "$C_BOLD" "$C_RESET"
+printf '    %s/gpr%s             run one iteration\n' "$C_BOLD" "$C_RESET"
+printf '    %s/gpr-status%s      show progress\n' "$C_BOLD" "$C_RESET"
+printf '    %s/gpr-steer%s ...   write a human steer\n' "$C_BOLD" "$C_RESET"
+printf '    %s/gpr-settings%s    browse/edit gpr config\n' "$C_BOLD" "$C_RESET"

install/skill/gpr-settings/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: gpr-settings
+description: Interactive editor for gpr config — run defaults (agent, model, max-iters, deep-audit), viewer style/theme, plus env-var hints and Plan.json budget pointers. Trigger when user types /gpr-settings, /gpr settings, "show gpr config", "change gpr defaults", "edit gpr settings", or asks to inspect or change anything gpr-related that is not a Plan intent. Wraps `gpr config` deterministically — never edits Plan.json directly.
+---
+
+# gpr-settings — interactive config editor
+
+Three things live under "gpr settings", and the user can confuse them. Surface all three, then drill into whichever the user picks:
+
+1. **`gpr config`** — defaults that apply across runs. Two scopes:
+   - `user` — `~/.config/gpr/config.toml`. Applies to every project.
+   - `project` — `.gpr/config.toml`. Overrides user scope for this repo only.
+2. **Env vars** — runtime overrides. Set in the shell that launches `gpr run`. Highest precedence.
+3. **`.gpr/Plan.json`** — per-project Plan fields (`budget`, `qualityGates`, `persona`). Edit via `/gpr-grill` (revise mode) or your `$EDITOR`. **This skill does NOT edit Plan.json** — that's grill territory.
+
+## Routing
+
+Inspect `$ARGUMENTS`:
+
+- empty → present the full menu (step 1 below).
+- `list` / `show` → run `gpr config list` and `gpr config list --scope project`, render both, then yield. Skip the menu.
+- a known key like `run.agent`, `viewer.theme`, etc. → jump to "Set one key" with that key preselected.
+- `reset` → jump to "Reset" branch.
+- `env` → jump to "Env vars" branch.
+
+## Step 1 — show the current state
+
+Run both:
+
+```bash
+gpr config list --scope user --json
+gpr config list --scope project --json
+```
+
+Parse the JSON. Render a single compact table for the user:
+
+```
+KEY                     USER          PROJECT       DEFAULT
+run.agent               claude        —             claude
+run.audit_agent         —             —             None
+run.deep_audit          False         —             False
+run.max_iters           50            —             50
+viewer.style            editorial     —             editorial
+viewer.theme            paper         —             paper
+…
+```
+
+Mark non-default values with a `*` so the user can see what's customized.
+
+Below the table, surface the env vars that override at runtime:
+
+- `GPR_AGENT_EXTRA_ARGS` — appended to the spawned agent command. Use for `--allowedTools`, `--model`, MCP server flags. Quoted; shell-split.
+- `GPR_NO_NOTIFY=1` — disable desktop notifications (`osascript` / `notify-send` / `powershell.exe toast`).
+- `GPR_BUDGET_MAX_COST_USD=USD` — runtime cap; overrides `Plan.budget.maxCostUsd` for this run.
+- `GPR_HOME` — override gpr install dir (rarely needed).
+
+And point at the Plan:
+
+> "Per-project caps (`budget.tokens`, `budget.wallClockSeconds`, `budget.maxCostUsd`), `qualityGates`, `persona` live in `.gpr/Plan.json`. Edit those via `/gpr-grill` (revise mode) or `$EDITOR .gpr/Plan.json` — not here."
+
+## Step 2 — ask what to change
+
+> "What would you like to do?
+> 1. Set a key (e.g. `run.agent = codex`)
+> 2. Unset a key (revert to default)
+> 3. Reset a whole scope (clear user OR project config)
+> 4. Show env-var examples
+> 5. Quit"
+
+One option per turn. If the user names a key directly, skip to step 3.
+
+## Step 3 — Set one key
+
+Ask the user three things in one go:
+
+1. Key — auto-complete from `gpr config keys` output. Reject unknown keys with the keys list.
+2. Value — type-check against the default's type (bool, int, string, enum). For enums (`viewer.style`, `viewer.theme`), enumerate valid values.
+3. Scope — `user` (global) or `project` (this repo only).
+
+Then run:
+
+```bash
+gpr config set <key> <value> --scope <user|project>
+```
+
+Re-run `gpr config get <key> --scope <scope>` to confirm. Show the user the before/after.
+
+## Step 4 — Unset / Reset
+
+- **Unset one key** — `gpr config unset <key> --scope <scope>`. Confirms the key falls back to the next-precedence value.
+- **Reset a scope** — `gpr config reset --scope <user|project>`. **Destructive.** Show the user the keys that will be cleared first; require explicit yes.
+
+## Step 5 — Env-var examples
+
+If the user picks the env-vars branch, print a few concrete invocations:
+
+```bash
+# Inherit MCP/allowed-tools into the spawned agent
+GPR_AGENT_EXTRA_ARGS='--allowedTools "Bash(rtk *)"' gpr run --agent claude
+
+# Cheap dry run, no notifications
+GPR_NO_NOTIFY=1 gpr run --agent echo --max-iters 1
+
+# Hard-cap a run below the Plan's budget
+GPR_BUDGET_MAX_COST_USD=2 gpr run --agent claude
+```
+
+Then yield — env vars are set in the user's shell, not by us.
+
+## Hard rules
+
+- Never edit `~/.config/gpr/config.toml` or `.gpr/config.toml` directly with `Write`. Always go through `gpr config set/unset/reset`.
+- Never edit `.gpr/Plan.json` from this skill. Direct the user to `/gpr-grill` or `$EDITOR`.
+- Validate enum values against `gpr config keys` output before calling `set` — a bad value will be rejected by the CLI but the user experience is cleaner if we catch it first.
+- Show the before/after for every change. The user should never have to run `gpr config get` themselves to confirm.
+
+## Smoke test
+
+A minimal happy path the skill should be able to walk end-to-end:
+
+1. `/gpr-settings`
+2. User picks "Set a key" → `viewer.theme` → `dark` → `user` scope.
+3. Skill runs `gpr config set viewer.theme dark --scope user`.
+4. Skill confirms with `gpr config get viewer.theme --scope user` → prints `'dark'`.
+5. User runs `gpr render` in any project → HTML reflects the new theme.