feed-the-machine 1.7.1 → 1.7.2

package/README.md

@@ -24,11 +24,23 @@ Think of it like this: regular AI is a blank whiteboard every time you walk into
 
 ## Install
 
+**Everything** (26 skills + 15 hooks):
 ```bash
 npx feed-the-machine@latest
 ```
 
-That's it. Takes 30 seconds. Works with any existing Claude Code setup.
+**Just the skills you want:**
+```bash
+npx feed-the-machine --only ftm-council-chat,ftm-mind
+```
+This always includes `ftm` (the router) and `ftm-config` as base dependencies.
+
+**See what's available:**
+```bash
+npx feed-the-machine --list
+```
+
+Works with any existing Claude Code setup. After install, restart Claude Code or start a new session.
 
 ---
 
@@ -64,6 +76,8 @@ Not sure about an architecture choice or debugging approach? This sends the prob
 ```
 An AIM-styled browser chatroom where you, Claude, Codex, and Gemini all talk in real time. You're a full participant, not just watching.
 
+<img src="docs/images/council-chat.png" alt="ftm-council-chat screenshot — AIM-styled chatroom with Claude, Codex, and Gemini debating Jira token types" width="800" />
+
 ---
 
 ## Before / After
@@ -165,18 +179,28 @@ FTM ships with 26 skills and 15 automation hooks. You don't need to memorize the
 | **ftm-pause / resume** | Save and restore. Pick up exactly where you left off in a new conversation |
 | **ftm-upgrade** | Self-update. Stay current with one command |
 
-### Hooks (15 automations)
+### Hooks (16 automations)
 
 These run automatically in the background — no slash commands needed:
 
-- **Auto-logging** — every tool call gets logged to events.log
-- **Learning capture** — extracts lessons from completed tasks
-- **Session snapshots** — saves state for crash recovery
-- **Secret scanning** — blocks commits containing credentials
-- **Task loading** — hydrates tasks from plans on session start
-- **Plan gates** — enforces plan approval before execution
-- **Compaction handlers** — preserves critical state when context compresses
-- And 8 more for blackboard enforcement, map auto-detection, drafts gating, etc.
+| Hook | What It Does |
+|------|-------------|
+| **event-logger** | Logs every tool use to a JSONL file with debouncing and 30-day rotation |
+| **auto-log** | Detects when you report completing work and reminds Claude to log progress |
+| **learning-capture** | Captures edits and task completions into a learning database for pattern recognition |
+| **session-snapshot** | Saves the last 15 exchanges as a markdown snapshot when a session ends — crash recovery |
+| **session-end** | Marks the current session as completed in the blackboard |
+| **blackboard-enforcer** | Nudges Claude to record meaningful work to the blackboard before a session ends undocumented |
+| **plan-gate** | Prevents code edits without a plan — soft-warns at first, blocks after 3+ edits |
+| **task-loader** | Loads active tasks from your task database when a session starts |
+| **pre-compaction** | Monitors token usage and flushes state to disk before context hits 75% capacity |
+| **post-compaction** | After context compresses, reloads critical state from disk before responding |
+| **map-autodetect** | Detects unmapped projects on first use and bootstraps the code knowledge graph |
+| **post-commit-trigger** | After git commits, triggers code map sync and documentation updates |
+| **pending-sync-check** | Surfaces out-of-session commits that need code map syncing |
+| **discovery-reminder** | Reminds Claude to run a discovery interview for tasks involving external systems or migrations |
+| **drafts-gate** | Blocks Slack and Gmail sends unless a draft file exists first — no accidental messages |
+| **install-hooks** | Self-installer that registers all hooks into Claude Code's settings.json |
 
 ---
 
@@ -236,7 +260,9 @@ Everything else runs on Claude Code alone.
 
 ```bash
 git clone https://github.com/kkudumu/feed-the-machine.git ~/feed-the-machine
-cd ~/feed-the-machine && ./install.sh
+cd ~/feed-the-machine && ./install.sh                          # everything
+# or: ./install.sh --only ftm-council-chat                     # just one skill
+# or: ./install.sh --list                                      # see what's available
 ```
 
 **Uninstall:** `./uninstall.sh` (removes skills, keeps your memory data)

package/bin/install.mjs

@@ -7,9 +7,12 @@
  * Safe to re-run — idempotent.
  *
  * Flags:
- *   --with-inbox    Also install the inbox service
- *   --no-hooks      Skip hooks entirely
- *   --skip-merge    Install hook files but don't touch settings.json
+ *   --only skill1,skill2  Install specific skills (always includes ftm + ftm-config)
+ *   --list                List available skills with descriptions
+ *   --with-inbox          Also install the inbox service
+ *   --no-hooks            Skip hooks entirely
+ *   --with-hooks          Include hooks even with --only
+ *   --skip-merge          Install hook files but don't touch settings.json
  */
 
 import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, cpSync } from "fs";
@@ -31,8 +34,25 @@ const INBOX_INSTALL_DIR = join(HOME, ".claude", "ftm-inbox");
 
 const ARGS = process.argv.slice(2);
 const WITH_INBOX = ARGS.includes("--with-inbox");
-const NO_HOOKS = ARGS.includes("--no-hooks");
 const SKIP_MERGE = ARGS.includes("--skip-merge");
+const LIST_MODE = ARGS.includes("--list");
+const WITH_HOOKS_FLAG = ARGS.includes("--with-hooks");
+
+// Parse --only (supports --only=x,y and --only x,y)
+const ONLY_RAW = ARGS.find(a => a.startsWith("--only="))?.split("=")[1]
+  || (ARGS.includes("--only") ? ARGS[ARGS.indexOf("--only") + 1] : null);
+
+const ONLY_SKILLS = ONLY_RAW
+  ? new Set(["ftm", "ftm-config", ...ONLY_RAW.split(",").map(s => s.trim())])
+  : null;
+
+// When --only is used, skip hooks unless --with-hooks or explicit --no-hooks
+const NO_HOOKS = ARGS.includes("--no-hooks") || (ONLY_SKILLS && !WITH_HOOKS_FLAG);
+
+function skillWanted(name) {
+  if (!ONLY_SKILLS) return true;
+  return ONLY_SKILLS.has(name);
+}
 
 let warnCount = 0;
 
@@ -268,29 +288,58 @@ function verify(skillCount, hookCount) {
   return { errors };
 }
 
+// --- List Mode ---
+
+function listSkills() {
+  console.log("\nAvailable FTM skills:\n");
+  const ymlFiles = readdirSync(REPO_DIR).filter(
+    (f) => f.startsWith("ftm-") && f.endsWith(".yml") && !f.includes("config.default")
+  );
+  for (const yml of ymlFiles) {
+    const name = yml.replace(".yml", "");
+    const content = readFileSync(join(REPO_DIR, yml), "utf8");
+    const descMatch = content.match(/^description:\s*(.+)/m);
+    const desc = descMatch ? descMatch[1].slice(0, 80) : "";
+    console.log(`  ${name.padEnd(22)} ${desc}`);
+  }
+  console.log("\nInstall specific skills: npx feed-the-machine --only ftm-council-chat,ftm-mind");
+  console.log("Install everything:      npx feed-the-machine\n");
+  process.exit(0);
+}
+
 // --- Main ---
 
 function main() {
+  if (LIST_MODE) {
+    listSkills();
+  }
+
   preflight();
 
-  console.log(`Installing ftm skills from: ${REPO_DIR}`);
+  if (ONLY_SKILLS) {
+    const requested = [...ONLY_SKILLS].filter(s => s !== "ftm" && s !== "ftm-config").join(", ");
+    console.log(`Installing selected FTM skills: ${requested} (+ ftm, ftm-config)`);
+  } else {
+    console.log(`Installing all FTM skills from: ${REPO_DIR}`);
+  }
   console.log(`Linking into: ${SKILLS_DIR}`);
   console.log("");
 
   ensureDir(SKILLS_DIR);
 
-  // Link all ftm*.yml files
+  // Link ftm*.yml files (filtered by --only if set)
   const ymlFiles = readdirSync(REPO_DIR).filter(
     (f) => f.startsWith("ftm") && f.endsWith(".yml") && !f.includes("config.default")
-  );
+  ).filter((f) => skillWanted(f.replace(".yml", "")));
   for (const yml of ymlFiles) {
     safeSymlink(join(REPO_DIR, yml), join(SKILLS_DIR, yml));
   }
 
-  // Link all ftm* directories (skills with SKILL.md)
+  // Link ftm* directories (filtered by --only if set)
   const dirs = readdirSync(REPO_DIR).filter((f) => {
     if (!f.startsWith("ftm")) return false;
     if (f === "ftm-state") return false;
+    if (!skillWanted(f)) return false;
     const fullPath = join(REPO_DIR, f);
     try {
       return lstatSync(fullPath).isDirectory();

package/ftm-mind/references/blackboard-protocol.md

@@ -108,3 +108,22 @@ If `experiences/index.json` has no usable matches:
 - continue normally
 - lean harder on current repo state and direct inspection
 - record the resulting experience aggressively after completion
+
+## Recording Code Patterns and API Gotchas
+
+When writing an experience after task completion, actively check for these:
+
+**code_patterns** — If during the task you wrote code that interacts with an API, library, or module, save the **final working version** (not the failed attempts). Include imports, setup, and the actual call. This is the copy-pasteable snippet future sessions will use.
+
+**api_gotchas** — If you hit errors because an API behaved differently than expected (wrong return type, unexpected method name, None instead of Response, objects instead of dicts), record each one. Format: what the module is, what's surprising, and what you'd wrongly assume.
+
+**playbook_ref** — If a brain.py playbook was created (via ftm-capture or auto-playbook trigger), record the path so the experience and playbook cross-reference each other.
+
+**When to populate these fields:**
+- You hit 2+ errors on the same module before getting it right → record code_patterns + api_gotchas
+- You used an API/library for the first time in this project → record code_patterns
+- The auto-playbook hook fired → record all three fields
+
+**When to skip:**
+- Pure file editing, config changes, or git operations — no API interaction worth capturing
+- The code pattern is already in an existing experience (check by module name before duplicating)

package/ftm-mind/references/decide-act-protocol.md

@@ -37,11 +37,7 @@ Going ahead unless you say otherwise.
 
 **Step 0: Discovery Interview (if applicable).** Before generating the plan, check whether a Discovery Interview is needed (see Orient reference). If the task involves external systems, stakeholder coordination, or unfamiliar code, run the interview FIRST.
 
-**Step 1: Generate the plan.** Build a numbered list of concrete steps. Each step has:
-- A number
-- A one-line description
-- The files that will be touched
-- The verification method
+**Step 1: Generate the plan.** Build a numbered checkbox list. This format is **mandatory** — no narrative steps, no prose paragraphs. Every plan MUST use: `N. [ ] One-line action → target`. See `references/protocols/PLAN-APPROVAL.md` for the full format spec, examples for code/ops/comms/infra tasks, and the list of NEVER-produce anti-patterns.
 
 **Step 2: Parse the user's response.**
 

package/ftm-mind/references/protocols/PLAN-APPROVAL.md

@@ -10,11 +10,30 @@ For **medium and large** tasks, present a numbered task list and wait for the us
 
 **Step 1: Generate the plan.**
 
-Build a numbered list of concrete steps based on Orient synthesis. Each step must have:
+Build a numbered checkbox list. This format is **mandatory** — no narrative steps, no prose paragraphs, no bullet-point summaries. Every plan, whether it's code, ops, comms, or infrastructure, MUST use this exact format:
+
+```
+  N. [ ] One-line action → target (file, channel, system, or person)
+```
+
+Each step must have:
 - A number
+- A `[ ]` checkbox (literal characters, not rendered)
 - A one-line description of what will be done
-- The files that will be touched
-- The verification method (test, lint, visual check, or "self-evident")
+- An arrow `→` pointing to the target: file path for code, channel/email for comms, system name for infra, or "self-evident" for simple actions
+- If applicable, a verification method after the target: `verify: test / lint / visual check / confirmation`
+
+**This applies to ALL task types, not just code:**
+- Code tasks: `3. [ ] Add OAuth validation → src/middleware/oauth.ts  verify: npm test`
+- Ops/comms tasks: `1. [ ] Reply to Everett requesting domain mapping → Braintrust support thread`
+- Infra tasks: `2. [ ] Create Freshservice webhook trigger → freshservice admin / workflows`
+- Admin tasks: `4. [ ] Close out ITWORK2-9772 → Jira`
+
+**NEVER produce:**
+- Narrative paragraphs describing steps
+- Numbered steps without `[ ]` checkboxes
+- Steps with sub-bullets explaining details (put that in execution, not the plan)
+- Headers like "Step 1:" or "### Step 1" — use the numbered checkbox format only
 
 Present it like this:
 
@@ -36,6 +55,21 @@ Approve all? Or tell me what to change.
   - "deny" or "stop" → cancel entirely
 ```
 
+**Ops example:**
+
+```
+Here's my plan for the Braintrust post-SSO setup:
+
+  1. [ ] Reply to Everett requesting domain mapping + group mappings → Braintrust support thread
+  2. [ ] Reply to Spencer with admin process answer → #proj-braintrust
+  3. [ ] Request API key from Everett or Spencer → Braintrust org settings
+  4. [ ] Build Freshservice webhook → Braintrust API integration → freshservice workflows + Lambda
+  5. [ ] Reconcile existing users vs Okta groups → Braintrust API + Okta
+  6. [ ] Close out ITWORK2-9772 → Jira
+
+Approve all? Or tell me what to change.
+```
+
 **Step 2: Parse the user's response.**
 
 | User says | Action |

package/ftm-state/schemas/experience.schema.json

@@ -73,6 +73,56 @@
       "items": {
         "type": "string"
       }
+    },
+    "code_patterns": {
+      "type": "array",
+      "description": "Working code snippets discovered during this task — the final correct version, not the failed attempts. Include imports, setup, and the actual call pattern.",
+      "items": {
+        "type": "object",
+        "required": ["module", "code"],
+        "additionalProperties": false,
+        "properties": {
+          "module": {
+            "type": "string",
+            "description": "The primary module/library this pattern uses (e.g. shared_services.okta.groups)"
+          },
+          "code": {
+            "type": "string",
+            "description": "The working code snippet — complete and copy-pasteable"
+          },
+          "description": {
+            "type": "string",
+            "description": "One-line description of what this pattern does"
+          }
+        }
+      }
+    },
+    "api_gotchas": {
+      "type": "array",
+      "description": "Surprising API behaviors, wrong assumptions, and type mismatches discovered during this task. Things that caused errors and would cause them again without this note.",
+      "items": {
+        "type": "object",
+        "required": ["module", "gotcha"],
+        "additionalProperties": false,
+        "properties": {
+          "module": {
+            "type": "string",
+            "description": "The module/API where the gotcha was discovered"
+          },
+          "gotcha": {
+            "type": "string",
+            "description": "What's surprising or wrong — e.g. 'list_members() returns OktaUser objects, not dicts'"
+          },
+          "wrong_assumption": {
+            "type": "string",
+            "description": "What you'd naturally assume that turns out to be wrong"
+          }
+        }
+      }
+    },
+    "playbook_ref": {
+      "type": "string",
+      "description": "Path to the brain.py playbook entry if one was created from this experience, for cross-referencing"
     }
   }
 }

package/hooks/ftm-learning-capture.sh

@@ -100,6 +100,139 @@ except Exception:
   fi
 fi
 
+# --- Auto-Playbook Trigger: detect repeated errors then success on same module ---
+ERROR_TRACKER="$FTM_STATE/.error-tracker.jsonl"
+
+if [ "$TOOL_NAME" = "Bash" ]; then
+  # Extract module/import and error status from the tool result
+  ANALYSIS=$(printf '%s' "$PAYLOAD" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    output = d.get("tool_result", "") or ""
+    tool_input = d.get("tool_input", {})
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    is_error = "Error:" in output or "Traceback" in output or "AttributeError" in output or "TypeError" in output or "ImportError" in output or "ModuleNotFoundError" in output
+    # Extract the primary module from import statements in the command
+    module = ""
+    for line in command.split("\n"):
+        line = line.strip()
+        if line.startswith("from ") and " import " in line:
+            module = line.split("from ")[1].split(" import")[0].strip()
+            break
+        elif line.startswith("import "):
+            module = line.split("import ")[1].split()[0].strip()
+            break
+    import json as j
+    j.dump({"is_error": is_error, "module": module}, sys.stdout)
+except Exception:
+    import json as j
+    j.dump({"is_error": False, "module": ""}, sys.stdout)
+' 2>/dev/null)
+
+  IS_ERROR=$(printf '%s' "$ANALYSIS" | python3 -c 'import json,sys; print("1" if json.load(sys.stdin).get("is_error") else "0")' 2>/dev/null)
+  MODULE=$(printf '%s' "$ANALYSIS" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("module",""))' 2>/dev/null)
+
+  if [ -n "$MODULE" ]; then
+    TIMESTAMP=$(date +%s)
+    if [ "$IS_ERROR" = "1" ]; then
+      # Append error event
+      echo "{\"ts\":$TIMESTAMP,\"module\":\"$MODULE\",\"type\":\"error\"}" >> "$ERROR_TRACKER"
+    else
+      # Success — check if this module had 3+ recent errors
+      if [ -f "$ERROR_TRACKER" ]; then
+        ERROR_COUNT=$(python3 -c "
+import json, sys
+count = 0
+cutoff = $TIMESTAMP - 600  # last 10 minutes
+for line in open('$ERROR_TRACKER'):
+    line = line.strip()
+    if not line: continue
+    try:
+        ev = json.loads(line)
+        if ev.get('module') == '$MODULE' and ev.get('type') == 'error' and ev.get('ts', 0) >= cutoff:
+            count += 1
+    except: pass
+print(count)
+" 2>/dev/null)
+
+        if [ "$ERROR_COUNT" -ge 3 ]; then
+          # Write a blackboard experience with the module and error count
+          SLUG=$(echo "$MODULE" | tr '.' '-' | tr '[:upper:]' '[:lower:]')
+          DATE_STAMP=$(date +%Y-%m-%d)
+          EXP_FILE="$FTM_STATE/blackboard/experiences/${DATE_STAMP}_auto-playbook-${SLUG}.json"
+          python3 -c "
+import json, os, datetime
+exp = {
+    'task_type': 'api-discovery',
+    'task_description': 'Auto-captured: $ERROR_COUNT errors on $MODULE before finding the working pattern',
+    'lessons_learned': [
+        '$MODULE required $ERROR_COUNT attempts to get right — working pattern saved as playbook',
+        'Check experience code_patterns before using this module in future sessions'
+    ],
+    'code_patterns': [],
+    'api_gotchas': [],
+    'playbook_ref': None,
+    'timestamp': datetime.datetime.utcnow().isoformat() + 'Z',
+    'confidence': 0.7,
+    'tags': ['auto-playbook', '$(echo "$MODULE" | tr "." " ")']
+}
+os.makedirs(os.path.dirname('$EXP_FILE'), exist_ok=True)
+with open('$EXP_FILE', 'w') as f:
+    json.dump(exp, f, indent=2)
+
+# Update index
+idx_path = '$FTM_STATE/blackboard/experiences/index.json'
+try:
+    with open(idx_path) as f:
+        idx = json.load(f)
+except:
+    idx = {'entries': [], 'metadata': {'total_count': 0, 'last_updated': None, 'max_entries': 200, 'pruning_strategy': 'remove_oldest_low_confidence'}}
+
+idx['entries'].append({
+    'id': 'auto-playbook-${SLUG}-${DATE_STAMP}',
+    'file': os.path.basename('$EXP_FILE'),
+    'task_type': 'api-discovery',
+    'tags': ['auto-playbook', '$(echo "$MODULE" | tr "." " ")'],
+    'timestamp': exp['timestamp'],
+    'confidence': 0.7
+})
+idx['metadata']['total_count'] = len(idx['entries'])
+idx['metadata']['last_updated'] = exp['timestamp']
+with open(idx_path, 'w') as f:
+    json.dump(idx, f, indent=2)
+" 2>/dev/null
+
+          echo ""
+          echo "[Auto-Playbook] Detected $ERROR_COUNT errors on '$MODULE' followed by a success in this session."
+          echo "A skeleton experience has been saved to the blackboard at: $EXP_FILE"
+          echo "NOW you MUST do two things:"
+          echo "1. Proactively invoke ftm-capture to save the working code pattern as a playbook"
+          echo "2. Update the experience file at $EXP_FILE — fill in the code_patterns array with the working snippet and api_gotchas with every wrong assumption you hit"
+          echo "Tell the user: \"That was rough — I'm saving the working pattern so next time it's one clean shot.\""
+          echo ""
+
+          # Clear tracked errors for this module so we don't re-trigger
+          python3 -c "
+import json
+lines = []
+for line in open('$ERROR_TRACKER'):
+    line = line.strip()
+    if not line: continue
+    try:
+        ev = json.loads(line)
+        if ev.get('module') != '$MODULE':
+            lines.append(line)
+    except: pass
+with open('$ERROR_TRACKER', 'w') as f:
+    f.write('\n'.join(lines) + '\n' if lines else '')
+" 2>/dev/null
+        fi
+      fi
+    fi
+  fi
+fi
+
 # --- Feed Playbook Tracer if active trace exists ---
 ACTIVE_TRACE_FILE="$FTM_STATE/.active-trace-id"
 if [ -f "$ACTIVE_TRACE_FILE" ] && [ -f "$BRAIN_PY" ]; then

package/install.sh

@@ -7,9 +7,13 @@ set -euo pipefail
 # Safe to re-run — idempotent.
 #
 # Usage:
-#   ./install.sh              # Full install (skills + hooks + settings merge)
-#   ./install.sh --no-hooks   # Skills and state only, skip hooks entirely
-#   ./install.sh --skip-merge # Install hook files but don't touch settings.json
+#   ./install.sh                              # Full install (all skills + hooks)
+#   ./install.sh --only ftm-council-chat      # Install specific skill(s)
+#   ./install.sh --only ftm-mind,ftm-debug    # Install multiple specific skills
+#   ./install.sh --list                       # List available skills
+#   ./install.sh --no-hooks                   # Skills only, skip hooks
+#   ./install.sh --only ftm-mind --with-hooks # Specific skills + all hooks
+#   ./install.sh --skip-merge                 # Install hook files but don't touch settings.json
 
 REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
 SKILLS_DIR="$HOME/.claude/skills"
@@ -20,21 +24,85 @@ SETTINGS_FILE="$CONFIG_DIR/settings.json"
 
 NO_HOOKS=false
 SKIP_MERGE=false
-for arg in "$@"; do
+WITH_HOOKS=false
+LIST_MODE=false
+ONLY_SKILLS=""
+
+i=1
+while [ "$i" -le "$#" ]; do
+  arg="${!i}"
   case "$arg" in
     --no-hooks) NO_HOOKS=true ;;
     --skip-merge) SKIP_MERGE=true ;;
