akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/read/show.js

@@ -8,100 +8,49 @@
  *
  *   show(ref) → indexer.lookup(ref) → readFile(entry.filePath)
  *
- * The richer presentation logic (matchers, renderers, wiki-root handling,
- * edit-hints, summary-detail truncation) lives below in this file. The flow:
+ * The richer presentation logic (matchers, renderers, edit-hints,
+ * summary-detail truncation) lives below in this file. The flow:
  *
- *   1. Special-case wiki-root refs (`wiki:<name>` with no page path).
- *   2. Auto-index when stale so the index is current.
- *   3. Ask `indexer.lookup(ref)` for the row in the FTS index.
- *   4. Render the file via the matcher/renderer pipeline.
+ *   1. Auto-index when stale so the index is current.
+ *   2. Ask `indexer.lookup(ref)` for the row in the FTS index.
+ *   3. Render the file via the matcher/renderer pipeline.
  */
 import fs from "node:fs";
 import path from "node:path";
-import { findCittyTopLevelCommandIndex } from "../../cli/parse-args.js";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { recognizeMatch } from "../../core/adapter/recognize-match.js";
+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 { displayRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString } from "../../core/common.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
-import { closeDatabase, computeBodyHash, findEntryIdByRef, openExistingDatabase } from "../../indexer/db/db.js";
+import { withStateDbTelemetry } from "../../core/state-db.js";
+import { presentationFor } from "../../core/type-presentation.js";
 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 { lookup } from "../../indexer/indexer.js";
+import { lookupBundleRef } from "../../indexer/indexer.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
+import { usageEventAttributionMetadata } from "../../indexer/search/search-attribution.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
-import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../../indexer/walk/file-context.js";
+import { buildFileContext, buildRenderContext, getRenderer, } from "../../indexer/walk/file-context.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { resolveIndexPassLLM } from "../../llm/index-passes.js";
 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 { findEntryIdByRef, getEntryById, getEntryIdByFilePath, getItemRefById, } from "../../storage/repositories/index-entries-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";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
+import { buildWorkflowAction } from "../../workflows/renderer.js";
 import { getActiveWorkflowRun } from "../../workflows/runtime/runs.js";
