akm-cli 0.9.26-alpha.1 → 0.9.26-alpha.2

package/CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.26-alpha.2] - 2026-10-05
+
+### Added
+
+- **`akm feedback --negative` can carry an exact fix of the asset's text:**
+  `--replace "<exact current text>" --with "<corrected text>" --source "<URL,
+  command or file>"`, repeatable for several edits. akm checks at once that each
+  `--replace` text appears exactly once and that the frontmatter still parses,
+  records nothing if a check fails (so the caller can correct it and retry), and
+  queues the edit as a `feedback` proposal that shows the reason and source to
+  the reviewer. Improve has edited only an asset's frontmatter since 0.9.25, so
+  this is how a wrong fact in a note's text gets corrected: by the agent that
+  found it, with its evidence, instead of by a nightly rewrite.
+
+### Changed
+
+- **`akm feedback` help, the shipped hints and the docs no longer promise that
+  improve proposes a fix of the text from a negative reason;** they say it may
+  repair the frontmatter, and point to the exact-fix flags.
+
 ## [0.9.26-alpha.1] - 2026-10-05
 
 ### Changed

package/dist/assets/hints/cli-hints-full.md

@@ -95,7 +95,8 @@ akm workflow create ship-release               # Create a workflow asset in the
 akm lint --type workflows                      # Parse and compile every .md/.yml workflow source; list every error
 akm workflow run workflows/ship-release        # Start or resume and execute the workflow
 akm feedback skills/code-review --positive     # Record that an asset helped (ranks it higher; no rewrite)
-akm feedback agents/reviewer --negative --reason "wrong framework" # Flag it for review: improve proposes a fix from the reason
+akm feedback agents/reviewer --negative --reason "wrong framework" # Flag it: lowers its ranking; improve may repair its frontmatter
+akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/" # Queue an exact fix
 akm feedback memories/deployment-notes --positive # Works for memories too
 akm feedback env/prod --positive               # Records env feedback without surfacing values
 ```
@@ -103,8 +104,11 @@ akm feedback env/prod --positive               # Records env feedback without su
 Use `akm feedback` whenever an asset's content materially helps, or proves wrong,
 stale or unhelpful, so future search ranking can learn from actual usage.
 `akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
-flags the asset for review: the next improve run proposes a fix based on your
-reason, so be specific. `--positive` records that an asset helped (it raises its
+flags the asset: it ranks lower right away, and the next improve run may repair
+its description, title or `when_to_use` from your reason. Improve does not
+rewrite an asset's text: to correct a wrong fact there, attach the exact fix
+with `--replace "<exact current text>" --with "<corrected text>" --source "<URL,
+command or file>"`, which akm checks and queues as a proposal. `--positive` records that an asset helped (it raises its
 ranking) and does not trigger a rewrite; improve no longer rewrites assets from
 positive signals or on a proactive cadence. An akm command that fails says
 nothing about the asset; don't record it as feedback.

package/dist/assets/hints/cli-hints-short.md

@@ -8,7 +8,7 @@ For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
 2. `akm show <ref>` — read the schema (field names and structure)
 3. Edit the workspace file using schema field names + task-specific values from your README
-4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite); when its content was wrong, stale or unhelpful, `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it for review: the next improve run proposes a fix based on your reason, so be specific. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
+4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite); when its content was wrong, stale or unhelpful, `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it: the next improve run may repair its description, title or `when_to_use` from your reason, but not its text. To correct a wrong fact in the text, add the exact fix: `--replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"`. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
 
 For workflow tasks:
 1. `akm show workflows/<name>` — inspect the procedure before executing it
@@ -40,7 +40,8 @@ akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8
 akm proposal accept 7c115132                  # Accept by UUID prefix
 akm proposal reject skills/my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive                 # Record that an asset helped (ranks it higher; no rewrite)
-akm feedback <ref> --negative --reason "..."  # Flag it for review: the next improve run proposes a fix from your reason
+akm feedback <ref> --negative --reason "..."  # Flag it: lowers its ranking; improve may repair its frontmatter
+akm feedback <ref> --negative --reason "..." --replace "<exact text>" --with "<fix>" --source "<url|cmd|file>"  # Queue an exact fix of its text
 akm bundle add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working bundle (optional --dest arg to clone to specific location)
 akm sync                                      # Commit (and push if writable remote) changes in the primary bundle (--no-push to commit only)

package/dist/assets/stash-skeleton/README.md

