@softspark/ai-toolkit 4.19.1 → 4.21.0

package/app/skills/seo-validate/scripts/seo-scanner.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
 """SEO scanner -- pattern-matching heuristics for common SEO issues.
 
 Stdlib only. No external dependencies.

package/app/skills/skill-creator/templates/reasoning-engine/search.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
 """Generic domain reasoning engine for ai-toolkit skills.
 
 Multi-domain search across a categorized knowledge base with anti-pattern filtering.

package/app/skills/test/scripts/detect-runner.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
 """Auto-detect test framework and runner from project configuration files.
 
 Scans a project directory for well-known config files (pyproject.toml,

package/app/skills/write-a-prd/scripts/poll.js

@@ -1,3 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+// Source: https://github.com/softspark/ai-toolkit
+
 (function () {
   var contentEl = document.getElementById("content");
   var lastHtml = "";

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-07-27T07:12:31Z",
+  "last_run": "2026-07-27T11:02:34Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "1925050f50fb6fc3",
+      "docs_hash": "08443e412637cd52",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -364,7 +364,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "1149b358f401b6b3",
+      "docs_hash": "6e930c2fa0b827f5",
       "headings": [
         "Breadcrumbs",
         "Directory actions",

package/benchmarks/run.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+# Source: https://github.com/softspark/ai-toolkit
+
 """benchmarks/run.py — structured benchmark runner for ai-toolkit.
 
 Usage:

package/bin/ai-toolkit.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
+// Source: https://github.com/softspark/ai-toolkit
+
 'use strict';
 
 const { execFileSync, spawnSync } = require('child_process');

package/kb/{planning/drop-cascade-hooks-after-sunset.md → history/completed/drop-cascade-hooks-after-sunset-20260710.md}

@@ -22,6 +22,30 @@ description: "Completed cleanup of the deprecated Windsurf Cascade hooks generat
 
 **Completed in v4.13.0 (2026-07-10).** The deprecated generator and install/test wiring were removed; the Devin hook generator remains.
 
+> **Filed to history 2026-07-27.** The plan was finished in v4.13.0 but sat in
+> `kb/planning/` for another two and a half weeks, where it read as open work.
+> Before moving it, every claim in the Verification section below was re-run
+> against the codebase:
+>
+> | Check | Result |
+> |---|---|
+> | `scripts/generate_windsurf_hooks.py` deleted | gone |
+> | `grep -rn generate_windsurf_hooks scripts/ tests/` | no source references (one stale `.pyc` under gitignored `__pycache__`) |
+> | `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` retained in `validate.py` | present, line 882 |
+> | windsurf `our_generators` in `scripts/ecosystem_tools.json` | Cascade generator absent, `generate_devin_hooks.py` present |
+> | `kb/reference/supported-tools-registry.md` hooks-migration row | reads "Complete" in past tense |
+> | `validate.py --strict` | 0 errors, 0 warnings |
+>
+> The work was real and complete. Only the filing was wrong.
+>
+> **Process note.** This is the second document found misfiled in
+> `kb/planning/` on the same day; the other,
+> [`mcp-context-trim-v4-prd-obsoleted-20260727.md`](mcp-context-trim-v4-prd-obsoleted-20260727.md),
+> had gone obsolete because the platform shipped the fix first. A plan with a
+> `trigger_date` needs a matching move-to-history step in the release that acts
+> on it — otherwise `kb/planning/` accumulates work that is already done or no
+> longer worth doing, and the next reader cannot tell which is which.
+
 ## Why this exists
 
 Windsurf rebranded to Devin Desktop on 2026-06-02. The Cascade agent — and its

package/kb/{reference/language-packs.md → history/completed/language-packs-removed-20260727.md}

@@ -1,15 +1,40 @@
 ---
-title: "AI Toolkit - Language Plugin Packs"
-category: reference
+title: "AI Toolkit - Language Plugin Packs (removed)"
+category: planning
 service: ai-toolkit
-tags: [plugins, languages, rust, java, csharp, kotlin, swift, ruby]
-version: "1.0.0"
+tags: [plugins, languages, rust, java, csharp, kotlin, swift, ruby, removed]
+doc_type: postmortem
+status: completed
+version: "1.1.0"
 created: "2026-03-29"
