acstack 0.48.0 → 0.48.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acstack",
   "description": "Agentic coding stack where planning grows only as far as needed: a map of decisions, tasks, checks, and handoffs behind a pluggable tracker.",
-  "version": "0.48.0",
+  "version": "0.48.2",
   "author": {
     "name": "ac8318740"
   },

package/assets/terminal-workspace/config.example.yaml

@@ -236,6 +236,19 @@ pi:
   # retro. Needs the agentic-retro plugin installed first, and apply says so
   # when it is not.
   agentic_retro: true
+  # Zentui supplies the accent-rail editor and Starship footer. The footer
+  # format keeps model/provider/thinking visible on the right, including in
+  # compact mode.
+  zentui: true
+  # Hide pi-lens's LSP status footer and diagnostics widget rows.
+  hide_lens_lsp_status: true
+  # Extra pi-lens tools installed onto PATH for ecosystems used across repos.
+  # These are machine-wide, not project dependencies.
+  lens_extra_tools:
+    python: true          # black, mypy, pyright
+    docker: true          # hadolint, Dockerfile language server
+    github_actions: true  # actionlint, zizmor
+    terraform: true       # terraform-ls, tflint, terragrunt
   # Written into ~/.pi/agent/settings.json. Empty leaves pi's own value alone.
   # Every other key in that file stays as you set it, and disable puts back
   # any value of yours that apply replaced.
@@ -247,8 +260,9 @@ pi:
     mermaid: streaming
     # pi's anonymous install and update reporting. Kept off by this setup.
     install_telemetry: false
-    # A pi theme name. "system" takes its colours from the terminal.
-    theme: system
+    # A pi theme name. alex-mid-grey is written by this setup and shades
+    # user messages.
+    theme: alex-mid-grey
 
 neovim:
   # The one component that is off by default, because it writes into a neovim

package/assets/terminal-workspace/setup.sh

@@ -38,7 +38,13 @@ PI_SUBAGENT_CFG="$PI_DIR/extensions/subagent/config.json"
 PI_RETRO_EXT="${PI_HOME:-$HOME/.pi}/agent/extensions/agentic-retro.ts"
 PI_ACSTACK="npm:acstack"
 PI_BILLION="npm:billion-context"
+BILLION_CONFIG="$HOME/.config/billion-context/billion-context.json"
 PI_SLASH_ANYWHERE="npm:pi-slash-anywhere"
+PI_ZENTUI="npm:pi-zentui"
+PI_ZENTUI_CFG="$PI_DIR/zentui.json"
+PI_THEME_DIR="$PI_DIR/themes"
+PI_THEME="$PI_THEME_DIR/alex-mid-grey.json"
+PI_LENS_CFG="$HOME/.pi-lens/config.json"
 # A line starting with # is a heading in markdown, and the model reads it. An
 # HTML comment carries the same marker and renders as nothing.
 PI_MD_BEGIN="<!-- >>> acstack terminal-workspace >>> -->"
@@ -180,6 +186,57 @@ PY
   say "$name installed to $BIN/$name"
 }
 