@@ -80,10 +80,13 @@ akm search "<query>" --type skill
 # Mark an asset as helpful (raises its ranking; does not trigger a rewrite)
 akm feedback <ref> --positive
 
-# Flag an asset for review: the next improve run proposes a fix based on your
-# reason, so be specific about what is wrong and what should change
+# Flag an asset: it ranks lower, and the next improve run may repair its
+# description, title or when_to_use from your reason
 akm feedback <ref> --negative --reason "<what is wrong and what should change>"
 
+# Correct a wrong fact in an asset's text: the exact fix is checked and queued for review
+akm feedback <ref> --negative --reason "<what is wrong>" --replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"
+
 # Capture a durable lesson or memory from the current session
 akm remember "<fact or lesson>"
 ```

package/dist/commands/feedback-cli.js

@@ -2,12 +2,13 @@
 // 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/.
 import fs from "node:fs";
+import { parse as yamlParse } from "yaml";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
 import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
 import { assembleAsset } from "../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../core/asset/resolve-ref.js";
-import { isWithin, writeFileAtomic } from "../core/common.js";
+import { isWithin, resolveStashDir, writeFileAtomic } from "../core/common.js";
 import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
@@ -23,6 +24,7 @@ import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { findEntryIdByRef, getEntryFilePathById, getItemRefById, } from "../storage/repositories/index-entries-repository.js";
 import { applyFeedbackToUtilityScore } from "../storage/repositories/index-utility-repository.js";
+import { createProposal } from "./proposal/repository.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
 function validateFeedbackTags(raw) {
@@ -185,15 +187,74 @@ function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadata
     });
     return { utilityResult, rankingUpdateApplied, rankingUpdateSkippedReason };
 }
+// ── Exact fixes ──────────────────────────────────────────────────────────────
+/** 1-based numbers of the lines on which `needle` starts. */
+function startLines(text, needle) {
+    const lines = [];
+    for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + 1)) {
+        lines.push(text.slice(0, at).split("\n").length);
+    }
+    return lines;
+}
+/**
+ * Apply `--replace`/`--with` pairs in order. Each `--replace` text must appear
+ * exactly once in the text as it stands at that point, so the edit can only
+ * land where the caller meant it.
+ */
+export function applyExactReplacements(text, pairs, file) {
+    let out = text;
+    pairs.forEach((pair, i) => {
+        const label = `--replace #${i + 1}`;
+        if (!pair.old)
+            throw new UsageError(`${label} is empty.`, "INVALID_FLAG_VALUE");
+        const lines = startLines(out, pair.old);
+        if (lines.length === 0) {
+            throw new UsageError(`${label} was not found in ${file}.`, "INVALID_FLAG_VALUE", "Copy the text verbatim from the file, including whitespace and punctuation.");
+        }
+        if (lines.length > 1) {
+            throw new UsageError(`${label} appears ${lines.length} times in ${file} (lines ${lines.join(", ")}).`, "INVALID_FLAG_VALUE", "Include more of the surrounding text so it appears once.");
+        }
+        const at = out.indexOf(pair.old);
+        out = out.slice(0, at) + pair.new + out.slice(at + pair.old.length);
+    });
+    return out;
+}
+/** A fix may change the frontmatter's values, but it must still parse as YAML. */
+function assertFrontmatterStillParses(before, after, file) {
+    if (!parseFrontmatterBlock(before))
+        return;
+    const block = parseFrontmatterBlock(after);
+    let problem;
+    if (!block) {
+        problem = "the frontmatter block is gone";
+    }
+    else if (block.frontmatter.trim()) {
+        try {
+            const data = yamlParse(block.frontmatter);
+            if (typeof data !== "object" || data === null || Array.isArray(data))
+                problem = "it is no longer a mapping";
+        }
+        catch (err) {
+            problem = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+        }
+    }
+    if (problem) {
+        throw new UsageError(`The fix breaks the frontmatter of ${file}: ${problem}.`, "INVALID_FLAG_VALUE", 'Quote a value that contains ": ", or leave the frontmatter alone.');
+    }
+}
 // ── Command definition ────────────────────────────────────────────────────────
 export const feedbackCommand = defineJsonCommand({
     meta: {
         name: "feedback",
         description: "Record positive or negative feedback for any indexed bundle asset.\n\n" +
             '`akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags\n' +
-            "the asset for review: the next improve run proposes a fix based on your reason, so be\n" +
-            "specific. `--positive` records that an asset helped (it raises its ranking) and does not\n" +
-            "trigger a rewrite.\n\n" +
+            "the asset: the next improve run may repair its description, title or when_to_use from\n" +
+            "your reason, but it does not rewrite the text. To correct a wrong fact in the text, attach\n" +
+            'the exact fix: --replace "<exact current text>" --with "<corrected text>" --source "<URL,\n' +
+            'command or file that shows it>" (repeat --replace/--with for several edits; use --with=...\n' +
+            "for a value that starts with -). akm checks that each --replace text appears exactly once\n" +
+            "and queues the edit as a proposal for review. `--positive` records that an asset helped\n" +
+            "(it raises its ranking) and does not trigger a rewrite.\n\n" +
             "Both signals adjust the asset's usefulness score right away, in the same\n" +
             "process: positive feedback raises it, negative lowers it, and recent\n" +
             "feedback counts for more than old feedback. No reindex is needed — the new\n" +
@@ -211,12 +272,24 @@ export const feedbackCommand = defineJsonCommand({
         },
         negative: {
             type: "boolean",
-            description: "Flag the asset for review: the next improve run proposes a fix from --reason (also lowers its ranking immediately, no reindex needed).",
+            description: "Flag the asset: lowers its ranking immediately (no reindex needed), and the next improve run may repair its frontmatter from --reason. Attach --replace/--with/--source to correct its text.",
             default: false,
         },
         reason: {
             type: "string",
-            description: "What is wrong with the asset's content and what should change; the next improve run proposes a fix from it, so be specific (required for negative feedback by default). Not for akm command errors.",
+            description: "What is wrong with the asset's content and what should change, specifically (required for negative feedback by default). Not for akm command errors.",
+        },
+        replace: {
+            type: "string",
+            description: "Exact text to correct, copied verbatim from the asset file; it must appear exactly once (repeatable, each paired with a --with in order). Negative feedback only.",
+        },
+        with: {
+            type: "string",
+            description: "Corrected text for the matching --replace (repeatable, in the same order).",
+        },
+        source: {
+            type: "string",
+            description: "Where the correct fact comes from: a URL, command or file. Required with --replace.",
         },
         "failure-mode": {
             type: "string",
@@ -262,18 +335,37 @@ export const feedbackCommand = defineJsonCommand({
                 throw new UsageError(`Invalid --failure-mode "${failureMode}". Accepted values: ${allowedModes.join(", ")}.`, "INVALID_FLAG_VALUE", `Use one of: ${allowedModes.join(", ")}`);
             }
         }
+        // An exact fix for the asset's text: each --replace pairs with a --with, in order.
+        const replaces = parseAllFlagValues("--replace");
+        const withs = parseAllFlagValues("--with");
+        const fixSource = args.source?.trim() || undefined;
+        const fixPairs = replaces.map((old, i) => ({ old, new: withs[i] ?? "" }));
+        if (replaces.length > 0 || withs.length > 0 || fixSource !== undefined) {
+            if (!args.negative) {
+                throw new UsageError("--replace, --with and --source are only for negative feedback.", "INVALID_FLAG_VALUE");
+            }
+            if (replaces.length === 0 || replaces.length !== withs.length) {
+                throw new UsageError(`Each --replace needs one --with (got ${replaces.length} --replace and ${withs.length} --with).`, "INVALID_FLAG_VALUE");
+            }
+            if (!fixSource) {
+                throw new UsageError("A fix needs --source: the URL, command or file that shows the correct fact.", "MISSING_REQUIRED_ARGUMENT");
+            }
+            if (!reason?.trim()) {
+                throw new UsageError("A fix needs --reason: say what is wrong.", "MISSING_REQUIRED_ARGUMENT");
+            }
+        }
         if (args.negative === true && !reason?.trim()) {
             // F-3 / #384: Default requireReason is now true. Load config to allow
             // operators to opt out via feedback.requireReason: false in akm.json.
             const cfg = loadConfig();
             const requireReason = cfg.feedback?.requireReason ?? true; // Default: true (F-3 / #384)
             if (requireReason) {
-                throw new UsageError("Negative feedback requires --reason: the next improve run proposes a fix from it, so say what is wrong and what should change. " +
+                throw new UsageError("Negative feedback requires --reason: say what is wrong and what should change. " +
                     "Use --failure-mode for a curated taxonomy or --reason for free text. " +
                     "Set feedback.requireReason: false in akm.json to downgrade to a warning.", "MISSING_REQUIRED_ARGUMENT", `Hint: akm feedback ${ref} --negative --reason "<what is wrong and what should change>" [--failure-mode incorrect|outdated|dangerous|incomplete|redundant]`);
             }
             else {
-                warn("Warning: negative feedback without --reason gives the next improve run nothing to base a fix on.");
+                warn("Warning: negative feedback without --reason says nothing about what is wrong.");
             }
         }
         const rawTags = parseAllFlagValues("--tag");
@@ -283,6 +375,7 @@ export const feedbackCommand = defineJsonCommand({
             ...(reason?.trim() ? { reason: reason.trim() } : {}),
             ...(failureMode ? { failureMode } : {}),
             ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
+            ...(fixPairs.length > 0 ? { fix: { source: fixSource, replacements: fixPairs.length } } : {}),
         };
         const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
         // Feedback only needs the index to exist, not to be current. A stale index
@@ -309,6 +402,7 @@ export const feedbackCommand = defineJsonCommand({
         let rankingUpdateApplied = false;
         let rankingUpdateSkippedReason;
         let durableRef = ref;
+        let fix;
         const db = openExistingDatabase();
         try {
             const config = loadConfig();
@@ -338,6 +432,23 @@ export const feedbackCommand = defineJsonCommand({
             if (!itemRef)
                 throw new UsageError(`Indexed ref "${ref}" has no durable item ref.`, "INVALID_PROPOSAL");
             durableRef = itemRef;
+            if (fixPairs.length > 0) {
+                // Checked before anything is recorded, so a fix that does not apply leaves no trace.
+                const filePath = getEntryFilePathById(db, entryId);
+                if (!filePath || !fs.existsSync(filePath)) {
+                    throw new NotFoundError(`The file for ${itemRef} is missing on disk.`, "ASSET_NOT_FOUND");
+                }
+                const resolved = resolveMutationTarget(config, parseRefInput(itemRef), undefined, { requireWritable: true });
+                if (!isWithin(filePath, resolved.target.source.path)) {
+                    throw new UsageError(`${itemRef} is outside bundle "${resolved.target.source.name}".`);
+                }
+                const before = fs.readFileSync(filePath, "utf8");
+                const after = applyExactReplacements(before, fixPairs, filePath);
+                if (after === before)
+                    throw new UsageError("The fix changes nothing.", "INVALID_FLAG_VALUE");
+                assertFrontmatterStillParses(before, after, filePath);
+                fix = { content: after, target: { source: resolved.target.source.name, root: resolved.target.source.path } };
+            }
             const recordResult = recordFeedbackUsage(db, entryId, itemRef, signal, metadataStr);
             utilityResult = recordResult.utilityResult;
             rankingUpdateApplied = recordResult.rankingUpdateApplied;
@@ -351,6 +462,16 @@ export const feedbackCommand = defineJsonCommand({
             ref: durableRef,
             metadata: metadataObj,
         });
+        const fixProposal = fix && reason?.trim() && fixSource
+            ? createProposal(resolveStashDir(), {
+                ref: durableRef,
+                itemRef: durableRef,
+                target: fix.target,
+                source: "feedback",
+                payload: { content: fix.content },
+                feedback: { reason: reason.trim(), source: fixSource },
+            })
+            : undefined;
         // F-5 / #386: When a high-utility asset crosses below the review threshold,
         // auto-create a review-needed escalation proposal so a human can confirm
         // whether the negative feedback is valid before the asset falls out of
@@ -419,6 +540,7 @@ export const feedbackCommand = defineJsonCommand({
             rankingUpdate: rankingUpdateApplied
                 ? { applied: true }
                 : { applied: false, reason: rankingUpdateSkippedReason ?? "unknown" },
+            ...(fixProposal ? { fix: { proposalId: fixProposal.id, replacements: fixPairs.length, source: fixSource } } : {}),
             ...(appliedToResult
                 ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
                 : {}),

package/dist/commands/proposal/repository.js

@@ -287,6 +287,7 @@ export function createProposal(stashDir, input, ctx) {
             ...(input.eligibilitySource !== undefined ? { eligibilitySource: input.eligibilitySource } : {}),
             ...(input.promotionSource !== undefined ? { promotionSource: input.promotionSource } : {}),
             ...(input.promotionSourceHash !== undefined ? { promotionSourceHash: input.promotionSourceHash } : {}),
+            ...(input.feedback !== undefined ? { feedback: input.feedback } : {}),
         };
         upsertProposal(db, proposal, stashDir);
         for (const ref of input.attemptedRefs ?? [normalizedRef]) {

package/dist/output/shapes/helpers.js

@@ -85,6 +85,7 @@ export function shapeProposalEntry(entry, detail) {
             "updatedAt",
             "confidence",
             "gateDecision",
+            "feedback",
             "review",
             "reviewHistory",
             "retirement",
@@ -101,6 +102,7 @@ export function shapeProposalEntry(entry, detail) {
         "updatedAt",
         "confidence",
         "gateDecision",
+        "feedback",
         "payload",
         "review",
         "reviewHistory",

package/dist/output/text/proposal-format.js

@@ -183,6 +183,11 @@ export function formatProposalShowPlain(r) {
         if (gate.decidedAt)
             lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
     }
+    const fix = p.feedback;
+    if (fix) {
+        lines.push(`feedback.reason: ${String(fix.reason)}`);
+        lines.push(`feedback.source: ${String(fix.source)}`);
+    }
     const review = p.review;
     if (review) {
         lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);

package/dist/scripts/akm-migrate-node.js

@@ -28539,6 +28539,7 @@ function shapeProposalEntry(entry, detail) {
       "updatedAt",
       "confidence",
       "gateDecision",
+      "feedback",
       "review",
       "reviewHistory",
       "retirement"
@@ -28554,6 +28555,7 @@ function shapeProposalEntry(entry, detail) {
     "updatedAt",
     "confidence",
     "gateDecision",
+    "feedback",
     "payload",
     "review",
     "reviewHistory",
@@ -30491,6 +30493,11 @@ function formatProposalShowPlain(r) {
     if (gate.decidedAt)
       lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
   }
+  const fix = p.feedback;
+  if (fix) {
+    lines.push(`feedback.reason: ${String(fix.reason)}`);
+    lines.push(`feedback.source: ${String(fix.source)}`);
+  }
   const review = p.review;
   if (review) {
     lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);

package/dist/scripts/akm-migrate.js

@@ -27867,6 +27867,7 @@ function shapeProposalEntry(entry, detail) {
       "updatedAt",
       "confidence",
       "gateDecision",
+      "feedback",
       "review",
       "reviewHistory",
       "retirement"
@@ -27882,6 +27883,7 @@ function shapeProposalEntry(entry, detail) {
     "updatedAt",
     "confidence",
     "gateDecision",
+    "feedback",
     "payload",
     "review",
     "reviewHistory",
@@ -29819,6 +29821,11 @@ function formatProposalShowPlain(r) {
     if (gate.decidedAt)
       lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
   }
+  const fix = p.feedback;
+  if (fix) {
+    lines.push(`feedback.reason: ${String(fix.reason)}`);
+    lines.push(`feedback.source: ${String(fix.source)}`);
+  }
   const review = p.review;
   if (review) {
     lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);

package/dist/storage/repositories/proposals-repository.js

@@ -171,6 +171,12 @@ function validatePresentMetadata(meta) {
             }
         }
     }
+    if (Object.hasOwn(meta, "feedback")) {
+        const fix = meta.feedback;
+        if (!isRecord(fix) || typeof fix.reason !== "string" || typeof fix.source !== "string") {
+            invalidPresentField("feedback");
+        }
+    }
     if (Object.hasOwn(meta, "acceptedTarget")) {
         const target = meta.acceptedTarget;
         if (typeof target !== "object" ||
@@ -293,6 +299,7 @@ export function proposalRowToProposal(row) {
         ...(meta.reviewHistory !== undefined ? { reviewHistory: meta.reviewHistory } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
+        ...(meta.feedback !== undefined ? { feedback: meta.feedback } : {}),
         ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
         ...(meta.acceptedTarget !== undefined ? { acceptedTarget: meta.acceptedTarget } : {}),
         ...(typeof meta.eligibilitySource === "string"
@@ -359,6 +366,8 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.confidence = proposal.confidence;
     if (proposal.gateDecision !== undefined)
         metaObj.gateDecision = proposal.gateDecision;
+    if (proposal.feedback !== undefined)
+        metaObj.feedback = proposal.feedback;
     if (proposal.backupContent !== undefined)
         metaObj.backupContent = proposal.backupContent;
     if (proposal.acceptedTarget !== undefined)

package/docs/reference/cli.md

@@ -1589,9 +1589,14 @@ preserves it byte-for-byte.
 
 Record positive or negative feedback for any indexed bundle asset.
 `akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
-flags the asset for review: the next improve run proposes a fix based on your
-reason, so be specific. `--positive` records that an asset helped (it raises
-its ranking) and does not trigger a rewrite. Both signals update the asset's
+flags the asset: it ranks lower right away, and the next improve run may repair
+its description, title or `when_to_use` from your reason. Improve does not
+rewrite an asset's text. To correct a wrong fact there, attach the exact fix
+with `--replace`, `--with` and `--source`: akm checks that each `--replace`
+text appears exactly once and that the frontmatter still parses, records nothing
+if either check fails, and queues the edit as a `feedback` proposal for review.
+`--positive` records that an asset helped (it raises its ranking) and does not
+trigger a rewrite. Both signals update the asset's
 utility score right away, so highly-rated assets rank higher in search results.
 
 ```sh
@@ -1602,13 +1607,17 @@ akm feedback env/prod --positive
 akm feedback skills/code-review --positive --reason "Worked perfectly for PR reviews"
 akm feedback skills/code-review --negative --failure-mode outdated --reason "references a removed flag"
 akm feedback skills/code-review --negative --reason "flaky" --tag slice:train --tag team:platform
+akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/"
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--positive` | Record that an asset helped: it raises its ranking and does not trigger a rewrite |
-| `--negative` | Flag the asset for review: the next improve run proposes a fix based on `--reason`, so be specific |
-| `--reason` | What is wrong with the asset's content and what should change; not for `akm` command errors. Attached to the feedback event and read by the next improve run's fix proposal (required for negative feedback by default) |
+| `--negative` | Flag the asset: it ranks lower right away, and the next improve run may repair its frontmatter from `--reason` |
+| `--reason` | What is wrong with the asset's content and what should change; not for `akm` command errors. Attached to the feedback event (required for negative feedback by default, and always with `--replace`) |
+| `--replace <text>` | Exact text to correct, copied verbatim from the asset file; it must appear exactly once. Repeatable, each paired in order with a `--with`. Negative feedback only |
+| `--with <text>` | The corrected text for the matching `--replace`. Use `--with=<text>` for a value that starts with `-` |
+| `--source <where>` | The URL, command or file that shows the correct fact. Required with `--replace`; shown to the reviewer with the proposal |
 | `--failure-mode` | Structured failure-mode taxonomy for negative feedback: `incorrect`, `outdated`, `dangerous`, `incomplete`, `redundant`. Stored alongside `--reason` in event metadata for the distill pipeline. |
 | `--tag` | Tag to attach to the feedback (repeatable, e.g. `--tag slice:train --tag team:platform`) |
 | `--applied-to <ref>` | Credit a `lessons/<name>` lesson that helped resolve this task. When combined with `--positive`, appends this feedback ref to the target lesson's `lessonStrength[]` frontmatter array (dedup, idempotent). A non-lesson target, or a missing `--positive`, produces a warning rather than silently doing nothing. |
@@ -3097,8 +3106,8 @@ akm proposal drain --strategy default --promote -y  # Read the triage block from
 
 `akm feedback` accepts an optional `--reason <text>` flag whose value is
 forwarded into feedback metadata and consumed by improve/distill proposal
-prompts. Negative feedback requires a reason by default: the next improve run
-proposes a fix from it, so say what is wrong and what should change.
+prompts. Negative feedback requires a reason by default: say what is wrong and
+what should change.
 
 Write the reason about the asset's content. Reflect treats it as an unverified
 report to investigate, not a fact to insert, and is told to leave the section

package/docs/reference/data-and-telemetry.md

@@ -159,7 +159,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `curate` | `akm curate <prompt>` | `query`, `itemCount`, `itemRefs` |
 | `show` | `akm show <ref>` | `ref`, `type`, `name` |
 | `select` | `akm show` after a search returning the same ref | `ref`, `query`, `searchTs`, `rankPosition` |
-| `feedback` | `akm feedback <ref>` | `signal` (positive/negative), `reason`, `failureMode`, `tags` |
+| `feedback` | `akm feedback <ref>` | `signal` (positive/negative), `reason`, `failureMode`, `tags`, `fix` (`source` and the number of replacements, when an exact fix was attached) |
 | `sync` | `akm sync` | `name`, `message`, `ok` |
 | `index_db_vacuumed` | `akm index` VACUUMed index.db, after an index layout migration or because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
 | `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.26-alpha.1",
+  "version": "0.9.26-alpha.2",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [