@techgoblin/gobstack 0.5.0-beta.8 → 0.6.0-alpha.2

package/bin/goblin

@@ -1,20 +1,25 @@
 #!/usr/bin/env bash
-# goblin — the global CLI dispatcher (W1, PLAN-V1 §2.3 / W1-SPEC §3).
+# goblin — the CLI dispatcher.
 #
-#   gob verify [--only <id[,id...]>] [--json] [--list] [--source <path>]
-#   gob bans   [--only <id[,id...]>] [--list]
-#   gob audit  [--target <dir>] [--print]
-#   gob doctor [--platform <p>]      # W4a
-#   gob emit   --platform <p> [...]  # W4a/W4b; `gob sync` is the same verb, renamed
-#   gob init   [...]                 # W6: the first-run wizard
-#   gob upgrade [--target .] [...]   # W3
+#   gob init    [--heuristic | --write <proposal>] [--target <dir>] [...]
+#   gob map     [target] [--agent | --heuristic] [--write <dir>] [--force]
+#   gob verify  [--only <id[,id...]>] [--json] [--list] [--source <path>]
+#   gob bans    [--only <id[,id...]>] [--list]
+#   gob extras  list [category] | show <id> | install <id...> [--target <dir>]
+#                    [--platform <id>] [--with-mcp-config] [--dry-run]
+#   gob mcp                                     serve the harness over MCP stdio
+#   gob uninstall --target <dir>
 #   gob --version
 #
+# v2 SURFACE (AI-driven development): the CLI calls no AI API. `gob init` and `gob map`
+# EMIT a prompt + schema that the agent already running in this repo fulfils with its own
+# tools; heuristic detection demotes to the --heuristic fallback.
+#
+# UNWIRED this session (code kept under bin/, deletion is session 3): doctor, audit,
+# upgrade, emit/sync. `sync` becomes an init-internal step (hidden --resync flag).
+#
 # Identity: the package is gobstack (npm @techgoblin/gobstack), the command is `gob`
-# (`goblin` remains as a legacy alias). W1 ships the DISPATCH
-# SHELL only — the node shim and npm packaging are W2, doctor/emit are W4a (exit-2
-# placeholders naming their workstream), upgrade is W3 (same). G3 forbids a runtime
-# rewrite: the engine stays bash, this file only routes and propagates.
+# (`goblin` remains as a legacy alias).
 #
 # The four-value verify contract is unchanged and non-negotiable (bin/goblin-verify:5-9):
 #   0  every executed check passed
@@ -22,11 +27,10 @@
 #   2  could not run
 #   3  the manifest itself is broken
 # Every subcommand propagates the engine's exit code verbatim; no wrapper translates a
-# 1 into a 0. A placeholder that silently exited 0 would be a green build doing nothing.
+# 1 into a 0.
 #
-# Root resolution: find_installed_root() at bin/goblin-verify:64-77 is preserved
-# BYTE-FOR-BYTE (walk up from $PWD to .goblin/goblin.yaml; fall back to git toplevel,
-# then $PWD — the D20 nested-repo fix). W1 changes nothing about its logic.
+# Root resolution: find_installed_root() walks up from $PWD to an AGENTS.md carrying the
+# gob marker block; fall back to git toplevel, then $PWD — the D20 nested-repo fix.
 #
 # No npm, no jq, no yq, no network. bash/awk/sed/grep only.
 
@@ -42,27 +46,31 @@ usage() {
   cat <<'USAGE'
 gob — the gobstack command line.
 
-  gob verify [--only <id[,id...]>] [--json] [--list] [--source <path>]
-  gob bans   [--only <id[,id...]>] [--list]
-  gob audit  [--target <dir>] [--print]
-  gob doctor [--platform <p>] [--target <dir>]
-  gob emit   --platform <p> --scope project|global [...]   # alias: gob sync
-  gob sync   --platform <p> --scope project|global [...]   # the same verb, friendlier name
-  gob init   [--target <dir>] [--class app|A-F] [--dry-run]
-  gob map    [target] [--force]          # the standalone feature-map generator (no install needed)
-  gob upgrade [--target .] [--dry-run] [--yes] [--engine-dir <path>]
+  gob init    [--heuristic | --write <proposal>] [--target <dir>] [--class app|A-F] [--dry-run]
+  gob map     [target] [--agent | --heuristic] [--write <dir>] [--force]
+  gob verify  [--only <id[,id...]>] [--json] [--list] [--source <path>]
+  gob bans    [--only <id[,id...]>] [--list]
+  gob extras  list [category] | show <id> | install <id...>   # the curated extras catalogue
+  gob mcp     serve the harness to your agent over MCP stdio (verify/map/init tools)
+  gob uninstall --target <dir>
   gob --version
 
+gob init and gob map are AI-DRIVEN: they print a prompt + schema for the agent already
+running in this repo, which writes the proposal file; `--write` validates and installs
+it. The heuristic detectors are the --heuristic fallback.
+
 Exit codes (verify): 0 pass | 1 a check failed | 2 could not run | 3 the manifest is
 broken. Every subcommand propagates the engine's exit code verbatim.
 USAGE
 }
 