+install_plain_github_binary() {  # install_plain_github_binary <name> <repo> <asset-match>
+  local name="$1" repo="$2" match="$3"
+  if [ "${INSTALL_FORCE:-0}" != "1" ] && have "$name"; then
+    say "$name already installed"; return 0
+  fi
+  local json url tmp
+  json=$(curl -sSf "https://api.github.com/repos/$repo/releases/latest" 2>/dev/null)
+  [ -z "$json" ] && { say "$name: could not reach the GitHub release API"; return 1; }
+  url=$(MAPFLOW_JSON="$json" py "$match" <<'PY'
+import json, os, sys
+try:
+    d = json.loads(os.environ["MAPFLOW_JSON"])
+except ValueError:
+    raise SystemExit
+for a in d.get("assets", []):
+    if sys.argv[1] in a["name"]:
+        print(a["browser_download_url"]); break
+PY
+)
+  [ -z "$url" ] && { say "$name: no matching release asset, install manually"; return 1; }
+  tmp=$(mktemp)
+  if ! curl -fsSL "$url" -o "$tmp"; then
+    rm -f "$tmp"; say "$name: download failed"; return 1
+  fi
+  mkdir -p "$BIN"; cp "$tmp" "$BIN/$name"; chmod +x "$BIN/$name"
+  rm -f "$tmp"
+  say "$name installed to $BIN/$name"
+}
+
+install_npm_tool() {  # install_npm_tool <command> <package>
+  local command="$1" package="$2"
+  if have "$command"; then say "$command already installed"; return 0; fi
+  have npm || { say "$command: npm not installed, skipping"; return 0; }
+  if npm install -g "$package" >/dev/null 2>&1; then
+    say "$command installed with npm"
+  else
+    say "$command install failed, run: npm install -g $package"
+  fi
+}
+
+install_uv_tool() {  # install_uv_tool <command> <package>
+  local command="$1" package="$2"
+  if have "$command"; then say "$command already installed"; return 0; fi
+  have uv || { say "$command: uv not installed, skipping"; return 0; }
+  if uv tool install "$package" >/dev/null 2>&1; then
+    say "$command installed with uv"
+  else
+    say "$command install failed, run: uv tool install $package"
+  fi
+}
+
 write_helpers() {
   mkdir -p "$BIN"
   # Helpers this script used to write and no longer does. Upgrading otherwise
@@ -3184,6 +3241,30 @@ apply_harlequin() {
     || say "harlequin install failed, run: uv tool install harlequin"
 }
 
+apply_lens_extra_tools() {
+  # A small machine-wide pi-lens toolbelt for common project ecosystems.
+  # Pi-lens can fall back to npx or prompt for some tools, but putting these
+  # on PATH makes them available in any repo without per-project setup.
+  if [ "$(cfg_get pi.lens_extra_tools.python false)" = "true" ]; then
+    install_uv_tool black black
+    install_uv_tool mypy mypy
+    install_npm_tool pyright pyright
+  fi
+  if [ "$(cfg_get pi.lens_extra_tools.docker false)" = "true" ]; then
+    install_plain_github_binary hadolint hadolint/hadolint Linux-x86_64
+    install_npm_tool docker-langserver dockerfile-language-server-nodejs
+  fi
+  if [ "$(cfg_get pi.lens_extra_tools.github_actions false)" = "true" ]; then
+    install_binary actionlint rhysd/actionlint linux_amd64
+    install_uv_tool zizmor zizmor
+  fi
+  if [ "$(cfg_get pi.lens_extra_tools.terraform false)" = "true" ]; then
+    install_binary terraform-ls hashicorp/terraform-ls linux_amd64
+    install_binary tflint terraform-linters/tflint linux_amd64
+    install_plain_github_binary terragrunt gruntwork-io/terragrunt linux_amd64
+  fi
+}
+
 apply_ghdash() {
   have gh || { say "gh not installed, skipping dashboard"; return 0; }
   gh extension list 2>/dev/null | grep -q gh-dash || gh extension install dlvhdr/gh-dash >/dev/null 2>&1
@@ -3495,7 +3576,7 @@ s = ((c.get("pi") or {}).get("settings") or {})
 KEYS = {"hide_thinking_block": ("hideThinkingBlock", True, (True, False)),
         "mermaid": ("markdown.mermaid", "streaming", ("off", "final", "streaming")),
         "install_telemetry": ("enableInstallTelemetry", False, (True, False)),
-        "theme": ("theme", "system", None)}
+        "theme": ("theme", "alex-mid-grey", None)}
 out = {}
 for k, (key, default, allowed) in KEYS.items():
     v = s.get(k, default)
@@ -3514,6 +3595,153 @@ print(json.dumps(out))
 PY
 }
 