-last_updated: "2026-03-29"
-description: "6 language-specific plugin packs providing knowledge skills for Rust, Java, C#, Kotlin, Swift, and Ruby."
+last_updated: "2026-07-27"
+description: "REMOVED 2026-07-27 in v4.20.0. The six language packs wrapped skills that already ship in core, so installing one put zero files on disk. The skills themselves (rust-patterns, java-patterns, csharp-patterns, kotlin-patterns, swift-patterns, ruby-patterns) were never in the packs and are unaffected."
 ---
 
-# Language Plugin Packs
+# Language Plugin Packs — REMOVED
+
+> **Removed 2026-07-27 in v4.20.0. Nothing was lost.**
+>
+> The six packs described below each declared exactly one skill —
+> `rust-patterns`, `java-patterns`, `csharp-patterns`, `kotlin-patterns`,
+> `swift-patterns`, `ruby-patterns` — and every one of those skills lives in
+> `app/skills/`, is part of the core install, and **still does**. The packs
+> owned no files of their own beyond a `README.md`.
+>
+> Because `ai-toolkit install` links every core skill, installing a language
+> pack put **zero** files on disk. Measured on both runtimes and all three
+> profiles: `(0 file items)` every time.
+>
+> **If you used one of these packs, you lose nothing.** The skill it named is
+> already installed and triggers on the same file types it always did — open a
+> `.rs` file and `rust-patterns` still loads.
+>
+> Full measurement and the rule that now prevents a repeat:
+> [`no-op-plugin-packs-removed-20260727.md`](no-op-plugin-packs-removed-20260727.md).
+>
+> The document below is preserved as written on 2026-03-29.
+
+---
 
 ## Overview
 

package/kb/{planning/mcp-context-trim-v4-prd.md → history/completed/mcp-context-trim-v4-prd-obsoleted-20260727.md}

@@ -10,23 +10,56 @@ tags:
   - tokens
   - v4
 doc_type: plan
-status: proposed
+status: obsoleted
 created: "2026-05-04"
-last_updated: "2026-05-04"
-completion: "0%"
-target_milestone: "v4.0"
+last_updated: "2026-07-27"
+completion: "0% — never started, and no longer worth starting"
+target_milestone: "v4.0 (abandoned)"
 predecessor:
   - "kb/history/completed/output-token-discipline-plan-20260504.md"
   - "kb/history/completed/f2-mcp-trim-spike-20260504.md"
-description: "Local MCP proxy server that compresses tool descriptions before they reach the model. Carved out of the v3.2.0 output-token-discipline plan (Feature 2), deferred after the 2026-05-04 spike showed Claude Code hooks cannot modify tools/list metadata. Targets ~8-15k token reduction per session for users with many MCP servers."
+description: "ABANDONED 2026-07-27. Local MCP proxy that would compress tool descriptions before they reach the model. Never built. Claude Code now defers MCP tool schemas by default — the catalog costs ~120 tokens of tool names, with schemas fetched on demand — so the 8-15k per-turn overhead this PRD was written to remove no longer exists. Kept as the record of a plan the platform solved first."
 ---
 