-/**
- * Show a wiki root (no page path) — returns the same payload as
- * `akm wiki show <name>`.
- */
-async function showWikiRoot(stashDir, wikiName) {
-    const { showWiki } = await import("../../wiki/wiki.js");
-    const result = showWiki(stashDir, wikiName);
-    return {
-        type: "wiki",
-        name: result.ref,
-        path: result.path,
-        ...(result.description ? { description: result.description } : {}),
-        origin: null,
-        editable: false,
-        pages: result.pages,
-        raws: result.raws,
-        ...(result.lastModified ? { lastModified: result.lastModified } : {}),
-        recentLog: result.recentLog,
-    };
-}
-async function showWikiRootForSource(stashDir, source, wikiName) {
-    const { showWikiAtPath } = await import("../../wiki/wiki.js");
-    if (source.wikiName === wikiName) {
-        const result = showWikiAtPath(wikiName, source.path);
-        return {
-            type: "wiki",
-            name: result.ref,
-            path: result.path,
-            ...(result.description ? { description: result.description } : {}),
-            origin: null,
-            editable: false,
-            pages: result.pages,
-            raws: result.raws,
-            ...(result.lastModified ? { lastModified: result.lastModified } : {}),
-            recentLog: result.recentLog,
-        };
-    }
-    return showWikiRoot(stashDir, wikiName);
-}
-function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
-    const pageName = assetName === wikiName ? "" : assetName.slice(wikiName.length + 1);
-    if (!pageName) {
-        throw new NotFoundError(`Wiki page not found: wiki:${assetName}`);
-    }
-    const candidate = path.resolve(wikiRoot, `${pageName}.md`);
-    const resolvedRoot = fs.realpathSync(wikiRoot);
-    if (!candidate.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
-    }
-    if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
-        throw new NotFoundError(`Stash asset not found for ref: wiki:${assetName}`);
-    }
-    const realTarget = fs.realpathSync(candidate);
-    if (!realTarget.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
-    }
-    return realTarget;
-}
 /**
  * Unified show: queries the local FTS5 index, then falls back to on-disk
  * type-dir resolution if the index has no row. Spec §6.2; no remote provider
@@ -115,55 +64,33 @@ export async function akmShowUnified(input) {
     // 0a. Stash `.meta/` convention: `[origin//]meta[:name]` direct-reads a
     //     human-authored orientation doc from the stash's `.meta/` directory.
     //     These files are not indexed (the walker skips dot-dirs), so they are
-    //     resolved here before the index lookup and the `type:name` parser,
-    //     which would otherwise reject the non-asset-type `meta`.
+    //     resolved here before the index lookup; meta docs are not asset refs.
     {
         const metaRef = parseMetaRef(ref);
         if (metaRef)
             return showStashMeta(metaRef);
     }
-    // 0. Wiki-root shortcut: `wiki:<name>` with no page path routes to the
-    //    wiki summary (same payload as `akm wiki show <name>`). Honour
-    //    `parsed.origin` by resolving against the matching stash source(s),
-    //    falling back to the primary stash when no origin is given.
-    {
-        const parsed = parseAssetRef(ref);
-        if (parsed.type === "wiki" && !parsed.name.includes("/")) {
-            const allSources = resolveSourceEntries();
-            const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-            let lastError;
-            for (const source of searchSources) {
-                try {
-                    return await showWikiRootForSource(allSources[0]?.path ?? source.path, source, parsed.name);
-                }
-                catch (err) {
-                    if (!(err instanceof NotFoundError))
-                        throw err;
-                    lastError = err;
-                }
-            }
-            throw (lastError ??
-                new NotFoundError(`Wiki not found: ${parsed.name}. Run \`akm wiki create ${parsed.name}\` to create it.`));
-        }
-    }
     // Auto-index when stale so the index is current before lookup.
     const { primarySource } = resolveReadSources();
     await ensurePrimaryIndexForRead(primarySource);
     // Try local filesystem (FTS5 index lookup)
     const result = await showLocal(input);
-    // Scope filter narrows resolution: if --scope was supplied, the asset's
-    // frontmatter scope must satisfy every supplied key. We re-read the file
-    // (cheap — already on the show hot path) so we don't have to thread scope
-    // through the renderer chain just for one verification step.
+    // Scope filter narrows resolution: if a scope filter was supplied, the
+    // asset's frontmatter scope must satisfy every supplied key. We re-read the
+    // file (cheap — already on the show hot path) so we don't have to thread
+    // scope through the renderer chain just for one verification step.
     if (input.scope && hasAnyScopeKey(input.scope) && result.path) {
         enforceScopeOrThrow(result.path, ref, input.scope);
     }
     // Count prior shows of this ref before logging the current one.
-    const priorShowCount = recentShowCount(ref);
-    logShowEvent(ref, input.eventSource);
-    if (priorShowCount >= 2) {
-        // Agent has shown this same asset 3+ times — inject a loop-break hint.
-        result.showLoopWarning = priorShowCount + 1;
+    if (!input.skipLogging) {
+        const consumedRef = result.ref ?? makeBundleRef(undefined, parseBundleRef(ref).conceptId);
+        const priorShowCount = recentShowCount(consumedRef);
+        logShowEvent(consumedRef, result.type, result.name, input.eventSource, result.path);
+        if (priorShowCount >= 2) {
+            // Agent has shown this same asset 3+ times — inject a loop-break hint.
+            result.showLoopWarning = priorShowCount + 1;
+        }
     }
     return result;
 }
@@ -180,7 +107,7 @@ async function showStashMeta(metaRef) {
     const sources = resolveSourcesForOrigin(metaRef.origin, allSources);
     if (metaRef.origin && sources.length === 0) {
         throw new NotFoundError(`Stash "${metaRef.origin}" is not installed, so its ${META_DIR}/ docs are unavailable. ` +
-            `Run: akm add ${metaRef.origin}`);
+            `Run: akm bundle add ${metaRef.origin}`);
     }
     const config = loadConfig();
     for (const source of sources) {
@@ -188,12 +115,13 @@ async function showStashMeta(metaRef) {
         if (!filePath)
             continue;
         const content = fs.readFileSync(filePath, "utf8");
-        const editable = isEditable(filePath, config);
+        const editable = isEditable(filePath, config, allSources);
         appendEvent({ eventType: "show", ref: `meta:${metaRef.name}`, metadata: { type: "meta", name: metaRef.name } });
         return {
             type: "meta",
             name: metaRef.name,
             path: filePath,
+            ref: `meta:${metaRef.name}`,
             content,
             origin: source.registryId ?? null,
             editable,
@@ -257,11 +185,11 @@ function recentShowCount(ref) {
         return 0;
     }
 }
-function logShowEvent(ref, eventSource = "user") {
+function logShowEvent(ref, type, name, eventSource = "user", filePath) {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm show invocations without relying on stdout scraping.
-    const parsed = parseAssetRef(ref);
-    appendEvent({ eventType: "show", ref, metadata: { type: parsed.type, name: parsed.name } });
+    const eventRef = makeBundleRef(parseBundleRef(ref).bundle, parseBundleRef(ref).conceptId);
+    appendEvent({ eventType: "show", ref: eventRef, metadata: { type, name } });
     // Detect if this show is a selection from a recent search result.
     try {
         // D7: bound the query to the last 60 s so we never scan unbounded history
@@ -293,12 +221,25 @@ function logShowEvent(ref, eventSource = "user") {
     }
     try {
         withIndexDb((db) => {
-            insertUsageEvent(db, {
-                event_type: "show",
-                entry_ref: ref,
-                entry_id: findEntryIdByRef(db, ref),
-                source: eventSource,
-            });
+            const entryId = filePath ? getEntryIdByFilePath(db, filePath) : findEntryIdByRef(db, eventRef);
+            if (entryId === undefined)
+                return;
+            // Usage events carry only the resolved row's fully-qualified item_ref.
+            // A disk-only show has no durable indexed identity yet, so it does not
+            // create a per-entry usage row.
+            const entryRef = getItemRefById(db, entryId);
+            if (!entryRef)
+                return;
+            const entry = getEntryById(db, entryId);
+            withStateDbTelemetry((stateDb) => {
+                insertUsageEvent(stateDb, {
+                    event_type: "show",
+                    entry_ref: entryRef,
+                    entry_id: entryId,
+                    metadata: usageEventAttributionMetadata(entry?.entry.derivedFrom ? { memoryInference: { exposure: "direct" } } : undefined, entryRef),
+                    source: eventSource,
+                });
+            }, TELEMETRY_BUSY_TIMEOUT_MS);
         }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
@@ -308,61 +249,102 @@ function logShowEvent(ref, eventSource = "user") {
 }
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
-    const parsed = parseAssetRef(input.ref);
-    const displayType = parsed.type;
+    const parsed = parseBundleRef(input.ref);
+    const assetParts = typeNameFromConceptId(parsed.conceptId);
     const config = loadConfig();
     const allSources = resolveSourceEntries(input.stashDir);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
+    const searchSources = resolveSourcesForOrigin(parsed.bundle, allSources);
     const allSourceDirs = searchSources.map((s) => s.path);
-    let assetPath;
-    const matchedSource = parsed.type === "wiki" ? searchSources.find((source) => parsed.name.startsWith(`${source.wikiName}/`)) : undefined;
-    let lastError;
-    if (parsed.type === "wiki" && matchedSource?.wikiName) {
-        try {
-            assetPath = resolveRegisteredWikiAssetPath(matchedSource.path, matchedSource.wikiName, parsed.name);
-        }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
-        }
-    }
-    if (!assetPath) {
-        const resolvedAssetPath = await resolveAssetPath(parsed, {
-            stashDir: input.stashDir,
-            mode: "index-first",
-        });
-        assetPath = resolvedAssetPath ?? undefined;
+    let indexedEntry = null;
+    try {
+        indexedEntry = await lookupBundleRef(parsed);
     }
-    if (!assetPath && parsed.origin && searchSources.length === 0) {
-        const installCmd = `akm add ${parsed.origin}`;
-        throw new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
-            `Stash "${parsed.origin}" is not installed. Run: ${installCmd}`);
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        indexedEntry = null;
+    }
+    const resolvedAssetPath = indexedEntry?.filePath ??
+        (assetParts
+            ? await resolveAssetPath({ type: assetParts.type, name: assetParts.name, origin: parsed.bundle }, {
+                stashDir: input.stashDir,
+                mode: "disk-only",
+            })
+            : null);
+    const assetPath = resolvedAssetPath ?? undefined;
+    const displayType = indexedEntry?.type ?? assetParts?.type ?? "asset";
+    const displayName = indexedEntry?.name ?? assetParts?.name ?? parsed.conceptId;
+    if (!assetPath && parsed.bundle && searchSources.length === 0) {
+        const installCmd = `akm bundle add ${parsed.bundle}`;
+        throw new NotFoundError(`Stash asset not found for ref: ${makeBundleRef(parsed.bundle, parsed.conceptId)}. ` +
+            `Stash "${parsed.bundle}" is not installed. Run: ${installCmd}`);
     }
     if (!assetPath) {
-        throw (lastError ??
-            new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
-                "Check the name with `akm search` or verify the asset exists in your stash."));
+        throw new NotFoundError(`Stash asset not found for ref: ${makeBundleRef(parsed.bundle, parsed.conceptId)}. ` +
+            "Check the name with `akm search` or verify the asset exists in your stash.");
     }
-    const source = matchedSource ?? findSourceForPath(assetPath, allSources);
+    if (indexedEntry) {
+        try {
+            fs.accessSync(assetPath, fs.constants.R_OK);
+        }
+        catch (error) {
+            throwIndexedPathNotFound(error, input.ref);
+        }
+    }
+    const source = findSourceForPath(assetPath, allSources);
     const sourceStashDir = source?.path ?? allSourceDirs[0];
     if (!sourceStashDir) {
-        throw new UsageError(`Could not determine stash root for asset: ${displayType}:${parsed.name}. ` +
-            "Run `akm init` to create the stash directory, or check `akm stash list` for configured paths.");
+        throw new UsageError(`Could not determine stash root for asset: ${makeBundleRef(parsed.bundle, parsed.conceptId)}. ` +
+            "Run `akm bundle create` to create the stash directory, or check `akm bundle list` for configured paths.");
     }
     const fileCtx = buildFileContext(sourceStashDir, assetPath);
-    const forcedWikiMatch = parsed.type === "wiki" && source?.wikiName && parsed.name.startsWith(`${source.wikiName}/`)
-        ? { type: "wiki", specificity: 20, renderer: "wiki-md", meta: {} }
-        : undefined;
-    const match = forcedWikiMatch ?? (await runMatchers(fileCtx));
-    if (!match) {
-        throw new UsageError(`Could not display asset "${displayType}:${parsed.name}" — unsupported file type or unrecognized layout`);
-    }
-    match.meta = { ...match.meta, name: parsed.name, view: input.view };
-    const renderer = await getRenderer(match.renderer);
-    if (!renderer) {
-        throw new UsageError(`Renderer "${match.renderer}" not found for asset: ${displayType}:${parsed.name}`);
-    }
-    const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, source?.registryId);
-    const response = renderer.buildShowResponse(renderCtx);
+    const indexedRenderer = indexedEntry ? rendererForIndexedEntry(indexedEntry, fileCtx) : undefined;
+    let response;
+    try {
+        if (indexedEntry && indexedRenderer === null) {
+            response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment);
+        }
+        else {
+            const match = indexedEntry && typeof indexedRenderer === "string"
+                ? indexedMatch(indexedEntry, indexedRenderer)
+                : recognizeMatch(fileCtx);
+            if (!match) {
+                throw new UsageError(`Could not display asset "${makeBundleRef(parsed.bundle, parsed.conceptId)}" — unsupported file type or unrecognized layout`);
+            }
+            match.meta = { ...match.meta, name: displayName };
+            const renderer = await getRenderer(match.renderer);
+            if (!renderer) {
+                throw new UsageError(`Renderer "${match.renderer}" not found for asset: ${makeBundleRef(parsed.bundle, parsed.conceptId)}`);
+            }
+            const renderBundle = indexedEntry ? indexedEntry.bundleId : source?.registryId;
+            const renderDefaultBundle = config.defaultBundle ?? (source?.path === allSources[0]?.path ? renderBundle : undefined);
+            const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, renderBundle, renderDefaultBundle);
+            response = renderer.buildShowResponse(renderCtx);
+            if (parsed.fragment !== undefined) {
+                if (!match.renderer.endsWith("-md")) {
+                    throw new UsageError(`Fragments are not supported for ${makeBundleRef(parsed.bundle, parsed.conceptId)}. Only Markdown documents support heading fragments.`, "INVALID_FLAG_VALUE");
+                }
+                applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, displayName);
+            }
+        }
+    }
+    catch (error) {
+        if (indexedEntry)
+            throwIndexedPathNotFound(error, input.ref);
+        throw error;
+    }
+    if (indexedEntry) {
+        response.type = indexedEntry.type;
+        response.name = indexedEntry.name;
+    }
+    const isPrimaryStash = source !== undefined && source.path === allSources[0]?.path;
+    const canonicalRef = displayRef({
+        type: displayType,
+        name: displayName,
+        conceptId: indexedEntry?.conceptId,
+        bundleId: indexedEntry ? indexedEntry.bundleId : source?.registryId,
+    }, config.defaultBundle ?? (isPrimaryStash ? indexedEntry?.bundleId : undefined));
+    if (response.type === "workflow")
+        response.action = buildWorkflowAction(canonicalRef);
     // 07 P1-D: provenance-aware toolPolicy CEILING. An agent's self-declared
     // `tools` frontmatter is honoured ONLY for the operator's own PRIMARY stash —
     // the assets they authored. Every other source is content pulled from
@@ -374,16 +356,16 @@ export async function showLocal(input) {
     // `allSources[0]` is always the primary (search-source.ts) — not a
     // name-derived registryId or the orthogonal `writable` bit. `source` undefined
     // (unresolved path) also fails closed.
-    const isPrimaryStash = source !== undefined && source.path === allSources[0]?.path;
     if (response.toolPolicy !== undefined && !isPrimaryStash) {
         delete response.toolPolicy;
     }
-    const editable = isEditable(assetPath, config);
+    const editable = isEditable(assetPath, config, allSources);
     const fullResponse = {
         ...response,
+        ref: canonicalRef,
         origin: source?.registryId ?? null,
         editable,
-        ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
+        ...(!editable ? { editHint: buildEditHint(canonicalRef) } : {}),
         related: (() => {
             try {
                 return withIndexDb((db) => {
@@ -476,14 +458,87 @@ async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
  * renderer graph. Spec §6.2's literal flow.
  */
 export async function showByRef(ref) {
-    const parsed = parseAssetRef(ref);
-    const entry = await lookup(parsed);
+    const parsed = parseBundleRef(ref);
+    if (parsed.fragment !== undefined) {
+        throw new UsageError(`Fragments are not accepted by raw show: ${ref}`, "INVALID_FLAG_VALUE");
+    }
+    const entry = await lookupBundleRef(parsed);
     if (!entry) {
-        throw new NotFoundError(`Asset not found for ref: ${parsed.type}:${parsed.name}`);
+        throw new NotFoundError(`Asset not found for ref: ${makeBundleRef(parsed.bundle, parsed.conceptId)}`);
+    }
+    let body;
+    try {
+        body = await fs.promises.readFile(entry.filePath, "utf8");
+    }
+    catch (error) {
+        throwIndexedPathNotFound(error, ref);
     }
-    const body = await fs.promises.readFile(entry.filePath, "utf8");
     return { filePath: entry.filePath, body };
 }