+pi_zentui_wanted() {
+  cat <<'JSON'
+{
+  "components.editor.enabled": true,
+  "components.editor.style": "accent-rail",
+  "components.editor.styles.accent-rail.transparent": false,
+  "components.userMessages.enabled": false,
+  "components.footer.style": "starship",
+  "components.footer.modelLabel": "id",
+  "components.footer.styles.starship.segments.modelInfo": true,
+  "components.footer.styles.starship.extensionStatuses.defaultPlacement": "off",
+  "components.extensionStatuses.defaultVisibility": "hide",
+  "components.extensionStatuses.visibility.pi-lens": "hide",
+  "components.extensionStatuses.visibility.pi-lens-lsp": "hide",
+  "components.extensionStatuses.visibility.ponytail": "hide",
+  "components.footer.styles.starship.responsive": true,
+  "components.footer.styles.starship.format": "$cwd( in $session_name)( on $git_branch)( $git_status)( via $runtime)$fill$model($sep$provider)($sep$thinkingLevel)($sep$context)( $auto_compaction)($sep$tokens)( $cache_read)( $cache_write)($sep$cost)( $subscription)",
+  "components.footer.styles.starship.compactFormat": "$cwd$wrap(in $session_name)$wrap(on $git_branch) $git_status$fill$model$wrap_sep($provider)$wrap_sep($thinkingLevel)$wrap_sep$context$wrap_sep$tokens"
+}
+JSON
+}
+
+pi_zentui_release() {
+  cat <<'JSON'
+{
+  "components.editor.enabled": null,
+  "components.editor.style": null,
+  "components.editor.styles.accent-rail.transparent": null,
+  "components.userMessages.enabled": null,
+  "components.footer.style": null,
+  "components.footer.modelLabel": null,
+  "components.footer.styles.starship.segments.modelInfo": null,
+  "components.footer.styles.starship.extensionStatuses.defaultPlacement": null,
+  "components.extensionStatuses.defaultVisibility": null,
+  "components.extensionStatuses.visibility.pi-lens": null,
+  "components.extensionStatuses.visibility.pi-lens-lsp": null,
+  "components.extensionStatuses.visibility.ponytail": null,
+  "components.footer.styles.starship.responsive": null,
+  "components.footer.styles.starship.format": null,
+  "components.footer.styles.starship.compactFormat": null
+}
+JSON
+}
+
+pi_write_theme() {
+  if [ -e "$PI_THEME" ] && ! pi_state owns file "$PI_THEME"; then
+    say "pi: $PI_THEME already exists, so the Mapflow theme was left alone"
+    return 0
+  fi
+  MAPFLOW_PI_THEME="$PI_THEME" py <<'PY'
+import json, os
+
+target = os.environ["MAPFLOW_PI_THEME"]
+theme = {
+    "$schema": "https://pi.dev/schemas/theme.schema.json",
+    "name": "alex-mid-grey",
+    "vars": {
+        "surfaceMuted": "#21262D",
+        "border": "#30363D",
+        "borderSubtle": "#21262D",
+        "text": "#C9D1D9",
+        "textBright": "#E6EDF3",
+        "muted": "#8B949E",
+        "dim": "#6E7681",
+        "toolStatus": "#59616B",
+        "blue": "#58A6FF",
+        "blueSoft": "#79C0FF",
+        "inlineCode": "#D2A8FF",
+        "green": "#3FB950",
+        "red": "#F85149",
+        "yellow": "#E0A052",
+        "orange": "#FFA657",
+        "purple": "#D2A8FF",
+        "toolAccent": "#95A7FF",
+        "toolName": "#8B85D6",
+        "toolText": "#98A1AC",
+        "pink": "#FF7B72",
+        "userPromptBg": "#24272e",
+    },
+    "colors": {
+        "accent": "toolAccent",
+        "border": "border",
+        "borderAccent": "toolStatus",
+        "borderMuted": "borderSubtle",
+        "success": "green",
+        "error": "red",
+        "warning": "yellow",
+        "muted": "muted",
+        "dim": "dim",
+        "text": "text",
+        "thinkingText": "toolText",
+        "selectedBg": "surfaceMuted",
+        "searchMatchBg": "#3B2E10",
+        "searchMatchText": "textBright",
+        "userMessageBg": "userPromptBg",
+        "userMessageText": "textBright",
+        "customMessageBg": "",
+        "customMessageText": "text",
+        "customMessageLabel": "muted",
+        "toolPendingBg": "",
+        "toolSuccessBg": "",
+        "toolErrorBg": "#211414",
+        "toolTitle": "toolName",
+        "toolOutput": "toolText",
+        "scrollbarTrack": "borderSubtle",
+        "scrollbarThumb": "border",
+        "mdHeading": "textBright",
+        "mdLink": "blue",
+        "mdLinkUrl": "dim",
+        "mdCode": "inlineCode",
+        "mdCodeBlock": "text",
+        "mdCodeBlockBorder": "#0D1117",
+        "mdQuote": "toolText",
+        "mdQuoteBorder": "border",
+        "mdHr": "borderSubtle",
+        "mdListBullet": "muted",
+        "toolDiffAdded": "#45B85A",
+        "toolDiffRemoved": "#E45D57",
+        "toolDiffContext": "dim",
+        "syntaxComment": "dim",
+        "syntaxKeyword": "pink",
+        "syntaxFunction": "purple",
+        "syntaxVariable": "text",
+        "syntaxString": "blueSoft",
+        "syntaxNumber": "orange",
+        "syntaxType": "orange",
+        "syntaxOperator": "muted",
+        "syntaxPunctuation": "muted",
+        "thinkingOff": "borderSubtle",
+        "thinkingMinimal": "border",
+        "thinkingLow": "dim",
+        "thinkingMedium": "muted",
+        "thinkingHigh": "blue",
+        "thinkingXhigh": "blueSoft",
+        "thinkingMax": "#9FCFF8",
+        "bashMode": "green",
+    },
+    "export": {"pageBg": "#0D1117", "cardBg": "#161B22", "infoBg": "#1C2128"},
+}
+os.makedirs(os.path.dirname(target), exist_ok=True)
+json.dump(theme, open(target, "w"), indent=2, ensure_ascii=False)
+open(target, "a").write("\n")
+PY
+  pi_state own file "$PI_THEME"
+  say "pi: Mapflow theme written to $PI_THEME"
+}
+
 # npm installs pi into its global bin, which a fresh shell may not have on
 # PATH. Asking npm costs a process, so only when pi is not already found.
 find_pi() {
@@ -3762,10 +3990,16 @@ apply_pi() {
   bili_client remove codex
   bili_client remove claude
   if [ "$(cfg_get pi.billion_context true)" = "true" ]; then
-    pi_add "$PI_BILLION" "$PI_BILLION"
-    bili_client install pi
+    pi_state merge "$BILLION_CONFIG" billion '{"pi.subagents": false}'
+    if [ "$(json_field "$BILLION_CONFIG" pi.subagents)" = "False" ]; then
+      pi_add "$PI_BILLION" "$PI_BILLION"
+      bili_client install pi
+    else
+      say "pi: billion-context acp_delegate could not be disabled, so billion-context setup was skipped"
+    fi
   else
     bili_client remove pi
+    pi_state merge "$BILLION_CONFIG" billion '{"pi.subagents": null}'
     pi_drop "$PI_BILLION"
   fi
   if [ "$(cfg_get pi.question_tool true)" = "true" ]; then
@@ -3803,6 +4037,20 @@ apply_pi() {
   else
     pi_drop npm:pi-compact-tools
   fi
+  [ "$(cfg_get pi.settings.theme alex-mid-grey)" = "alex-mid-grey" ] && pi_write_theme
+  if [ "$(cfg_get pi.zentui true)" = "true" ]; then
+    pi_add "$PI_ZENTUI" "$PI_ZENTUI"
+    pi_state merge "$PI_ZENTUI_CFG" zentui "$(pi_zentui_wanted)"
+  else
+    pi_state merge "$PI_ZENTUI_CFG" zentui "$(pi_zentui_release)"
+    pi_drop "$PI_ZENTUI"
+  fi
+  if [ "$(cfg_get pi.hide_lens_lsp_status true)" = "true" ]; then
+    pi_state merge "$PI_LENS_CFG" pi_lens '{"ui.hideLspStatus": true, "widget.visible": false}'
+  else
+    pi_state merge "$PI_LENS_CFG" pi_lens '{"ui.hideLspStatus": null, "widget.visible": null}'
+  fi
+  apply_lens_extra_tools
 
   # agentic-retro writes its own extension file. This setup only asks it to,
   # and owns the file only when it was not there before.
@@ -3850,6 +4098,7 @@ remove_pi() {
     pi_drop npm:pi-plugin-manager
     pi_drop npm:@juicesharp/rpiv-todo
     pi_drop npm:pi-compact-tools
+    pi_drop "$PI_ZENTUI"
     pi_drop npm:@juicesharp/rpiv-ask-user-question
     pi_drop npm:pi-web-access
     pi_drop npm:pi-lens
@@ -3858,6 +4107,7 @@ remove_pi() {
   else
     say "pi: $PI_SETTINGS does not parse, so its packages were left installed"
   fi
+  pi_state merge "$BILLION_CONFIG" billion '{"pi.subagents": null}'
   if pi_state owns file "$PI_RETRO_EXT"; then
     rm -f "$PI_RETRO_EXT"
     pi_state disown file "$PI_RETRO_EXT"
@@ -3865,6 +4115,13 @@ remove_pi() {
   fi
   pi_state merge "$PI_SETTINGS" settings \
     '{"hideThinkingBlock": null, "markdown.mermaid": null, "enableInstallTelemetry": null, "theme": null}'
+  pi_state merge "$PI_ZENTUI_CFG" zentui "$(pi_zentui_release)"
+  pi_state merge "$PI_LENS_CFG" pi_lens '{"ui.hideLspStatus": null, "widget.visible": null}'
+  if pi_state owns file "$PI_THEME"; then
+    rm -f "$PI_THEME"
+    pi_state disown file "$PI_THEME"
+    say "pi: Mapflow theme removed"
+  fi
   pi_state merge "$PI_KEYBINDINGS" keybindings '{"app.message.dequeue": null}'
   pi_state merge "$PI_SUBAGENT_CFG" subagent '{"toolActivation": null}'
   pi_state md strip
@@ -3899,6 +4156,12 @@ pi-web-access	pi	npm	pi-web-access	-
 pi-lens	pi	npm	pi-lens	-
 pi-slash-anywhere	pi	npm	pi-slash-anywhere	-
 pi-compact-tools	pi	npm	pi-compact-tools	-
+pi-zentui	pi	npm	pi-zentui	-
+actionlint	pi	github	rhysd/actionlint	linux_amd64
+hadolint	pi	github	hadolint/hadolint	Linux-x86_64
+terraform-ls	pi	github	hashicorp/terraform-ls	linux_amd64
+tflint	pi	github	terraform-linters/tflint	linux_amd64
+terragrunt	pi	github	gruntwork-io/terragrunt	linux_amd64
 T
 }
 
@@ -3929,8 +4192,18 @@ installed_version() {  # installed_version <name> -> a bare version, or nothing
     harlequin) v=$(uv tool list 2>/dev/null | awk '$1=="harlequin"{print $2}') ;;
     # 1.1.0
     pi)        find_pi; v=$(pi --version 2>/dev/null | awk '{print $NF}') ;;
+    # actionlint version 1.7.7
+    actionlint) v=$(actionlint -version 2>/dev/null | awk '{print $2}') ;;
+    # Haskell Dockerfile Linter 2.12.0
+    hadolint)  v=$(hadolint --version 2>/dev/null | awk '{print $NF}') ;;
+    # terraform-ls version 0.36.5
+    terraform-ls) v=$(terraform-ls version 2>/dev/null | awk '{print $2}') ;;
+    # TFLint version 0.59.1
+    tflint)    v=$(tflint --version 2>/dev/null | awk 'NR==1{print $3}') ;;
+    # terragrunt version v0.91.2
+    terragrunt) v=$(terragrunt --version 2>/dev/null | awk '{print $NF}') ;;
     # pi installs npm packages under its own directory, not npm's global one.
