scip-query 0.10.2 → 0.10.4

package/skills/scip-diagram/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: scip-diagram
+description: Create evidence-backed HTML diagrams of how code works using scip-query. Use when the user asks for a code flow diagram, architecture diagram, data-flow diagram, dependency map, blast-radius visualization, module map, or an HTML artifact that explains a system.
+---
+
+# SCIP Diagram
+
+Use this skill to build a visual explanation from compiler-resolved code facts. A code diagram is an HTML artifact that turns source units, calls, dependencies, data flow, or blast radius into a visual map. Its defining trait is that every node and edge comes from scip-query evidence, not from guessed folder structure.
+
+## Rules
+
+1. Run scip-query evidence first, then draw. Do not invent nodes or arrows.
+2. Make a self-contained HTML file unless the user asks for another format.
+3. Include command provenance in the HTML so readers can see which scip-query commands produced the diagram.
+4. Keep diagrams scoped. If the graph is huge, summarize clusters and link to detailed evidence rather than rendering a hairball.
+5. Verify the HTML opens cleanly and contains the expected diagram content.
+
+## Pick the Diagram Type
+
+| User wants | Use |
+|---|---|
+| "How does this feature work?" | Call-flow diagram |
+| "Where does this value come from?" | Data-flow diagram |
+| "What depends on this?" | Blast-radius diagram |
+| "What is this module's architecture?" | Module/dependency diagram |
+| "Why is this hard to change?" | Change-surface or bottleneck diagram |
+| "Show classes or ownership" | Hierarchy and surface diagram |
+
+## Evidence Commands
+
+Start with current graph facts:
+
+```bash
+scip-query status --capabilities
+scip-query reindex
+```
+
+Collect only the commands needed for the diagram:
+
+```bash
+scip-query system <module>
+scip-query surface <module>
+scip-query outline <file>
+scip-query trace <symbol>
+scip-query code <symbol>
+scip-query call-graph <symbol>
+scip-query dataflow <symbol>
+scip-query slice <symbol>
+scip-query slice <symbol> --forward
+scip-query deps <file>
+scip-query rdeps <file>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+scip-query hierarchy <symbol> --json
+scip-query fan-out <file> --json
+scip-query bottlenecks
+scip-query cycles
+```
+
+Use `scip-query kind-counts --scope <scope>` and `scip-query by-kind <kind> --scope <scope>` when the diagram needs an inventory of symbols.
+
+## Build the HTML
+
+Write the artifact under:
+
+```text
+docs/scip-query/diagrams/YYYY-MM-DD-<scope>.html
+```
+
+If the repo has a different reports convention, follow it. The file should include:
+
+- title and scope;
+- short textual summary;
+- the visual diagram;
+- legend for node colors, edge styles, and risk labels;
+- evidence table listing every scip-query command used;
+- notes for omitted nodes, collapsed clusters, or unavailable capabilities.
+
+Implementation guidance:
+
+- Use inline CSS and either semantic HTML layout or inline SVG.
+- Use stable dimensions and labels that wrap cleanly.
+- Use one visual encoding per meaning: call edges, data edges, dependency edges, and risk edges should look different.
+- Keep colors accessible and avoid relying on color alone; include labels or edge styles.
+- For large graphs, group by module, ownership, lifecycle phase, or public surface.
+
+## Diagram Recipes
+
+### Call Flow
+
+```bash
+scip-query trace <entry-symbol>
+scip-query call-graph <entry-symbol>
+scip-query code <entry-symbol>
+```
+
+Render entry point -> major callees -> side effects or terminal outputs. Label each edge with the call or branch reason when `code` proves it.
+
+### Data Flow
+
+```bash
+scip-query dataflow <value-symbol>
+scip-query slice <value-symbol>
+scip-query slice <value-symbol> --forward
+```
+
+Render producers, transformations, validators, storage, and consumers. Mark inferred or unavailable parts explicitly.
+
+### Dependency or Module Map
+
+```bash
+scip-query system <module>
+scip-query deps <file>
+scip-query rdeps <file>
+scip-query surface <module>
+```
+
+Render internal files, imported modules, reverse consumers, and public surfaces. Distinguish internal dependencies from external consumers.
+
+### Blast Radius
+
+```bash
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+```
+
+Render the changed symbol, direct consumers, transitive consumers, and high-risk surfaces. Show depth so the user can see how far the change travels.
+
+## Verification
+
+After writing the HTML:
+
+1. Open it locally or use a browser/screenshot tool when available.
+2. Confirm the diagram is nonblank and labels do not overlap badly.
+3. Confirm every major node and edge is traceable to the evidence table.
+4. Run `scip-query diff-gate --json` if the diagram is part of a code or docs change.
+
+End by giving the file path and a short summary of what the diagram proves.