-# ---- the repo-root locator, preserved byte-for-byte from bin/goblin-verify:64-77 ----
+# ---- the repo-root locator (an AGENTS.md gob block is the install marker) ----
 find_installed_root() {
   local d="$PWD"
   while :; do
-    if [ -f "$d/.goblin/goblin.yaml" ]; then printf '%s\n' "$d"; return 0; fi
+    if [ -f "$d/AGENTS.md" ] && grep -q '^<!-- gob:begin' "$d/AGENTS.md" 2>/dev/null; then
+      printf '%s\n' "$d"; return 0
+    fi
     [ "$d" = "/" ] && return 1
     d=$(dirname "$d")
   done
@@ -74,6 +82,15 @@ CMD="${1:-}"
 shift
 
 case "$CMD" in
+  init)
+    # The prompt+schema engine: prints the agent brief, or installs a proposal.
+    exec bash "$SRC/bin/goblin-init" "$@"
+    ;;
+  map)
+    # The standalone feature-map generator: `--agent` (default) prints prompt+schema;
+    # --heuristic runs the scanner. Routes and propagates its 0/1/2 contract verbatim.
+    exec bash "$SRC/bin/goblin-map" "$@"
+    ;;
   verify)
     # The engine is whatever the per-repo chain resolves (W1 §2.3): --source, vendored,
     # engine_dir:, GOBLIN_ENGINE_DIR, ~/.goblin/engine — all inside goblin-verify. The
@@ -83,38 +100,22 @@ case "$CMD" in
   bans)
     exec bash "$SRC/bin/goblin-bans" "$@"
     ;;
-  audit)
-    exec bash "$SRC/bin/goblin-audit" "$@"
-    ;;
-  doctor)
-    # W4a: one run, three platforms (the §7 report); the dispatcher routes and
-    # propagates the doctor's 0/1/2 verbatim, like every other subcommand.
-    exec bash "$SRC/bin/goblin-doctor" "$@"
+  extras)
+    # The curated catalogue browser + installer (bin/goblin-extras): list/show/install
+    # over extras-catalogue/catalogue.tsv. The catalogue is the ALLOWLIST: nothing is
+    # ever installed that a catalogue row does not name, and `gob init` only suggests.
+    exec bash "$SRC/bin/goblin-extras" "$@"
     ;;
-  emit)
-    # W4a: per-platform emission (the §4 contract); the 0/1/2 exit contract is the
-    # same three values verify's wrapper states, propagated verbatim.
-    exec bash "$SRC/bin/goblin-emit" "$@"
+  mcp)
+    # The MCP stdio server (bin/goblin-mcp.js): JSON-RPC 2.0 over stdin/stdout, a LOCAL
+    # tool server over the vendored harness — no API call, no socket. node is the same
+    # runtime bin/goblin.js already needs; it is exec'd directly, args pass through.
+    exec node "$SRC/bin/goblin-mcp.js" "$@"
     ;;
-  sync)
-    # Wizard v2: the friendlier name for the same emission engine. `emit` stays a
-    # first-class verb; this case only adds the alias and propagates identically.
-    exec bash "$SRC/bin/goblin-emit" "$@"
-    ;;
-  init)
-    # W6: the first-run wizard. It drives install/emit/verify and propagates their
-    # exit contract verbatim, like every other subcommand here.
-    exec bash "$SRC/bin/goblin-init" "$@"
-    ;;
-  map)
-    # The standalone feature-map generator: routes and propagates its 0/1/2 contract
-    # verbatim, like every other subcommand. It needs no .goblin/ install by design.
-    exec bash "$SRC/bin/goblin-map" "$@"
-    ;;
-  upgrade)
-    # W3: the migration lives in its own checkout-level script (W3-SPEC §1.1);
-    # the dispatcher routes and propagates the four-value contract verbatim.
-    exec bash "$SRC/bin/goblin-upgrade" "$@"
+  uninstall)
+    # Routes into the installer's uninstall job. `--uninstall` is appended FIRST so the
+    # user's own `--target <dir>` and options still parse.
+    exec bash "$SRC/bin/goblin-install" --uninstall "$@"
     ;;
   --version|-V|-v)
     printf '%s\n' "$VERSION"