-    pi-subagents|pi-compact-tools|pi-web-access|pi-lens|pi-slash-anywhere|@juicesharp/rpiv-ask-user-question|billion-context|@juicesharp/rpiv-todo|pi-plugin-manager)
+    pi-subagents|pi-compact-tools|pi-zentui|pi-web-access|pi-lens|pi-slash-anywhere|@juicesharp/rpiv-ask-user-question|billion-context|@juicesharp/rpiv-todo|pi-plugin-manager)
                v=$(json_field "$PI_DIR/npm/node_modules/$1/package.json" version) ;;
   esac
   printf '%s' "${v#v}"
@@ -4080,7 +4353,7 @@ upgrade_one() {  # upgrade_one <name>
                else
                  say "pi update failed"
                fi ;;
-    pi-subagents|pi-compact-tools|pi-web-access|pi-lens|pi-slash-anywhere|@juicesharp/rpiv-ask-user-question|billion-context|@juicesharp/rpiv-todo|pi-plugin-manager)
+    pi-subagents|pi-compact-tools|pi-zentui|pi-web-access|pi-lens|pi-slash-anywhere|@juicesharp/rpiv-ask-user-question|billion-context|@juicesharp/rpiv-todo|pi-plugin-manager)
       if pi_npm_pin "$1"; then
         say "$1 is pinned to $(pi_state pkg "npm:$1") in pi, which pi update never moves"
         return 0
