akm-cli 0.9.13 → 0.9.14

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.9.14] - 2026-09-04
+
+### Added
+
+- **Long Markdown bodies can return the matching lexical fragment (#937).**
+  The derived index now keeps a separate, safe fragment population for lexical
+  retrieval. Search can return an addressable `#akm-fragment-…` ref, and `akm
+  show` resolves that ref to the exact indexed projection. Headingless and
+  oversized documents split at paragraph or word boundaries, so a fact in the
+  middle of a long body is no longer represented only by its parent document.
+
+### Changed
+
+- **Index generations are checked before use (#934).** A newer index is never
+  queried or rebuilt by an older binary; it reports that akm must be upgraded.
+  An older derived index is rebuilt from the materialized sources by the current
+  binary. A current-generation stamp is accepted only when the canonical entry,
+  parent FTS, and fragment surfaces all match, and the stamp is written only
+  after schema creation succeeds. This release advances the derived index from
+  v22 to v23 for fragment retrieval.
+- **Lexical relevance remains stable through scoring and relaxed-query ties
+  (#933, #940).** Lexical scores use a fixed monotone calibration rather than a
+  result-set-relative scale, preserving score headroom. Relaxed matches retain
+  body relevance as tie evidence, including when a belief-state ceiling also
+  applies. This compound-safe implementation supersedes PR #941.
+- **The frozen W0 lexical weight matrix remains the shipped policy (#930).**
+  The W1 and W2 alternatives were measured and rejected; no unvalidated weight
+  change is included in this release.
+
+### Fixed
+
+- **Fuzzy name matches require structural identity.** Short or opaque name
+  fragments no longer create a false identity match merely because their text
+  overlaps a stored name.
+- **Full indexing honors canonical workflow-source ownership.** When peer `.md`
+  and `.yml` sources map to one workflow ref, the index now persists the same
+  deterministic `.md` winner used by lookup and execution instead of allowing
+  filesystem enumeration order to select the stored row.
+
 ## [0.9.13] - 2026-09-04
 
 ### Added

package/dist/commands/improve/eligibility.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput, resolveRef } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
-import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
+import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { readEvents } from "../../core/events.js";
 import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
@@ -47,19 +47,11 @@ function describeIndexSnapshot(readOnly, status) {
             reason: readOnly ? "loaded a non-mutating point-in-time copy of the existing index" : "loaded the prepared index",
         };
     }
-    if (status === "missing") {
-        return {
-            status,
-            reason: readOnly
-                ? "index.db is missing; dry-run uses an empty snapshot and does not create it"
-                : "index.db is missing after index preparation; the selector uses an empty snapshot",
-        };
-    }
     return {
         status,
         reason: readOnly
-            ? "index.db has no entries table; dry-run uses an empty snapshot and does not migrate it"
-            : "index.db has no entries table; the selector uses an empty snapshot",
+            ? "index.db is missing; dry-run uses an empty snapshot and does not create it"
+            : "index.db is missing after index preparation; the selector uses an empty snapshot",
     };
 }
 function describeUnavailableSnapshot(error) {
@@ -68,6 +60,26 @@ function describeUnavailableSnapshot(error) {
         reason: `index.db cannot provide a stable non-mutating snapshot (${error.message}); dry-run uses an empty snapshot`,
     };
 }
+/**
+ * A dry-run is explicitly a non-mutating planning operation, so it may report
+ * an unusable derived index as an empty snapshot.  This is deliberately a
+ * typed boundary mapping: readers otherwise receive no incompatible handle,
+ * and we must not turn an arbitrary SQLite error into a successful plan by
+ * matching its text.
+ */
+function isIncompatibleIndexError(error) {
+    return error instanceof ConfigError && error.code === "INDEX_SCHEMA_INCOMPATIBLE";
+}
+function describeIncompatibleIndexSnapshot(error) {
+    // `INDEX_SCHEMA_INCOMPATIBLE` establishes that this is the derived-index
+    // boundary, and the error's hint preserves whether this binary should
+    // rebuild an older/unknown generation or upgrade for a newer one.
+    const action = error.hint() ?? error.message;
+    return {
+        status: "incompatible",
+        reason: `index.db is incompatible; ${action} Dry-run uses an empty snapshot and does not migrate it.`,
+    };
+}
 export function resolveImproveScope(scope) {
     const trimmed = scope?.trim();
     if (!trimmed)
@@ -194,12 +206,12 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
                     indexSnapshot: describeUnavailableSnapshot(error),
                 };
             }
-            if (error instanceof Error && /no such table:\s*entries/i.test(error.message)) {
+            if (readOnly && isIncompatibleIndexError(error)) {
                 return {
                     plannedRefs: [],
                     memorySummary: { eligible: 0, derived: 0 },
                     strategyFilteredRefs: [],
-                    indexSnapshot: describeIndexSnapshot(readOnly, "incompatible"),
+                    indexSnapshot: describeIncompatibleIndexSnapshot(error),
                 };
             }
             throw error;
@@ -300,12 +312,12 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
                 indexSnapshot: describeUnavailableSnapshot(error),
             };
         }
-        if (error instanceof Error && /no such table:\s*entries/i.test(error.message)) {
+        if (readOnly && isIncompatibleIndexError(error)) {
             return {
                 plannedRefs: [],
                 memorySummary: { eligible: 0, derived: 0 },
                 strategyFilteredRefs: [],
-                indexSnapshot: describeIndexSnapshot(readOnly, "incompatible"),
+                indexSnapshot: describeIncompatibleIndexSnapshot(error),
             };
         }
         throw error;

package/dist/commands/read/curate.js

@@ -529,8 +529,9 @@ function getCurateFamily(ref) {
     try {
         // F4b: `ref` is a search-hit ref in the 0.9.0 conceptId grammar — parse via
         // the new-grammar `parseRefInput` so skill/reference family grouping still
-        // recognizes it.
-        const parsed = parseRefInput(ref);
+        // recognizes it. Search may add an opaque Markdown selector; identity and
+        // family ownership are on the parent asset, not that selector.
+        const parsed = parseRefInput(ref.split("#", 1)[0]);
         if (parsed.type === "skill") {
             return { key: parsed.name, role: "root" };
         }

package/dist/commands/read/show.js

@@ -23,6 +23,7 @@ import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
+import { fragmentForSelector } from "../../core/asset/markdown-fragments.js";
 import { displayRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString, isWithin } from "../../core/common.js";
@@ -36,6 +37,7 @@ import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
 import { lookupBundleRef, lookupBundleRefWithResolution } from "../../indexer/indexer.js";
+import { projectMarkdownFragmentContent } from "../../indexer/passes/metadata.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries, } from "../../indexer/search/search-source.js";
 import { recentShowCount, recordShowUsage } from "../../indexer/usage/show-usage.js";
@@ -45,6 +47,7 @@ import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { resolveStorageLocations } from "../../storage/locations.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
+import { getIndexedMarkdownFragment } from "../../storage/repositories/index-fts-repository.js";
 import { computeBodyHash } from "../../storage/repositories/index-llm-cache-repository.js";
 // Eagerly import source providers to trigger self-registration.
 import "../../sources/providers/index.js";
@@ -76,9 +79,15 @@ export async function akmShowUnified(input) {
     // (env — key names only; secret — never rendered), fragment or not. Warn
     // and ignore the fragment rather than refusing the whole show.
     warnSensitiveFragmentUnsupported(parseBundleRef(ref));
-    // Auto-index when stale so the index is current before lookup.
-    const { primarySource } = resolveReadSources();
-    await ensurePrimaryIndexForRead(primarySource);
+    // An opaque fragment selector is an indexed revision handle. Do not refresh
+    // it away between search and show if disk changed concurrently; the stored
+    // safe substrate below is its source of truth. Friendly heading selectors
+    // intentionally retain the normal source-live read behavior.
+    const parsedRef = parseBundleRef(ref);
+    if (!parsedRef.fragment?.startsWith("akm-fragment-")) {
+        const { primarySource } = resolveReadSources();
+        await ensurePrimaryIndexForRead(primarySource);
+    }
     // Try local filesystem (FTS5 index lookup)
     const result = await showLocal(input);
     // Scope filter narrows resolution: if a scope filter was supplied, the
@@ -226,11 +235,14 @@ export async function showLocal(input) {
     }
     const fileCtx = buildFileContext(sourceStashDir, assetPath);
     const presentedName = indexedEntry.name;
+    const indexedFragment = parsed.fragment?.startsWith("akm-fragment-")
+        ? withIndexDb((db) => getIndexedMarkdownFragment(db, indexedEntry.itemRef, parsed.fragment))
+        : undefined;
     const indexedRenderer = rendererForIndexedEntry(indexedEntry, fileCtx);
     let response;
     try {
         if (indexedRenderer === null) {
-            response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment);
+            response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment, indexedFragment?.content);
         }
         else {
             const match = typeof indexedRenderer === "string" ? indexedMatch(indexedEntry, indexedRenderer) : recognizeMatch(fileCtx);
@@ -251,7 +263,7 @@ export async function showLocal(input) {
                     warn(`Fragment "#${parsed.fragment}" was ignored: ${makeBundleRef(parsed.bundle, parsed.conceptId)} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
                 }
                 else {
-                    applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName);
+                    applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName, indexedFragment?.content);
                 }
             }
         }
@@ -495,7 +507,7 @@ function rendererForIndexedEntry(entry, _file) {
 function indexedMatch(entry, renderer) {
     return { type: entry.type, specificity: Number.MAX_SAFE_INTEGER, renderer, meta: { name: entry.name } };
 }
-function buildIndexedProjectionResponse(entry, assetPath, fragment) {
+function buildIndexedProjectionResponse(entry, assetPath, fragment, indexedFragmentContent) {
     const isMarkdown = path.extname(assetPath).toLowerCase() === ".md";
     if (fragment !== undefined && !isMarkdown) {
         warn(`Fragment "#${fragment}" was ignored: ${entry.conceptId} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
@@ -503,7 +515,7 @@ function buildIndexedProjectionResponse(entry, assetPath, fragment) {
     const raw = fs.readFileSync(assetPath, "utf8");
     const parsed = parseFrontmatter(raw);
     const content = fragment !== undefined && isMarkdown
-        ? requireMarkdownSection(parsed.content, fragment, entry.name).content
+        ? (indexedFragmentContent ?? requireMarkdownSection(raw, fragment, entry.name).content)
         : parsed.content;
     const description = entry.document?.description ?? asNonEmptyString(parsed.data.description);
     const tags = entry.document?.tags ??
@@ -520,8 +532,8 @@ function buildIndexedProjectionResponse(entry, assetPath, fragment) {
         ...(tags && tags.length > 0 ? { tags } : {}),
     };
 }
-function applyMarkdownFragment(response, raw, fragment, name) {
-    const section = requireMarkdownSection(parseFrontmatter(raw).content, fragment, name).content;
+function applyMarkdownFragment(response, raw, fragment, name, indexedFragmentContent) {
+    const section = indexedFragmentContent ?? requireMarkdownSection(raw, fragment, name).content;
     if (response.template !== undefined)
         response.template = section;
     else if (response.prompt !== undefined)
@@ -533,6 +545,11 @@ function requireMarkdownSection(content, fragment, name) {
     const section = extractSection(content, fragment);
     if (section)
         return section;
+    const indexed = projectMarkdownFragmentContent(content);
+    const safeFragment = indexed ? fragmentForSelector(indexed, fragment) : undefined;
+    if (safeFragment) {
+        return { content: safeFragment.text, startLine: safeFragment.startLine, endLine: safeFragment.endLine };
+    }
     const available = markdownFragmentSlugs(content);
     throw new NotFoundError(`Fragment "#${fragment}" not found in ${name}.` +
         (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""));

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

@@ -81,7 +81,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, } from "../../../indexer/passes/metadata.js";
+import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "../../../indexer/passes/metadata.js";
 import { assetPathCandidatesForName, assetPathForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
@@ -244,6 +244,10 @@ function indexDocumentFromEntry(entry, base, rendererName) {
         doc.lessonStrength = entry.lessonStrength;
     if (entry.derivedFrom !== undefined)
         doc.derivedFrom = entry.derivedFrom;
+    // Internal fragment substrate follows the recognition projection without
+    // becoming an IndexDocument field or serialized search payload.
+    if (hasMarkdownFragmentContent(entry))
+        setMarkdownFragmentContent(doc, getMarkdownFragmentContent(entry));
     return doc;
 }
 function conceptIdForRecognizedType(root, filePath, type) {

package/dist/core/asset/markdown-fragments.js

@@ -0,0 +1,146 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+/**
+ * Deterministic, addressable Markdown fragments.
+ *
+ * Input is the safe, line-preserving Markdown projection, never the raw file.
+ * Keeping that distinction here means search can only emit selectors that
+ * `show` can reproduce without disclosing fenced/commented/link-target bytes.
+ */
+import { createHash } from "node:crypto";
+import { markdownHeadingSlug, parseMarkdownToc } from "./markdown.js";
+export const MARKDOWN_FRAGMENT_MAX_CHARS = 1600;
+export const MARKDOWN_FRAGMENT_PREFIX = "akm-fragment-";
+function hash(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function uniqueSlugs(body) {
+    const out = new Map();
+    const seen = new Set();
+    for (const heading of parseMarkdownToc(body).headings) {
+        const base = markdownHeadingSlug(heading.text);
+        if (!base)
+            continue;
+        let slug = base;
+        for (let suffix = 1; seen.has(slug); suffix++)
+            slug = `${base}-${suffix}`;
+        seen.add(slug);
+        out.set(heading.line, slug);
+    }
+    return out;
+}
+function textOf(lines) {
+    return lines.join("\n").trim();
+}
+/** Split a large sequence only at paragraph, then word, boundaries. */
+function splitPiece(piece, maxChars) {
+    if (textOf(piece.lines).length <= maxChars)
+        return [piece];
+    const pieces = [];
+    let start = 0;
+    while (start < piece.lines.length) {
+        let end = start;
+        let chars = 0;
+        while (end < piece.lines.length) {
+            const next = piece.lines[end];
+            // Let the single-line word-window path below own an oversized first
+            // line. Without this guard it is consumed whole before that path can
+            // run, silently defeating the fragment bound for transcripts/logs.
+            if (end === start && next.length > maxChars)
+                break;
+            if (end > start && chars + next.length + 1 > maxChars)
+                break;
+            chars += next.length + (end > start ? 1 : 0);
+            end++;
+        }
+        // A single long authored line needs word windows, but its source range is
+        // intentionally the same line for every window.
+        if (end === start) {
+            const line = piece.lines[start];
+            let offset = 0;
+            while (offset < line.length) {
+                let cut = Math.min(offset + maxChars, line.length);
+                if (cut < line.length) {
+                    const space = line.lastIndexOf(" ", cut);
+                    if (space > offset + Math.floor(maxChars * 0.55))
+                        cut = space;
+                }
+                pieces.push({ lines: [line.slice(offset, cut).trim()], startLine: piece.startLine + start });
+                offset = cut;
+                while (line[offset] === " ")
+                    offset++;
+            }
+            start++;
+            continue;
+        }
+        // Prefer not to split a paragraph if a blank boundary fits before `end`.
+        let preferred = -1;
+        for (let i = start + 1; i < end; i++)
+            if (!piece.lines[i].trim())
+                preferred = i;
+        if (preferred > start)
+            end = preferred;
+        pieces.push({ lines: piece.lines.slice(start, end), startLine: piece.startLine + start });
+        start = end;
+        while (start < piece.lines.length && !piece.lines[start].trim())
+            start++;
+    }
+    return pieces.filter((candidate) => textOf(candidate.lines));
+}
+/**
+ * Heading sections first, then paragraph/word windows. `startLine`/`endLine`
+ * always refer to the authored file's line numbers because the projection
+ * preserves one line per source line (with excluded bytes blanked out).
+ */
+export function splitMarkdownFragmentStats(body, maxChars = MARKDOWN_FRAGMENT_MAX_CHARS) {
+    const lines = body.split(/\r?\n/);
+    const headings = parseMarkdownToc(body).headings;
+    const boundaries = [1, ...headings.map((heading) => heading.line), lines.length + 1]
+        .filter((line, index, all) => index === 0 || line !== all[index - 1])
+        .sort((left, right) => left - right);
+    const slugs = uniqueSlugs(body);
+    const pieces = [];
+    let sectionCount = 0;
+    for (let i = 0; i < boundaries.length - 1; i++) {
+        const startLine = boundaries[i];
+        const end = boundaries[i + 1] - 1;
+        const section = { lines: lines.slice(startLine - 1, end), startLine, headingSlug: slugs.get(startLine) };
+        if (textOf(section.lines)) {
+            sectionCount++;
+            pieces.push(...splitPiece(section, maxChars));
+        }
+    }
+    // Whether a heading section survived as one fragment is a property of the
+    // complete piece set. Count once before materialization instead of scanning
+    // every piece for every fragment (which made many headed documents O(N²)).
+    const piecesPerHeading = new Map();
+    for (const piece of pieces) {
+        if (piece.headingSlug)
+            piecesPerHeading.set(piece.headingSlug, (piecesPerHeading.get(piece.headingSlug) ?? 0) + 1);
+    }
+    const fragments = pieces.map((piece, ordinal) => {
+        const text = textOf(piece.lines);
+        const contentLines = piece.lines.map((line, index) => ({ line, index })).filter(({ line }) => line.trim());
+        const first = contentLines[0]?.index ?? 0;
+        const last = contentLines.at(-1)?.index ?? 0;
+        const digest = hash(text);
+        const unsplitHeading = piece.headingSlug && piecesPerHeading.get(piece.headingSlug) === 1;
+        return {
+            fragmentId: `${MARKDOWN_FRAGMENT_PREFIX}${ordinal + 1}-${digest.slice(0, 12)}`,
+            ordinal,
+            startLine: piece.startLine + first,
+            endLine: piece.startLine + last,
+            ...(unsplitHeading ? { headingSlug: piece.headingSlug } : {}),
+            text,
+            hash: digest,
+        };
+    });
+    return { fragments, hardSplitCount: Math.max(0, pieces.length - sectionCount) };
+}
+export function splitMarkdownFragments(body, maxChars = MARKDOWN_FRAGMENT_MAX_CHARS) {
+    return splitMarkdownFragmentStats(body, maxChars).fragments;
+}
+export function fragmentForSelector(body, selector) {
+    return splitMarkdownFragments(body).find((fragment) => fragment.fragmentId === selector || fragment.headingSlug === selector);
+}

package/dist/core/lexical-score.js

@@ -0,0 +1,25 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+/** Dependency-safe fixed FTS5 calibration shared by storage and ranking. */
+const SCORE_FLOOR = 0.3;
+const PARENT_CEILING = 0.8;
+// Fragment BM25 is from a distinct FTS population. Its separately calibrated
+// ceiling is an explicit evidence policy, not a cross-table comparability claim:
+// when a body fragment independently proves the query, retain that actionable
+// selector beside the same parent's length-penalized whole-body row. Metadata
+// and cross-fragment conjunctions cannot enter this population.
+const FRAGMENT_CEILING = 0.8;
+const BM25_REFERENCE = 0.000001;
+const LOG_SHAPE = 3;
+export function stableFtsScore(bm25Score, population = "parent") {
+    const ceiling = population === "fragment" ? FRAGMENT_CEILING : PARENT_CEILING;
+    if (bm25Score === Number.NEGATIVE_INFINITY)
+        return ceiling;
+    if (!Number.isFinite(bm25Score) || bm25Score >= 0)
+        return SCORE_FLOOR;
+    const scaled = Math.log1p(-bm25Score / BM25_REFERENCE);
+    if (!Number.isFinite(scaled))
+        return ceiling;
+    return SCORE_FLOOR + (ceiling - SCORE_FLOOR) * (scaled / (scaled + LOG_SHAPE));
+}

package/dist/core/type-presentation.js

@@ -51,20 +51,41 @@ function buildWorkflowAction(ref) {
  * see the file header.
  */
 export const TYPE_PRESENTATION = {
-    skill: { label: "Skill", renderer: "skill-md", action: (ref) => `akm show ${ref} -> follow the instructions` },
+    skill: {
+        label: "Skill",
+        renderer: "skill-md",
+        action: (ref) => `akm show ${ref} -> follow the instructions`,
+        fragmentRef: false,
+    },
     command: {
         label: "Command",
         renderer: "command-md",
         action: (ref) => `akm show ${ref} -> fill placeholders and dispatch`,
+        fragmentRef: false,
+    },
+    agent: {
+        label: "Agent",
+        renderer: "agent-md",
+        action: (ref) => `akm show ${ref} -> dispatch with full prompt`,
+        fragmentRef: false,
     },
-    agent: { label: "Agent", renderer: "agent-md", action: (ref) => `akm show ${ref} -> dispatch with full prompt` },
     knowledge: {
         label: "Knowledge",
         renderer: "knowledge-md",
         action: (ref) => `akm show ${ref} -> read reference material`,
     },
-    workflow: { label: "Workflow", renderer: "workflow-md", action: (ref) => buildWorkflowAction(ref) },
-    script: { label: "Script", renderer: "script-source", action: (ref) => `akm show ${ref} -> execute the run command` },
+    workflow: {
+        label: "Workflow",
+        renderer: "workflow-md",
+        action: (ref) => buildWorkflowAction(ref),
+        fragmentRef: false,
+    },
+    script: {
+        label: "Script",
+        renderer: "script-source",
+        action: (ref) => `akm show ${ref} -> execute the run command`,
+        fragmentRef: false,
+    },
     memory: { label: "Memory", renderer: "memory-md", action: (ref) => `akm show ${ref} -> recall context` },
     env: {
         label: "Env",
@@ -85,6 +106,7 @@ export const TYPE_PRESENTATION = {
         label: "Task",
         renderer: "task-yaml",
         action: (ref) => `akm show ${ref} -> inspect; akm task run <id> -> run now; edit the file + akm task sync -> unschedule`,
+        fragmentRef: false,
     },
     session: {
         label: "Session",
@@ -105,6 +127,7 @@ export const TYPE_PRESENTATION = {
         label: "Instruction",
         renderer: "knowledge-md",
         action: (ref) => `akm show ${ref} -> read the project instructions`,
+        fragmentRef: false,
     },
 };
 /** Generic fallback for a type outside {@link KNOWN_TYPES} — never `undefined`, never a throw. */
@@ -120,6 +143,15 @@ export function presentationFor(type) {
         return TYPE_PRESENTATION[type];
     return DEFAULT_PRESENTATION;
 }
+/**
+ * A missing declaration means a read-like reference or foreign type can expose
+ * a safe selector. Built-in executable and instruction-bearing types opt out
+ * explicitly above: their search match can be a fragment, but the advertised
+ * action needs the parent canonical ref and its complete context.
+ */
+export function allowsFragmentRef(type) {
+    return presentationFor(type).fragmentRef !== false;
+}
 export const defaultRendererRegistry = {
     rendererNameFor(type) {
         return presentationFor(type).renderer;

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

@@ -31,6 +31,7 @@ import { closeDatabase, openExistingDatabase } from "../storage/repositories/ind
 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 { getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { buildFileContext } from "./walk/file-context.js";
@@ -158,6 +159,9 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
                         let entryWithSize = entry;
                         try {
                             entryWithSize = { ...entry, fileSize: fs.statSync(file).size };
+                            if (hasMarkdownFragmentContent(entry)) {
+                                setMarkdownFragmentContent(entryWithSize, getMarkdownFragmentContent(entry));
+                            }
                         }
                         catch {
                             // stat raced a delete — index without the size, like the full walk does.

package/dist/indexer/indexer.js

@@ -31,7 +31,7 @@ import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
-import { isEnrichmentComplete, isWorkflowSkipWarning } from "./passes/metadata.js";
+import { getMarkdownFragmentContent, hasMarkdownFragmentContent, isEnrichmentComplete, isWorkflowSkipWarning, setMarkdownFragmentContent, } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
@@ -1504,7 +1504,10 @@ export function createEnrichmentDeadline(timeoutMs, totalEntries) {
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function attachFileSize(entry, entryPath) {
     try {
-        return { ...entry, fileSize: fs.statSync(entryPath).size };
+        const sized = { ...entry, fileSize: fs.statSync(entryPath).size };
+        if (hasMarkdownFragmentContent(entry))
+            setMarkdownFragmentContent(sized, getMarkdownFragmentContent(entry));
+        return sized;
     }
     catch {
         return entry;

package/dist/indexer/passes/metadata.js

@@ -1179,6 +1179,67 @@ export function projectMarkdownContent(body, truncationInfo) {
         truncationInfo.truncated = text.length > MARKDOWN_CONTENT_MAX_CHARS;
     return truncateUnicodeSafe(text, MARKDOWN_CONTENT_MAX_CHARS);
 }
+// Fragment text is intentionally not an IndexDocument field. IndexDocument is
+// an adapter/search payload boundary; this is an internal, derived index input
+// that is persisted separately by the entries repository for deterministic FTS
+// rebuilds. The WeakMap follows the already-read document through recognition
+// without making safe body bytes observable through public payloads.
+const markdownFragmentContentByEntry = new WeakMap();
+const markdownFragmentProjectionEntries = new WeakSet();
+export function setMarkdownFragmentContent(entry, content) {
+    markdownFragmentProjectionEntries.add(entry);
+    if (content)
+        markdownFragmentContentByEntry.set(entry, content);
+}
+export function getMarkdownFragmentContent(entry) {
+    return markdownFragmentContentByEntry.get(entry);
+}
+export function hasMarkdownFragmentContent(entry) {
+    return markdownFragmentProjectionEntries.has(entry);
+}
+/**
+ * Produce a safe, structure-preserving projection for fragment indexing.
+ * Excluded source lines are retained as blank lines so fragment locations map
+ * exactly to authored line numbers. This must be called from both indexing and
+ * `show`; it deliberately never performs a storage-layer file reread.
+ */
+export function projectMarkdownFragmentContent(raw) {
+    const lines = raw.split(/\r?\n/);
+    const parsed = parseFrontmatter(raw);
+    const start = parsed.frontmatter ? parsed.bodyStartLine - 1 : 0;
+    const projected = lines.map(() => "");
+    let fence;
+    const htmlComment = { inComment: false };
+    for (let index = start; index < lines.length; index++) {
+        const rawLine = lines[index];
+        if (fence) {
+            if (isMarkdownFenceClosing(rawLine, fence))
+                fence = undefined;
+            continue;
+        }
+        if (!htmlComment.inComment) {
+            const opening = parseMarkdownFenceOpening(rawLine);
+            if (opening) {
+                fence = opening;
+                continue;
+            }
+        }
+        let safe = stripMarkdownHtmlComments(rawLine, htmlComment);
+        const opening = parseMarkdownFenceOpening(safe.trim());
+        if (opening) {
+            fence = opening;
+            continue;
+        }
+        // Reference link destinations and standalone HTML are not retrieval
+        // evidence and can contain credential-bearing URLs.
+        if (/^\s*\[[^\]]+\]:\s*\S+/.test(safe) || /^\s*<[^>]+>\s*$/.test(safe))
+            continue;
+        safe = stripMarkdownLinkDestinations(safe).replace(/<[^>]+>/g, " ");
+        projected[index] = safe.replace(/[ \t]+$/g, "");
+    }
+    const text = projected.join("\n");
+    return text.trim() ? text : undefined;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
 /**
  * Priorities 1-2 of the metadata pipeline — package.json (P1), `.md`
@@ -1220,7 +1281,9 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
         applyProvenanceFrontmatter(entry, parsed.data);
         // Native Markdown has one bounded low-weight body projection. Sensitive
         // types and raw session/checkpoint material never cross this boundary.
-        if (entry.type !== "env" && entry.type !== "session" && !hasSessionMemoryMarker(parsed.data, parsed.content)) {
+        const safeForFragments = entry.type !== "env" && entry.type !== "session" && !hasSessionMemoryMarker(parsed.data, parsed.content);
+        setMarkdownFragmentContent(entry, safeForFragments ? projectMarkdownFragmentContent(content) : undefined);
+        if (safeForFragments) {
             const truncationInfo = { truncated: false };
             const contentProjection = projectMarkdownContent(parsed.content, truncationInfo);
             if (contentProjection) {