@@ -124,6 +125,17 @@ case "$CMD" in
     usage
     exit 0
     ;;
+  doctor|audit|upgrade|emit|sync|install)
+    # Unwired from usage in v2 (code kept; deletion is session 3). The refusal names
+    # what replaced each verb rather than silently executing the old path.
+    g_err "gob $CMD is unwired in v2."
+    case "$CMD" in
+      install|init-legacy) g_err "fix: gob init --write <proposal> installs a repo now." ;;
+      sync|emit)           g_err "fix: gob init --write <proposal> runs the sync step internally." ;;
+      doctor|audit|upgrade) g_err "fix: gob verify (audit stays a deliberate manual step; see docs/)." ;;
+    esac
+    exit 2
+    ;;
   *)
     g_err "unknown subcommand: $CMD"
     usage >&2

package/bin/goblin-audit

@@ -16,14 +16,14 @@
 #
 # Exit codes:
 #   0  the record was written (whether or not it is clean)
-#   2  usage, or no .goblin/goblin.yaml to read `security.audit_cmd` from
+#   2  usage, or no AGENTS.md frontmatter to read `security.audit_cmd` from
 #   3  the class declares no audit command (security.audit_cmd is empty) - nothing to run
 #   4  the declared command could not run
 #   5  the output could not be parsed as an audit report - REFUSING to write an empty record,
 #      because an empty record reads to SC-07 as "clean" and that would be a fabricated pass
 set -uo pipefail
 