@@ -4097,6 +4370,10 @@ upgrade_one() {  # upgrade_one <name>
     # here rather than behind a table lookup that will never find it.
     mermaid-ascii)
       INSTALL_FORCE=1 install_binary mermaid-ascii AlexanderGrooff/mermaid-ascii Linux_x86_64 ;;
+    hadolint)
+      INSTALL_FORCE=1 install_plain_github_binary hadolint hadolint/hadolint Linux-x86_64 ;;
+    terragrunt)
+      INSTALL_FORCE=1 install_plain_github_binary terragrunt gruntwork-io/terragrunt linux_amd64 ;;
     # The fork build comes from a local checkout, so a release archive would
     # replace it with the stock binary and silently drop the patches it carries.
     # outdated already skips it; naming it here has to skip it too.
@@ -4165,7 +4442,7 @@ case "$ACTION" in
     if have pi || [ "$(cfg_get pi.enabled false)" = "true" ]; then
       echo
       have pi && say "pi: $(installed_version pi)" || say "pi: not installed"
-      for id in npm:pi-subagents "$PI_ACSTACK" "$PI_BILLION" npm:@juicesharp/rpiv-todo npm:pi-plugin-manager npm:@juicesharp/rpiv-ask-user-question npm:pi-web-access npm:pi-lens "$PI_SLASH_ANYWHERE" npm:pi-compact-tools; do
+      for id in npm:pi-subagents "$PI_ACSTACK" "$PI_BILLION" npm:@juicesharp/rpiv-todo npm:pi-plugin-manager npm:@juicesharp/rpiv-ask-user-question npm:pi-web-access npm:pi-lens "$PI_SLASH_ANYWHERE" npm:pi-compact-tools "$PI_ZENTUI"; do
         src=$(pi_state pkg "$id") && say "pi package: $src" || say "pi package: $id not installed"
       done
       [ -e "$PI_RETRO_EXT" ] && say "pi agentic-retro extension: present" \

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.48.0",
+  "version": "0.48.2",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",