+function throwIndexedPathNotFound(error, ref) {
+    const code = error?.code;
+    if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM") {
+        throw new NotFoundError(`The indexed file for ${ref} is missing or unreadable. The search index may be stale.`, "ASSET_NOT_FOUND", "Run `akm index` to reconcile indexed paths, then retry `akm show`.");
+    }
+    throw error;
+}
+/** `null` selects adapter-owned projection; a string selects a core renderer. */
+function rendererForIndexedEntry(entry, _file) {
+    if (entry.document?.ownsPresentation === true)
+        return null;
+    switch (entry.adapterId) {
+        case null:
+        case undefined:
+        case "akm":
+            return undefined;
+        case "akm-workflow":
+            return "workflow-md";
+        default:
+            return presentationFor(entry.type).renderer;
+    }
+}
+function indexedMatch(entry, renderer) {
+    return { type: entry.type, specificity: Number.MAX_SAFE_INTEGER, renderer, meta: { name: entry.name } };
+}
+function buildIndexedProjectionResponse(entry, assetPath, fragment) {
+    if (fragment !== undefined && path.extname(assetPath).toLowerCase() !== ".md") {
+        throw new UsageError(`Fragments are not supported for ${entry.conceptId}. Only Markdown documents support heading fragments.`, "INVALID_FLAG_VALUE");
+    }
+    const raw = fs.readFileSync(assetPath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const content = fragment ? requireMarkdownSection(parsed.content, fragment, entry.name).content : parsed.content;
+    const description = entry.document?.description ?? asNonEmptyString(parsed.data.description);
+    const tags = entry.document?.tags ??
+        (Array.isArray(parsed.data.tags)
+            ? parsed.data.tags.filter((tag) => typeof tag === "string" && tag.trim().length > 0)
+            : undefined);
+    return {
+        type: entry.type,
+        name: entry.name,
+        path: assetPath,
+        action: "Read the content below.",
+        content,
+        ...(description ? { description } : {}),
+        ...(tags && tags.length > 0 ? { tags } : {}),
+    };
+}
+function applyMarkdownFragment(response, raw, fragment, name) {
+    const section = requireMarkdownSection(parseFrontmatter(raw).content, fragment, name).content;
+    if (response.template !== undefined)
+        response.template = section;
+    else if (response.prompt !== undefined)
+        response.prompt = section;
+    else
+        response.content = section;
+}
+function requireMarkdownSection(content, fragment, name) {
+    const section = extractSection(content, fragment);
+    if (section)
+        return section;
+    const available = markdownFragmentSlugs(content);
+    throw new NotFoundError(`Fragment "#${fragment}" not found in ${name}.` +
+        (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""));
+}
 /**
  * Build a reduced brief response from a full ShowResponse.
  *
@@ -495,11 +550,13 @@ function buildBriefResponse(full, assetPath) {
         type: summary.type,
         name: summary.name,
         path: summary.path,
+        ...(summary.ref ? { ref: summary.ref } : {}),
         ...(summary.description ? { description: summary.description } : {}),
         ...(summary.action ? { action: summary.action } : {}),
         ...(summary.run ? { run: summary.run } : {}),
         ...(summary.origin !== undefined ? { origin: summary.origin } : {}),
         ...(full.editable !== undefined ? { editable: full.editable } : {}),
+        ...(full.editHint ? { editHint: full.editHint } : {}),
     };
 }
 /**
@@ -525,6 +582,7 @@ function buildSummaryResponse(full, assetPath) {
         type: full.type,
         name: full.name,
         path: full.path,
+        ...(full.ref ? { ref: full.ref } : {}),
         ...(description ? { description } : {}),
         ...(tags && tags.length > 0 ? { tags } : {}),
         ...(full.parameters ? { parameters: full.parameters } : {}),
@@ -532,90 +590,8 @@ function buildSummaryResponse(full, assetPath) {
         ...(full.action ? { action: full.action } : {}),
         ...(full.run ? { run: full.run } : {}),
         ...(full.origin !== undefined ? { origin: full.origin } : {}),
+        ...(full.editable !== undefined ? { editable: full.editable } : {}),
+        ...(full.editHint ? { editHint: full.editHint } : {}),
     };
     return summary;
 }
-// ── argv normalisation ───────────────────────────────────────────────────────
-const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
-const SHOW_ARGV_TOP_LEVEL_ARGS = {
-    format: { type: "string" },
-    output: { type: "string" },
-    detail: { type: "string" },
-    shape: { type: "string" },
-    quiet: { type: "boolean", alias: "q" },
-    verbose: { type: "boolean" },
-};
-/**
- * Normalize argv so positional view-mode arguments after the asset ref
- * are rewritten into internal flags that citty can parse.
- *
- * Converts:
- *   akm show knowledge:guide.md toc          → akm show knowledge:guide.md --akmView toc
- *   akm show knowledge:guide.md section Auth → akm show knowledge:guide.md --akmView section --akmHeading Auth
- *   akm show knowledge:guide.md lines 1 50   → akm show knowledge:guide.md --akmView lines --akmStart 1 --akmEnd 50
- *
- * Legacy `--view` is intentionally unsupported.
- * Returns a new array; the input is never modified.
- */
-export function normalizeShowArgv(argv) {
-    const rawArgs = argv.slice(2);
-    const commandIndex = findCittyTopLevelCommandIndex(rawArgs, SHOW_ARGV_TOP_LEVEL_ARGS);
-    if (commandIndex < 0 || rawArgs[commandIndex] !== "show")
-        return argv;
-    const commandArgs = rawArgs.slice(commandIndex + 1);
-    if (commandArgs.includes("--view") ||
-        commandArgs.includes("--heading") ||
-        commandArgs.includes("--start") ||
-        commandArgs.includes("--end")) {
-        throw new UsageError('Legacy show flags are no longer supported. Use positional syntax like `akm show knowledge:guide toc` or `akm show knowledge:guide section "Auth"`.');
-    }
-    // Separate global flags from positional/show-specific args
-    const prefix = [...argv.slice(0, 2), ...rawArgs.slice(0, commandIndex + 1)];
-    const rest = commandArgs;
-    const globalFlags = [];
-    const showArgs = [];
-    for (let i = 0; i < rest.length; i++) {
-        const arg = rest[i];
-        if (arg === "--quiet" || arg === "-q" || arg === "--verbose") {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg.startsWith("--format=") || arg.startsWith("--detail=") || arg.startsWith("--shape=")) {
-            globalFlags.push(arg);
-            continue;
-        }
-        if (arg === "--format" || arg === "--detail" || arg === "--shape") {
-            globalFlags.push(arg);
-            if (rest[i + 1] !== undefined) {
-                globalFlags.push(rest[i + 1]);
-                i++;
-            }
-            continue;
-        }
-        showArgs.push(arg);
-    }
-    // showArgs[0] = ref, showArgs[1] = potential view mode, showArgs[2..] = view params
-    const ref = showArgs[0];
-    const viewMode = showArgs[1];
-    if (!ref || !viewMode || !SHOW_VIEW_MODES.has(viewMode)) {
-        return argv;
-    }
-    const result = [...prefix, ref, "--akmView", viewMode];
-    if (viewMode === "section") {
-        // Next arg is the heading name; pass empty string when missing so the
-        // show handler can produce a clear "section not found" error.
-        const heading = showArgs[2] ?? "";
-        result.push("--akmHeading", heading);
-    }
-    else if (viewMode === "lines") {
-        // Next two args are start and end
-        const start = showArgs[2];
-        const end = showArgs[3];
-        if (start)
-            result.push("--akmStart", start);
-        if (end)
-            result.push("--akmEnd", end);
-    }
-    result.push(...globalFlags);
-    return result;
-}