akm-cli 0.9.12 → 0.9.14-beta.1

package/CHANGELOG.md

@@ -4,6 +4,106 @@ 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-beta.1] - 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
+
+- **A stable `results` alias on every list-returning command (#922).** `search`,
+  `curate`, `proposal list`, `bundle list`, `env list`, `secret list`,
+  `registry search`, `registry list`, `workflow list`, `task history` and
+  `log list` each keep their existing semantic key (`hits`, `items`,
+  `proposals`, …) and now also expose the same array as `results`, in every
+  shape including `--shape agent`. It is the same array, not a copy. A caller
+  reading `hits` from a `curate` response previously got nothing back and could
+  reasonably read that as "no results" — there was no error and the `summary`
+  alongside it still reported that results were selected. Commands carrying
+  several heterogeneous collections (`health`, `task doctor`) are deliberately
+  excluded.
+- **Engine and embedding credentials can resolve from the secret store
+  (#917).** `apiKey` accepts `secret://<name>` alongside `$VAR` / `${VAR}`,
+  resolved through the existing store-backed resolver. A detached SessionEnd
+  hook or a cron job — the two contexts least able to supply an environment
+  variable and most likely to need extraction — no longer requires editing the
+  login environment for a value akm already stores. Literal keys in
+  `config.json` are still refused, and an unresolvable reference fails loudly,
+  naming the reference and never the secret.
+- **`akm proposal drain` reports what failed (#921).** The envelope carries a
+  `failed[]` naming each proposal and why it was refused (stale target,
+  validation), instead of reporting `failed: 0` while the same run printed five
+  failures to stderr. `--dry-run` now applies the same stale-target check the
+  real run does, so its prediction stops disagreeing with the outcome. The
+  refusals themselves are correct and unchanged: declining to overwrite a target
+  modified since the proposal was created is the desired behaviour. `akm
+  improve`'s triage pre-pass reports the same count.
+- **Workflow step output is checked against its declared schema (#923).** A step
+  whose returned object does not match its `outputSchema` now says so, naming
+  the step and the specific problem (a missing required field, say). This is a
+  warning: the run continues and its status is unchanged, because a workflow is
+  a guide rather than a contract. Previously an author got neither enforcement
+  nor feedback — the only signal was a notice saying akm was not checking, which
+  is a different fact from whether the output matched.
+
+### Changed
+
+- **A held run lease no longer reports as database corruption (#924).** `akm
+  workflow run` surfaced raw SQLite text — `database is locked`, `database disk
+  image is malformed`, `disk I/O error` — for what was simply another
+  invocation holding the lease. `disk image is malformed` in particular reads as
+  data loss and sent one reporter through integrity checks and a WAL review
+  before finding the real cause. The lease message now appears at default
+  verbosity and carries a dedicated `RUN_LEASE_HELD` code, so a wrapper can tell
+  "retry shortly" from "you passed bad input". Genuine SQLite errors still
+  report as themselves.
+- **`akm lint` stops flagging templated output paths (#927).** A documented
+  run-time filename such as `reports/review-<timestamp>.md` is no longer
+  reported as a `stale-path` broken reference. Angle-bracket and brace
+  placeholders, `${VAR}`, date-format runs like `YYYYMMDD`, and glob characters
+  are all recognised as parameterised rather than missing. Genuinely broken
+  literal paths are still reported.
+- **The workflow level-2 heading rule is discoverable before you trip it
+  (#926).** The `workflow create` template states that `##` headings are step
+  ids and points at `###` for cross-cutting notes, and the compiler's rejection
+  now carries the remedy rather than only the diagnosis.
+
 ## [0.9.12] - 2026-09-03
 
 ### Added

package/dist/assets/workflows/workflow-template.md

@@ -16,6 +16,10 @@ steps:
 Free preamble prose describing what this workflow does. It is indexed for
 search and shown in `akm show`, but it is never dispatched to a step.
 
+Level-2 (`##`) headings below are step ids and must exactly match one
+declared in `steps:` above — for cross-cutting notes that aren't a step
+(shared context, prerequisites), use a level-3 (`###`) heading instead.
+
 ## first-step
 
 Describe what to do in this step. Refer to run parameters in plain

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/improve/improve.js

@@ -1380,6 +1380,7 @@ function finalizeImproveResult(args) {
                     promoted: triageDrain.promoted.length,
                     rejected: triageDrain.rejected.length,
                     deferred: triageDrain.deferred.length,
+                    failed: triageDrain.failed.length,
                     skippedByCap: triageDrain.skippedByCap.length,
                 },
             }

package/dist/commands/lint/base-linter.js

@@ -132,6 +132,14 @@ function fixMissingUpdated(raw, mtime) {
     return spliceFrontmatterLine(raw, `updated: ${localDateStamp(mtime)}`) ?? raw;
 }
 // ── stale-path helpers ────────────────────────────────────────────────────────
+/**
+ * A path segment shaped like a run-time filename template rather than a
+ * literal reference: `<timestamp>`-style angle brackets, `{stamp}`/`${VAR}`
+ * braces, a `YYYYMMDD`/`HHMMSS`-style run of date-format letters, or a glob
+ * character. Such a path never exists under its literal spelling, so
+ * `stale-path` skips it instead of flagging it.
+ */
+const PATH_PLACEHOLDER_PATTERN = /[<{]|[*?]|[YMDHS]{4,}/;
 function checkStalePath(body) {
     const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
     let match;
@@ -139,6 +147,8 @@ function checkStalePath(body) {
     // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
     while ((match = pathRe.exec(body)) !== null) {
         const candidate = match[0];
+        if (PATH_PLACEHOLDER_PATTERN.test(candidate))
+            continue;
         if (!fs.existsSync(candidate)) {
             stale.push(candidate);
         }

package/dist/commands/proposal/drain.js

@@ -123,6 +123,42 @@ export function classifyProposal(proposal, policy, maxDiffLines) {
 function deferReasonForSource(source) {
     return source === "distill" ? "possible-dup" : "mid-band";
 }
+/**
+ * Map a thrown error's message to one of `DrainResult.failed`'s stable reason
+ * codes, falling back to `fallback` for anything not specifically recognized.
+ * Recognizes the write-time guards a proposal can trip during promotion
+ * (see repository.ts's `promoteProposalWithLease` / `preflightProposalPromotion`).
+ */
+function categorizeDrainFailure(message, fallback) {
+    if (/target (?:changed after|was created after) proposal/.test(message))
+        return "stale-target";
+    if (/failed validation:/.test(message))
+        return "validation";
+    return fallback;
+}
+function pushDrainFailure(result, id, err, fallbackReason) {
+    const message = err instanceof Error ? err.message : String(err);
+    result.failed.push({ id, reason: categorizeDrainFailure(message, fallbackReason), detail: message });
+    return message;
+}
+/**
+ * Mirror repository.ts's `promoteProposalWithLease` stale-target guard so a
+ * dry-run preflight predicts the same refusal a real promote would hit,
+ * without writing anything. `assetPath` is the path `preflightProposalPromotion`
+ * already resolved for this proposal.
+ */
+function assertProposalTargetFresh(proposal, assetPath) {
+    const backup = fs.existsSync(assetPath) ? fs.readFileSync(assetPath) : undefined;
+    const currentHash = backup ? createHash("sha256").update(backup).digest("hex") : undefined;
+    if (proposal.beforeHash !== undefined && (!backup || currentHash !== proposal.beforeHash)) {
+        throw new Error(`Proposal target changed after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    }
+    if (proposal.beforeHash === undefined &&
+        backup !== undefined &&
+        proposal.changes.some((change) => change.op === "create")) {
+        throw new Error(`Proposal target was created after proposal ${proposal.id} was created; refusing to overwrite newer content.`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Judgment tier (Phase 3)
 // ---------------------------------------------------------------------------
@@ -493,6 +529,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
         deferred: classification.deferred,
         skippedByCap: [],
         staged: [],
+        failed: [],
     };
     // A configured judgment runner makes every deferred item dispatch-eligible.
     // Validate its symbolic credentials before applying any deterministic gate,
@@ -518,7 +555,8 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                 result.rejected.push(target.id);
             }
             catch (err) {
-                warn(`[triage] reject failed for ${target.id}: ${err instanceof Error ? err.message : String(err)}`);
+                const message = pushDrainFailure(result, target.id, err, "reject-error");
+                warn(`[triage] reject failed for ${target.id}: ${message}`);
             }
         }
         // --- Accept ceiling: enforced BEFORE the promote loop ---
@@ -550,13 +588,15 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    warn(`[triage] promote failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    warn(`[triage] promote failed for ${id}: ${message}`);
                 }
             }
         }
         else if (opts.applyMode === "promote" && opts.dryRun) {
-            // Exercise the same stamped candidate and lint boundary as real promotion.
-            // Tests that omit config retain the classification-only seam.
+            // Exercise the same stamped candidate, lint, and stale-target boundary as
+            // real promotion so a dry-run's predicted promotions match what a real
+            // run would do. Tests that omit config retain the classification-only seam.
             const byId = new Map(pending.map((proposal) => [proposal.id, proposal]));
             for (const id of withinCap) {
                 try {
@@ -564,7 +604,7 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                         const proposal = byId.get(id);
                         if (!proposal)
                             throw new Error(`Proposal ${id} disappeared during drain preflight.`);
-                        preflightProposalPromotion(opts.config, proposal, {
+                        const preflight = preflightProposalPromotion(opts.config, proposal, {
                             ...(opts.target ? { target: opts.target } : {}),
                             gateDecision: {
                                 outcome: "auto-accepted",
@@ -572,12 +612,14 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
                                 gate: gateLabel,
                             },
                         });
+                        assertProposalTargetFresh(proposal, preflight.assetPath);
                     }
                     result.promoted.push(id);
                     deterministicPromoted += 1;
                 }
                 catch (err) {
-                    warn(`[triage] preflight failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+                    const message = pushDrainFailure(result, id, err, "promote-error");
+                    warn(`[triage] preflight failed for ${id}: ${message}`);
                 }
             }
         }

package/dist/commands/proposal/proposal-cli.js

@@ -473,6 +473,7 @@ const proposalDrainCommand = defineJsonCommand({
             deferred: result.deferred,
             skippedByCap: result.skippedByCap,
             staged: result.staged,
+            failed: result.failed,
         });
     },
 });

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);
+}