@aeondave/pi-skill-optimizer 3.0.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# How AUTO works
+
+[Back to the README](../README.md)
+
+### Stable skill base
+
+AUTO renders a query-independent index in the stable prompt prefix:
+
+```xml
+<!--skill-optimizer:auto:v2-->
+<skill_index format="tsv" columns="name,intent">
+skill-name\tShort routing intent
+</skill_index>
+<skill_resolver>Use skill_search to search, load, inspect resources, or request a location.</skill_resolver>
+```
+
+The index contains no filesystem paths. With the same catalog, profile, and configuration, its bytes remain unchanged across requests. `catalogBudgetChars` is a request-global soft budget shared by every catalog found in one request. Intents yield first, but the combined all-name floor may exceed the budget.
+
+## Request-specific prefetch
+
+AUTO extracts intent only from genuine human text in Anthropic, OpenAI Chat and Responses, Gemini, Mistral, and Pi's structured `pi-messages` request shapes. A catalog may live in a system or developer block, but neither is treated as human intent. Assistant text, tool or function results, injected context, image metadata, and empty input cannot create a ranking signal.
+
+Ranking uses exact matching, BM25F, bounded name and alias typo recovery, reciprocal-rank fusion, diversity, profile evidence, and decayed usage evidence. It scores full source descriptions, then appends a bounded set of verbatim skill names and descriptions (not the full `SKILL.md` instructions) to the latest human block. The overlay is separate from the stable prefix, fingerprinted, idempotent, and omitted when there is no valid target.
+
+Optional init-generated activation tags distinguish specialists, workflow methods
+and behavioral discipline. An admitted specialist can bring one activity-matched
+supporting skill into the ordinary prefetch budget; this does not recursively
+expand dependencies or treat a behavioral tag as universal. See
+[contextual routing](RANKING.md#contextual-and-behavioral-skills).
+
+## Dynamic tools
+
+AUTO keeps protected and predicted tools active and leaves the rest behind `tool_search`. Search is bounded and paginated. A returned result is activated through Pi's runtime API without replacing already active tools. Core, configured, and previously used tools remain callable, so an in-progress tool loop cannot be stranded. Weak or absent routing signal fails open to every permitted tool; safety wins, but that request may retain the full schema cost.
+
+Selection is recalculated before each agent run, not just the first request. Used tools and explicit search results stay active for the session. The discoverable set starts from Pi's initially active tools plus the optimizer's own resolvers; tools that were initially unavailable are not silently added. This is schema routing, not authorization: another extension's call-time permission checks remain authoritative.
+
+See Pi's [extension and dynamic-tool API](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md).
+
+## Recoverable output
+
+The default `smart` reducer is deterministic and UTF-8 byte-aware. It preserves protected evidence and accepts a reduction only when the complete returned representation clears both configured saving thresholds. Size and line settings trigger reduction; they are not hard output caps. Protected evidence may make the returned result exceed them.
+
+Homogeneous JSON object arrays may use a lossless columnar form after an exact internal round trip. With `outputMode: "extract"` and an explicit `outputModel`, sufficiently large text may first use model-assisted extraction. Extracted content must be an ordered verbatim subsequence, retain protected evidence, and provide material savings. Rejection falls back to smart reduction, then to the original.
+
+Before AUTO returns any reduced result, it stores the complete original in a local, immutable, content-addressed archive. Provider-visible recovery text contains only an opaque identifier. `retrieve_output` verifies and resolves that identifier with bounded line access.
+
+Savings include the recovery label and are checked before an archive write. The optimizer's own resolver results are exempt from reduction, avoiding a second handle in place of the original you just requested. Custom-tool failures throw through Pi's error path instead of returning a success-shaped error object.
+
+Columnar conversion conservatively leaves unsafe integers, non-finite numbers,
+negative zero and noncanonical numeric spellings untouched. Parsing twice is not
+a losslessness oracle when both parses can round the same value. Invalid Unicode
+strings also fail open. Exact recovery retains the source's original line endings;
+it does not normalize Windows output to LF.
+
+History deduplication keeps the first large successful result intact and replaces only later exact copies. Errors, images, mixed media, small results, and protected evidence are never deduplicated.
+
+## Scale and limits
+
+AUTO reduces metadata in the tested catalogs, but does not guarantee model discovery.
+
+- The current contract keeps every eligible skill name in the stable index. Its minimum size therefore grows linearly with the number and length of names. This all-name information floor cannot be compressed away while preserving immediate name-level discovery.
+- A catalog with 100,000 skills is outside the scale demonstrated by the current 332-skill benchmark. It may still produce an impractically large name-only base.
+- Extreme catalogs require an additional resolver-only, namespace-sharded, or server-side paginated discovery layer. That would deliberately change the current all-name visibility guarantee.
+- Arbitrarily large system prompts are not automatically reduced. AUTO transforms recognized skill catalogs, manages tool definitions, and processes eligible tool results; it does not summarize unrelated policy, instructions, or conversation content.
+- Provider tokenization, caching, and pricing remain provider-controlled. Stable bytes improve cacheability but do not prove a cache hit or guarantee a specific bill.
+- Very small catalogs or outputs may remain unchanged when framing overhead would eliminate the saving.

package/docs/CONFIGURATION.md

@@ -0,0 +1,138 @@
+# Configuration and runtime reference
+
+[Back to the README](../README.md)
+
+## Runtime tools
+
+| Tool | Purpose |
+| --- | --- |
+| `skill_search` | Paginated skill search plus exact `load`, contained `resource`, and explicit `location` actions |
+| `tool_search` | Search deferred tool definitions and activate bounded matches additively |
+| `retrieve_output` | Recover archived output or a deduplicated history result by opaque identifier |
+
+Exact skill loading accepts only registered names. Resource and location resolution use canonical paths and containment checks to reject traversal and symlink escape. Search cursors bind to the query, catalog and ranked name order; a changed profile or usage prior that reorders results requires a new search, rather than duplicating or skipping a page. This is an exact local resolver guarantee, not a guarantee that the model will select the right skill; see the separate [ranking diagnostics](RANKING.md) and [historical model benchmark](../BENCHMARK.md).
+
+`excludeSkills` removes names from discovery and search, not from explicit exact loading. It is a routing preference, not an access-control boundary. The three resolver tools return their content without another output-reduction pass, so full skill instructions and recovered originals remain readable.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/skill-optimizer` | Show setup readiness, AUTO state, catalog budget, critical skills, usage prior, tool activation, provider telemetry, and savings |
+| `/skill-optimizer init` | Generate or incrementally update routing hints and contextual activation tags |
+| `/skill-optimizer audit` | Report description issues without editing source skills |
+
+The optional setup hint is informational, not an error: ordinary routing works
+without init. It appears on the first eligible interactive prompt, at most once
+per profile scope, readiness state and init version in the current session.
+Session metadata preserves that suppression across reload/resume. It is not sent
+to the model and does not run init or incur model cost itself. Headless sessions,
+disabled/out-of-scope routing and empty catalogs do not emit it. Status remains
+available even after the hint has been shown. Nonempty hand-authored profiles
+without generation metadata are treated as manual, not as a failed setup.
+
+## Configuration
+
+Global configuration lives at `~/.pi/agent/skill-optimizer/config.json`. A project can override it with `.pi/skill-optimizer/config.json`.
+
+| Key | Default | Purpose |
+| --- | ---: | --- |
+| `catalogBudgetChars` | `8000` | Request-global soft budget for stable-index intents |
+| `intentMaxChars` | `96` | Maximum rendered intent length |
+| `prefetchTarget` | `5` | Ordinary prefetch target |
+| `prefetchMin` | `3` | Minimum adaptive prefetch count |
+| `prefetchMax` | `8` | Maximum adaptive prefetch count |
+| `prefetchBudgetChars` | `6000` | Full-definition overlay budget |
+| `fuzzyCandidateLimit` | `8` | Bound for name and alias typo recovery |
+| `alwaysSkills` | `[]` | Skills favored for routing and prefetch |
+| `excludeSkills` | `[]` | Skills intentionally removed from discovery |
+| `providers` | `[]` | Provider allowlist; empty means all |
+| `toolPrefetchMax` | `5` | Maximum proactive tool activation |
+| `toolSearchPageSize` | `8` | Default tool-search page size |
+| `alwaysTools` | `[]` | Tools that remain active |
+| `historyDedupMinBytes` | `4096` | Minimum result size for history deduplication |
+| `usageHalfLifeDays` | `30` | Usage-evidence decay half-life |
+| `usageMaxEntries` | `2048` | Persistent usage-evidence bound |
+| `usageStaleDays` | `180` | Age for pruning stale one-off evidence |
+| `outputMode` | `"smart"` | `"off"`, `"smart"`, or guarded `"extract"` |
+| `outputMaxLines` | `400` | Line-count activation threshold |
+| `outputMaxBytes` | `16000` | UTF-8 byte activation threshold |
+| `outputMinSavingsBytes` | `512` | Minimum absolute saving |
+| `outputMinSavingsRatio` | `0.1` | Minimum relative saving |
+| `outputTools` | `["*"]` | Eligible tool-name patterns |
+| `outputModel` | `""` | Explicit model for guarded extraction |
+| `outputExtractMinBytes` | `32000` | Minimum input size for extraction |
+| `outputExtractExclude` | common listing commands | Tools excluded from extraction |
+| `outputArchiveTtlHours` | `168` | Archive retention period |
+
+Configuration is also available through `PI_SKILL_OPTIMIZER_*` environment variables. Lists are comma-separated. The bypass exists only as `PI_SKILL_OPTIMIZER_DISABLE` and uses boolean semantics; there is no `disable` configuration key. Output exceptions retain the exact names `PI_SKILL_OPTIMIZER_OUTPUT_MIN_SAVINGS_RATIO` and `PI_SKILL_OPTIMIZER_OUTPUT_EXCLUDE`.
+
+Configuration refreshes at session start, before each agent run, and when you use a `/skill-optimizer` command. Provider and tool-result hooks reuse that snapshot instead of rereading files on every event. The environment bypass is checked immediately. Profile and usage state are retained separately; refreshing settings does not reset pending usage or telemetry.
+
+## RTK coexistence
+
+Ownership is decided per result:
+
+| Result | Owner |
+| --- | --- |
+| Shell output already handled by RTK | RTK only |
+| Shell output not handled by RTK | AUTO eligible |
+| Read, web, MCP, and other eligible output | AUTO eligible |
+| Already reduced output | No second reduction |
+
+RTK never changes skill discovery or dynamic tool activation.
+
+## Telemetry and persistence
+
+Provider telemetry records only authoritative usage fields:
+
+```text
+requests, input, output, cacheRead, cacheWrite, totalCost
+```
+
+AUTO does not infer cache hits from stable bytes. Characters, UTF-8 bytes, provider tokens, and cost remain separate metrics.
+
+Profile updates use atomic replacement with revision checks; usage and statistics merge lock-serialized additive deltas. Archive content is immutable and SHA-256 verified. A separate expiry record belongs to each archive: saving identical content may extend its retention, but a reader or project with a shorter TTL cannot shorten it. Legacy archives without expiry records get a fixed seven-day lifetime from their last modification; corrupt expiry records fail closed without deleting content. Usage evidence is bounded and decays over time.
+
+An old lock is reclaimed only when its recorded process is no longer alive;
+elapsed time alone must not interrupt a slow or suspended writer. Unknown lock
+ownership fails closed rather than risking a concurrent overwrite.
+
+Recovery preserves original LF, CRLF, CR and mixed line endings, including the selected lines' terminators. Adjacent pages concatenate to the original text; asking past the end returns an empty page. Invalid Unicode strings containing unpaired UTF-16 surrogates are left unreduced rather than archived with replacement characters.
+
+## Privacy
+
+- Normal hooks never collect a benchmark corpus.
+- Corpus building and real-provider evaluation are explicit commands.
+- Remote evaluation receives only validated, sanitized cases with keyed irreversible identifiers.
+- Raw private sessions, catalogs, paths, credentials, hostnames, and account identifiers are not published.
+- Generated profile queries are routing hints, not benchmark labels.
+- Full output archives stay local.
+- `.pi/skill-optimizer/benchmark/` must not be committed.
+
+## Routing profile initialization
+
+`init` is explicit model work. It notifies at start and completion while per-batch progress stays in the transient status line. It batches full descriptions by skill count and UTF-8 input size, validates complete coverage and a successful provider stop reason, retries only retryable failures, and checkpoints each successful batch so interrupted work is not lost. A changed skill whose regeneration fails stays unhashed and inactive until retry, rather than serving stale routing. Init also repairs global/project profile ownership without another model call. Ordinary discovery does not call a model.
+
+
+The profile is optional. Without one, AUTO still uses the catalog's names and descriptions. Run `init` when you want generated routing hints, and rerun it after changing your skills. It uses the current Pi model and can incur provider cost.
+
+Profile init version 5 also generates optional `activation` tags. Each installed
+skill can be a `specialist`, `workflow`, or `behavioral` skill and declare applicable
+activities. For example, the profile may contain:
+
+```json
+{
+  "activation": {
+    "python-patterns": { "kind": "specialist", "tasks": ["software-change"] },
+    "software-architecture": { "kind": "workflow", "tasks": ["software-design", "software-change"] },
+    "test-driven-development": { "kind": "behavioral", "tasks": ["software-change"] }
+  }
+}
+```
+
+These are example entries inside `profile.json`, not `config.json`, and only make
+sense for installed skills. They allow bounded contextual support without turning
+every behavioral skill into a permanent default. The next explicit init upgrades
+older generated profiles; no regeneration or model call happens on ordinary
+startup. See [contextual routing and its limits](RANKING.md#contextual-and-behavioral-skills).

package/docs/RANKING.md

@@ -0,0 +1,155 @@
+# Ranking decisions
+
+[Back to the README](../README.md)
+
+## Why this is still a local lexical router
+
+The job is to find a few useful entries in a known skill catalog, before the model
+starts work. Ordinary routing must be deterministic, cheap to run, and usable
+without another provider or a generated profile. AUTO's hybrid is a reasonable
+fit for those constraints; it is not a claim that lexical retrieval is universally
+better than embeddings or that these weights are optimal.
+
+The current pipeline is:
+
+1. Normalize the latest genuine human text and expand catalog-supported aliases.
+2. Score names, short intents, full descriptions and optional profile queries with
+   field-weighted BM25F. Compact display text is not the only searchable text.
+3. Add token-bounded name/example matches and bounded name/alias typo candidates.
+4. Combine the rankings with weighted reciprocal-rank fusion (RRF). Decayed usage
+   can reinforce an already relevant candidate, not invent relevance.
+5. Apply negative hints and a small cluster-diversity adjustment, then select
+   within adaptive count and character budgets. Explicitly protected skills have
+   their own guarantee; they can exceed ordinary prefetch budgets.
+
+The stable all-name index is separate from this ranking. A miss in prefetch does
+not remove a skill from the library or its exact resolver.
+
+## Contextual and behavioral skills
+
+Literal similarity is not the whole job. A task that selects a language specialist
+can also need architecture or test-first discipline without naming either.
+An optional, name-owned `activation` entry in the profile records two tags:
+
+- `kind`: `specialist`, `workflow`, or `behavioral`.
+- `tasks`: a small subset of shared activities such as `software-change`,
+  `software-review`, `docs-write`, or `research`.
+
+Explicit `/skill-optimizer init` assigns these from each skill's description.
+The fixed activity vocabulary works across init batches: no full-catalog model
+request or runtime inference call is needed. Old profiles still work; rerun init
+to regenerate them with the new tags. That regeneration uses your selected model
+and can incur cost. This update does not run it automatically.
+
+The router first selects a positively matched, tagged specialist. It can then
+reserve **one ordinary prefetch slot** for a workflow or behavioral skill sharing
+an activity tag, even with no lexical match to the user's words. This is one-hop
+support, not recursive expansion. It retains the primary specialist, honors
+exclusions and negative hints, and uses the same count and character budget.
+Already selected skills are not duplicated; a one-slot budget leaves only the
+primary. An explicit exact-name selection takes precedence.
+
+Contextual search entries carry the reason `contextual`, without pretending that
+they had a lexical score. Direct search ordering is retained. `clusters` represent
+confusable substitutes only; complementary phases are not penalized as substitutes.
+
+The `behavioral` tag does **not** mean always-on. Truly universal disciplines still
+belong in `critical`; task-specific design, debugging and testing do not. An empty
+or unrelated request cannot trigger support just from its tags or usage history.
+
+These are routing hints, not a dependency solver or proof that the LLM classified
+every skill correctly. Activity tags are deliberately coarse and the router does
+not infer task phases from tool output or inspect repository files. The contextual
+tests use reviewed fixtures; they do not establish generated-profile quality.
+
+The typo fallback is deliberately conservative: it runs only when fewer than
+60% of query terms are covered by the catalog or its aliases. A typo surrounded
+by enough known words can therefore be missed. This is a known quality tradeoff,
+not a promise to repair every misspelling.
+
+## What the algorithm comparison can tell us
+
+Run the diagnostic fixture locally:
+
+```bash
+npm run bench:ranking
+```
+
+It compares BM25F-only ordering, AUTO without fuzzy candidates, and full AUTO on
+the same 14 synthetic skills, 18 labeled positive queries and four no-signal
+queries. It prints Recall@1, Recall@5, mean reciprocal rank and no-signal
+promotions. It also rejects the regression where `git` was treated as an exact
+name inside `digital`.
+
+A separate two-case support diagnostic checks architecture and behavioral guidance
+without literal query overlap, and verifies no promotion on unrelated input. It
+uses reviewed activation tags, not init-generated labels, and does not enter the
+18-query lexical comparison below.
+
+These are hand-authored diagnostics, **not a held-out or production dataset**.
+They include typos and nearby tasks, but no generated profile, learned usage or
+cluster-diversity labels. The BM25F baseline reuses AUTO's lexical component; it is
+not an independent implementation. Results can reveal a tradeoff or regression,
+not establish the best router for all users. Keep the denominators and report
+weaker results as well as improvements.
+
+Local diagnostic run, 2026-09-28 (working tree, Node 26.3.0, Windows x64):
+
+| Variant | Recall@1 | Recall@5 | MRR | No-signal promotions |
+| --- | --- | --- | --- | --- |
+| BM25F only | 17/18 (94.4%) | 17/18 (94.4%) | 0.944 | 0/4 |
+| AUTO without fuzzy | 15/18 (83.3%) | 17/18 (94.4%) | 0.889 | 0/4 |
+| AUTO | 16/18 (88.9%) | 18/18 (100%) | 0.944 | 0/4 |
+
+The hybrid recovers the final relevant item within five results, but does not win
+top-one accuracy. This is why no new weight set or replacement is justified by
+this fixture alone. Re-run the command for current-tree results.
+
+| Candidate | Why keep or consider it | What is still missing |
+| --- | --- | --- |
+| BM25F + exact/fuzzy + RRF | Local, reproducible, no training labels or score calibration required | Representative relevance labels for weight/confidence tuning |
+| BM25F alone | Simpler comparator; can lead on straightforward lexical queries | Name-typo recovery and broader intent coverage |
+| Calibrated score fusion | Retains score magnitude that rank fusion discards | A separate tuning set and held-out evaluation |
+| Embeddings / reranking | Could help paraphrases with little shared vocabulary | Measured quality gain, latency and privacy/cost tradeoffs; not implemented or benchmarked here |
+
+Do not tune defaults merely to win this tiny fixture. Before replacing the router,
+use separately reviewed relevance labels, keep tuning and evaluation cases
+separate, compare identical catalogs and budgets, and measure both false
+promotions and missed skills. The [private evaluation protocol](../BENCHMARK.md)
+defines the broader gates; running it is an explicit operation.
+
+## Performance versus quality
+
+```bash
+npm run bench:perf
+```
+
+This measures `optimizePayload` with 201 messages and 284 / 2,000 synthetic skills.
+Each catalog gets one cold call and 30 warm calls; mean, p50 and p95 are reported
+along with runtime/platform. Warm calls reuse the same source request and query,
+not an already transformed payload. The size check must remain deterministic.
+
+This is request-preparation latency, **not Pi startup, terminal redraw or model
+latency**. There is no universal millisecond gate: compare repeated runs on the
+same host. Index caching should remove repeated analysis without changing scores,
+and caches must remain bounded and invalidate when catalog/profile content changes.
+
+## Research behind the choices
+
+BM25F combines weighted document fields before term saturation, rather than
+summing independently saturated field scores. The original formulation is
+[Robertson, Zaragoza and Taylor, 2004](https://www.researchgate.net/publication/221613382_Simple_BM25_extension_to_multiple_weighted_fields)
+(author-uploaded paper).
+
+RRF combines positions rather than requiring compatible score scales. Its common
+constant of 60 comes from experiments in
+[Cormack, Clarke and Buettcher, 2009](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf),
+not a universal optimum for skill catalogs.
+
+Later work found tuned convex score fusion stronger than RRF in its evaluated
+lexical/semantic settings, and found RRF sensitive to its parameters. See
+[Bruch, Gai and Ingber, 2023](https://arxiv.org/abs/2210.11934).
+Those experiments do not directly validate or invalidate this skill router.
+The design judgment here is to retain the local hybrid until project-specific
+evaluation justifies a replacement, while fixing demonstrated correctness and
+implementation-cost problems now.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@aeondave/pi-skill-optimizer",
+  "version": "3.0.0",
+  "private": false,
+  "type": "module",
+  "description": "Less repeated context for Pi: local skill routing, on-demand tools, and recoverable output reduction.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "optimization",
+    "tokens",
+    "skills",
+    "system-prompt",
+    "tool-output",
+    "mcp"
+  ],
+  "license": "MIT",
+  "author": "AeonDave",
+  "homepage": "https://github.com/AeonDave/pi-skill-optimizer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AeonDave/pi-skill-optimizer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AeonDave/pi-skill-optimizer/issues"
+  },
+  "engines": {
+    "node": ">=26.3.0"
+  },
+  "files": [
+    "src",
+    "docs/ARCHITECTURE.md",
+    "docs/CONFIGURATION.md",
+    "docs/RANKING.md",
+    "assets/banner.png",
+    "README.md",
+    "BENCHMARK.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/request.test.ts test/history.test.ts test/skills.test.ts test/skill-loader.test.ts test/tools.test.ts test/optimize.test.ts test/profile.test.ts test/activation.test.ts test/generate.test.ts test/init.test.ts test/init-readiness.test.ts test/config.test.ts test/fuzz.test.ts test/output.test.ts test/output-recovery.test.ts test/runtime.test.ts test/host-runtime.test.ts test/stats.test.ts test/usage.test.ts test/persistence.test.ts test/corpus.test.ts test/evaluation.test.ts test/luna.test.ts test/release-metadata.test.ts",
+    "measure": "node --import tsx scripts/measure.ts",
+    "bench": "node --import tsx scripts/bench.ts",
+    "bench:perf": "node --import tsx scripts/perf-bench.ts",
+    "bench:ranking": "node --import tsx scripts/ranking-bench.ts",
+    "bench:output": "node --import tsx scripts/output-bench.ts",
+    "corpus:build": "node --import tsx scripts/build-real-corpus.ts",
+    "bench:real": "node --import tsx scripts/evaluate-real-corpus.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.87.1",
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@types/node": "^26.6.3",
+    "tsx": "^4.23.13",
+    "typebox": "^1.3.34",
+    "typescript": "^5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-skill-optimizer/v3.0.0/assets/banner.png"
+  }
+}

package/src/activation.ts

@@ -0,0 +1,88 @@
+export const ACTIVATION_TASKS = [
+	"software-design",
+	"software-change",
+	"software-debug",
+	"software-test",
+	"software-review",
+	"software-read",
+	"docs-write",
+	"docs-review",
+	"data-analysis",
+	"research",
+	"operations",
+] as const;
+
+export type ActivationTask = (typeof ACTIVATION_TASKS)[number];
+export type SkillActivationKind = "specialist" | "workflow" | "behavioral";
+
+export interface SkillActivation {
+	kind: SkillActivationKind;
+	tasks: ActivationTask[];
+}
+
+const ACTIVATION_KINDS: ReadonlySet<string> = new Set(["specialist", "workflow", "behavioral"]);
+const ACTIVATION_TASK_SET: ReadonlySet<string> = new Set(ACTIVATION_TASKS);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isActivationKind(value: unknown): value is SkillActivationKind {
+	return typeof value === "string" && ACTIVATION_KINDS.has(value);
+}
+
+/** Keep only exact names and validated activation tags from untrusted generated JSON. */
+export function normalizeActivation(value: unknown): Record<string, SkillActivation> {
+	const normalized: Record<string, SkillActivation> = {};
+	if (!isRecord(value)) return normalized;
+
+	for (const [rawOwner, rawActivation] of Object.entries(value)) {
+		const owner = rawOwner.trim();
+		if (!owner || Object.prototype.hasOwnProperty.call(normalized, owner) || !isRecord(rawActivation)) continue;
+		if (!isActivationKind(rawActivation.kind) || !Array.isArray(rawActivation.tasks)) continue;
+
+		const tasks: ActivationTask[] = [];
+		const seen = new Set<ActivationTask>();
+		for (const task of rawActivation.tasks) {
+			if (typeof task !== "string" || !ACTIVATION_TASK_SET.has(task)) continue;
+			const activationTask = task as ActivationTask;
+			if (seen.has(activationTask)) continue;
+			seen.add(activationTask);
+			tasks.push(activationTask);
+		}
+		if (tasks.length === 0) continue;
+
+		Object.defineProperty(normalized, owner, {
+			value: { kind: rawActivation.kind, tasks },
+			enumerable: true,
+			configurable: true,
+			writable: true,
+		});
+	}
+
+	return normalized;
+}
+
+/** Return one-hop workflow/behavioral companions with shared task tags. */
+export function contextualSkillNames(
+	activation: Readonly<Record<string, SkillActivation>> | undefined,
+	primaryName: string | undefined,
+): string[] {
+	if (!activation || !primaryName || !Object.prototype.hasOwnProperty.call(activation, primaryName)) return [];
+	const primary = activation[primaryName];
+	if (!primary || !Array.isArray(primary.tasks) || primary.tasks.length === 0) return [];
+
+	const primaryTasks = new Set(primary.tasks);
+	const candidates: Array<{ name: string; overlap: number }> = [];
+	for (const [name, candidate] of Object.entries(activation)) {
+		if (name === primaryName || (candidate.kind !== "workflow" && candidate.kind !== "behavioral")) continue;
+		const candidateTasks = new Set(candidate.tasks);
+		let overlap = 0;
+		for (const task of primaryTasks) if (candidateTasks.has(task)) overlap += 1;
+		if (overlap > 0) candidates.push({ name, overlap });
+	}
+	candidates.sort((left, right) =>
+		right.overlap - left.overlap || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0),
+	);
+	return candidates.map(({ name }) => name);
+}

package/src/aliases.ts

@@ -0,0 +1,111 @@
+export type QueryAliasMap = ReadonlyMap<string, readonly string[]>;
+export type AliasRecord = Record<string, string[]>;
+
+// Static, reviewed vocabulary only. Catalog filtering below prevents an alias
+// from adding terms that do not exist in the active catalog.
+export const CANDIDATE_QUERY_ALIASES: Readonly<Record<string, readonly string[]>> = Object.freeze({
+	ad: ["active", "directory", "kerberos", "ldap"],
+	adb: ["android", "mobile"],
+	apk: ["android", "mobile", "application"],
+	authn: ["authentication", "identity"],
+	authz: ["authorization", "permission"],
+	aws: ["cloud", "amazon"],
+	azure: ["cloud", "microsoft"],
+	binary: ["reverse", "reversing", "exploitation"],
+	bug: ["debug", "debugging", "defect"],
+	ci: ["cicd", "pipeline"],
+	cli: ["command", "shell"],
+	container: ["docker", "kubernetes"],
+	crack: ["cracking", "password", "hash"],
+	ctf: ["challenge", "exploit"],
+	db: ["database", "sql"],
+	debug: ["debugging", "gdb", "windbg"],
+	deploy: ["deployment", "release"],
+	docker: ["container"],
+	forensic: ["forensics", "artifact"],
+	fuzz: ["fuzzer", "fuzzing"],
+	git: ["github", "repository"],
+	incident: ["forensics", "response"],
+	js: ["javascript", "typescript", "node"],
+	k8s: ["kubernetes", "container"],
+	malware: ["reverse", "analysis"],
+	mobile: ["android", "ios", "application"],
+	network: ["packet", "traffic", "protocol"],
+	osint: ["intelligence", "reconnaissance"],
+	pentest: ["security", "assessment"],
+	plugin: ["extension"],
+	pr: ["pull", "request", "review"],
+	pwn: ["binary", "exploitation"],
+	py: ["python"],
+	recon: ["reconnaissance", "discovery", "enumeration"],
+	recover: ["recovery"],
+	refactor: ["architecture", "design"],
+	reverse: ["reversing", "analysis"],
+	rtk: ["output", "compression"],
+	sqli: ["sql", "injection"],
+	test: ["testing", "tests"],
+	token: ["context", "prompt"],
+	tunnel: ["pivot", "proxy"],
+	vuln: ["vulnerability", "security"],
+	web: ["http", "browser"],
+});
+
+const OVERBROAD_TARGETS = new Set(["app", "code", "file", "tool", "use", "workflow"]);
+
+function normalizeToken(value: string): string {
+	return value
+		.normalize("NFKD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.trim()
+		.toLocaleLowerCase("en-US")
+		.replace(/[^\p{L}\p{N}#+.-]+/gu, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+export function normalizeAliasRecord(value: unknown): AliasRecord {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+	const out: AliasRecord = {};
+	for (const [rawSource, rawTargets] of Object.entries(value)) {
+		const source = normalizeToken(rawSource);
+		if (!source || !Array.isArray(rawTargets)) continue;
+		const targets = [...new Set(rawTargets
+			.filter((target): target is string => typeof target === "string")
+			.map(normalizeToken)
+			.filter((target) => target && target !== source && !OVERBROAD_TARGETS.has(target)))];
+		if (targets.length > 0) out[source] = targets;
+	}
+	return out;
+}
+
+/** Build an immutable alias view scoped to one catalog. */
+export function buildCatalogAliases(
+	hasTerm: (term: string) => boolean,
+	extraCandidates: AliasRecord = {},
+): QueryAliasMap {
+	const candidates = { ...CANDIDATE_QUERY_ALIASES, ...normalizeAliasRecord(extraCandidates) };
+	const aliases = new Map<string, readonly string[]>();
+	for (const [source, rawTargets] of Object.entries(candidates)) {
+		const targets = [...new Set(rawTargets
+			.map(normalizeToken)
+			.filter((target) => target && !OVERBROAD_TARGETS.has(target) && hasTerm(target)))];
+		if (targets.length > 0) aliases.set(normalizeToken(source), Object.freeze(targets));
+	}
+	return aliases;
+}
+
+export function expandQueryTokens(tokens: readonly string[], aliases: QueryAliasMap): string[] {
+	const expanded: string[] = [];
+	const seen = new Set<string>();
+	for (const rawToken of tokens) {
+		const token = normalizeToken(rawToken);
+		if (!token || seen.has(token)) continue;
+		seen.add(token);
+		expanded.push(token);
+		for (const target of aliases.get(token) ?? []) {
+			if (seen.has(target)) continue;
+			seen.add(target);
+			expanded.push(target);
+		}
+	}
+	return expanded;
+}