wizz-method 1.14.0 → 1.16.0

package/src/core-skills/wizz-advanced-elicitation/SKILL.md

@@ -1,142 +1,64 @@
 ---
 name: wizz-advanced-elicitation
-description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.'
+description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team'
 ---
 
 # Advanced Elicitation
 
-**Goal:** Push the LLM to reconsider, refine, and improve its recent output.
+You are Wizz's shared refinement checkpoint: other skills invoke you at natural pauses to pressure the piece of work they just produced, and users call you directly on anything recent. The target is the most recent output in the conversation — a section, plan, draft, or decision — unless the caller or user points at something else. You offer a short menu of elicitation methods, run the chosen ones against the target, and hand back the improved version so the invoking flow resumes exactly where it paused. Work in the surrounding session's communication language.
 
----
-
-## CRITICAL LLM INSTRUCTIONS
+## Conventions
 
-- **MANDATORY:** Execute ALL steps in the flow section IN EXACT ORDER
-- DO NOT skip steps or change the sequence
-- HALT immediately when halt-conditions are met
-- Each action within a step is a REQUIRED action to complete that step
-- Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution
-- **YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the `communication_language`**
-
----
+- Bare paths (e.g. `assets/methods.csv`) resolve from `{skill-root}` (where `customize.toml` lives); `{project-root}`-prefixed paths from the project working directory.
+- `{workflow.<name>}` resolves to fields in the merged `customize.toml` `[workflow]` table.
 
-## INTEGRATION (When Invoked Indirectly)
+## On Activation
 
-When invoked from another prompt or process:
-
-1. Receive or review the current section content that was just generated
-2. Apply elicitation methods iteratively to enhance that specific content
-3. Return the enhanced version back when user selects 'x' to proceed and return back
-4. The enhanced content replaces the original section content in the output document
-
----
+1. Resolve customization: `python3 {project-root}/_wizz/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+2. Hold every `{workflow.preferences}` entry for the whole session, fix the target, and serve the first menu.
 
-## FLOW
+## Serving the Catalog
 
-### Step 1: Method Registry Loading
-
-**Action:** Load `./methods.csv` for elicitation methods. If party-mode may participate, resolve the agent roster via:
+`scripts/pick_methods.py` serves the method catalog (num, category, method_name, description, output_pattern) so it never enters context whole — the one exception is listing the full catalog, when the user asked for all of it. Invoke as:
 
 ```bash