-GOBLIN_AUDIT_VERSION="0.5.0"
+GOBLIN_AUDIT_VERSION="0.6.0-alpha.1"
 
 usage() { sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
 
@@ -40,22 +40,20 @@ done
 [ -n "$TARGET" ] || { printf 'goblin-audit: --target needs a directory\n' >&2; exit 2; }
 cd "$TARGET" || { printf 'goblin-audit: no such directory: %s\n' "$TARGET" >&2; exit 2; }
 
-CONFIG=".goblin/goblin.yaml"
-[ -f "$CONFIG" ] || { printf 'goblin-audit: %s has no %s - run goblin-install first\n' "$TARGET" "$CONFIG" >&2; exit 2; }
+CONFIG="AGENTS.md"
+[ -f "$CONFIG" ] && grep -q "^$GOB_AGENTS_BEGIN" "$CONFIG" 2>/dev/null \
+  || { printf 'goblin-audit: %s has no %s gob block - run gob init first\n' "$TARGET" "$CONFIG" >&2; exit 2; }
 
 # Self-contained on purpose: the audit runner must work even if goblin-lib.sh was edited or is
 # missing, because it is the one tool a human runs by hand.
-g_yaml_block_scalar() { # <file> <block> <key>
-  awk -v b="$2" -v k="$3" '
-    $0 ~ ("^" b ":[[:space:]]*$") { inb = 1; next }
-    inb && /^[^ ]/ { inb = 0 }
-    inb && $0 ~ ("^  " k ":") {
-      v = $0; sub("^  " k ":[[:space:]]*", "", v); print v; exit
-    }
-  ' "$1"
+g_agents_read_inline() { # <file> <dotted-key> — the one reader the audit needs, inline
+  local f="$1" k="$2" line
+  while IFS= read -r line; do
+    case "$line" in "$k:"*) printf '%s\n' "${line#"$k":}"; return 0 ;; esac
+  done < "$f"
 }
 
-AUDIT_CMD=$(g_yaml_block_scalar "$CONFIG" security audit_cmd)
+AUDIT_CMD=$(g_agents_read_inline "$CONFIG" security.audit_cmd)
 if [ -z "$AUDIT_CMD" ]; then
   printf 'goblin-audit: this class declares no audit command (security.audit_cmd is empty in\n'
   printf '  %s). Nothing to run, and no record to write.\n' "$CONFIG"

package/bin/goblin-bans

@@ -28,7 +28,7 @@
 
 set -uo pipefail
 
-GOBLIN_BANS_VERSION="0.5.0"
+GOBLIN_BANS_VERSION="0.6.0-alpha.1"
 SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 # shellcheck source=goblin-lib.sh
 . "$SELF_DIR/goblin-lib.sh"
@@ -49,7 +49,7 @@ done
 find_installed_root() {
   local d="$PWD"
   while :; do
-    if [ -f "$d/.goblin/goblin.yaml" ]; then printf '%s\n' "$d"; return 0; fi
+    if [ -f "$d/AGENTS.md" ] && grep -q "^$GOB_AGENTS_BEGIN" "$d/AGENTS.md" 2>/dev/null; then printf '%s\n' "$d"; return 0; fi
     [ "$d" = "/" ] && return 1
     d=$(dirname "$d")
   done
@@ -60,9 +60,9 @@ if [ -z "$ROOT" ]; then
   [ -n "$ROOT" ] || ROOT="$PWD"
 fi
 
-CONFIG="$ROOT/.goblin/goblin.yaml"
-if [ -f "$ROOT/.goblin/manifest/bans.tsv" ]; then
-  BANS="$ROOT/.goblin/manifest/bans.tsv"
+CONFIG="$ROOT/AGENTS.md"
+if [ -f "$ROOT/.gob/manifest/bans.tsv" ]; then
+  BANS="$ROOT/.gob/manifest/bans.tsv"
 else
   BANS="$SELF_DIR/../manifest/bans.tsv"
 fi
@@ -85,13 +85,11 @@ fi
 # ---- the config: which bans this project turns on, and its narrow exceptions --
 ENABLED=""
 if [ -f "$CONFIG" ]; then
-  ENABLED=$(g_yaml_scalar "$CONFIG" bans)
-  ENABLED=${ENABLED#[}; ENABLED=${ENABLED%]}
-  ENABLED=$(printf '%s' "$ENABLED" | tr ',' ' ' | tr -s ' ' ' ')
+  ENABLED=$(g_agents_list "$CONFIG" bans | tr '\n' ' ')
   # The electron opt-in (software class): `electron: true` turns the electron ban set ON even
   # when a hand-edited bans: list omits it — the declaration is the contract, and the engine
   # (not the LLM) is what makes a listed ban non-skippable. A repo without the key is unaffected.
-  if [ "$(g_yaml_scalar "$CONFIG" electron)" = "true" ]; then
+  if [ "$(g_agents_read "$CONFIG" electron)" = "true" ]; then
     for e in BN-06 BN-07 BN-08 BN-09; do
       case " $ENABLED " in *" $e "*) ;; *) ENABLED="$ENABLED $e" ;; esac
     done
@@ -113,7 +111,9 @@ enabled() {
 # keeps the old behaviour, which fails CLOSED, never open.
 exempt_paths() { # exempt_paths <id> -> path prefixes, one per line
   [ -f "$CONFIG" ] || return 0
-  g_yaml_list "$CONFIG" bans_exempt | awk -v id="$1" '$1==id {print $2}'
+  # v2 shape: one flat `[BN-01 src, BN-02 app]` array — item 1 is the ban id, item 2 its
+  # path prefix (g_agents_list splits on the commas, so an item keeps its inner space).
+  g_agents_list "$CONFIG" bans_exempt | awk -v id="$1" '$1==id {print $2}'
 }
 
 only_selected() {
@@ -131,7 +131,7 @@ while IFS=$'\t' read -r id ban globs detect replacement escape reviewer source;
   SEL=$((SEL + 1))
 
   if ! enabled "$id"; then
-    SKIP=$((SKIP + 1)); g_skip "$id" "$ban (not enabled in bans: - add $id to .goblin/goblin.yaml to turn it on)"
+    SKIP=$((SKIP + 1)); g_skip "$id" "$ban (not enabled in bans: - add $id to the bans: array in AGENTS.md to turn it on)"
     continue
   fi
   # A ban whose globs match no file is a SKIP with a reason, not a pass and not a fail.

package/bin/goblin-extras

@@ -0,0 +1,342 @@
+#!/usr/bin/env bash
+# goblin-extras — `gob extras`: the curated catalogue browser + installer (v2 W-extras).
+#
+#   gob extras list [category]                 the catalogue, grouped by category
+#   gob extras show <id>                       one row, every field, + the install hint
+#   gob extras install <id...> [--target <dir>] [--platform <id>]
+#                    [--with-mcp-config] [--dry-run]
+#
+# The ALLOWLIST RULE (non-negotiable): only ids that exist in catalogue.tsv are ever
+# installed. An id the catalogue does not carry is refused by name — there is no path from
+# a URL or a repo name on this command to a file write. `gob init` SUGGESTS rows and never
+# auto-installs; a human (or the proposal the human approves) names ids explicitly, and
+# the curator maintains the catalogue (add a row = PR or edit catalogue.tsv).
+#
+# Verdicts: RECOMMEND rows install; MAYBE rows install (an explicit choice, never
+# pre-ticked at init); SKIP rows refuse — the curator's verdict is the contract.
+#
+# NO NETWORK. Skill and workflow installs copy from a VENDORED PAYLOAD the curator
+# maintains under extras-catalogue/payload/<id>/ (payload/README.md is the layout
+# contract); a row whose payload is absent is refused with the named fix, never
+# downloaded. MCP installs are a printed mcp.json snippet plus — with
+# --with-mcp-config — a merge into the target's .mcp.json that never overwrites an
+# existing server entry (the ask-once rule .mcp.json has always had).
+#
+# Skill destinations follow the sync_platforms pattern: --platform <adapter-id> copies
+# each vendored skill dir under that adapter's project skills root (read from
+# adapters/<id>/adapter.tsv, column skills_path_project); with no --platform the skill
+# lands in the repo-neutral .gob/extras/<skill-name>/ (standalone repos). Workflows copy
+# the payload into .gob/playbooks/<id>/.
+#
+# Exit codes: 0 ok | 1 a refusal (named path + fix) | 2 bad input.
+# No npm, no jq, no yq, no network. bash/awk/sed/grep only (python3 only for the
+# .mcp.json merge, where a hand-rolled JSON edit would corrupt files it must not).
+
+set -uo pipefail
+
+SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+SRC=$(cd "$SELF_DIR/.." && pwd)
+# shellcheck source=goblin-lib.sh
+. "$SELF_DIR/goblin-lib.sh"
+
+g_info() { printf '%s\n' "$*"; }
+
+usage() { sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+
+# ---- the catalogue source (overridable for tests) ------------------------------
+# The default is the shipped catalogue; GOB_EXTRAS_CATALOGUE points a test at a fixture.
+# Same for the payload root: a test vendors a fixture payload and aims the installer at it.
+CATALOGUE="${GOB_EXTRAS_CATALOGUE:-$SRC/extras-catalogue/catalogue.tsv}"
+PAYLOAD="${GOB_EXTRAS_PAYLOAD:-$SRC/extras-catalogue/payload}"
+
+die() { g_err "extras: $*"; exit "${2:-2}"; }
+
+# catalogue_row <id> — the whole data row (tab-separated), empty when absent.
+catalogue_row() {
+  awk -F'\t' -v id="$1" 'NR>1 && $1==id { print; exit }' "$CATALOGUE"
+}
+
+# catalogue_field <row> <n> — the nth tab field of a row.
+catalogue_field() { printf '%s' "$1" | awk -F'\t' -v n="$2" '{ print $n }'; }
+
+# catalogue_ids — every id, file order.
+catalogue_ids() { awk -F'\t' 'NR>1 && $1!="" { print $1 }' "$CATALOGUE"; }
+
+# category_order — the categories in catalogue file order of first appearance.
+category_order() { awk -F'\t' 'NR>1 && !seen[$2]++ { print $2 }' "$CATALOGUE"; }
+
+# ---- adapters (the platform enum is data, never literals) ----------------------
+# MD-01: agent-family names are read from adapters/<id>/adapter.tsv at run time, never
+# written here — the same discipline the sync engine's assembled platform list keeps.
+adapter_ids() {
+  for t in "$SRC"/adapters/*/adapter.tsv; do
+    [ -f "$t" ] || continue
+    awk -F'\t' '!/^#/ && NF>1 && $1!="id" { print $1 }' "$t"
+  done
+}
+
+# adapter_skills_root <id> — the PROJECT skills root (the pattern with its
+# `<name>/SKILL.md` tail stripped), one dot-dir per agent family. Read at run time;
+# the family names live in the adapter tables, never here (the MD-01 discipline).
+adapter_skills_root() {
+  local t="$SRC/adapters/$1/adapter.tsv" pat
+  [ -f "$t" ] || return 0
+  pat=$(awk -F'\t' '!/^#/ && NF>1 && $1!="id" { print $4 }' "$t")
+  [ -n "$pat" ] || return 0
+  printf '%s\n' "${pat%%<name>*}"
+}
+
+# ---- list ----------------------------------------------------------------------
+cmd_list() {
+  local want="${1:-}"
+  [ -f "$CATALOGUE" ] || die "catalogue not found: $CATALOGUE" 2
+  if [ -n "$want" ]; then
+    # An unknown category is bad input, not an empty table: a typo must not read as
+    # "the catalogue has nothing here". Captured, not piped: under pipefail a `grep -q`
+    # match closes the pipe early and SIGPIPE-kills the producer (pipeline 141), which
+    # would read as "unknown category" for a category the catalogue carries.
+    CATS=$(category_order)
+    printf '%s\n' "$CATS" | grep -qx "$want" || die "unknown category '$want' (want one of: $(printf '%s' "$CATS" | tr '\n' ' '))" 2
+  fi
+  local total
+  total=$(catalogue_ids | wc -l | tr -d ' ')
+  g_info "gob extras — the curated catalogue ($total rows; RECOMMEND pre-ticks at init, MAYBE is visible but never pre-ticked, SKIP refuses install)"
+  g_info "install: gob extras install <id...>   ·   one row: gob extras show <id>"
+  local cat
+  for cat in $(category_order); do
+    [ -z "$want" ] || [ "$cat" = "$want" ] || continue
+    printf '\n[%s]\n' "$cat"
+    printf '  %-34s %-8s %-7s %-24s %-10s %s\n' "id" "kind" "stars" "license" "verdict" "matches"
+    awk -F'\t' -v cat="$cat" 'NR>1 && $2==cat {
+      printf "  %-34s %-8s %-7s %-24s %-10s %s\n", $1, $3, $9, $8, $15, $11
+    }' "$CATALOGUE"
+  done
+  return 0
+}
+
+# ---- show ----------------------------------------------------------------------
+cmd_show() {
+  local id="${1:-}"
+  [ -n "$id" ] || die "show: an id is required (gob extras list)" 2
+  [ -f "$CATALOGUE" ] || die "catalogue not found: $CATALOGUE" 2
+  local row
+  row=$(catalogue_row "$id")
+  [ -n "$row" ] || die "unknown id '$id' — gob extras list names the catalogue" 2
+  local labels=(id category kind name source_repo path_within_repo has_skill_md license
+                stars last_push matches conflicts requires install_hint verdict
+                reviewed_by reviewed_date)
+  local i
+  for i in $(seq 1 17); do
+    printf '%-16s %s\n' "${labels[$((i-1))]}:" "$(catalogue_field "$row" "$i")"
+  done
+  return 0
+}
+
+# ---- install -------------------------------------------------------------------
+TARGET="" PLATFORM="" WITH_MCP=0 DRYRUN=0 IDS=()
+parse_install() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --target)          TARGET="${2:-}"; shift 2 ;;
+      --platform)        PLATFORM="${2:-}"; shift 2 ;;
+      --with-mcp-config) WITH_MCP=1; shift ;;
+      --dry-run)         DRYRUN=1; shift ;;
+      --yes)             shift ;;   # accepted for pipe parity; install is already explicit
+      -h|--help)         usage; exit 0 ;;
+      -*)                die "install: unknown option: $1" 2 ;;
+      *)                 IDS+=("$1"); shift ;;
+    esac
+  done
+  [ "${#IDS[@]}" -gt 0 ] || die "install: at least one id is required (gob extras list)" 2
+  [ -f "$CATALOGUE" ] || die "catalogue not found: $CATALOGUE" 2
+  TARGET="${TARGET:-$PWD}"
+  TARGET=$(g_expand_tilde "$TARGET")
+  [ -d "$TARGET" ] || die "--target is not a directory: $TARGET" 2
+  TARGET=$(cd "$TARGET" && pwd)
+  if [ -n "$PLATFORM" ]; then
+    # Captured, not piped (see cmd_list: pipefail + grep -q closes the pipe early and
+    # SIGPIPE-kills the producer — a valid platform id read as unknown).
+    ADAPTERS=$(adapter_ids)
+    printf '%s\n' "$ADAPTERS" | grep -qx "$PLATFORM" \
+      || die "unknown --platform '$PLATFORM' (the adapters this checkout ships: $(printf '%s' "$ADAPTERS" | tr '\n' ' '))" 2
+  fi
+}
+
+# resolve_one <id> — validates against the ALLOWLIST and the curator's verdicts; prints
+# the row. Every install path goes through here: no row, no install. That is the whole
+# allowlist rule, in one gate.
+resolve_one() {
+  local id="$1" row verdict
+  row=$(catalogue_row "$id")
+  # Captured, not piped (pipefail + grep -q early-exit trap — see cmd_list).
+  if [ -n "$row" ]; then
+    verdict=$(catalogue_field "$row" 15)
+  else
+    die "unknown id '$id' — nothing outside catalogue.tsv is ever installed (gob extras list names the allowlist)" 2
+  fi
+  case "$verdict" in
+    RECOMMEND|MAYBE) ;;
+    SKIP) die "id '$id' carries verdict SKIP — the curator declined it; it stays visible in the catalogue but refuses install" 1 ;;
+    *) die "id '$id' carries verdict '$verdict' — not an installable verdict (RECOMMEND|MAYBE|SKIP)" 2 ;;
+  esac
+  printf '%s\n' "$row"
+}
+
+# copy_tree <src> <dst> — byte-copy with the installer's ownership gate: an existing
+# file is left alone when identical (unchanged) and REFUSED when it differs (a file the
+# project wrote is never clobbered silently). Returns 0 ok, 1 on a refusal (named).
+COPY_REFUSALS=0
+copy_tree() {
+  local src="${1%/}" dst="$2" f rel sd dd
+  [ -d "$src" ] || die "payload missing: $src" 2
+  while IFS= read -r f; do
+    rel="${f#"$src"/}"
+    dd="$dst/$rel"
+    if [ "$DRYRUN" -eq 1 ]; then
+      g_info "plan: ${dd#"$TARGET"/}"
+      continue
+    fi
+    mkdir -p "$(dirname "$dd")" || die "cannot create $(dirname "$dd")" 1
+    if [ -f "$dd" ]; then
+      if [ "$(g_sha256_file "$dd")" = "$(g_sha256_file "$f")" ]; then
+        g_info "unchanged ${dd#"$TARGET"/}"
+      else
+        g_err "refusing to overwrite ${dd#"$TARGET"/}: it exists with different content and goblin-stack did not install it — remove or rename it first"
+        COPY_REFUSALS=$((COPY_REFUSALS + 1))
+      fi
+      continue
+    fi
+    cp "$f" "$dd" || die "cannot write $dd" 1
+    g_info "wrote ${dd#"$TARGET"/}"
+  done < <(find "$src" -type f | sort)
+  return 0
+}
+
+# install_skill <row> — copy the payload's skill dirs into the platform skills root
+# (per sync_platforms) or .gob/extras/ (standalone).
+install_skill() {
+  local row="$1" id name src_root dst_root d n=0
+  id=$(catalogue_field "$row" 1)
+  src_root="$PAYLOAD/$id"
+  [ -d "$src_root" ] \
+    || die "no vendored payload for '$id' at $src_root — extras install needs no network: vendor the accepted skill dirs there first (see extras-catalogue/payload/README.md)" 2
+  if [ -n "$PLATFORM" ]; then
+    dst_root="$TARGET/$(adapter_skills_root "$PLATFORM")"
+    dst_root="${dst_root%/}/"
+  else
+    dst_root="$TARGET/.gob/extras"
+  fi
+  [ -n "$(adapter_skills_root "$PLATFORM")" ] || [ -z "$PLATFORM" ] \
+    || die "adapter '$PLATFORM' carries no project skills path" 2
+  for d in "$src_root"/*/; do
+    [ -d "$d" ] || continue
+    name=$(basename "$d")
+    n=$((n + 1))
+    g_info "extras: skill $name -> ${dst_root#"$TARGET"/}$name/"
+    copy_tree "$d" "$dst_root/$name"
+  done
+  [ "$n" -gt 0 ] || die "payload for '$id' holds no skill dirs ($src_root/*/ with SKILL.md each) — see extras-catalogue/payload/README.md" 2
+  return 0
+}
+
+# install_workflow <row> — copy the payload into .gob/playbooks/<id>/.
+install_workflow() {
+  local row="$1" id src dst
+  id=$(catalogue_field "$row" 1)
+  src="$PAYLOAD/$id"
+  [ -d "$src" ] \
+    || die "no vendored payload for '$id' at $src — vendor the playbook files there first (see extras-catalogue/payload/README.md)" 2
+  dst="$TARGET/.gob/playbooks/$id"
+  g_info "extras: workflow $id -> ${dst#"$TARGET"/}/"
+  copy_tree "$src" "$dst"
+  return 0
+}
+
+# install_mcp <row> — print the mcp.json snippet; --with-mcp-config merges it into
+# the target's .mcp.json. The merge NEVER overwrites: an existing entry for the same
+# server name must match the generated bytes (no-op) or the merge refuses (ask-once).
+install_mcp() {
+  local row="$1" id hint cmd rest first_arg
+  id=$(catalogue_field "$row" 1)
+  hint=$(catalogue_field "$row" 14)
+  case "$hint" in
+    npx\ *|npm\ exec\ *)
+      read -r cmd rest <<< "$hint"
+      first_arg="$rest" ;;
+    *)
+      if [ "$WITH_MCP" -eq 1 ]; then
+        die "id '$id' carries install_hint '$hint' — only an 'npx <package>' hint can be merged into .mcp.json; follow the row's own hint by hand" 1
+      fi
+      g_info "extras: mcp $id — install per the row's own hint: $hint (no .mcp.json snippet is generated for it)"
+      return 0 ;;
+  esac
+  local snippet
+  snippet=$(python3 -c 'import json,sys; print(json.dumps({"mcpServers": {sys.argv[1]: {"command": sys.argv[2], "args": sys.argv[3].split()}}}, separators=(",",":")))' "$id" "$cmd" "$first_arg")
+  g_info "extras: mcp $id — mcp.json snippet:"
+  g_info "  $snippet"
+  [ "$WITH_MCP" -eq 1 ] || return 0
+  [ "$DRYRUN" -eq 0 ] || { g_info "plan: merge $id into ${TARGET#.}/.mcp.json"; return 0; }
+  MERGE_OUT=$(MCP_ID="$id" MCP_SNIPPET="$snippet" python3 - "$TARGET/.mcp.json" <<'PYEOF'
+import json, os, sys
+path = sys.argv[1]
+mcp_id = os.environ["MCP_ID"]
+snippet = json.loads(os.environ["MCP_SNIPPET"])
+server = snippet["mcpServers"][mcp_id]
+data = {}
+if os.path.exists(path):
+    raw = open(path).read().strip()
+    if raw:
+        try:
+            data = json.loads(raw)
+        except ValueError:
+            sys.stderr.write("extras: refusing %s: it is not valid JSON - edit it by hand\n" % path)
+            sys.exit(1)
+servers = data.setdefault("mcpServers", {})
+if mcp_id in servers:
+    if servers[mcp_id] == server:
+        print("extras: unchanged %s (already carries the %s registration)" % (path, mcp_id))
+        sys.exit(0)
+    sys.stderr.write("extras: refusing to overwrite the existing %s entry in %s - an mcp registration you customized is the project's (ask-once)\n" % (mcp_id, path))
+    sys.exit(1)
+servers[mcp_id] = server
+with open(path, "w") as fh:
+    json.dump(data, fh, separators=(",", ":"))
+    fh.write("\n")
+print("extras: merged %s into %s" % (mcp_id, path))
+PYEOF
+  )
+  local rc=$?
+  [ -n "$MERGE_OUT" ] && printf '%s\n' "$MERGE_OUT"
+  [ "$rc" -eq 0 ] || exit 1
+  return 0
+}
+
+cmd_install() {
+  parse_install "$@"
+  [ "$DRYRUN" -eq 0 ] || g_info "extras: --dry-run (nothing is written)"
+  local id row
+  for id in "${IDS[@]}"; do
+    row=$(resolve_one "$id") || exit $?
+    case "$(catalogue_field "$row" 3)" in
+      skill)    install_skill "$row" ;;
+      workflow) install_workflow "$row" ;;
+      mcp)      install_mcp "$row" ;;
+      *)        die "row '$id' carries unknown kind '$(catalogue_field "$row" 3)' (want skill|mcp|workflow)" 2 ;;
+    esac
+  done
+  [ "$COPY_REFUSALS" -eq 0 ] || die "$COPY_REFUSALS file(s) refused (named above) — nothing overwritten" 1
+  return 0
+}
+
+# ---- dispatch ------------------------------------------------------------------
+CMD="${1:-}"
+[ -n "$CMD" ] || { usage; exit 2; }
+shift
+case "$CMD" in
+  list)    cmd_list "$@" ;;
+  show)    cmd_show "$@" ;;
+  install) cmd_install "$@" ;;
+  -h|--help|help) usage; exit 0 ;;
+  *) g_err "extras: unknown subcommand: $CMD"; usage >&2; exit 2 ;;
+esac
+exit 0