package/skills/scip-diagram/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Diagram"
+  short_description: "Create HTML code-flow diagrams from scip-query"
+  default_prompt: "Generate an HTML diagram that explains this code path using scip-query evidence and command provenance."

package/skills/scip-directory-architecture/SKILL.md

@@ -24,7 +24,7 @@ A migration slice is the smallest set of file moves and import updates that can
 3. Preserve working conventions. Existing boundaries are not wrong just because they are broad; central folders such as `errors`, `routes`, `workflows`, `schemas`, `contracts`, or `features` may be doing real work.
 4. Do not reward generic `shared`. A shared folder is justified only when the shared concept has a name, owner, and consumers across real boundaries.
 5. Treat messy repos honestly. If ownership concepts are not stable, produce a discovery map and decision list instead of pretending the repo has a clean target structure.
-6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, `scip-query reindex`, and `scip-query diff-gate`.
+6. Prefer small verified moves. Broad reorganizations need staged migration slices with import updates, tests, `scip-query reindex`, and `scip-query diff-gate --json`.
 
 ## Workflow
 
@@ -159,7 +159,7 @@ scip-query reindex
 scip-query incomplete-migration
 scip-query recent-duplicates
 scip-query co-change <moved-file-or-config>
-scip-query diff-gate
+scip-query diff-gate --json
 ```
 
 Also run the repo's normal tests or typecheck for the affected workspace. If the migration adds or changes `.scipquery.json` locality settings, run:

package/skills/scip-directory-architecture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Directory Architecture"
+  short_description: "Review and propose source folder boundaries"
+  default_prompt: "Use $scip-directory-architecture to review this repository directory structure and propose safer ownership boundaries."

package/skills/scip-doc-reconcile/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-doc-reconcile
 description: Reconcile standards docs and living documentation with the current code using scip-query doc-drift evidence. Updates descriptive claims, repairs broken file references, and escalates normative violations instead of silently blessing them. Ends with staleness driven to zero.
-allowed-tools: [Bash, Read, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [docs, standards, reconcile, doc-drift, stale-docs, agent-os, spec, documentation, drift, sync]
 ---
 
 # Doc Reconciliation with scip-query
@@ -76,7 +74,7 @@ Then edit the doc:
 
 ```bash
 scip-query doc-drift <doc>     # staleness must drop to 0, broken refs to none
-scip-query diff-gate           # your own doc edits gate clean before commit
+scip-query diff-gate --json    # your own doc edits gate clean before commit
 ```
 
 A doc still showing staleness after your edit means a subject changed in

package/skills/scip-doc-reconcile/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Doc Reconcile"
+  short_description: "Repair docs that drift from code"
+  default_prompt: "Use $scip-doc-reconcile to reconcile this documentation with current SCIP-backed code evidence."

package/skills/scip-explore/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-explore
 description: Deep codebase exploration using scip-query. Trace how any system works end-to-end — call graphs, data flow, dependencies, blast radius — using compiler-resolved analysis. Use when you need to understand how something works before answering questions or making changes.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [explore, understand, trace, investigate, how-does, explain, architecture, flow, debug, navigate, codebase]
 ---
 
 # Codebase Exploration with scip-query
@@ -90,8 +88,10 @@ Start with the high-level map. Run these first:
 
 ```bash
 scip-query stats                      # How big is this codebase?
+scip-query kind-counts                # What symbol kinds dominate?
 scip-query system <module>            # Full module map: files, symbols, deps
 scip-query outline <entry-file>       # What's in the entry point?
+scip-query by-kind function --scope <module>  # Inventory one kind in scope
 ```
 
 **Output:** List all files in the module, the key symbols, what it depends on, and what depends on it. This is your map.
@@ -115,6 +115,7 @@ Understand what the system depends on and who depends on it:
 ```bash
 scip-query deps <file>                # Forward: what does this file need?
 scip-query rdeps <file>               # Reverse: who breaks if this changes?
+scip-query fan-out <file>             # External symbols this file reaches for
 scip-query surface <module>           # True public API (what consumers use)
 scip-query affected <symbol>          # Full transitive blast radius
 ```
@@ -158,6 +159,7 @@ scip-query coupling <file1> <file2>   # How tightly coupled are two files?
 
 ```bash
 scip-query code X                     # Read the source
+scip-query hierarchy X                # Symbol ancestry: method -> class -> module
 scip-query call-graph X               # What it calls, who calls it
 scip-query dataflow X                 # What data flows through it
 scip-query complexity X               # How complex is it
@@ -222,13 +224,17 @@ Every file path, line number, and behavioral claim includes the scip-query comma
 | Read source code | `scip-query code <symbol> [-C N]` |
 | All symbols in a file | `scip-query outline <file>` |
 | Find files | `scip-query files <pattern>` |
+| Symbol kind histogram | `scip-query kind-counts` |
+| Symbols by kind | `scip-query by-kind <kind>` |
 | Full module map | `scip-query system <module>` |
 | True public API | `scip-query surface <module>` |
+| Symbol ancestry | `scip-query hierarchy <symbol>` |
 | Callers + callees | `scip-query call-graph <symbol>` |
 | Every reference | `scip-query refs <symbol>` |
 | Definition + references | `scip-query trace <symbol>` |
 | Forward dependencies | `scip-query deps <file>` |
 | Reverse dependencies | `scip-query rdeps <file>` |
+| External symbol reach | `scip-query fan-out [file]` |
 | Transitive blast radius | `scip-query affected <symbol>` |
 | Pre-change risk briefing | `scip-query change-surface <file>` |
 | Dataflow analysis | `scip-query dataflow <symbol>` |

package/skills/scip-explore/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Explore"
+  short_description: "Trace systems with SCIP evidence"
+  default_prompt: "Use $scip-explore to understand this system end to end with SCIP-backed code evidence."

package/skills/scip-health-audit/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: scip-health-audit
+description: Confirm and prioritize scip-query health signals before cleanup. Use after `scip-query setup`, when reviewing `docs/scip-query/health-dossier.*`, when a user asks for a health audit, issue cleanup, perfect-code pass, setup follow-through, or confirmation of raw scip-query findings before an agent starts fixing them.
+---
+
+# SCIP Health Audit
+
+Use this skill to turn raw scip-query health output into a confirmed cleanup queue.
+
+A health signal is a scip-query reported fact about source code, references, docs, or capability coverage that may indicate maintenance risk. A confirmed issue is a health signal the agent has checked against the current code and SCIP evidence, then classified as a real fix target, an intentional design choice, a false positive, or a blocked investigation.
+
+For autonomous score improvement after this confirmation pass, invoke
+`scip-health-improve`. This skill is the confirmation and ranking pass; the
+improvement skill owns the keep-working cleanup loop.
+
+## Non-Negotiables
+
+1. Start from current evidence. Run `scip-query reindex` when the index is stale, missing, or uncertain.
+2. Do not start cleanup before telling the user the health score and listing the confirmed items that need attention.
+3. Do not call raw analyzer output an issue until you inspect the code or graph evidence that makes it real.
+4. Do not defer confirmed fix targets into vague future work. If the active user request asks for cleanup, start the safest confirmed batch after the visible health report.
+5. Do not use `scip-query setup-ci` in this workflow. CI setup is intentionally outside first-run setup and health cleanup for now.
+
+## Evidence Collection
+
+If setup just ran, read the dossier first:
+
+```bash
+scip-query setup --json
+```
+
+Then collect the current state:
+
+```bash
+scip-query doctor
+scip-query status --capabilities
+scip-query reindex
+scip-query health --json --full
+scip-query diff-gate --json
+scip-query capability-matrix --json
+scip-query config-validate --json
+```
+
+If `doctor`, `status`, or `capability-matrix` reports unavailable capabilities, record them as unavailable checks. Unavailable is not clean; it means this signal class was not proven in this repository.
+
+## Signal Sweep
+
+Run the relevant commands for the repository and scope. Prefer `--json` where supported so the dossier can be updated without scraping prose.
+
+```bash
+scip-query cleanup-plan --verify --json
+scip-query recent-duplicates --json --full
+scip-query incomplete-migration --json --full
+scip-query unused-params --json --full
+scip-query stale-abstractions --json --full
+scip-query wrapper-candidates --json --full
+scip-query passthrough-candidates --json --full
+scip-query dead --json --full
+scip-query isolated --json --full
+scip-query cycles
+scip-query co-change --json --full
+scip-query doc-drift --json --full
+```
+
+For React projects, add:
+
+```bash
+scip-query react-component-duplicates --json --full
+scip-query react-hook-candidates --json --full
+scip-query react-large-component-pressure --json --full
+```
+
+For Vue projects, add:
+
+```bash
+scip-query vue-component-duplicates --json --full
+scip-query vue-composable-candidates --json --full
+scip-query vue-large-view-pressure --json --full
+```
+
+## Confirm Findings
+
+For every candidate that could become a fix target, inspect the relevant code and graph evidence.
+
+Use these probes as needed:
+
+```bash
+scip-query code <symbol-or-file>
+scip-query refs <symbol>
+scip-query fan-in <symbol>
+scip-query fan-out <symbol>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+scip-query convergence <symbolA> <symbolB>
+scip-query co-change <file> --json --full
+```
+
+Classify each candidate:
+
+- `confirmed fix target`: the code evidence shows unnecessary code, broken migration, stale docs, accidental duplication, hidden coupling, or another real maintenance burden.
+- `intentional design`: the finding is real but the current shape exists for a documented product, compatibility, performance, API, or ownership reason.
+- `false positive`: the analyzer report contradicts inspected code or graph evidence. Record the analyzer improvement needed.
+- `blocked`: confirmation needs a missing toolchain, missing test command, missing product decision, or unavailable capability.
+
+Use `scip-query suppress <id> --reason "<specific reason>"` only for accepted findings that have stable finding IDs and a durable reason. A suppression is an explicit design record, not a way to hide uncertainty.
+
+## User Handoff Before Cleanup
+
+Before editing application code, send the user a compact report in this order:
+
+```markdown
+Health score: N/100
+
+Confirmed items to address:
+- [priority] <finding> - <evidence command> - <first safe action>
+
+Unconfirmed signals:
+- <signal> - <what evidence is still needed>
+
+Unavailable or blocked checks:
+- <check> - <why it could not be proven>
+
+Recommended first cleanup batch:
+- <batch> - <why this is safe to start now>
+```
+
+If there are no confirmed fix targets, say that clearly and list remaining unconfirmed or unavailable signals.
+
+## Cleanup Order
+
+When the user has asked for cleanup or the current workflow is post-setup cleanup, start after the handoff with the safest confirmed batch:
+
+1. Compiler-verified deletion batches from `scip-query cleanup-plan --verify --json`, applied with `scip-query cleanup-apply --verified --batch <n>`.
+2. Broken or stale docs from `scip-query doc-drift --json --full`.
+3. Incomplete migrations and recent duplicate echoes from `scip-query incomplete-migration --json --full` and `scip-query recent-duplicates --json --full`.
+4. Unused trailing parameters from `scip-query unused-params --json --full`.
+5. Thin wrappers, passthroughs, stale abstractions, and hidden co-change couplings after confirming behavior.
+
+After every batch:
+
+```bash
+scip-query reindex
+scip-query diff-gate --json
+scip-query health --json --full
+```
+
+Update `docs/scip-query/health-dossier.md` and `docs/scip-query/health-dossier.json` when they exist. Preserve raw signals, confirmation status, evidence commands, fixes applied, and remaining blockers.
+
+## Finish Criteria
+
+The audit is complete only when every collected signal is one of:
+
+- fixed and verified;
+- confirmed intentional with a durable reason;
+- recorded as a false positive with analyzer-improvement notes;
+- blocked by a named external constraint or user decision.
+
+End with the final health score, the verification commands run, and the remaining blocked or intentionally accepted items.

package/skills/scip-health-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Health Audit"
+  short_description: "Confirm scip-query health signals before cleanup"
+  default_prompt: "Run a scip-query health audit, show the score and confirmed items first, then begin the safest cleanup batch."

package/skills/scip-health-improve/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: scip-health-improve
+description: Autonomously raise a scip-query repository's health score with verified, bounded cleanup. Use when the user asks to improve, raise, or maximize the health score; clean up as much as reasonable; continue after setup; pursue perfect code; or keep working with minimal interaction until no safe confirmed work remains.
+---
+
+# SCIP Health Improve
+
+Use this skill for an autonomous health-improvement campaign. The target is not
+score chasing: fix confirmed issues that make the codebase harder to understand,
+verify, or change, then stop when the remaining score movement is unsafe,
+unproven, blocked, or not worth the risk.
+
+A confirmed issue is a raw scip-query signal that the agent has checked against
+current code, graph evidence, or repository checks and classified as real,
+intentional, false positive, or blocked.
+
+## Non-Negotiables
+
+1. If the environment supports durable goals and the user asked for autonomous
+   health improvement, create or continue a concrete goal: raise the scip-query
+   health score as high as reasonably possible by fixing confirmed actionable
+   findings while preserving behavior.
+2. Start from current evidence. Run setup first only if the repository has not
+   been bootstrapped; otherwise refresh the index and collect current signals.
+3. Before editing code, tell the user the current health score and the first
+   confirmed batch you will address.
+4. Do not treat raw health output as actionable until you inspect the relevant
+   code, graph, or verification evidence.
+5. Prioritize worst confirmed offenders first: high risk, high confidence, low
+   blast radius, strong expected score movement, and clear verification path.
+6. Keep working batch by batch until no safe confirmed improvement remains, the
+   score stabilizes, or a real external decision blocks progress.
+7. Do not run `scip-query setup-ci` in this workflow. CI setup is intentionally
+   separate until that path is mature.
+
+## Evidence Baseline
+
+Collect the baseline before ranking:
+
+```bash
+scip-query doctor
+scip-query status --capabilities
+scip-query reindex
+scip-query health --json --full
+scip-query diff-gate --json
+scip-query capability-matrix --json
+```
+
+Unavailable capabilities are not clean results. Record them as unproven signal
+classes and fix missing local prerequisites when that is in scope.
+
+## Priority Ladder
+
+Work from the safest, highest-confidence improvements toward broader design
+work:
+
+1. Compiler-verified cleanup-plan deletion batches.
+2. Incomplete migrations and recent duplicate echoes.
+3. Unused params, unused imports, dead symbols, and isolated symbols.
+4. Broken or stale docs, config validation issues, and missing co-change
+   partners.
+5. Thin wrappers, passthrough layers, stale abstractions, and speculative
+   generality.
+6. React or Vue duplicate components, hooks, composables, and large
+   component/view pressure.
+7. Directory architecture and maintainability repairs only when the evidence is
+   strong and the blast radius is bounded.
+
+## Confirmation Sweep
+
+Run the relevant commands for the current repository and scope:
+
+```bash
+scip-query cleanup-plan --verify --json
+scip-query recent-duplicates --json --full
+scip-query incomplete-migration --json --full
+scip-query unused-params --json --full
+scip-query stale-abstractions --json --full
+scip-query wrapper-candidates --json --full
+scip-query passthrough-candidates --json --full
+scip-query doc-drift --json --full
+scip-query co-change --json --full
+```
+
+For frontend projects, add the relevant React or Vue maintainability commands.
+
+Confirm candidates with targeted probes before editing:
+
+```bash
+scip-query code <symbol-or-file>
+scip-query refs <symbol>
+scip-query fan-in <symbol>
+scip-query fan-out <symbol>
+scip-query affected <symbol> --json
+scip-query change-surface <file> --json --full
+scip-query co-change <file> --json --full
+```
+
+## Autonomous Loop
+
+Before the first edit, report:
+
+```markdown
+Health score: N/100
+
+First confirmed batch:
+- <finding> - <evidence> - <planned fix> - <verification>
+
+Remaining notable signals:
+- <signal> - <status: unconfirmed, intentional, false positive, blocked>
+```
+
+Then repeat:
+
+1. Apply one verified deletion batch or one small targeted refactor.
+2. Run the project check that proves the touched behavior.
+3. Run:
+   ```bash
+   scip-query reindex
+   scip-query diff-gate --json
+   scip-query health --json --full
+   ```
+4. Fix new diff-gate findings immediately unless they are documented,
+   intentional, or blocked.
+5. Update `docs/scip-query/health-dossier.md` and
+   `docs/scip-query/health-dossier.json` when they exist.
+6. Pick the next highest-priority confirmed item.
+
+Use `scip-query cleanup-apply --verified --batch <n>` for verified deletion
+batches. Use `--all` only with explicit human approval. Use `--force-dirty`
+only after inspecting the touched files and confirming existing edits are
+unrelated to the cleanup batch.
+
+## Stop Criteria
+
+Stop the campaign when one of these is true:
+
+- the health score stabilizes after a verified batch;
+- only intentional, false-positive, blocked, or unconfirmed items remain;
+- the next improvement requires a product, API, compatibility, or ownership
+  decision from the user;
+- a missing toolchain or unavailable capability prevents trustworthy
+  verification;
+- further work would be broad architectural redesign rather than bounded health
+  improvement.
+
+## Closeout
+
+End with the starting and final health scores, batches applied, important files
+changed, verification commands run, remaining accepted or blocked items, and the
+next highest-value follow-up if one exists.