-# PRD: MCP Context Trim v4.0
+# PRD: MCP Context Trim v4.0 — ABANDONED
+
+> **Abandoned 2026-07-27, never implemented.**
+>
+> **Why:** the premise expired. This PRD is built on one measured claim — that
+> MCP tool descriptions sit in every turn's system prompt, costing 8–15k tokens
+> per turn. Claude Code now **defers MCP tool schemas by default**: the model
+> receives roughly 120 tokens of tool *names*, and full schemas are fetched on
+> demand through tool search when a task actually needs one.
+> ([Claude Code docs — context window](https://code.claude.com/docs/en/context-window),
+> `ENABLE_TOOL_SEARCH=auto|false` controls the older eager behaviour.)
+>
+> The overhead this proxy was designed to remove is already gone. Building it
+> now would add a supervised local daemon, an `.mcp.json` rewrite, a rollback
+> path and five pre-mortem failure modes in order to compress a 120-token
+> catalog.
+>
+> **How it was caught:** during the 2026-07-27 token-reduction review, a
+> measurement of 1189 real sessions put the median startup context at 22,175
+> tokens against ~7,850 in the documented reference shape. Attributing that gap
+> showed the excess was skill and agent descriptions and rule files — not MCP.
+> The MCP catalog was already deferred, exactly as the docs describe. Full
+> context: [`tool-output-token-reduction-closed-20260727.md`](tool-output-token-reduction-closed-20260727.md).
+>
+> **What survives:** nothing in the architecture below is reusable, because it
+> exists to solve a problem the host now solves. What survives is the process
+> note — this PRD sat in `kb/planning/` for nearly three months while the
+> platform shipped the fix, and nobody re-checked the premise. A plan blocked on
+> a host limitation should carry a re-validation date, not wait indefinitely.
+>
+> Everything below is the document as written on 2026-05-04. It is preserved
+> unedited so the reasoning stays auditable.
 
-**Status:** Proposed
+---
+
+**Status:** Proposed *(as of 2026-05-04; see abandonment note above)*
 **Target milestone:** v4.0
-**Carved out of:** [`output-token-discipline-plan-20260504.md`](../history/completed/output-token-discipline-plan-20260504.md) (was Feature 2)
-**Spike basis:** [`f2-mcp-trim-spike-20260504.md`](../history/completed/f2-mcp-trim-spike-20260504.md)
+**Carved out of:** [`output-token-discipline-plan-20260504.md`](output-token-discipline-plan-20260504.md) (was Feature 2)
+**Spike basis:** [`f2-mcp-trim-spike-20260504.md`](f2-mcp-trim-spike-20260504.md)
 
 ## Problem
 
@@ -156,3 +189,4 @@ Applied to each tool description in `tools/list` response:
 | Date | Status | Author |
 |------|--------|--------|
 | 2026-05-04 | PRD drafted from spike conclusions, carved out of v3.2.0 plan | claude |
+| 2026-07-27 | Abandoned without implementation. Claude Code began deferring MCP tool schemas by default, removing the per-turn overhead this proxy targeted. Moved from `kb/planning/` to `kb/history/completed/`. | claude |

package/kb/history/completed/no-op-plugin-packs-removed-20260727.md

@@ -0,0 +1,127 @@
+---
+title: "Removed: Nine Plugin Packs That Installed Nothing"
+category: planning
+service: ai-toolkit
+tags:
+  - plugins
+  - plugin-pack
+  - measurement
+  - postmortem
+  - dead-code
+doc_type: postmortem
+status: completed
+created: "2026-07-27"
+last_updated: "2026-07-27"
+shipped_in: "v4.20.0 (removal)"
+description: "Nine of eleven plugin packs installed zero files, because every asset they declared already ships in the core install. Measured across both runtimes and all three profiles. Records what was removed, what survived, why the authoring guidance produced the problem, and the check that now prevents a repeat."
+---
+
+# Removed: Nine Plugin Packs That Installed Nothing
+
+`csharp-pack`, `java-pack`, `kotlin-pack`, `ruby-pack`, `rust-pack`,
+`swift-pack`, `frontend-pack`, `research-pack`, `security-pack` — removed in
+v4.20.0. `memory-pack` and `enterprise-pack` stay.
+
+## The measurement
+
+`ai-toolkit install` into a throwaway `HOME`, then `plugin install <pack>`, on
+each runtime. The number is what `plugin install` itself reports:
+
+| Pack | claude | codex |
+|---|---:|---:|
+| `csharp-pack` | 0 | 0 |
+| `java-pack` | 0 | 0 |
+| `kotlin-pack` | 0 | 0 |
+| `ruby-pack` | 0 | 0 |
+| `rust-pack` | 0 | 0 |
+| `swift-pack` | 0 | 0 |
+| `research-pack` | 0 | 0 |
+| `security-pack` | 0 | 0 |
+| `frontend-pack` | 0 | **1** |
+| **`memory-pack`** | **4** | **4** |
+| **`enterprise-pack`** | **2** | **2** |
+
+Cross-checked against the filesystem, not just the reported count: after core
+install (108 skills, 44 agents, 4742 characters of hook config), installing
+`rust-pack`, `security-pack`, `research-pack` or any language pack produced
+`+0` skills, `+0` agents, `+0` bytes of `settings.json` and `+0` files under
+`~/.softspark`.
+
+Profiles make no difference. `minimal`, `standard` and `strict` all install the
+same 108 skills and 44 agents, and packs add `+0` to each.
+
+## Why
+
+Every one of the nine declared only assets that already ship in core:
+
+| Pack | Declared | All present in core? |
+|---|---|---|
+| `rust-pack` | `rust-patterns` | yes |
+| `security-pack` | `review`, `security-patterns`, `panic`, `security-auditor`, `security-architect`, `code-reviewer` | yes |
+| `research-pack` | `docs`, `research-mastery`, `plan`, `technical-researcher`, `fact-checker`, `search-specialist` | yes |
+
+Since `ai-toolkit install` links every core skill and agent, a manifest that
+names only core assets resolves to a set of things already installed. There is
+nothing left to do, so nothing is done.
+
+Eight of the nine owned no file but `README.md`. `security-pack`'s two hooks
+were core's `guard-destructive.sh` and `quality-gate.sh`; `research-pack`'s was
+core's `user-prompt-submit.sh`.
+
+## The one that was not quite zero
+
+`frontend-pack` installed exactly one file, on codex only:
+`plugin-frontend-pack-post-tool-use.sh`. The pack owned no such file — it
+declared core's `post-tool-use.sh`, which core's codex surface does not install,
+so the pack copied it in under a pack-prefixed name.
+
+That is a generic hook wearing a domain label, not frontend functionality. It
+was removed with the pack. **If `post-tool-use` should run on codex, it belongs
+in the core codex hook set**, and adding it there is a separate, honest change —
+not a side effect of installing a pack named after a UI framework.
+
+## The authoring rule that caused this
+
+`app/skills/plugin-creator/SKILL.md` told pack authors:
+
+> **MUST** reference existing toolkit assets before duplicating — packs extend,
+> they do not fork
+
+Read literally against a core install that ships everything, that instruction
+produces a no-op every time. It was correct about avoiding forks and silent
+about the pack needing to add anything. Nine packs followed it exactly.
+
+The rule now reads that a pack **must install something the core install does
+not**, with the verification spelled out, and the validation checklist carries a
+line item requiring a non-zero file count on every runtime the pack claims.
+
+## What survived, and what users lose
+
+**Nothing.** Every skill and agent the nine packs named is a core asset, still
+present, still installed, still triggering on the same conditions. A Rust
+developer who had `rust-pack` installed keeps `rust-patterns`, because it was
+never in the pack.
+
+The two remaining packs are the two that own files:
+
+- `memory-pack` — two hooks, `init_db.py`, `strip_private.py`, and its own
+  `mem-search` skill. Verified working the same day: driving
+  `observation-capture.sh` with a real payload wrote a row to the SQLite store.
+- `enterprise-pack` — `status-line.sh` and `output-style.sh`, both its own.
+
+## Process note
+
+The removal was nearly made on a wrong measurement. The first pass concluded
+"nine no-ops on every editor" after testing only four packs on the claude
+surface. `tests/test_plugin.bats` contradicted it by asserting that
+`frontend-pack` creates a file on codex — the test was right and the
+measurement was incomplete. The full 11 × 2 matrix was only then run.
+
+The existing test suite caught an error in a fresh measurement. That is worth
+remembering next time a test looks like it is merely in the way of a cleanup.
+
+## Related
+
+- [Plugin Pack Conventions](../../reference/plugin-pack-conventions.md) — the rule this postmortem installed
+- [Language Packs (removed)](language-packs-removed-20260727.md) — the reference doc for six of the nine
+- [rtk-pack Retirement](rtk-pack-retirement-20260727.md) — the pack removed the day before, for a different reason

package/kb/history/completed/tool-output-token-reduction-closed-20260727.md

@@ -0,0 +1,190 @@
+---
+title: "Closed: Tool-Output Token Reduction — Three Attempts, One Ceiling"
+category: planning
+service: ai-toolkit
+tags:
+  - token-reduction
+  - measurement
+  - postmortem
+  - prompt-caching
+  - context-window
+  - closed-line-of-work
+doc_type: postmortem
+status: completed
+created: "2026-07-27"
+last_updated: "2026-07-27"
+description: "Closes the tool-output token-reduction line of work after a third measurement. Decomposes 1189 real sessions by cost: 84% is context being fed to the model, 14.7% is responses. Tool output is a small lever by construction and three independent attempts have now hit the same ceiling. Records what shipped (a 20.2% rag-mcp response trim, worth 0.49% of cost), what was killed by its own kill number, and the three measurement errors made on the way."
+---
+
+# Closed: Tool-Output Token Reduction
+
+**Read this before proposing a fourth attempt.**
+
+Three independent efforts have tried to cut tokens by shrinking what tools
+return. All three were competently built. All three measured out near zero.
+
+| Attempt | Shipped | Measured saving |
+|---|---|---:|
+| [Native tool-output filter](output-filter-retirement-20260726.md) | v4.16.0, removed v4.17.0 | **0.0000%** |
+| [rtk-pack](rtk-pack-retirement-20260727.md) | v4.18.0, removed v4.19.0 | **0.0615%** |
+| This review's only clean win (rag-mcp response trim) | rag-mcp, 2026-07-27 | **0.49%** |
+
+This is not three unlucky implementations. It is one structural fact, measured
+three different ways.
+
+## Where the money actually is
+
+1189 sessions with traffic, 83,352 assistant turns, priced at Opus list rates:
+
+| Component | Share of cost |
+|---|---:|
+| `cache_read` | **63.1%** |
+| `cache_creation` | 20.9% |
+| `output` | 14.7% |
+| `input` (uncached) | 1.3% |
+
+**84% of cost is feeding context to the model.** Responses are 14.7%. That
+closes "make the model write less" as a serious lever — the whole `brand-voice`
+concise mode plays for a seventh of the bill.
+
+Cache hit rate is **97.4%**. Published guidance treats 80–95% as the achievable
+band, so there is nothing to win in cache tuning either.
+
+Session shape: median 29 turns (mean 70.1), median peak context 71,276 tokens
+(mean 114,712), median startup context 22,175 tokens.
+
+## Why tool output cannot be the lever
+
+Decomposed by amplification — every tool result is re-read on every turn that
+follows it, so a result's true cost is its size times the turns remaining:
+
+| Category | Share of `cache_read` |
+|---|---:|
+| Fixed startup prelude | 12.4% |
+| `Read` results | 15.6% |
+| `Bash` results | 6.7% |
+| `rag-mcp` results | 3.8% |
+| Unattributed (assistant text, thinking, user messages, reminders) | ~61% |
+
+Every tool in the toolbox, amplified across every turn, is **26.1%** of
+`cache_read`, and it is not compressible without losing what it says. The
+original Phase 0 calculation reached the same place from the other direction:
+tool results are 4.54% of input-token volume, so 4.54% is the arithmetic
+ceiling for any mechanism operating on them.
+
+Raw tool-result bytes, 113 MB across 1308 session files:
+
+| Tool | Share of bytes |
+|---|---:|
+| `Read` | 62.2% |
+| `Bash` | 26.1% |
+| `rag-mcp` (3 tools) | 7.6% |
+| everything else | <2% each |
+
+## What shipped
+
+**rag-mcp response compaction** — `compact_payload()` in
+`app/rag-mcp-server/routes/kb_search.py`, applied to `smart_query`,
+`hybrid_search_kb` and `get_document`, plus both sides of the smart_query cache
+so a hit and a miss return identical bytes.
+
+Verified by running the shipped function over 1356 real responses captured from
+session logs: **20.2% smaller, with no field the agent acts on removed.**
+That is 0.77% of `cache_read`, **0.49% of total cost**.
+
+It drops request echo (`use_hyde`/`use_crag`/`use_multi_hop`), null result
+columns, `_from_cache: false`, `total_documents_used` when it equals the result
+count, and the part of `source_documents_used` that merely repeats
+`results[].kb_id`. It deliberately keeps `file_path` (addresses Read/Edit, where
+`kb_id` addresses get_document), `routing` (the only signal for which pipeline
+ran), `score: 0.0`, and empty result sets. 16 unit tests, most of them asserting
+what must survive rather than what gets removed.
+
+## What was killed, and by what
+
+A kill number was published before the work: *if the shipped changes do not cut
+`cache_read` by 3%, stop and do not proceed to the behavioural changes.*
+
+Result: **0.79%.** The threshold was not met, and the remaining items were not
+built. The kill number did its job — this is the first of the three attempts
+where it bound before code was written rather than after it shipped.
+
+## Three measurement errors, and what they cost
+
+Recorded because each one nearly produced a wrong decision, and because two of
+them are the same class of error that produced the previous two failures.
+
+**1. Duplicate reads: 11.1% was actually 0.1%.** The first pass keyed duplicate
+detection on `file_path` alone, counting re-reads of *different ranges* of the
+same file as waste. Re-keyed on `(file_path, offset, limit)`:
+
+| Key | Duplicates | Bytes | Share of `Read` |
+|---|---:|---:|---:|
+| path only (wrong) | 1754 | 7,787,530 | 11.1% |
+| path + offset + limit (right) | **36** | **90,975** | **0.1%** |
+
+A whole planned deliverable — a session-scoped dedup hook, with a designed
+mitigation for the post-compaction re-read hazard — rested on that 11.1%. It
+does not exist.
+
+**2. A 58% "trim" that was deleting document content.** An aggressive variant of
+the rag-mcp compaction measured 58% smaller. It was whitelisting top-level keys
+and thereby dropping `content` — which for `get_document` *is* the document,
+30.5% of all bytes those endpoints return. Not a trim; data loss that looked
+like a win. The honest figure is 20.2%.
+
+**3. "77.5% of the rag-mcp response is overhead."** Roughly half of that
+non-content mass is `kb_id`, `file_path`, `title` and `score` — fields the agent
+uses. Removable overhead is about 20%, not 77%.
+
+The common thread: **every one of these errors made the opportunity look bigger
+than it is, and every one was caught only by decomposing before building.** The
+filter retirement drew the same conclusion about premise validation; rtk-pack
+drew it about installing the artifact. This adds a third: decompose the metric
+before trusting its headline.
+
+## What is left, and why it was not taken
+
+| Option | Value | Why not |
+|---|---:|---|
+| Model routing | tens of % | Ruled out by the maintainer — Opus 5 stays |
+| Trim the toolkit's own startup prelude | ~2.5% of cost | Ruled out — costs skill/agent discoverability |
+| `Read` with ranges instead of whole files | up to 10.4% of `cache_read` | The only remaining item of size, and **not quality-neutral**: it is a behavioural change whose effect on correctness cannot be measured automatically |
+| Unattributed ~61% of `cache_read` | unknown | Assistant text, thinking blocks, user messages, system reminders — no clean cut available |
+
+For the record, the startup prelude was measured rather than guessed. Median
+startup context is 22,175 tokens against ~7,850 in the documented reference
+shape, and the gap is the toolkit's own:
+
+| Component | Count | ~tokens |
+|---|---:|---:|
+| skill descriptions | 108 | 5,051 |
+| agent descriptions | 44 | 2,750 |
+| project rules | 5 | 3,802 |
+| global rules | 6 | 3,133 |
+| `CLAUDE.md` files | 3 | 2,338 |
+| **total** | | **17,076** |
+
+The tool built to reduce tokens is the single largest addition to every
+session's context. That is worth knowing, and it is still only 2.5% of cost,
+because the prelude is 12.4% of `cache_read` and only part of it is removable.
+
+## The rule this leaves behind
+
+**Do not open a fourth tool-output token-reduction effort without first
+producing a measurement that beats 4.54%.** That is the ceiling on this workload
+and it has now been approached from three directions. Any proposal in this space
+must state, before any code, which share of *input token volume* it addresses —
+not which share of tool output, not which share of Bash bytes.
+
+If token cost genuinely needs to come down, the levers that are actually large
+are model selection and turn count. Both are policy decisions, not engineering
+projects, and neither is in this line of work.
+
+## Related
+
+- [Output Filter Retirement](output-filter-retirement-20260726.md) — attempt one, 0.0000%
+- [rtk-pack Retirement](rtk-pack-retirement-20260727.md) — attempt two, 0.0615%
+- [rtk Pack Integration](rtk-pack-integration-20260726.md) — the Phase 0 ceiling calculation
+- [MCP Context Trim v4.0 — abandoned](mcp-context-trim-v4-prd-obsoleted-20260727.md) — a fourth idea in this space, killed by the platform shipping the fix first
+- [Output & Token Discipline](output-token-discipline-plan-20260504.md) — the plan all of this descends from