package/docs/workflows.md

@@ -121,7 +121,7 @@ Nodes live in a tracker. That is the storage layer, and you can swap it.
 
 - `/acstack:implement` claims `afk` work nodes from the frontier when a map exists
     - It treats the request itself as the work item when none does
-    - Either way, parallel explorer subagents run over the relevant code before anyone writes anything
+    - Either way, parallel read-only codebase-search subagents run over the relevant code before anyone writes anything
 - The command resolves paths at claim time
     - A node describes behaviour
     - It can sit unstarted for weeks

package/orchestrator/AGENTS.md

@@ -55,7 +55,7 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
 - **Launch a subagent** – start a child agent with its own context, by its ACStack name (`test-writer`, `task-executor`, `task-checker`, `frontend-verifier`)
     - Claude Code: the Agent tool, with `subagent_type` set to that name
     - pi: the `subagent` tool from `pi-subagents`
-    - `Explore` names a read-only codebase-search agent: Claude Code's `Explore`, pi's `scout`
+    - **Read-only codebase-search subagent** – Claude Code's `Explore`, pi's `scout`
     - `debugger` names a debugging agent
     - On a host without a matching built-in agent, launch a general subagent with that brief
 - **Agent team** – parallel full sessions, each owning one scope and launching its own subagents
@@ -502,7 +502,7 @@ Launch each agent by the name below (see Host tools for how your host takes it).
 | Implement task        | `task-executor`     | CANNOT modify tests                                |
 | Verify implementation | `task-checker`      | Mock skepticism, full regression, TDD isolation    |
 | Verify frontend UI    | `frontend-verifier` | Real browser, screenshots, non-negotiable          |
-| Find/locate something | `Explore`           | Built-in codebase search                           |
+| Find/locate something | `Explore` / `scout` | Read-only codebase search; `scout` on pi           |
 | Debug/investigate     | `debugger`          | Built-in debugging agent                           |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack",
-  "version": "0.48.0",
+  "version": "0.48.2",
   "private": false,
   "description": "Agentic coding stack with first-class Claude Code and pi support: skills, orchestrator instructions, and verification agents.",
   "license": "MIT",

package/skills/bootstrap/SKILL.md

@@ -41,7 +41,7 @@ Your job is to:
 
 ## Phase 1: independent exploration (passes 1-3)
 
-Launch **3 parallel `Explore` subagents** at once. Each gets a different exploration strategy:
+Launch **3 parallel read-only codebase-search subagents** at once. Use `Explore` on Claude Code and `scout` on pi. Each gets a different exploration strategy:
 
 ### Pass 1 – entry points strategy
 
@@ -90,7 +90,7 @@ Launch a single subagent to merge the 3 independent drafts per domain. It resolv
 
 ## Phase 3: validation (passes 5-7)
 
-Launch 3 parallel Explore subagents to validate ALL domains independently – each checks that FRs match actual code behavior.
+Launch 3 parallel read-only codebase-search subagents to validate ALL domains independently. Each checks that FRs match actual code behavior.
 
 ## Phase 4: correction merge (pass 8)
 

package/skills/grilling/SKILL.md

@@ -29,9 +29,11 @@ session.
    nothing else. Never ask a question whose answer depends on one still open.
 
 2. **Facts are your job, never the user's.** Skip a question that an
-   environment fact would answer. Dispatch parallel `Explore` subagents, one
-   per distinct place to look, not a fixed count. Fold what they find into
-   the round.
+   environment fact would answer.
+
+   Dispatch parallel read-only codebase-search subagents, one per distinct
+   place to look, not a fixed count. Use `Explore` on Claude Code and `scout`
+   on pi. Fold what they find into the round.
 
 3. **Run it before you ask it.** Check whether running something could answer
    the question – behaviour, timing, output, or performance. If it could,
@@ -106,8 +108,8 @@ the tracker's `update` and `create` operations:
     Write the answer per the `writing` skill.
 
 2. Create a node for each new question the answer surfaced, with `answers`
-   naming the node that surfaced it. Questions that can be stated precisely
-   are `open`; the rest are `fog`.
+   naming the node that surfaced it. Mark precise questions `open`; mark the
+   rest `fog`.
 
 3. Invoke the `record-context` skill for each resolution – it decides whether
    the decision earns an ADR, a glossary term, both, or neither.

package/skills/implement/SKILL.md

@@ -98,9 +98,11 @@ Claim each node as you start it:
 
 Nodes describe behaviour, not paths. **Resolve paths at claim time**.
 