package/skills/scip-health-improve/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Health Improve"
+  short_description: "Autonomous verified health cleanup"
+  default_prompt: "Use $scip-health-improve to raise this repo health score as high as reasonably possible with verified cleanup."

package/skills/scip-language-playbook/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: scip-language-playbook
 description: Pick the highest-signal scip-query commands for the language in front of you so you can understand a system granularly and find DRY or de-bloat opportunities without wandering through low-signal queries first.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
-keywords: [language, playbook, commands, cheat-sheet, understand, granular, flow, dry, debloat, consolidate, similarity, ts, typescript, python, java, scala, kotlin, rust, cpp, c, ruby, csharp, vb, dart, php]
 ---
 
 # Best scip-query Commands by Language
@@ -26,9 +24,12 @@ Run these in almost every codebase, regardless of language:
 
 ```bash
 scip-query stats
+scip-query kind-counts
 scip-query files <feature-or-module-name>
 scip-query outline <file>
+scip-query by-kind function --scope <feature-or-module-name>
 scip-query trace <symbol>
+scip-query hierarchy <symbol>
 scip-query code <symbol>
 ```
 
@@ -69,7 +70,7 @@ Vue note: `.vue` single-file components are handled by the same path. scip-query
 Use first:
 ```bash
 scip-query outline <file>
-scip-query outline <file>
+scip-query kind-counts --scope <module-or-file>
 scip-query system <module-or-file>
 scip-query imports <file>
 scip-query imported-by <symbol>
@@ -210,7 +211,7 @@ scip-query trace <symbol>
 scip-query call-graph <symbol>
 scip-query refs <symbol>
 scip-query outline <file>
-scip-query outline <file>
+scip-query fan-out <file>
 ```
 
 Skip:
@@ -348,6 +349,8 @@ scip-query extract-candidates
 ```bash
 scip-query files <feature>
 scip-query outline <file>
+scip-query kind-counts --scope <feature>
+scip-query fan-out <file>
 scip-query trace <entry-symbol>
 scip-query call-graph <entry-symbol>
 scip-query code <entry-symbol>

package/skills/scip-language-playbook/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Language Playbook"
+  short_description: "Pick high-signal SCIP commands by language"
+  default_prompt: "Use $scip-language-playbook to choose the best scip-query commands for this language and task."

package/skills/scip-maintainability/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: scip-maintainability
 description: Principled maintainability review using scip-query. Finds hidden policies, scattered concepts, accidental variation, weak boundaries, and system-compression opportunities, then proposes or executes structural improvements and verifies post-change wiring without chasing health scores.
-allowed-tools: [Bash, Write, Edit, Glob, Agent, TaskCreate, TaskUpdate, TaskGet, TaskList]
 ---
 
 # SCIP Maintainability Review
@@ -41,6 +40,11 @@ System compression belongs inside this review. A system compression is a maintai
 
 6. **Prefer small named mechanisms.** Delete, inline, merge, generate, or enforce before adding broad frameworks.
 
+7. **Treat suppressions as accepted design records.** Prefer fixing findings.
+   Use `scip-query suppress <id> --reason "<specific reason>"` only for
+   intentional design, compatibility shims, framework entry points, or accepted
+   false positives. Run `scip-query config-validate` afterward.
+
 ---
 
 ## Core Concepts
@@ -259,8 +263,8 @@ Then run the post-change checks that match what the fix actually did:
 Always finish implemented maintainability work with:
 
 ```bash
-scip-query diff-impact
-scip-query reindex && scip-query diff-gate
+scip-query diff-impact --json
+scip-query reindex && scip-query diff-gate --json
 ```
 
 Treat `diff-gate` findings as unfinished work. Fix them or state a concrete acceptance reason; do not silently report success.

package/skills/scip-maintainability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SCIP Maintainability"
+  short_description: "Review hidden policy and boundaries"
+  default_prompt: "Use $scip-maintainability to find maintainability risks, hidden policies, and weak boundaries with SCIP evidence."