-python3 {project-root}/_wizz/scripts/resolve_config.py --project-root {project-root} --key agents
+python3 {skill-root}/scripts/pick_methods.py --file {workflow.methods_file} <command>
 ```
 
-The resolver merges four layers in order: `_wizz/config.toml` (installer base, team-scoped), `_wizz/config.user.toml` (installer base, user-scoped), `_wizz/custom/config.toml` (team overrides), and `_wizz/custom/config.user.toml` (personal overrides). Each entry under `agents` is keyed by the agent's `code` and carries `name`, `title`, `icon`, `description`, `module`, and `team`.
-
-#### CSV Structure
-
-- **category:** Method grouping (core, structural, risk, etc.)
-- **method_name:** Display name for the method
-- **description:** Rich explanation of what the method does, when to use it, and why it's valuable
-- **output_pattern:** Flexible flow guide using arrows (e.g., "analysis -> insights -> action")
+If `{workflow.additional_methods}` is non-empty, add `--extra '<its entries as a JSON array>'` (or a path to a JSON file holding them) on every call, so custom methods are first-class in menus, reshuffles, and listings.
 
-#### Context Analysis
+- `categories` — category names + counts, the cheap map.
+- `list --category <cat> [--category <cat>]` — the index for chosen categories; `--all` dumps the whole catalog, only when listing all.
+- `show <name-or-num> [...]` — full rows by name or num.
+- `random -n 5 --spread [--exclude <name>]...` — a category-diverse random draw.
 
-- Use conversation history
-- Analyze: content type, complexity, stakeholder needs, risk level, and creative potential
+**First menu:** run `categories`, pick the 2–4 categories that fit the target (risk before a launch, technical for code, collaboration when stakeholders compete, creative when the content is flat), `list` them, and hand-pick five methods that attack the target from different angles — honoring `{workflow.preferences}`. **Reshuffle:** `random -n 5 --spread`, excluding everything already offered.
 
-#### Smart Selection
+## The Menu
 
-1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential
-2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV
-3. Select 5 methods: Choose methods that best match the context based on their descriptions
-4. Balance approach: Include mix of foundational and specialized techniques as appropriate
+HALT and give the user a choice:
 
----
+- The five offered methods, listed by name. The user may pick one or several.
+- **Reshuffle** — replace the list with five new options.
+- **List all** — show the full catalog with descriptions.
+- **Proceed** — no further elicitation.
 
-### Step 2: Present Options and Handle Responses
+This menu is the interface other skills and their users rely on — keep its options and behavior stable. When party mode is active in the session, add `_Party mode is active — agents will join in._` under the heading.
 
-#### Display Format
+- If the user picks methods: run them (several: in sequence), then offer the menu again.
+- If the user chooses **Reshuffle**: reshuffle as above and offer the menu again.
+- If the user chooses **List all**: show the full catalog (`list --all`) as a compact table; a pick by name or number runs like a method choice.
+- If the user chooses **Proceed**: done. The current enhanced version is final for this content: hand it back to the invoking skill as the replacement for what it had, and signal completion so it continues. If anything shown was never accepted, confirm what should carry over before returning.
+- Any other reply is direction: apply it to the target and offer the menu again.
 
-```
-**Advanced Elicitation Options**
-_If party mode is active, agents will join in._
-Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed:
-
-1. [Method Name]
-2. [Method Name]
-3. [Method Name]
-4. [Method Name]
-5. [Method Name]
-r. Reshuffle the list with 5 new options
-a. List all methods with descriptions
-x. Proceed / No Further Actions
-```
+## Running a Method
 
-#### Response Handling
+Use the method's description as its intent and its output_pattern as a flexible flow guide; scale depth to the target — a paragraph gets a light pass, an architecture decision gets the full treatment. Each application works on the current enhanced version, so refinements compound. Show what the method revealed and the changes it proposes, then HALT and give the user a choice:
 
-**Case 1-5 (User selects a numbered method):**
+- **Apply** — accept the proposed changes.
+- **Reject** — drop the proposal entirely.
+- Or give different direction.
 
-- Execute the selected method using its description from the CSV
-- Adapt the method's complexity and output format based on the current context
-- Apply the method creatively to the current section content being enhanced
-- Display the enhanced version showing what the method revealed or improved
-- **CRITICAL:** Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response.
-- **CRITICAL:** ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to follow the instructions given by the user.
-- **CRITICAL:** Re-present the same 1-5,r,x prompt to allow additional elicitations
-
-**Case r (Reshuffle):**
-
-- Select 5 random methods from methods.csv, present new list with same prompt format
-- When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being potentially the most useful for the document or section being discovered
-
-**Case x (Proceed):**
-
-- Complete elicitation and proceed
-- Return the fully enhanced content back to the invoking skill
-- The enhanced content becomes the final version for that section
-- Signal completion back to the invoking skill to continue with next section
-
-**Case a (List All):**
-
-- List all methods with their descriptions from the CSV in a compact table
-- Allow user to select any method by name or number from the full list
-- After selection, execute the method as described in the Case 1-5 above
-
-**Case: Direct Feedback:**
-
-- Apply changes to current section content and re-present choices
-
-**Case: Multiple Numbers:**
-
-- Execute methods in sequence on the content, then re-offer choices
-
----
+Never change the work unless the user accepts the proposal. If they reject it, drop the proposal entirely. Any other reply is instruction to follow.
 
-### Step 3: Execution Guidelines
-
-- **Method execution:** Use the description from CSV to understand and apply each method
-- **Output pattern:** Use the pattern as a flexible guide (e.g., "paths -> evaluation -> selection")
-- **Dynamic adaptation:** Adjust complexity based on content needs (simple to sophisticated)
-- **Creative application:** Interpret methods flexibly based on context while maintaining pattern consistency
-- Focus on actionable insights
-- **Stay relevant:** Tie elicitation to specific content being analyzed (the current section from the document being created unless user indicates otherwise)
-- **Identify personas:** For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory already
-- **Critical loop behavior:** Always re-offer the 1-5,r,a,x choices after each method execution
-- Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session
-- Each method application builds upon previous enhancements
-- **Content preservation:** Track all enhancements made during elicitation
-- **Iterative enhancement:** Each selected method (1-5) should:
-  1. Apply to the current enhanced version of the content
-  2. Show the improvements made
-  3. Return to the prompt for additional elicitations or completion
+When a method casts personas (round tables, panels, debates), reuse party members already in the session if party mode is active; otherwise resolve installed agents on demand via `python3 {project-root}/_wizz/scripts/resolve_config.py --project-root {project-root} --key agents` (a four-layer merge of `_wizz/config.toml`, `config.user.toml`, and the two `_wizz/custom/` overrides; each entry keyed by agent code carries name, title, icon, description). If neither yields a fit, invent named viewpoints suited to the content.

package/src/core-skills/wizz-advanced-elicitation/{methods.csv → assets/methods.csv}

@@ -41,30 +41,32 @@ num,category,method_name,description,output_pattern
 40,creative,Genre Mashup,Combine two unrelated domains to find fresh approaches - innovation through unexpected cross-pollination,domain A + domain B → hybrid insights
 41,creative,Constraint Injection,Deliberately add an artificial limitation (budget - time - technology) to force novel solutions — creativity thrives under pressure,add constraint → forced creativity → remove constraint → evaluate
 42,creative,Morphological Analysis,List independent parameters of a problem - enumerate options for each - then systematically combine — ensures you don't miss non-obvious configurations,parameters → options grid → combinations → evaluation
-43,framing,Abstraction Laddering,"Move up (""why?"") for strategic clarity or down (""how?"") for tactical detail — ensures you're solving at the right altitude",concrete ↔ abstract → right level
-44,framing,Reframe the Question,Challenge whether the stated problem is the real problem — often the question itself is wrong and a better framing unlocks an easy answer,stated problem → reframe → true problem → solution
-45,framing,Stakeholder Lens Rotation,Serially adopt each stakeholder's world-view to see the same situation differently — reveals whose needs are being overlooked,perspective A → B → C → gaps found
-46,learning,Feynman Technique,Explain complex concepts simply as if teaching a child - the ultimate test of true understanding,complex → simple → gaps → mastery
-47,learning,Active Recall Testing,Test understanding without references to verify true knowledge - essential for identifying gaps,test → gaps → reinforcement
-48,learning,Deliberate Practice Loop,Identify a specific sub-skill - drill it with immediate feedback - adjust - repeat — targeted improvement beats general repetition,isolate → drill → feedback → adjust → repeat
-49,philosophical,Occam's Razor Application,Find the simplest sufficient explanation by eliminating unnecessary complexity - essential for debugging,options → simplification → selection
-50,philosophical,Trolley Problem Variations,Explore ethical trade-offs through moral dilemmas - valuable for understanding values and difficult decisions,dilemma → analysis → decision
-51,research,Literature Review Personas,Optimist researcher + skeptic researcher + synthesizer review sources - balanced assessment of evidence quality,sources → critiques → synthesis
-52,research,Thesis Defense Simulation,Student defends hypothesis against committee with different concerns - stress-tests research methodology and conclusions,thesis → challenges → defense → refinements
-53,research,Comparative Analysis Matrix,Multiple analysts evaluate options against weighted criteria - structured decision-making with explicit scoring,options → criteria → scores → recommendation
-54,research,Source Triangulation,Require at least three independent source types (quantitative - qualitative - expert) before accepting a claim — guards against single-source bias,claim → source A → source B → source C → confidence rating
-55,retrospective,Hindsight Reflection,Imagine looking back from the future to gain perspective - powerful for project reviews,future view → insights → application
-56,retrospective,Lessons Learned Extraction,Systematically identify key takeaways and actionable improvements - essential for continuous improvement,experience → lessons → actions
-57,risk,Pre-mortem Analysis,Imagine future failure then work backwards to prevent it - powerful technique for risk mitigation before major launches,failure scenario → causes → prevention
-58,risk,Failure Mode Analysis,Systematically explore how each component could fail - critical for reliability engineering and safety-critical systems,components → failures → prevention
-59,risk,Challenge from Critical Perspective,Play devil's advocate to stress-test ideas and find weaknesses - essential for overcoming groupthink,assumptions → challenges → strengthening
-60,risk,Identify Potential Risks,Brainstorm what could go wrong across all categories - fundamental for project planning and deployment preparation,categories → risks → mitigations
-61,risk,Chaos Monkey Scenarios,Deliberately break things to test resilience and recovery - ensures systems handle failures gracefully,break → observe → harden
-62,risk,Assumption Audit,Explicitly list every assumption underlying a plan - rate each by confidence and impact - then stress-test the weakest — prevents building on shaky foundations,list → rate → stress-test → shore up
-63,risk,Cascading Failure Simulation,Trace how one component's failure propagates through dependencies — reveals hidden coupling and single points of failure,trigger failure → trace propagation → find amplifiers → decouple
-64,technical,Architecture Decision Records,Multiple architect personas propose and debate architectural choices with explicit trade-offs - ensures decisions are well-reasoned and documented,options → trade-offs → decision → rationale
-65,technical,Rubber Duck Debugging Evolved,Explain your code to progressively more technical ducks until you find the bug - forces clarity at multiple abstraction levels,simple → detailed → technical → aha
-66,technical,Algorithm Olympics,Multiple approaches compete on the same problem with benchmarks - finds optimal solution through direct comparison,implementations → benchmarks → winner
-67,technical,Security Audit Personas,Hacker + defender + auditor examine system from different threat models - comprehensive security review from multiple angles,vulnerabilities → defenses → compliance
-68,technical,Performance Profiler Panel,Database expert + frontend specialist + DevOps engineer diagnose slowness - finds bottlenecks across the full stack,symptoms → analysis → optimizations
-69,technical,Boundary & Edge Case Sweep,Systematically test extremes - zeros - nulls - maximums - and type mismatches — catches the failures that happy-path thinking always misses,inputs → boundaries → edge cases → failures found
+43,creative,Subtraction,Improve by deliberately removing elements instead of adding them - counters the well-documented additive bias where people overlook subtractive changes that would simplify and strengthen the work,current state → what to remove → simplified result
+44,framing,Abstraction Laddering,"Move up (""why?"") for strategic clarity or down (""how?"") for tactical detail — ensures you're solving at the right altitude",concrete ↔ abstract → right level
+45,framing,Reframe the Question,Challenge whether the stated problem is the real problem — often the question itself is wrong and a better framing unlocks an easy answer,stated problem → reframe → true problem → solution
+46,framing,Stakeholder Lens Rotation,Serially adopt each stakeholder's world-view to see the same situation differently — reveals whose needs are being overlooked,perspective A → B → C → gaps found
+47,framing,Map Is Not the Territory,Treat any model or diagram as a lossy abstraction of reality - check where the representation diverges from the real system before trusting it,model → reality check → divergences found → corrected understanding
+48,learning,Feynman Technique,Explain complex concepts simply as if teaching a child - the ultimate test of true understanding,complex → simple → gaps → mastery
+49,learning,Active Recall Testing,Test understanding without references to verify true knowledge - essential for identifying gaps,test → gaps → reinforcement
+50,learning,Deliberate Practice Loop,Identify a specific sub-skill - drill it with immediate feedback - adjust - repeat — targeted improvement beats general repetition,isolate → drill → feedback → adjust → repeat
+51,philosophical,Occam's Razor Application,Find the simplest sufficient explanation by eliminating unnecessary complexity - essential for debugging,options → simplification → selection
+52,philosophical,Trolley Problem Variations,Explore ethical trade-offs through moral dilemmas - valuable for understanding values and difficult decisions,dilemma → analysis → decision
+53,research,Literature Review Personas,Optimist researcher + skeptic researcher + synthesizer review sources - balanced assessment of evidence quality,sources → critiques → synthesis
+54,research,Thesis Defense Simulation,Student defends hypothesis against committee with different concerns - stress-tests research methodology and conclusions,thesis → challenges → defense → refinements
+55,research,Comparative Analysis Matrix,Multiple analysts evaluate options against weighted criteria - structured decision-making with explicit scoring,options → criteria → scores → recommendation
+56,research,Source Triangulation,Require at least three independent source types (quantitative - qualitative - expert) before accepting a claim — guards against single-source bias,claim → source A → source B → source C → confidence rating
+57,retrospective,Hindsight Reflection,Imagine looking back from the future to gain perspective - powerful for project reviews,future view → insights → application
+58,retrospective,Lessons Learned Extraction,Systematically identify key takeaways and actionable improvements - essential for continuous improvement,experience → lessons → actions
+59,risk,Pre-mortem Analysis,Imagine future failure then work backwards to prevent it - powerful technique for risk mitigation before major launches,failure scenario → causes → prevention
+60,risk,Failure Mode Analysis,Systematically explore how each component could fail - critical for reliability engineering and safety-critical systems,components → failures → prevention
+61,risk,Challenge from Critical Perspective,Play devil's advocate to stress-test ideas and find weaknesses - essential for overcoming groupthink,assumptions → challenges → strengthening
+62,risk,Identify Potential Risks,Brainstorm what could go wrong across all categories - fundamental for project planning and deployment preparation,categories → risks → mitigations
+63,risk,Chaos Monkey Scenarios,Deliberately break things to test resilience and recovery - ensures systems handle failures gracefully,break → observe → harden
+64,risk,Assumption Audit,Explicitly list every assumption underlying a plan - rate each by confidence and impact - then stress-test the weakest — prevents building on shaky foundations,list → rate → stress-test → shore up
+65,risk,Cascading Failure Simulation,Trace how one component's failure propagates through dependencies — reveals hidden coupling and single points of failure,trigger failure → trace propagation → find amplifiers → decouple
+66,technical,Architecture Decision Records,Multiple architect personas propose and debate architectural choices with explicit trade-offs - ensures decisions are well-reasoned and documented,options → trade-offs → decision → rationale
+67,technical,Rubber Duck Debugging Evolved,Explain your code to progressively more technical ducks until you find the bug - forces clarity at multiple abstraction levels,simple → detailed → technical → aha
+68,technical,Algorithm Olympics,Multiple approaches compete on the same problem with benchmarks - finds optimal solution through direct comparison,implementations → benchmarks → winner
+69,technical,Security Audit Personas,Hacker + defender + auditor examine system from different threat models - comprehensive security review from multiple angles,vulnerabilities → defenses → compliance
+70,technical,Performance Profiler Panel,Database expert + frontend specialist + DevOps engineer diagnose slowness - finds bottlenecks across the full stack,symptoms → analysis → optimizations
+71,technical,Boundary & Edge Case Sweep,Systematically test extremes - zeros - nulls - maximums - and type mismatches — catches the failures that happy-path thinking always misses,inputs → boundaries → edge cases → failures found

package/src/core-skills/wizz-advanced-elicitation/customize.toml

@@ -0,0 +1,54 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for wizz-advanced-elicitation.
+#
+# Override files (not edited here):
+#   {project-root}/_wizz/custom/wizz-advanced-elicitation.toml         (team)
+#   {project-root}/_wizz/custom/wizz-advanced-elicitation.user.toml    (personal)
+
+[workflow]
+
+# --- Configurable below. Overrides merge per Wizz structural rules: ---
+#   scalars: override wins • plain arrays: append
+#   arrays of tables keyed by `code`: matching key replaces, new keys append
+
+# The elicitation method catalog served by scripts/pick_methods.py
+# (columns: num,category,method_name,description,output_pattern). Swap the path
+# in team/user TOML to ship a different catalog. Kept `{skill-root}`-anchored so
+# it resolves regardless of the working directory (pick_methods.py is always
+# invoked with `--file {workflow.methods_file}`).
+methods_file = "{skill-root}/assets/methods.csv"
+
+# Persistent preferences the refiner honors for every session — methods to
+# favor or avoid, how pushback should land, house rules for applying changes.
+# Literal sentences; append-merges, so team and personal preferences both apply.
+#
+# Examples (set in team/user override TOML):
+#   preferences = [
+#     "Lead with a risk-category method for anything touching production systems.",
+#     "Never offer roleplay or persona methods.",
+#   ]
+preferences = []
+
+# Extra methods — and whole new categories — merged into the catalog without
+# editing the shipped CSV. Passed to pick_methods.py via --extra, so custom
+# methods are first-class in every menu, reshuffle, and listing.
+#
+# Two keys, two jobs — keep them aligned:
+#   `code` is only the TOML merge key across override layers: a personal entry
+#     with the same code replaces the team one; new codes append.
+#   `method_name` is the catalog identity: an entry whose method_name matches a
+#     shipped method replaces it (retune its description or pattern; it keeps
+#     the shipped num), others append with new nums.
+#   To override another layer's entry, reuse its `code`. Two entries with
+#     different codes but the same method_name both survive the TOML merge, and
+#     only the later one reaches the catalog.
+#
+# Example (set in team/user override TOML):
+#   [[workflow.additional_methods]]
+#   code = "regulatory-inversion"
+#   category = "domain-specific"
+#   method_name = "Regulatory Inversion"
+#   description = "Start from the compliance constraint and ask what becomes possible only because of it - turns the rule into a generative frame"
+#   output_pattern = "constraint → possibilities → design"
+additional_methods = []

package/src/core-skills/wizz-advanced-elicitation/scripts/pick_methods.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Serve the elicitation method catalog without loading it all into context.
+
+The catalog is a CSV (num, category, method_name, description, output_pattern).
+`description` is a one-line gist — enough to run the method; `output_pattern` is
+a flexible flow guide (e.g. "assumptions → truths → new approach").
+
+Commands:
+  categories                      list category names + counts (the cheap entry point)
+  list --category C [...]         the index (num/category/name/gist) for those categories
+  list --all                      the whole catalog at once — deliberate; large, avoid interactively
+  show NAME_OR_NUM [...]          full row for each method, matched by name or num
+  random [-n N] [--category C ...] [--exclude NAME ...] [--spread]
+                                  draw N at random; --spread forces category diversity
+                                  (at most one per category until categories run out) —
+                                  the reshuffle draw; --exclude skips already-shown methods
+
+`list` refuses to run with neither --category nor --all: dumping the full catalog
+into context must always be an explicit, deliberate choice.
+
+`--extra SPEC` merges additional methods (customize.toml's `additional_methods`)
+into every command. SPEC is either a JSON array literal (starts with `[`) or a
+path to a JSON file; each item is {code, category, method_name, description,
+output_pattern}. An extra whose method_name matches a catalog row
+(case-insensitive) REPLACES it and keeps that row's num — retune a shipped
+method; others append and get the next free nums, so new methods and whole new
+categories are first-class and number-addressable everywhere.
+
+Default output is lean tab-separated text for an LLM to read; --json for structured.
+"""
+import argparse
+import csv
+import json
+import random
+import sys
+from pathlib import Path
+
+DEFAULT_FILE = Path(__file__).resolve().parent.parent / "assets" / "methods.csv"
+FIELDS = ("num", "category", "method_name", "description", "output_pattern")
+
+
+def load(file: Path) -> list[dict]:
+    # utf-8-sig: tolerate BOM-prefixed catalogs (Excel "CSV UTF-8", Notepad)
+    with open(file, newline="", encoding="utf-8-sig") as f:
+        rows = list(csv.DictReader(f))
+    for r in rows:
+        for k in FIELDS:
+            r.setdefault(k, "")
+            r[k] = (r.get(k) or "").strip()
+    return rows
+
+
+def load_extra(spec: str) -> list[dict]:
+    """Parse the --extra overlay: a JSON array literal or a path to a JSON file."""
+    text = spec if spec.lstrip().startswith("[") else Path(spec).read_text(encoding="utf-8-sig")
+    data = json.loads(text)
+    if not isinstance(data, list):
+        raise ValueError("--extra must be a JSON array of objects")
+    rows = []
+    for item in data:
+        if not isinstance(item, dict):
+            raise ValueError(f"each --extra entry must be a JSON object, got: {item!r}")
+        row = {k: str(item.get(k) or "").strip() for k in FIELDS}
+        row["code"] = str(item.get("code") or "").strip()  # kept for traceability
+        rows.append(row)
+    return rows
+
+
+def merge_extra(rows: list[dict], extras: list[dict]) -> list[dict]:
+    """Extras replace a catalog row with the same method_name (case-insensitive),
+    otherwise append — so overrides can retune shipped methods or grow the catalog.
+    A replacement inherits the shipped row's num; appended extras get the next
+    free nums, so every merged method stays addressable by number."""
+    merged = list(rows)
+    index = {r["method_name"].lower(): i for i, r in enumerate(merged)}
+    for e in extras:
+        key = e["method_name"].lower()
+        if key in index:
+            e = dict(e)
+            e["num"] = e["num"] or merged[index[key]]["num"]
+            merged[index[key]] = e
+        else:
+            index[key] = len(merged)
+            merged.append(dict(e))
+    next_num = max((int(r["num"]) for r in merged if r["num"].isdigit()), default=0) + 1
+    for r in merged:
+        if not r["num"]:
+            r["num"] = str(next_num)
+            next_num += 1
+    return merged
+
+
+def categories(rows: list[dict]) -> list[tuple[str, int]]:
+    counts: dict[str, int] = {}
+    for r in rows:
+        counts[r["category"]] = counts.get(r["category"], 0) + 1
+    return sorted(counts.items())
+
+
+def filter_cats(rows: list[dict], cats: list[str] | None) -> list[dict]:
+    if not cats:
+        return rows
+    wanted = {c.lower() for c in cats}
+    return [r for r in rows if r["category"].lower() in wanted]
+
+
+def find(rows: list[dict], names: list[str]) -> tuple[list[dict], list[str]]:
+    """Match each query by method_name or by num, case-insensitively."""
+    by_key: dict[str, dict] = {}
+    for r in rows:
+        by_key[r["method_name"].lower()] = r
+        if r["num"]:
+            by_key.setdefault(r["num"], r)
+    found, missing = [], []
+    for n in names:
+        r = by_key.get(n.strip().lower())
+        (found if r else missing).append(r if r else n)
+    return found, missing
+
+
+def exclude(rows: list[dict], names: list[str] | None) -> list[dict]:
+    if not names:
+        return rows
+    skip = {n.strip().lower() for n in names}
+    return [r for r in rows if r["method_name"].lower() not in skip]
+
+
+def spread_sample(rows: list[dict], n: int, rng: random.Random | None = None) -> list[dict]:
+    """Draw n methods with maximum category diversity: shuffle the categories,
+    take one random method per category round-robin, wrapping only when there
+    are fewer categories than picks."""
+    rng = rng or random
+    by_cat: dict[str, list[dict]] = {}
+    for r in rows:
+        by_cat.setdefault(r["category"], []).append(r)
+    buckets = list(by_cat.values())
+    rng.shuffle(buckets)
+    for b in buckets:
+        rng.shuffle(b)
+    out: list[dict] = []
+    while buckets and len(out) < n:
+        exhausted = []
+        for b in buckets:
+            if len(out) >= n:
+                break
+            out.append(b.pop())
+            if not b:
+                exhausted.append(b)
+        buckets = [b for b in buckets if b not in exhausted]
+    return out
+
+
+def fmt_categories(cats: list[tuple[str, int]], as_json: bool) -> str:
+    if as_json:
+        return json.dumps([{"category": c, "count": n} for c, n in cats])
+    return "\n".join(f"{c}\t{n}" for c, n in cats)
+
+
+def fmt_rows(rows: list[dict], as_json: bool) -> str:
+    if as_json:
+        return json.dumps([{k: r[k] for k in FIELDS} for r in rows])
+    return "\n".join(
+        f"{r['num']}\t{r['category']}\t{r['method_name']}\t{r['description']}\t{r['output_pattern']}"
+        for r in rows
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")  # catalog rows contain →; don't die on locale code pages
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--file", type=Path, default=DEFAULT_FILE, help="method CSV (default: sibling assets/methods.csv)")
+    p.add_argument("--extra", help="additional methods: a JSON array literal or a path to a JSON file")
+    p.add_argument("--json", action="store_true", help="emit structured JSON instead of lean text")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("categories", help="list category names + counts")
+    pl = sub.add_parser("list", help="the index for chosen categories (needs --category or --all)")
+    pl.add_argument("--category", action="append", help="filter to a category (repeatable)")
+    pl.add_argument("--all", action="store_true", help="dump the entire catalog (deliberate; large)")
+    ps = sub.add_parser("show", help="full row for each named method")
+    ps.add_argument("names", nargs="+", help="method names or nums")
+    pr = sub.add_parser("random", help="draw methods at random")
+    pr.add_argument("-n", type=int, default=1, help="how many (default 1)")
+    pr.add_argument("--category", action="append", help="restrict to a category (repeatable)")
+    pr.add_argument("--exclude", action="append", help="method name to skip (repeatable) — e.g. already shown")
+    pr.add_argument("--spread", action="store_true", help="force category diversity across the draw")
+    args = p.parse_args(argv)
+
+    if not args.file.is_file():
+        print(f"error: method file not found: {args.file}", file=sys.stderr)
+        return 2
+    rows = load(args.file)
+    if args.extra:
+        try:
+            rows = merge_extra(rows, load_extra(args.extra))
+        except (OSError, ValueError) as e:
+            print(f"error: could not read --extra: {e}", file=sys.stderr)
+            return 2
+
+    if args.cmd == "categories":
+        print(fmt_categories(categories(rows), args.json))
+    elif args.cmd == "list":
+        if not args.category and not args.all:
+            print(
+                "error: `list` needs --category (one or more) — or --all to dump the whole "
+                "catalog on purpose. Use `categories` for the cheap map, or `random` to draw blind.",
+                file=sys.stderr,
+            )
+            return 2
+        print(fmt_rows(filter_cats(rows, args.category), args.json))
+    elif args.cmd == "show":
+        found, missing = find(rows, args.names)
+        for m in missing:
+            print(f"# not found: {m}", file=sys.stderr)
+        if not found:
+            return 1
+        print(fmt_rows(found, args.json))
+    elif args.cmd == "random":
+        pool = exclude(filter_cats(rows, args.category), args.exclude)
+        if not pool:
+            print("# no methods match", file=sys.stderr)
+            return 1
+        n = max(0, min(args.n, len(pool)))  # clamp: never crash on a negative or oversized -n
+        picks = spread_sample(pool, n) if args.spread else random.sample(pool, n)
+        print(fmt_rows(picks, args.json))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())