+    --with-hooks) WITH_HOOKS=true ;;
+    --list) LIST_MODE=true ;;
+    --only=*) ONLY_SKILLS="${arg#--only=}" ;;
+    --only)
+      i=$((i + 1))
+      ONLY_SKILLS="${!i}"
+      ;;
     # Keep --setup-hooks for backwards compat (now a no-op since merge is default)
     --setup-hooks) ;;
   esac
+  i=$((i + 1))
 done
 
+# When --only is used, skip hooks by default unless --with-hooks
+if [ -n "$ONLY_SKILLS" ] && [ "$WITH_HOOKS" != true ]; then
+  NO_HOOKS=true
+fi
+
 WARN_COUNT=0
 warn() {
   echo "  WARN: $1"
   WARN_COUNT=$((WARN_COUNT + 1))
 }
 
+# --- List Mode ---
+
+if [ "$LIST_MODE" = true ]; then
+  echo ""
+  echo "Available FTM skills:"
+  echo ""
+  for yml in "$REPO_DIR"/ftm-*.yml; do
+    [ -f "$yml" ] || continue
+    name=$(basename "$yml" .yml)
+    [[ "$name" == *".default"* ]] && continue
+    desc=$(grep '^description:' "$yml" | head -1 | sed 's/^description: *//' | cut -c1-80)
+    printf "  %-22s %s\n" "$name" "$desc"
+  done
+  echo ""
+  echo "Install specific skills: ./install.sh --only ftm-council-chat,ftm-mind"
+  echo "Install everything:      ./install.sh"
+  exit 0
+fi
+
+# --- Skill Filter ---
+
+declare -a SKILL_FILTER=()
+if [ -n "$ONLY_SKILLS" ]; then
+  # Always include base dependencies
+  SKILL_FILTER+=("ftm" "ftm-config")
+  IFS=',' read -ra REQUESTED <<< "$ONLY_SKILLS"
+  for s in "${REQUESTED[@]}"; do
+    s=$(echo "$s" | xargs) # trim whitespace
+    SKILL_FILTER+=("$s")
+  done
+fi
+
+skill_wanted() {
+  local name="$1"
+  if [ ${#SKILL_FILTER[@]} -eq 0 ]; then
+    return 0  # no filter = install all
+  fi
+  for wanted in "${SKILL_FILTER[@]}"; do
+    if [ "$name" = "$wanted" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
 # --- Preflight Checks ---
 
 echo "Preflight checks..."
@@ -76,7 +144,11 @@ else
 fi
 
 echo ""
-echo "Installing FTM skills from: $REPO_DIR"
+if [ -n "$ONLY_SKILLS" ]; then
+  echo "Installing selected FTM skills: $ONLY_SKILLS (+ ftm, ftm-config)"
+else
+  echo "Installing all FTM skills from: $REPO_DIR"
+fi
 echo "Linking into: $SKILLS_DIR"
 echo ""
 
@@ -84,12 +156,13 @@ mkdir -p "$SKILLS_DIR"
 
 # --- Skills ---
 
-# Link all ftm*.yml files
+# Link ftm*.yml files (filtered by --only if set)
 for yml in "$REPO_DIR"/ftm*.yml; do
   [ -f "$yml" ] || continue
   name=$(basename "$yml")
   # Skip ftm-config.default.yml — it's a template, not a skill
   [[ "$name" == *".default."* ]] && continue
+  skill_wanted "${name%.yml}" || continue
   target="$SKILLS_DIR/$name"
   if [ -L "$target" ]; then
     rm "$target"
@@ -101,11 +174,12 @@ for yml in "$REPO_DIR"/ftm*.yml; do
   echo "  LINK $name"
 done
 
-# Link all ftm* directories (skills with SKILL.md)
+# Link ftm* directories (filtered by --only if set)
 for dir in "$REPO_DIR"/ftm*/; do
   [ -d "$dir" ] || continue
   name=$(basename "$dir")
   [ "$name" = "ftm-state" ] && continue  # state is handled separately
+  skill_wanted "$name" || continue
   target="$SKILLS_DIR/$name"
   if [ -L "$target" ]; then
     rm "$target"
@@ -121,6 +195,8 @@ SKILL_COUNT=0
 for _f in "$REPO_DIR"/ftm*.yml; do
   [ -e "$_f" ] || continue
   case "$_f" in *.default.*) continue ;; esac
+  _name=$(basename "$_f" .yml)
+  skill_wanted "$_name" || continue
   SKILL_COUNT=$((SKILL_COUNT + 1))
 done
 echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feed-the-machine",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "A brain upgrade for Claude Code — 26 skills that teach it how to think before acting, remember across conversations, debug like a war room, run plans on autopilot with agent teams, and get second opinions from GPT & Gemini. Plus 15 hooks that automate the boring stuff.",
   "license": "MIT",
   "author": "kkudumu",
@@ -26,6 +26,7 @@
     "bin/",
     "hooks/",
     "docs/HOOKS.md",
+    "docs/images/",
     "install.sh",
     "uninstall.sh",
     "ftm.yml",