-Before any code change, dispatch parallel explorer subagents over the
-relevant code. Use as many as there are distinct places to look, not a fixed
-count. Act on what they find.
+Before any code change, dispatch parallel read-only codebase-search subagents
+over the relevant code. Use `Explore` on Claude Code and `scout` on pi.
+
+Use as many as there are distinct places to look, not a fixed count. Act on
+what they find.
 
 ### 5. Execute within the claim
 
@@ -219,8 +221,9 @@ diff.
 - **The tracker is the progress record** – claim on start, resolve on pass,
   release on stall. No checkbox files, no phase fields.
 
-- **Explore before writing** – parallel explorer subagents over the relevant
-  code, sized to the node, before any edit.
+- **Explore before writing** – parallel read-only codebase-search subagents
+  over the relevant code, sized to the node, before any edit. Use `Explore` on
+  Claude Code and `scout` on pi.
 
 - **Resume is a query** – picking up where you left off means asking the
   tracker what is workable now, not reconstructing history. A fresh session

package/skills/map/SKILL.md

@@ -182,8 +182,8 @@ the list, marked `skip: <reason>`.
     - `hitl` nodes: run grilling rounds over them. A round is the whole hitl
      frontier.
     - `afk` nodes: claim and run without the user. Unlimited, and in parallel
-     when independent. Research goes to `Explore` subagents, with the findings
-     written into the resolution.
+     when independent. Research goes to read-only codebase-search subagents:
+     `Explore` on Claude Code and `scout` on pi.
 
      Implementation work follows `/acstack:implement`'s procedure – it owns
      the claim-execute-resolve flow, the explorer dispatch, and the TDD

package/skills/pre-commit-review/SKILL.md

@@ -73,7 +73,8 @@ If no meaningful code changes exist (only docs, config, assets), report "No code
 
 ## Step 2: DISCOVER – Learn project conventions (parallel)
 
-Launch **3 parallel Explore subagents** to build a dynamic understanding of the project's current conventions.
+Launch **3 parallel read-only codebase-search subagents** to build a dynamic understanding of the project's current conventions.
+Use `Explore` on Claude Code and `scout` on pi.
 Do NOT hardcode conventions – discover them fresh each time.
 
 **Subagent A – Living Specs & Architecture:**
@@ -177,7 +178,8 @@ Add each finding to the review as `SHOULD | PROSE`, at the `file:line` it names.
 
 ## Step 4: ADJACENT – Check surrounding code for rot
 
-For each file with findings from Step 3, launch an **Explore subagent** (up to 3 in parallel).
+For each file with findings from Step 3, launch a **read-only codebase-search subagent**.
+Use up to 3 subagents in parallel.
 Each subagent examines the rest of that file and its immediate imports for the same categories of issue.
 
 ```

package/skills/quick-fix/SKILL.md

@@ -39,7 +39,7 @@ If the user provided an error message or stack trace, note the key details (file
 
 **Do NOT skip this step.** Delegate exploration to subagents:
 
-1. **Locate the code**: Launch an Explore subagent to find the files involved. Read only a file you can already name.
+1. **Locate the code**: Launch a read-only codebase-search subagent to find the files involved. Use `Explore` on Claude Code and `scout` on pi. Read only a file you can already name.
 
 2. **Read the integration points**: Have the subagent read the broken function's callers and callees, not just the function. Understand:
     - What calls this code? (upstream)

package/skills/setup/row-fixes.md

@@ -50,9 +50,11 @@ frontend and has not turned browser verification on. Turn it on:
 read it. Without it, every path through spec sync skips in silence, and the
 living specs never update.
 
-Launch an **Explore subagent** over `directories.source` to propose domains. Ask
-it for the top-level functional areas. Ask for a kebab-case name, the paths that
-belong to it, and one line saying what it owns.
+Launch a **read-only codebase-search subagent** over `directories.source` to propose domains.
+Use `Explore` on Claude Code and `scout` on pi.
+
+Ask it for the top-level functional areas.
+Ask for a kebab-case name, the paths that belong to it, and one line saying what it owns.
 
 Guidance for the subagent: