akm-cli 0.10.261016-beta → 0.10.261017-beta

package/dist/core/adapter/adapters/dotenv-adapter.js

@@ -25,7 +25,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/dotenv/` + goldens
- * `tests/fixtures/format-family-goldens/dotenv/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/dotenv/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/generic-files-adapter.js

@@ -19,7 +19,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/generic-files/` + goldens
- * `tests/fixtures/format-family-goldens/generic-files/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/generic-files/{recognition,lint,renderer}.json`.
  */
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";

package/dist/core/adapter/adapters/llm-wiki-adapter.js

@@ -11,7 +11,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/llm-wiki/` + goldens
- * `tests/fixtures/format-family-goldens/llm-wiki/{recognition,placement,renderer,lint}.json`.
+ * `tests/fixtures/format-family-goldens/llm-wiki/{recognition,renderer,lint}.json`.
  * The adapter is built to MATCH those goldens (driven by
  * `tests/core/adapter/llm-wiki-adapter.test.ts`).
  *

package/dist/core/adapter/adapters/opencode-adapter.js

@@ -16,7 +16,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/opencode/` + goldens
- * `tests/fixtures/format-family-goldens/opencode/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/opencode/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/website-snapshot-adapter.js

@@ -22,7 +22,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/website-snapshot/` + goldens
- * `tests/fixtures/format-family-goldens/website-snapshot/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/website-snapshot/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/bundle-rename.js

@@ -6,7 +6,9 @@
  * bundle's key. A bundle id is a mass identity prefix: every durable ref this
  * tool minted (`entries.item_ref`/`bundle_id`, `proposals.ref`, a pending
  * proposal's `proposedTarget.source`, a workflow task_history row's
- * `target_ref`, a `workflow_runs.workflow_ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
+ * `target_ref`, a `workflow_runs.workflow_ref`, a `usage_events.entry_ref`, an
+ * `events.ref`, an `asset_salience`/`asset_outcome` `asset_ref`, an
+ * `improve_ledger.ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
  * `bundles` key strands all of it (see `src/indexer/bundle-identity-guard.ts`
  * §11.5). This module is the rekey transaction that guard's docstring points
  * to.
@@ -20,17 +22,17 @@
  * `akm mv`/editing territory, not a config-identity rename. `--dry-run`
  * (and every real run) lists the indexed files that still spell the old
  * `<old>//` prefix so the operator can follow up.
- *
- * Left behind on purpose: `usage_events`/`asset_salience`/`asset_outcome`
- * keyed by the old bundle prefix (learned utility/outcome history) — outside
- * this item's scope; `warnOnBundleRenameDrift` already documents this class
- * of gap and `akm index --full` re-mints under the new id.
  */
 import fs from "node:fs";
+import { renameUsageEventRefs } from "../indexer/usage/usage-events.js";
 import { readLockfile, renameLockEntry } from "../integrations/lockfile.js";
+import { renameEventRefs } from "../storage/repositories/events-repository.js";
+import { renameImproveLedgerRefs } from "../storage/repositories/improve-ledger-repository.js";
 import { closeDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
 import { getFilePathsByBundle, renameEntriesBundleId } from "../storage/repositories/index-entries-repository.js";
+import { renameAssetOutcomeRefs } from "../storage/repositories/outcome-repository.js";
 import { countProposalsForBundleRename, renameProposalsBundleRef } from "../storage/repositories/proposals-repository.js";
+import { renameAssetSalienceRefs } from "../storage/repositories/salience-repository.js";
 import { countTaskHistoryTargetRefs, renameTaskHistoryTargetRefs, } from "../storage/repositories/task-history-repository.js";
 import { countWorkflowRunRefsForRename, renameWorkflowRunRefs } from "../storage/repositories/workflow-runs-repository.js";
 import { selectBackend } from "../tasks/backends/index.js";
@@ -262,12 +264,20 @@ export async function renameBundle(oldId, newId, options = {}, deps) {
         }
     }
     // State: proposals.ref, a pending proposal's proposedTarget.source,
-    // workflow task_history.target_ref, and workflow_runs.workflow_ref.
+    // workflow task_history.target_ref, workflow_runs.workflow_ref, and the
+    // learned history keyed by item ref: usage_events.entry_ref (search ranking
+    // counts feedback by it), events.ref and improve_ledger.ref (improve reads
+    // feedback and its own attempts by them), and asset_salience/asset_outcome.asset_ref.
     if (fs.existsSync(getStateDbPath())) {
         withStateDb((db) => {
             renameProposalsBundleRef(db, oldId, newId);
             renameTaskHistoryTargetRefs(db, oldId, newId);
             renameWorkflowRunRefs(db, oldId, newId);
+            renameUsageEventRefs(db, oldId, newId);
+            renameEventRefs(db, oldId, newId);
+            renameImproveLedgerRefs(db, oldId, newId);
+            renameAssetSalienceRefs(db, oldId, newId);
+            renameAssetOutcomeRefs(db, oldId, newId);
         });
     }
     // Scheduler: remove native rows still naming `<old>//` (see

package/dist/indexer/bundle-identity-guard.js

@@ -2,7 +2,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * §11.5 bundle-rename startup guard.
+ * Bundle-rename startup guard.
  *
  * Renaming a workspace bundle id is a mass identity migration (every ref in the
  * bundle changes without any file moving) and MUST go through the
@@ -10,13 +10,13 @@
  * every ref-keyed state table atomically. If a user instead hand-edits the
  * `bundles` KEY in config.json, the durable index/state rows still carry the OLD
  * bundle prefix while the config names the NEW id. Silently re-minting fresh
- * state under the new id would strand the old rows; §11.5 requires we detect this
- * and refuse-or-warn.
+ * state under the new id would strand the old rows, so this guard detects it
+ * and warns.
  *
  * This guard implements the cheap heuristic form (WARN, never silently re-mint):
  * it compares the configured bundle ids against the DISTINCT `bundle_id`
- * (item_ref bundle prefix) values already persisted in the index — and, by
- * cutover construction, the same prefixes key the state.db usage/salience rows.
+ * (item_ref bundle prefix) values already persisted in the index — the same
+ * prefixes key the state.db usage/salience rows.
  * The hand-rename signature is: a configured bundle id with NO indexed rows
  * co-existing with indexed rows under a bundle id that is no longer configured.
  *
@@ -70,7 +70,7 @@ function indexedBundlePaths(dbPath) {
 }
 /**
  * Warn (once per process) when the config's bundle ids and the index's bundle
- * prefixes show the hand-rename signature (§11.5). No-op for an old-shape config
+ * prefixes show the hand-rename signature. No-op for an old-shape config
  * (no `bundles`), an absent/empty index, or when the guard already settled.
  */
 export function warnOnBundleRenameDrift(config = loadConfig()) {

package/dist/indexer/index-written-assets.js

@@ -31,7 +31,7 @@ import { warn, warnVerbose } from "../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { deleteEntriesByIds, getEntryCount, upsertEntry } from "../storage/repositories/index-entries-repository.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
-import { generateEmbeddingsForDb, publishTargetedEmbeddingMeta } from "./materialize-embeddings.js";
+import { embeddingInputCap, generateEmbeddingsForDb, publishTargetedEmbeddingMeta } from "./materialize-embeddings.js";
 import { withFileSize } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildFileContext } from "./walk/file-context.js";
@@ -153,6 +153,7 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
             db.exec(`PRAGMA busy_timeout = ${WRITE_PATH_INDEX_BUSY_TIMEOUT_MS}`);
             if (getEntryCount(db) === 0)
                 return true;
+            const config = loadConfig();
             const targetEntryIds = new Set();
             let mutated = false;
             db.transaction(() => {
@@ -194,12 +195,11 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
                         .prepare("SELECT id FROM entries WHERE file_path = ? AND item_ref <> ?")
                         .all(file, provenance.itemRef);
                     deleteEntriesByIds(db, supersededIds.map((row) => row.id));
-                    targetEntryIds.add(upsertEntry(db, file, entryWithSize, provenance, contentHash));
+                    targetEntryIds.add(upsertEntry(db, file, entryWithSize, provenance, contentHash, embeddingInputCap(config)));
                     mutated = true;
                 }
             })();
             if (mutated) {
-                const config = loadConfig();
                 await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
                 publishTargetedEmbeddingMeta(db, config);
             }

package/dist/indexer/indexer.js

@@ -28,9 +28,9 @@ import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from
 import { reclassifyIndexDbContention } from "./index-db-contention.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveConceptOwner } from "./lookup/adapter-concept-owner.js";
-import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
+import { embeddingInputCap, generateEmbeddingsForDb } from "./materialize-embeddings.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
-import { isWorkflowSkipWarning, withFileSize } from "./passes/metadata.js";
+import { CONTENT_PROJECTION_VERSION, isWorkflowSkipWarning, withFileSize, } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { purgeOldUsageEvents, USAGE_EVENT_RETENTION_DAYS } from "./usage/usage-events.js";
 import { SEMANTIC_SEARCH_META_KEY, } from "./walk/index-context.js";
@@ -446,7 +446,7 @@ async function akmIndexReal(options) {
         // …then write it in one transaction: `item_ref = <bundle>//<conceptId>`
         // plus canonical component/adapter provenance per source root.
         const bundleByRoot = buildIndexedSourceOwners(sources);
-        persistDirRecords(db, dirRecords, warnings, bundleByRoot);
+        persistDirRecords(db, dirRecords, warnings, bundleByRoot, embeddingInputCap(config));
         onProgress({
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -819,7 +819,9 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             warn(`Skipping component "${component.id}": unknown adapter id "${component.adapter}".`);
             continue;
         }
-        const indexVariant = `${adapter.id}@${adapter.version}`;
+        // The content projection's version is part of the variant: a change to what Markdown bodies index re-projects
+        // every directory once instead of keeping the old text for unchanged files.
+        const indexVariant = `${adapter.id}@${adapter.version}+content${CONTENT_PROJECTION_VERSION}`;
         for (const removal of removals) {
             dirRecords.push(removal);
             scannedDirs++;
@@ -938,7 +940,7 @@ function requiresWorkflowSourcePreflight(ctxs) {
     });
 }
 /** Phase 2 (sync): write all pre-generated scan records inside a single transaction. */
-function persistDirRecords(db, dirRecords, warnings, bundleByRoot) {
+function persistDirRecords(db, dirRecords, warnings, bundleByRoot, maxInputTokens) {
     const deletedUsageEntryIds = new Set();
     const findPersisted = db.prepare("SELECT id, content_hash, file_path, adapter_id FROM entries WHERE item_ref = ?");
     const insertTransaction = db.transaction(() => {
@@ -1038,7 +1040,7 @@ function persistDirRecords(db, dirRecords, warnings, bundleByRoot) {
                     if (unchanged) {
                         continue;
                     }
-                    upsertEntry(db, entryPath, withFileSize(entry, entryPath), provenance, contentHash);
+                    upsertEntry(db, entryPath, withFileSize(entry, entryPath), provenance, contentHash, maxInputTokens);
                 }
             }
             // Prune the departed rows: everything under this dir NOT re-upserted above
@@ -1332,8 +1334,10 @@ export function recomputeUtilityScores(db, stateDb, onlyEntryId) {
     // (Chunk-8 WI-8.3); its table is created by state migration 020.
     if (!scoped)
         purgeOldUsageEvents(stateDb, USAGE_EVENT_RETENTION_DAYS);
-    // Time-proportional decay: apply one round of EMA per elapsed day so
-    // indexing frequency doesn't affect how fast scores decay.
+    // Decay is raised to the days since the last run, floored at one day. Every
+    // run therefore applies at least one full round of EMA decay (so runs less
+    // than a day apart each decay a full round), and a longer gap applies
+    // proportionally more rounds. The first run counts as one day.
     const lastComputedAt = getMeta(db, "last_utility_computed_at");
     let elapsedDays = 1; // default for first run
     if (lastComputedAt) {

package/dist/indexer/materialize-embeddings.js

@@ -32,6 +32,13 @@ export function deriveSemanticProviderFingerprint(embedding) {
     }
     return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}${template}`;
 }
+/**
+ * The most estimated tokens of an entry's search text that are embedded
+ * (`embedding.maxInputTokens`); the rest of the text never reaches the embedder.
+ */
+export function embeddingInputCap(config) {
+    return effectiveEmbedding(config)?.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS;
+}
 /**
  * The heartbeat text emitted every 15s while a provider request is in
  * flight, and by default (not `--verbose`-only) since silence indistinguishable
@@ -103,7 +110,7 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
     let targetEntryIds = entryIds;
     /** Set only when every entry is (re)embedded, so the up-front "Re-embedding N entries" line names why. */
     let rebuildReason;
-    const maxInputTokens = embedding?.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS;
+    const maxInputTokens = embeddingInputCap(config);
     if (opts?.forceReembed) {
         // The explicit operator override: purge and re-embed everything. The model
         // is recorded in the SAME transaction as the purge, before any embedding
@@ -171,9 +178,12 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
             const message = `[embed] Re-embedding ${pendingEntries.length} entr${pendingEntries.length === 1 ? "y" : "ies"} because ${rebuildReason}`;
             onProgress({ phase: "embeddings", message });
         }
+        // Names the size of the work before the first request, so a first index after an upgrade that
+        // re-embeds part of the corpus is not mistaken for a hang.
+        const unchangedCount = Math.max(0, getEmbeddableEntryCount(db) - pendingEntries.length);
         onProgress({
             phase: "embeddings",
-            message: `Generating embeddings for ${pendingEntries.length} entr${pendingEntries.length === 1 ? "y" : "ies"}.`,
+            message: `Embedding ${pendingEntries.length.toLocaleString()} changed entr${pendingEntries.length === 1 ? "y" : "ies"} (${unchangedCount.toLocaleString()} unchanged)`,
         });
         // Per-document sizes; the provider's actual request grouping is reported
         // per batch below (and each skipped document is listed at the end).

package/dist/indexer/passes/metadata.js

@@ -136,7 +136,7 @@ export function validateStashEntry(entry) {
     const sources = normalizeNonEmptyStringList(e.sources);
     if (sources)
         result.sources = sources;
-    // SPEC-6: `category` must survive the projection. Non-string values are
+    // `category` must survive the projection. Non-string values are
     // dropped, not coerced.
     if (typeof e.category === "string" && e.category.trim().length > 0) {
         result.category = e.category.trim();
@@ -346,7 +346,7 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const quality = asNonEmptyString(fmData.quality);
     if (quality)
         entry.quality = normalizeQuality(quality);
-    // SPEC-6 capture step: the `category:` frontmatter key (e.g. `convention`,
+    // Capture the `category:` frontmatter key (e.g. `convention`,
     // `meta` on facts) must land on the indexed entry so category-keyed
     // policies can see it. Trimmed; blank/non-string values are ignored.
     const category = asNonEmptyString(fmData.category);
@@ -384,13 +384,13 @@ export function applyCuratedFrontmatter(entry, fmData) {
         entry.evidenceSources = evidenceSources;
     if (typeof fmData.evidence === "string" && fmData.evidence.trim().length > 0)
         entry.evidence = fmData.evidence;
-    // Phase 5A / Advantage D5: capture parent ref for derived memories.
+    // Capture the parent ref for derived memories.
     // Memory-inference writes `source: "memories/<parent>"` and `inferred: true`
     // (and a derived child name suffix `.derived`). We mirror that source ref into
     // `entry.derivedFrom` so the indexer can populate the dedicated `derived_from`
-    // column. Group-C item 2: the column is stored in the 0.9.0 `memories/<name>`
-    // conceptId grammar — moving in lockstep with the `getDerivedForParent` lookup
-    // key (search-hit-enrichers) so producer + consumer speak one grammar.
+    // column. The column is stored as the `memories/<name>` conceptId, matching
+    // the `getDerivedForParent` lookup key (search-hit-enrichers) so producer and
+    // consumer speak one grammar.
     // Non-derived entries leave this field unset.
     if (entry.type === "memory") {
         const isDerivedByName = entry.name.toLowerCase().endsWith(".derived");
@@ -473,7 +473,7 @@ function isWikiRole(value) {
 /**
  * Parse one `verified:` family value into the `IndexDocument.provenance` shape.
  * Accepts OKF v0.2's list form and its documented single-mapping shorthand
- * ("consumers MUST treat a bare mapping as a one-element list", per OKF v0.2).
+ * ("consumers MUST treat a bare mapping as a one-element list", OKF v0.2 §5.2).
  * Tolerant: an entry without a usable `by` is dropped individually.
  */
 function parseVerifiedFamily(value) {
@@ -491,9 +491,9 @@ function parseVerifiedFamily(value) {
 }
 /**
  * Extract the OKF v0.2 provenance families that `promoteProposal` stamps onto
- * accepted AKM-native proposals (D2, #730), and apply them to the entry.
+ * accepted AKM-native proposals (#730), and apply them to the entry.
  *
- * The on-disk shape is deliberately **hybrid** (owner decision, #730 review):
+ * The on-disk shape is deliberately **hybrid** (#730 review):
  * `generated:` and `verified:` are stamped BARE at the top level, exactly as
  * OKF v0.2 spells them, because neither has any pre-existing AKM consumer — so
  * a third-party OKF v0.2 reader treating an AKM stash as an OKF bundle sees
@@ -505,8 +505,8 @@ function parseVerifiedFamily(value) {
  * non-strings).
  *
  * The nested `provenance.generatedBy` / `.generatedAt` / `.verified` spellings
- * are still read as a fallback so assets stamped by an earlier build of this
- * branch keep resolving. Tolerant throughout: any malformed sub-field is
+ * are still read as a fallback so assets stamped by an earlier build keep
+ * resolving. Tolerant throughout: any malformed sub-field is
  * dropped individually rather than rejecting the whole block.
  */
 export function applyProvenanceFrontmatter(entry, fmData) {
@@ -545,8 +545,8 @@ export function applyProvenanceFrontmatter(entry, fmData) {
         entry.provenance = result;
 }
 // AKM-stash indexing policy (env/vaults/secrets sensitive-marker + wiki-infra
-// exclusions) moved to the `akm` adapter's `recognize` as path/stat-based
-// abstention (owner ruling 2026-07-21 — adapter-owned filtering). See
+// exclusions) lives in the `akm` adapter's `recognize` as path/stat-based
+// abstention. See
 // `akmStashAbstains` in `src/core/adapter/adapters/akm-adapter.ts`.
 /**
  * Extract `@param` JSDoc tags from a script file's leading comment block.
@@ -764,11 +764,9 @@ function mergeAliases(existing, generated) {
 /**
  * Maximum native Markdown prose carried by the low-weight `content` field.
  *
- * Raised far past any real authored document:
- * this used to sit at 16_384 chars, tight enough that ordinary long-form
- * skills/knowledge docs lost their tail from both FTS and the embedding
- * input with no visible signal (the cut was reported via `warnVerbose`,
- * silent unless `AKM_VERBOSE` was set). The remaining bound exists only to
+ * Set far past any real authored document, so ordinary long-form
+ * skills/knowledge docs never lose their tail from FTS or the embedding
+ * input. The bound exists only to
  * stop a truly pathological single file (a committed data dump, a decompressed
  * log) from ballooning index size — not to shave real content — so a caller
  * that hits it is always told, unconditionally.
@@ -873,6 +871,58 @@ function isMarkdownFenceClosing(line, fence) {
         return false;
     return /^[\t ]*$/.test(line.slice(cursor));
 }
+/**
+ * Version of what {@link projectMarkdownContent} indexes. It is part of every
+ * directory's index fingerprint, so bumping it makes the next `akm index`
+ * re-project every directory once instead of keeping the old text for
+ * unchanged files. 2: identifiers from fenced code (akm#1260).
+ */
+export const CONTENT_PROJECTION_VERSION = 2;
+/** At or above this length a token with a digit reads as a key or hash, not a name. */
+const TOKEN_LIKE_MIN_LENGTH = 20;
+/**
+ * The searchable identifiers of one line of fenced code, without its literal
+ * values (akm#1260). Fenced code holds the names agents look for (functions,
+ * classes, CLI flags, config keys, environment variable names, paths) and
+ * also example secrets, so it keeps names and drops values:
+ *
+ * - a quoted string survives only as a key (`"name":`) or an absolute path;
+ *   every other quoted literal is dropped;
+ * - the value of an assignment (`KEY=value`, `key: value`, `"key": value`,
+ *   `Authorization: Bearer token`) is dropped unless it is a dotted code
+ *   reference (`process.env.CI`); the name stays;
+ * - long token-like strings with digits (keys, hashes) are dropped, base64
+ *   included: its `/`, `+` and `=` do not cut it into short kept pieces;
+ * - camelCase, snake_case, dotted and dashed names also add their parts.
+ *
+ * Numbers, punctuation and operators never reach the result.
+ */
+export function fencedCodeIdentifiers(line) {
+    const cleaned = line
+        .replace(/(["'`])((?:\\.|(?!\1).)*)\1(\s*:)?/g, (match, _quote, body, colon, offset) => {
+        // Keep a key's colon when an unquoted value follows, so the assignment rule below drops that value.
+        if (colon)
+            return /^\s*["'`]/.test(line.slice(offset + match.length)) ? ` ${body} ` : ` ${body}: `;
+        return /^\/[\w./-]+$/.test(body) ? ` ${body} ` : " ";
+    })
+        .replace(/([A-Za-z_][A-Za-z0-9_.-]*\s*[:=]\s*)((?:[Bb]earer|[Bb]asic|[Tt]oken|[Dd]igest)\s+\S+|\S+)/g, (_match, name, value) => /^[!(]*[A-Za-z_][\w$]*(?:\.[A-Za-z_][\w$]*)+[()\]}]*[,;]?$/.test(value) ? `${name} ${value}` : name)
+        // Base64 is one token: its `/`, `+` and `=` would otherwise cut a key body into short pieces that are kept.
+        .replace(/(?<![\w.-])[A-Za-z0-9+/=]{20,}(?![\w.-])/g, (run) => /[a-z]/.test(run) && /[A-Z]/.test(run) && /\d/.test(run) ? " " : run);
+    const words = [];
+    for (let token of cleaned.match(/--?[A-Za-z][A-Za-z0-9-]*|[A-Za-z_][A-Za-z0-9_.-]*/g) ?? []) {
+        token = token.replace(/[.-]+$/, "");
+        const bare = token.replace(/^-+/, "");
+        if (bare.length < 2)
+            continue;
+        if (bare.length >= TOKEN_LIKE_MIN_LENGTH && /\d/.test(bare))
+            continue;
+        words.push(token);
+        const parts = bare.split(/[_.-]|(?<=[a-z0-9])(?=[A-Z])/).filter((part) => part.length > 1);
+        if (parts.length > 1)
+            words.push(...parts);
+    }
+    return words.join(" ");
+}
 function stripMarkdownHtmlComments(line, state) {
     let cursor = 0;
     let visible = "";
@@ -1048,17 +1098,23 @@ function stripMarkdownLinkDestinations(text, nesting = 0) {
 }
 /**
  * Derive the one low-weight search projection for an AKM-native Markdown body.
- * Frontmatter is removed by the caller. This projection drops comments,
- * fenced code, raw link targets, and structural punctuation while retaining
- * prose, headings, link labels, and inline identifiers. It never receives
- * secret/env/session bytes; that policy is enforced at the adapter metadata
- * boundary below.
+ * Frontmatter is removed by the caller. This projection drops comments, raw
+ * link targets, and structural punctuation while retaining prose, headings,
+ * link labels, and inline identifiers. From fenced code it keeps only the
+ * identifiers ({@link fencedCodeIdentifiers}): names, flags, keys and paths,
+ * never literal values (akm#1260). It never receives secret/env/session bytes;
+ * that policy is enforced at the adapter metadata boundary below.
+ *
+ * Changing what this returns changes the indexed text of every Markdown entry,
+ * so bump {@link CONTENT_PROJECTION_VERSION} with it: the indexer re-projects
+ * every directory once on the next `akm index`.
  */
 export function projectMarkdownContent(body, truncationInfo) {
     const lines = body.split(/\r?\n/);
     const innerBlock = findInnerFrontmatterBlock(lines);
     const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
     const projected = [];
+    const fenced = [];
     forEachVisibleMarkdownLine(lines, start, (_index, visible) => {
         let trimmed = visible.trim();
         if (!trimmed || /^(-{3,}|\*{3,}|_{3,}|=+)$/.test(trimmed))
@@ -1077,8 +1133,13 @@ export function projectMarkdownContent(body, truncationInfo) {
         trimmed = trimmed.replace(/\s+/g, " ").trim();
         if (trimmed)
             projected.push(trimmed);
+    }, (_index, fencedLine) => {
+        const identifiers = fencedCodeIdentifiers(fencedLine);
+        if (identifiers)
+            fenced.push(identifiers);
     });
-    const text = projected.join(" ").replace(/\s+/g, " ").trim();
+    // Fenced identifiers follow the prose, so a head-truncated embedding input keeps the prose first.
+    const text = [...projected, ...fenced].join(" ").replace(/\s+/g, " ").trim();
     if (!text)
         return undefined;
     if (truncationInfo)
@@ -1088,8 +1149,10 @@ export function projectMarkdownContent(body, truncationInfo) {
 /**
  * Visit each line from `start` that lies outside fenced code, with HTML
  * comments removed (`visible`); fence lines themselves are never visited.
+ * `visitFenced`, when given, receives each raw line inside a fence (not the
+ * opening or closing fence line), from the same fence state.
  */
-function forEachVisibleMarkdownLine(lines, start, visit) {
+function forEachVisibleMarkdownLine(lines, start, visit, visitFenced) {
     let fence;
     const htmlComment = { inComment: false };
     for (let index = start; index < lines.length; index += 1) {
@@ -1097,6 +1160,8 @@ function forEachVisibleMarkdownLine(lines, start, visit) {
         if (fence) {
             if (isMarkdownFenceClosing(rawLine, fence))
                 fence = undefined;
+            else
+                visitFenced?.(index, rawLine);
             continue;
         }
         // A leading fence owns the whole line, including any info string that
@@ -1174,13 +1239,12 @@ export function projectMarkdownFragmentContent(raw) {
 /**
  * Priorities 1-2 of the metadata pipeline — package.json (P1), `.md`
  * frontmatter (P2), and script `@param`/comment metadata (P2b) — everything
- * that runs BEFORE the renderer-contributor step (P3). Extracted (Chunk 5 M-b)
- * so the `akm` adapter's synchronous `recognize` shares this exact assembly
- * with the live index-drain path; the two differ ONLY in how they obtain the
+ * that runs BEFORE the renderer-contributor step (P3). Shared by the `akm`
+ * adapter's synchronous `recognize` and the live index-drain path; the two
+ * differ ONLY in how they obtain the
  * P3 renderer metadata (the adapter uses the synchronous
  * `foldRecognizedMetadata`), guaranteeing P1/P2/P4 parity by construction.
- * Behavior-preserving: this is a verbatim lift of the former inline P1/P2/P2b
- * block. Mutates `entry` in place.
+ * Mutates `entry` in place.
  */
 export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
     const ext = path.extname(file).toLowerCase();
@@ -1207,7 +1271,7 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
             entry.parameters = fmParams;
         // Pass wiki-pattern frontmatter through onto the entry
         applyWikiFrontmatter(entry, parsed.data);
-        // D2 (#730): reread the namespaced `provenance:` block promoteProposal stamps.
+        // #730: reread the namespaced `provenance:` block promoteProposal stamps.
         applyProvenanceFrontmatter(entry, parsed.data);
         // Native Markdown has one bounded low-weight body projection. Sensitive
         // types and raw session/checkpoint material never cross this boundary.
@@ -1220,7 +1284,7 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
                 entry.content = contentProjection;
                 if (truncationInfo.truncated) {
                     entry.contentTruncated = true;
-                    // Unconditional, not warnVerbose: this bound now sits far past any
+                    // Unconditional, not warnVerbose: this bound sits far past any
                     // real document, so tripping it means
                     // something unusual is in the bundle and the operator should see
                     // it without having to pass --verbose.
@@ -1252,8 +1316,8 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
  * Priority 4 of the metadata pipeline — filename-heuristic fallbacks (P4) that
  * run AFTER the renderer-contributor step (P3): a filename description when none
  * was set, path/dir-derived tags, tag normalization, and alias generation.
- * Extracted (Chunk 5 M-b) alongside {@link applyPreContributorFields} so both
- * pipeline paths share it. Behavior-preserving verbatim lift. Mutates `entry`.
+ * Shared with {@link applyPreContributorFields} by both pipeline paths.
+ * Mutates `entry`.
  */
 export function applyPostContributorFields(entry, file, canonicalName, dirPath) {
     const ext = path.extname(file).toLowerCase();
@@ -1267,7 +1331,7 @@ export function applyPostContributorFields(entry, file, canonicalName, dirPath)
     if (!entry.tags || entry.tags.length === 0) {
         entry.tags = extractTagsFromPath(file, dirPath);
     }
-    // Stash-organization conventions (SPEC-2): directory (scope/domain) tokens
+    // Stash-organization conventions: directory (scope/domain) tokens
     // always reach the tags column, even when the author set explicit tags, so
     // nested assets keep the exact-tag ranking boost for their scope token.
     // Derived from canonicalName (the ref subpath) rather than the filesystem
@@ -1284,13 +1348,6 @@ export function applyPostContributorFields(entry, file, canonicalName, dirPath)
     // Heuristic search hints are too noisy to be useful for search quality
     entry.filename = path.basename(file);
 }
-// The pre-0.9.0 flat-walk matcher-pass metadata source was DELETED in Chunk 5
-// F4a M-core-3. Its role (recognize a stash root's files into durable entries)
-// is now the `akm` adapter's `recognize`, drained by `indexer/scan/drain-dir.ts`
-// (`drainDirDocuments` for the live indexer, `recognizeStashEntries` for the
-// `manifest` fallback / `registry` index builder / metadata unit tests). The
-// flip is the F4 engine swap; the shadow-parity gate proved recognize produced
-// the identical entries before the old pass was removed.
 export function buildMetadataSkipWarning(filePath, assetType, error) {
     const detail = error instanceof Error ? error.message : String(error);
     // Workflow errors are already multi-line `path:line — message` blocks; print
@@ -1327,9 +1384,9 @@ function normalizeTerms(values) {
         if (!cleaned)
             continue;
         normalized.add(cleaned);
-        // De-pluralization heuristic removed: the FTS5 porter stemmer (configured
-        // with `tokenize='porter unicode61'`) handles stemming correctly, including
-        // edge cases like "kubernetes" and "status" that the naive s-strip mangled.
+        // No de-pluralization here: the FTS5 porter stemmer (configured with
+        // `tokenize='porter unicode61'`) handles stemming correctly, including
+        // edge cases like "kubernetes" and "status" that a naive s-strip mangles.
     }
     return Array.from(normalized);
 }
@@ -1437,7 +1494,7 @@ export function extractTagsFromPath(filePath, rootDir) {
  * Unlike {@link extractTagsFromPath} this never tokenizes the filename
  * segment: it exists so a nested asset's directory (scope/domain) tokens can
  * be merged into explicit author tags without dragging every filename word
- * into exact-tag matching (SPEC-2, docs/architecture/specs/stash-conventions-code-spec.md).
+ * into exact-tag matching.
  * Tokenization mirrors `extractTagsFromPath`: each segment splits on `-`/`_`/
  * `.`, lowercased, single-character tokens dropped. A name with no directory
  * segments yields no tags.

package/dist/indexer/search/ranking.js

@@ -41,9 +41,13 @@ export function reciprocalRankFusion(channels) {
  * 1 + w·(ln(1+pos) − ln(1+neg)) moves a score by about 2% / 3% / 5% / 9% for
  * 1 / 2 / 5 / 20 positives at 0.03. Measured on the retrieval suite's fused
  * lists, 5 positives lift a hit from rank 10 by a median of 3 places (from rank 5,
- * by 2) and 20 by 4 to 5, so a voted hit passes its near neighbours and a clearly
- * better match stays ahead. At 0.05 the same votes lift it 4 to 5 and 6 to 7
- * places, and two wrong votes cost about 1.6 times the nDCG@10 they cost at 0.03.
+ * by 2) and 20 by 4 to 5. What a vote can pass depends on the channels. In
+ * keyword-only search every fused score is exactly 1 / (RRF_K + rank), so
+ * neighbours in the first 20 sit 1.3 to 1.6% apart and one vote (about 2%) moves
+ * a hit one place (through rank 38) whatever the keyword margin between them. When both channels contribute, their
+ * ranks spread the scores and a vote passes only near-ties. At 0.05 the same
+ * votes lift it 4 to 5 and 6 to 7 places, and two wrong votes cost about 1.6
+ * times the nDCG@10 they cost at 0.03.
  */
 export const FEEDBACK_WEIGHT = 0.03;
 /**

package/dist/indexer/search/search-fields.js

@@ -13,7 +13,7 @@
  *  - tags: tags + aliases joined
  *  - hints: searchHints + examples + usage + intent fields
  *  - content: bounded native/adapter body projection + TOC headings + parameters
- *    (lowest-weight catch-all)
+ *    (the catch-all; BM25 weighs all five fields equally)
  */
 export function buildSearchFields(entry) {
     const name = entry.name.replace(/[-_]/g, " ");