akm-cli 0.10.261004-beta → 0.10.261006-beta

package/dist/core/write-source.js

@@ -22,7 +22,8 @@
  * {@link commitWriteTargetBoundary} once — or wrap a custom mutation in
  * {@link withWriteTargetMutation}, which does both under the asset lease. An
  * accepted proposal commits its own paths ({@link commitAcceptedPaths}), on a
- * filesystem stash that is a git repository too.
+ * filesystem stash that is a git repository too. A process that accepts many
+ * proposals collects them and commits once at its boundary (#1185).
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -423,6 +424,7 @@ export function commitWriteTargetBoundary(target, message, options) {
         const saved = saveGitStash(undefined, message, resolveWritable(target.config), {
             repoDir,
             paths: committable,
+            ...(options?.body ? { body: options.body } : {}),
             ...(options?.push === undefined ? {} : { push: options.push }),
         });
         if (saved.reason)
@@ -430,9 +432,10 @@ export function commitWriteTargetBoundary(target, message, options) {
     }
     catch (error) {
         if (error instanceof GitStashPushError) {
-            throw new Error(`Changes were committed as ${error.commit}, but publication failed: ${error.message}`, {
-                cause: error,
-            });
+            const what = error.committedNow
+                ? `Changes were committed as ${error.commit}`
+                : `Nothing new to commit; earlier commits up to ${error.commit} are unpushed`;
+            throw new Error(`${what}, but publication failed: ${error.message}`, { cause: error });
         }
         throw error;
     }
@@ -443,10 +446,11 @@ export function commitWriteTargetBoundary(target, message, options) {
  * boundary commit skips, locally (the end-of-run sync pushes). A failed commit
  * only warns, since the accept already landed.
  */
-export function commitAcceptedPaths(target, message, paths) {
+export function commitAcceptedPaths(target, message, paths, body) {
     try {
         commitWriteTargetBoundary(target, message, {
             paths,
+            ...(body ? { body } : {}),
             filesystem: true,
             ...(target.source.kind === "git" ? {} : { push: false }),
         });

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

@@ -112,7 +112,8 @@ export async function searchLocal(input) {
     // Bootstrap-only: builds the index inline when it cannot serve this stash.
     // Content freshness is the writers' job (indexWrittenAssets + full runs);
     // reads serve the existing index as-is.
-    await ensureIndex(stashDir);
+    if (!input.readOnly)
+        await ensureIndex(stashDir);
     const dbPath = getDbPath();
     // An index we cannot READ is not an index that does not exist (#791). Saying
     // "No search index available" for a populated index the caller merely lacks

package/dist/output/format-exempt.js

@@ -41,6 +41,9 @@ const EXEMPT_COMMANDS = new Set([
     "help",
     // Embedded agent guide document (`src/output/cli-hints.ts`).
     "hints",
+    // Prints the URL it is serving and then runs until interrupted; the data is
+    // the web UI's own JSON API, not a result envelope.
+    "ui",
 ]);
 /**
  * `<command> <subcommand>` pairs that are exempt while the rest of the group

package/dist/sources/providers/git-stash.js

@@ -127,10 +127,13 @@ export function checkGitPathSafety(repoDir, pathspec) {
 }
 export class GitStashPushError extends Error {
     commit;
-    constructor(message, commit) {
+    /** False when the push was of commits made earlier (nothing was committed by this call). */
+    committedNow;
+    constructor(message, commit, committedNow = true) {
         super(message);
         this.name = "GitStashPushError";
         this.commit = commit;
+        this.committedNow = committedNow;
     }
 }
 const GIT_PUSH_TIMEOUT_MS = 120_000;
@@ -191,7 +194,11 @@ export function saveGitStash(name, message, writableOverride, options) {
     // Co-Authored-By: someone-else"` and forge trailers in the commit log.
     // Empty result falls back to the timestamped default.
     const sanitized = message ? sanitizeCommitMessage(message) : "";
-    const commitMessage = sanitized || `akm save ${timestamp}`;
+    const bodyLines = (options?.body ?? []).map(sanitizeCommitMessage).filter(Boolean);
+    const commitMessage = [
+        sanitized || `akm save ${timestamp}`,
+        ...(bodyLines.length > 0 ? ["", ...bodyLines] : []),
+    ].join("\n");
     const transactionId = options?.transactionId;
     if (transactionId !== undefined && !/^[A-Za-z0-9._-]{1,128}$/.test(transactionId)) {
         throw new Error("Invalid Git transaction identifier.");
@@ -317,22 +324,12 @@ export function saveGitStash(name, message, writableOverride, options) {
             commit: exactCommit,
         };
     }
-    const pushResult = runGit([
-        "-C",
-        repoDir,
-        "push",
-        `--force-with-lease=${pushTarget.mergeRef}:${pushTarget.upstreamHead}`,
-        pushTarget.remote,
-        `${readOptionalHead(repoDir) ?? exactCommit}:${pushTarget.mergeRef}`,
-    ], { timeout: GIT_PUSH_TIMEOUT_MS });
-    if (pushResult.status !== 0) {
-        throw new GitStashPushError(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`, exactCommit);
-    }
+    const pushOutput = pushToUpstream(repoDir, pushTarget, readOptionalHead(repoDir) ?? exactCommit, exactCommit);
     return {
         committed: true,
         pushed: true,
         skipped: false,
-        output: pushResult.stdout.trim() || "changes committed and pushed",
+        output: pushOutput || "changes committed and pushed",
         commit: exactCommit,
     };
 }
@@ -343,12 +340,46 @@ function readHasRemote(repoDir) {
     }
     return remoteResult.stdout.trim().length > 0;
 }
-/** Nothing to commit still brings in the upstream, so a host with no changes of its own keeps up. */
+/**
+ * Push `head` to the upstream, leased on the upstream head just read. Throws {@link GitStashPushError}
+ * (carrying `commit`) when git refuses. Returns git's stdout.
+ */
+function pushToUpstream(repoDir, target, head, commit, committedNow = true) {
+    const pushResult = runGit([
+        "-C",
+        repoDir,
+        "push",
+        `--force-with-lease=${target.mergeRef}:${target.upstreamHead}`,
+        target.remote,
+        `${head}:${target.mergeRef}`,
+    ], { timeout: GIT_PUSH_TIMEOUT_MS });
+    if (pushResult.status !== 0) {
+        throw new GitStashPushError(`git push failed: ${pushResult.stderr?.trim() || "unknown error"}`, commit, committedNow);
+    }
+    return pushResult.stdout.trim();
+}
+/**
+ * Nothing to commit still brings in the upstream, so a host with no changes of its own keeps up. Commits
+ * made earlier and never pushed (a proposal accept, a killed improve run) are pushed here, once the
+ * branch is up to date with its upstream and ahead of it.
+ */
 function nothingToCommit(repoDir, output, syncWithRemote) {
     const integration = syncWithRemote ? integrateUpstream(repoDir) : undefined;
     if (integration && "blocked" in integration) {
         return { committed: false, pushed: false, skipped: false, reason: `not pushed: ${integration.blocked}`, output };
     }
+    // readUpstreamConfig is undefined on a detached HEAD or a branch with no upstream: nothing to push.
+    const head = syncWithRemote && readUpstreamConfig(repoDir) ? readOptionalHead(repoDir) : undefined;
+    const upstream = head ? readActualUpstream(repoDir, head) : undefined;
+    if (head && typeof upstream === "object" && upstream.upstreamHead !== head) {
+        const pushOutput = pushToUpstream(repoDir, upstream, head, head, false);
+        return {
+            committed: false,
+            pushed: true,
+            skipped: false,
+            output: pushOutput || `pushed ${upstream.upstreamHead.slice(0, 7)}..${head.slice(0, 7)}`,
+        };
+    }
     return { committed: false, pushed: false, skipped: false, output: integration?.integrated ?? output };
 }
 function readUpstreamConfig(repoDir) {

package/dist/storage/repositories/improve-runs-repository.js

@@ -121,6 +121,12 @@ export function getLatestImproveRun(db) {
         .prepare(`SELECT ${IMPROVE_RUN_ROW_COLUMNS} FROM improve_runs WHERE dry_run = 0 ORDER BY started_at DESC LIMIT 1`)
         .get();
 }
+/** The `limit` most recent real (non-dry-run) improve runs, newest first (`akm ui`'s run list). */
+export function listRecentImproveRuns(db, limit) {
+    return db
+        .prepare("SELECT id, started_at, completed_at, ok, scope_mode, scope_value, strategy, result_json FROM improve_runs WHERE dry_run = 0 ORDER BY started_at DESC LIMIT ?")
+        .all(limit);
+}
 /**
  * #950: count real (non-dry-run) improve_runs rows whose `started_at` falls
  * in `[since, now)` — same filter as {@link queryImproveRuns}, but a `SELECT

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

@@ -17,6 +17,23 @@ export function listUsageEventRows(db, filter) {
        ORDER BY datetime(created_at), id`)
         .all(filter.sinceIso, untilBound, ...sourceParams);
 }
+/** One asset's feedback rows (`entry_ref` is the durable `bundle//conceptId`), newest first (`akm ui`'s asset view). */
+export function listFeedbackEventRows(db, entryRef, limit) {
+    return db
+        .prepare(`SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, source, created_at
+       FROM usage_events
+       WHERE event_type = 'feedback' AND entry_ref = ?
+       ORDER BY datetime(created_at) DESC, id DESC LIMIT ?`)
+        .all(entryRef, limit);
+}
+/** Feedback counts by signal for one asset, all sources (`akm ui`'s asset view). */
+export function countFeedbackBySignal(db, entryRef) {
+    const rows = db
+        .prepare(`SELECT COALESCE(signal, 'none') AS signal, COUNT(*) AS n FROM usage_events
+       WHERE event_type = 'feedback' AND entry_ref = ? GROUP BY signal`)
+        .all(entryRef);
+    return Object.fromEntries(rows.map((row) => [row.signal, row.n]));
+}
 /**
  * `select` events (a show within 60 s of a search that returned the ref) in the
  * window. The events stream stores the ref as the user typed it (often

package/docs/architecture/0.10-process-rules.md

@@ -11,7 +11,7 @@ This version adds the policy batch: Policy decisions 1, 3, 4, 5, 7 and 9 are imp
 ## TLDR
 
 - **The improve run** plans from fresh feedback plus a capped proactive lane, works only on the write-target bundle, and only touches assets someone retrieved in the last 90 days or new material. It takes a PID lock, syncs a git-backed bundle like `akm sync` (commit pending managed-path edits, fetch, merge, push) before it reads anything, has a 2-hour budget, commits and pushes only the files it wrote, and records every run in `improve_runs`.
-- **Reflect** runs only on fresh negative feedback (or the proactive lane) and may change only `description`, `when_to_use` and a title, never the body text (a title is added as a `# heading` when the body has none). The judge must score every criterion 4 or higher, and nothing is checked after it. A non-pass with a mean of 3.5 or more and a judge outage go to a person as a pending proposal; a lower non-pass or a defect is refused with no proposal and a hard 14-day window.
+- **Reflect** runs only on fresh negative feedback (or the proactive lane) and may change only `description`, `when_to_use` and a title, and the title edits the body only by adding a missing `# heading`; the body is otherwise byte for byte unchanged. The judge must score every criterion 4 or higher, and nothing is checked after it. A non-pass with a mean of 3.5 or more and a judge outage go to a person as a pending proposal; a lower non-pass or a defect is refused with no proposal and a hard 14-day window.
 - **Distill** needs feedback in the last 30 days, and skips a memory whose only feedback is a positive with no reason or note (10 of 11 lessons from such memories were rejected). Lessons that pass the judge still go to a person, never the drain. The proactive lane never feeds distill.
 - **Consolidate** only promotes memories to knowledge; the pair pass retires a duplicate only when the claim lists show nothing would be lost. A retirement is staged for the drain only if the claims are clean, there is no continuity risk and the second look agrees. There is no confidence cutoff. A `captureMode: hot` memory is retired, promoted and archived like any other. The pair pass, the coverage gate and the continuity check all need embeddings, which are off by default.
 - **Triage** accepts only what a deterministic gate passed (a proposal whose judge stamp still matches its content hash, or a retirement the pair pass staged), up to 200 per run. The judgment step is off by default and may only accept consolidate promotions. Proactive-lane proposals, distill lessons and uncertain judge verdicts wait for a person.
@@ -211,7 +211,7 @@ These 14 bugs are fixed on this branch; the rules below describe the fixed behav
 - **Ranking inside the lane** — Priority is the salience rank score computed from type-stub encoding, retrieval frequency, last use and file size. It has no outcome term. Ties break by staleness (never-touched first), then ref ascending. There is no randomisation, so at 15 a day and 30 days between visits at most about 450 distinct assets ever cycle, and among never-retrieved assets of one type priority differs only by file size, so the same smallest files recur. The lane has no memory of futility: a `no_change` reflect records `unchanged` and resets the 30-day clock, and the no-op damper applies only to the merged loop ranking, not to the lane's own priority (`rankScore` is used raw), so an asset reflect already found sound returns at full priority every 30 days. (`proactive-maintenance.ts:94-123`, `preparation.ts:963-966`)
 - **Lane attribution** — Each planned ref is tagged `proactive` < `signal-delta` < `scope`; the strongest lane wins. The tag goes on the dry-run plan, the events, and the proposal as `eligibilitySource`. *Why:* so outcomes can be sliced by lane. (`preparation.ts:948-954`, `src/commands/proposal/proposal-types.ts:15-27`)
 - **Events and plan** — A live run appends a `proactive_selected` event (count, dueTotal, neverReflected). The plan reports `configured`, `effective` (`dueDays`, `maxPerRun`), `candidatePool` and `selectedRefs`. (`preparation.ts:1119-1146`)
-- **What it may propose** — Reflect proposals in practice: reflect revises only `description`, `when_to_use` and the title, never the body. A proactively picked memory is never distilled, because it has no feedback signal (`memory_distill_requires_feedback`; non-memory picks fail distill's type filter); the only link to distill is that a distill attempt resets the lane's due clock. *Why:* on 396 labelled edits, frontmatter-only fixes were good 24/26 times, and edits that also rewrote the body were bad 175 of 224. (`docs/architecture/improvement.md` "Quality judge", `loop-stages.ts:302-310`)
+- **What it may propose** — Reflect proposals in practice: reflect edits frontmatter (`description`, `when_to_use`, `title`), plus at most a missing level-1 heading; the body is otherwise byte for byte unchanged. A proactively picked memory is never distilled, because it has no feedback signal (`memory_distill_requires_feedback`; non-memory picks fail distill's type filter); the only link to distill is that a distill attempt resets the lane's due clock. *Why:* on 396 labelled edits, frontmatter-only fixes were good 24/26 times, and edits that also rewrote the body were bad 175 of 224. (`docs/architecture/improvement.md` "Quality judge", `loop-stages.ts:302-310`)
 - **Its proposals wait for a person** — `proposal drain` never accepts a proposal with `eligibilitySource:"proactive"`, whether a deterministic gate, an earlier staged accept or the judgment tier would take it. It is deferred with reason `proactive-needs-review` and is not sent to the judgment tier. Empty diffs are still rejected. Unattended, then, the lane cannot fix anything: the proposal expires after 90 days while the asset is due again after 30, so it is re-reflected at about day 30 and day 60 before the first proposal expires, and up to three identical pending proposals can exist for one asset (nothing blocks a second pending reflect proposal for a ref; see Reflect: Nothing prevents a second pending reflect proposal). *Why:* with the lane on and the drain promoting, reflect edits on assets with no feedback were accepted unattended. The nightly eval showed `when_to_use`, `type` and provenance stamps and a title heading added to assets no one asked about (#1147). (`src/commands/proposal/drain.ts:12-17,593-596`, CHANGELOG 0.10.26101001 "A proposal from the proactive lane waits for a person", #1147)
 - **Unreviewed proactive proposals expire** — A pending proposal older than `archiveRetentionDays` (default 90; 0 disables) is archived as rejected (`expired`) in post-loop hygiene. Counting starts from the last reopen. Retire proposals expire the same way (fixed in this PR, #10). (`src/commands/proposal/repository.ts:872-927`)
 
@@ -296,7 +296,7 @@ All paths are relative to the `rules-010` worktree. Citation form is `path:line`
 
 ### What reflect may change
 
-- **Only `description`, `when_to_use` and a title. The body text is the source's own, except that a title adds a `# title` heading.** The engine returns `confidence` plus `frontmatterPatch {description, when_to_use, title}`, each a non-empty single-line string or `null`. akm applies the patch itself. When the patch carries a title and the body has no level-1 heading, akm prepends `# <title>` and strips every leading blank line of the body, so the body is not byte for byte unchanged; #1147 lists exactly this edit ("a title heading added to assets no one asked about") as harm. After the judge, the proposal mint also splices `type:` and `updated:` lines into the frontmatter when they are missing (next rules and Proposal outcome). *Why:* on 396 labelled reflect edits, frontmatter-only fixes were good 24 of 26 times, and edits that also rewrote the body were bad 175 of 224. (`reflect.ts:5-10,229-235,237-259,313-322,428-446`; CHANGELOG 0.9.25-alpha.3)
+- **Only `description`, `when_to_use` and a title. The body text is the source's own, byte for byte, except that a title adds a missing `# title` heading.** The engine returns `confidence` plus `frontmatterPatch {description, when_to_use, title}`, each a non-empty single-line string or `null`. akm applies the patch itself. When the patch carries a title and the body has no level-1 heading, akm inserts `# <title>` and one blank line at the body's first non-blank line, in the body's own line ending, and changes nothing else: leading blank lines stay, so the only body difference is the inserted heading. A missing H1 is a valid reflect edit and the only body change reflect may make, so a gate or reviewer that treats a proposal as frontmatter-only must accept it (#1183). Of 21 pending proactive-lane proposals on 2026-10-14, 17 differed from their source only by the inserted heading and the stripped blank lines, and all 17 were rejected as body edits; the title is kept because with the problem list in the prompt the model fixed 189 of 193 missing titles. After the judge, the proposal mint also splices `type:` and `updated:` lines into the frontmatter when they are missing (next rules and Proposal outcome). *Why:* on 396 labelled reflect edits, frontmatter-only fixes were good 24 of 26 times, and edits that also rewrote the body were bad 175 of 224. (`reflect.ts:5-10,229-235,237-259,313-322,428-446`; CHANGELOG 0.9.25-alpha.3)
 - **A title becomes a `# title` heading only if the body has no level-1 heading.** Otherwise the title is ignored. The test is a multi-line regex that also matches a `# comment` line inside a fenced shell block, which suppresses the title. (`reflect.ts:257-259`)
 - **Only the changed keys' frontmatter lines are rewritten.** Every other line is kept, and an unchanged-equal field is dropped from the patch. The mint then adds `type:` and `updated:` lines (see Mint below). *Why:* a source whose YAML the parser reads only partly (a broken description beside a list) must lose nothing. (`reflect.ts:243-245,274,289-304`)
 - **A source whose frontmatter fence is opened but never closed gets no proposal.** It is reported as `no_change` ("empty diff"), recorded `unchanged` and counted by the plasticity counter; the person the comment says should fix it is never told. *Why:* it would leave the old block in the body under a new one, so a person fixes it. (`reflect.ts:253-255,1042-1059`)
@@ -413,7 +413,6 @@ All paths are relative to the `rules-010` worktree. Citation form is `path:line`
 - `salience.ts:129-134` documents the no-op dampener as "Consolidation selection only", but `preparation.ts:956-969` applies it when ranking the reflect/distill loop.
 - The `content_policy_reject` / `reflect-guard-rejected` classification still exists, but the reflect size rail it was named for was removed in 0.9.25-alpha.3.
 - Reflect's judge labels a mean in [2.5, 4) as "review" (`runQualityJudge`), but reflect sends only a mean of 3.5 or more to a person and refuses 2.5 to 3.5; the cut is `REFLECT_REVIEW_MIN_SCORE`, not the judge's label (changed in this PR, decision 4). (`stage.ts:643`, `reflect.ts:1018,1104-1116`)
-- The code comment at `reflect.ts:239-241` and the judge intro (`stage.ts:464`) say the body is kept byte for byte / unchanged apart from an added title heading; neither mentions that every leading blank line of the body is stripped when the heading is prepended (`reflect.ts:258-259`).
 
 ## Distill
 
@@ -658,7 +657,7 @@ Paths are relative to the rules-010 checkout. `drain.ts` is `src/commands/propos
 - **Judgment verdict handling** — The judge returns accept, reject or defer, and parse failures and runner errors leave the item deferred (`judgment-parse-failure`, `judgment-error`). A judge reject becomes an auto-reject (`judgment-reject`). The judge sees the live asset (for a promotion, which is a create, the prompt prints "(none — this proposal would create a new asset)"), same-ref sibling proposals, and, only for such a create, the 5 nearest knowledge notes (300-character excerpts, plus promotions accepted earlier in the same drain). It is told to reject a promotion those notes already cover, or one that reports changing state ("as of <date>", a rollout, a plan not yet carried out). A lesson drawn from an incident is durable. *Why:* the model never sees `knowledge/` otherwise, and 18 of 51 promotions minted on 2026-10-07 and later rejected held 30% or more in a neighbouring doc. (`drain.ts:253-306,371-497,499-534`; `src/commands/improve/consolidate/coverage.ts:154-186`)
 - **Judgment queue-mode staging** — In `queue` mode a judged accept is stamped `staged` (`judgment-accept`) with its content hash, for a later promote run. (`drain.ts:444-464`)
 - **Excluded proposals** — `excludeIds` is always empty in improve (`improve.ts:869`); "this run's fresh proposals are never touched" is an ordering effect, because the pre-pass runs before consolidation mints. `--older-than <days>` on `proposal drain` excludes proposals younger than that, counted from creation or the last reopen, and fails safe by excluding any proposal whose age cannot be computed. (`drain.ts:559-564`; `src/commands/proposal/proposal-cli.ts:468-505`; `src/commands/proposal/proposal-types.ts:316-326`; `improve.ts:869`)
-- **What auto-accept means for git** — Every auto-accept is the ordinary promote path, so it writes the asset and commits it to the target with the subject `akm accept: <source> <8-char id> <ref>`. For a consolidate promotion the commit also carries the archived source memory and its tombstone. Filesystem targets never push; a git-kind target uses the default push behaviour. Commit failure is only a warning, not a failure of the accept. The standalone `drain --promote` asks for confirmation before promoting ("commit to git and cannot be batch-reverted"). A revert is per proposal (`akm proposal revert`). (`src/commands/proposal/repository.ts:1459-1462,1574-1596`; `src/core/write-source.ts:615-627`; `proposal-cli.ts:471-482`)
+- **What auto-accept means for git** — Every auto-accept is the ordinary promote path, so it writes the asset and commits it to the target with the subject `akm accept: <source> <8-char id> <ref>`, but a loop of accepts (`drain`, bulk `accept --generator`, `accept <id> <id>`) commits once per process: `<label>: N accepted (<source> n, ...)` with one `<id8> <source> <ref>` body line per proposal (#1185). Inside `akm improve` the triage accepts join the run's end-of-run batch commit (or, with sync off or no git repository, are committed once when the pre-pass ends). For a consolidate promotion the commit also carries the archived source memory and its tombstone. Filesystem targets never push; a git-kind target uses the default push behaviour. Commit failure is only a warning, not a failure of the accept. The standalone `drain --promote` asks for confirmation before promoting ("commit to git and cannot be batch-reverted"). A revert is per proposal (`akm proposal revert`). (`src/commands/proposal/repository.ts` (`commitAccept`, `commitCollectedAccepts`); `src/core/write-source.ts` (`commitAcceptedPaths`); `proposal-cli.ts:471-482`)
 - **Drain failures stay pending** — An attempt that fails (validation, promote error) is listed under `failed` with a categorized reason and the proposal stays pending. A rejected proposal is recorded with a gate decision under gate `triage`. (`drain.ts:142-150,641-656`)
 
 ## Proposals and feedback

package/docs/architecture/improvement.md

@@ -117,9 +117,12 @@ everything else routes through `akm proposal accept`.
 7. `akm proposal accept` promotes the proposal into the bundle; `akm proposal
    revert` restores the prior content from the backup captured at promotion
    time, if the proposal overwrote an existing asset. When the bundle is a git
-   repository (a `.git` directory, whatever its source kind), each accept is
-   committed as it happens, locally and with exactly the paths it wrote or
-   removed: `akm accept: <generator> <proposal-id-8> <ref>`. A retirement's
+   repository (a `.git` directory, whatever its source kind), an accept is
+   committed locally with exactly the paths it wrote or removed:
+   `akm accept: <generator> <proposal-id-8> <ref>`. A process that accepts
+   several (`akm proposal drain`, a bulk accept, `accept <id> <id>`) commits them
+   once at its end, with a summary subject and one body line per proposal; in
+   `akm improve` the triage accepts join the end-of-run batch commit. A retirement's
    archived copy and tombstone, and the source memory a consolidate promotion
    retires, go in the same commit. A commit that fails warns and the accept
    stands.
@@ -238,7 +241,8 @@ it for a person too. On 2026-10-05 the gate had
 staged 12 lessons and 10 were bad (they restated the memory, claimed what it
 does not say, or filed a dated status as a lesson), and no score separated them
 from the two good ones. Reflect revises only an asset's
-`description`, `when_to_use` and title, never its body. On 396 labelled edits,
+`description`, `when_to_use` and title, and edits the body only to add a missing level-1
+heading; the rest of the body stays byte for byte. On 396 labelled edits,
 those that fixed a frontmatter defect and left the body alone were good 24
 times in 26, and those that also rewrote the body were bad 175 times in 224.
 
@@ -438,7 +442,7 @@ tombstone `retiredAt` is more than 30 days old (`RETIRE_GRACE_DAYS`) AND
 whose archive directory is entirely git-tracked and clean (`git ls-files`
 plus `git status --porcelain -uall`, both checked once per sweep, not once
 per directory). `.git` presence alone does not guarantee a retirement was
-ever committed: an accept commits its own paths (`commitAcceptedPaths` in
+ever committed: an accept commits its own paths, once per process (`commitAcceptedPaths` in
 `src/core/write-source.ts`), on a `kind: "filesystem"` source with a `.git`
 directory too, but a commit that failed only warned, and a retirement accepted
 by an older akm left archived bytes sitting on disk with no commit behind them

package/docs/architecture/internals/improve-workflow.md

@@ -187,7 +187,7 @@ flowchart TD
 
 `akmReflect` is the agent-invocation subprocess. It always emits a `reflect_invoked` event at entry, regardless of success or failure.
 
-Reflect changes only an asset's `description`, `when_to_use` and title. The engine replies with those fields (each `null` when it needs no fix), and akm applies them to the asset it read: the body is kept byte for byte, apart from a `# <title>` heading akm adds when the body has none. A reply that changes nothing creates no proposal.
+Reflect changes only an asset's `description`, `when_to_use` and title. The engine replies with those fields (each `null` when it needs no fix), and akm applies them to the asset it read: the body is kept byte for byte, apart from a `# <title>` heading and one blank line akm inserts when the body has no level-1 heading (the only body change reflect makes). A reply that changes nothing creates no proposal.
 
 **Internal steps:**
 
@@ -208,7 +208,7 @@ Reflect changes only an asset's `description`, `when_to_use` and title. The engi
    LLM does. An LLM endpoint that rejects JSON Schema gets the framed-markdown
    contract instead.
 6. Validate the reply with `parseSchemaReflectOutput` (`parseFramedReflectOutput` for the framed contract), which strips `<think>` blocks and code fences, then requires exactly the contract's fields: `confidence` and a `frontmatterPatch` of `description`, `when_to_use` and `title` (each a non-empty single-line string, or `null` for no change), plus `ref` when no target was given. A reply that fails gets one repair turn, shared across self-refine passes: the conversation so far, and a request to reformat the reply in the contract (`reflect-output-repair.md`). A reply still invalid fails with `parse_error` and queues nothing. A failed agent or SDK dispatch is reported as it ran, with its exit code and stderr.
-7. Apply the patch (`applyReflectPatch`) to the source asset: its frontmatter with the non-null `description` and `when_to_use` set, and its body unchanged. A non-null `title` becomes a `# <title>` heading and one blank line at the top of the body, only when the body has no level-1 heading; otherwise it is ignored. A source that requires a `description` and has none gets one derived from its own text when the patch gave none (#636). A patch that changes nothing (every field `null`, or equal to the source's, and no `description` to derive) is the `no_change` outcome (`reflect_skipped_noop`), as is a source with no content to patch; a result that differs only cosmetically is `reflect_skipped_cosmetic`. Neither creates a proposal.
+7. Apply the patch (`applyReflectPatch`) to the source asset: its frontmatter with the non-null `description` and `when_to_use` set, and its body unchanged. A non-null `title` becomes a `# <title>` heading and one blank line inserted at the body's first non-blank line, in the body's line ending, only when the body has no level-1 heading; otherwise it is ignored. Leading blank lines and every other body byte are kept. A source that requires a `description` and has none gets one derived from its own text when the patch gave none (#636). A patch that changes nothing (every field `null`, or equal to the source's, and no `description` to derive) is the `no_change` outcome (`reflect_skipped_noop`), as is a source with no content to patch; a result that differs only cosmetically is `reflect_skipped_cosmetic`. Neither creates a proposal.
 8. Quality gate (`processes.reflect.qualityGate`, on unless disabled): one judge call scores the revision against the source on **need**, **preservation** and **quality** ([Quality judge](../improvement.md#quality-judge)), and passes it only when every criterion scores 4 or more. A score that does not pass is refused (`quality_rejected`, no proposal) unless its mean is 3.5 or more: that is uncertain, not bad, and the proposal is deferred for a person (`judge-uncertain`, gate `quality-gate`, with the criterion `scores` and the judge's reason) and records no rejection window. A judge that times out, errors or replies unparseably gives no verdict, and the proposal is deferred for review too (`judge-error`, gate `quality-gate`). Before the judge, with the gate on or off, reflect refuses (`quality_rejected`, no proposal, no judge call; the rule is the event's `reflectDefect`) a revision that adds placeholder text (`placeholder_added`: "please confirm", "to be confirmed"; not `TODO`, `TBD` or `FIXME`), talks about its own edit (`meta_commentary_added`: "the feedback says", "this revision") or copies frontmatter into its body (`frontmatter_copied_into_body`: `sources:` or `updated:` lines outside code, a `sources` value). Each rule counts only what the revision adds to its source (`findReflectDefect`), and its wording is a list that `processes.reflect.defectFilter` replaces or, when empty, turns off ([Configuration](../../reference/configuration.md#strategies)).
 9. Write the proposal (`mintProposal`). A pass the judge passed is stamped `staged`, and the triage drain accepts it; with the gate off the proposal is minted unstamped for the drain to decide. One made with no judge configured (`no-judge-configured`) is deferred for review (gate `reflect`), and so is one whose judge gave no verdict (`judge-error`) and one in the judge's uncertain band (`judge-uncertain`). `akm proposal list` shows the reason; the drain leaves every deferral for a person.
 

package/docs/reference/README.md

@@ -5,6 +5,7 @@ Authoritative reference documentation for the akm CLI and its data.
 - [Programmatic API](api.md) -- `akm-cli/api`: in-process `curate()` for the akm plugins
 - [Bundle Types](bundle-types.md) -- Supported bundle formats and compatibility
 - [CLI](cli.md) -- All `akm` commands and flags
+- [UI API](ui-api.md) -- The read-only JSON API behind `akm ui`
 - [Configuration](configuration.md) -- Engines, strategies, bundles, and settings
 - [Supported Formats](supported-formats.md) -- Formats akm can index, from its own bundle layout to other tools' existing asset directories
 - [Tasks](tasks.md) -- Task source v4 grammar, executable targets, scheduling, migration, and scheduler operations

package/docs/reference/cli.md

@@ -490,6 +490,55 @@ Notes you may see:
 - Selects are read from the events stream, which records no source, so they are
   counted whatever the usage source is.
 
+### ui
+
+**Experimental** (see [STABILITY.md](../../STABILITY.md)): the command, the page and the API it reads may change in any
+release.
+
+Serve a local web UI over your whole akm environment and open it in your browser. It is read-only except that you can accept and reject proposals in it: health and metrics, bundles
+(with git status and asset counts), the effective config with where each value comes from, the proposal queue with
+diffs, recent changes to the write-target stash, and search with an asset view. Every page reads through the functions
+the matching CLI commands use, so the UI and the CLI report the same numbers.
+
+| Page | Shows |
+| --- | --- |
+| Overview | Overall health, failing and warning check counts and the akm version; the health checks grouped by status with expandable evidence; metrics tiles; the last 10 improve runs (result, duration, model calls and failures, sync, triage) with bars; and a 14-day stacked usage chart (search, curate, show, feedback). |
+| Bundles | One card per bundle: kind, path or source, writable, git branch, ahead/behind, last commit time and asset counts by type; plus the index state. |
+| Config | The effective config as a collapsible tree with a `default` / `file` / `extends:<ref>` source badge on every key, the engines table and the `AKM_*` environment. |
+| Proposals | The pending queue grouped by source (filter by source) with age and gate decision, a Recent tab of accepted, rejected and reverted proposals with reasons, and a detail page with the unified diff and, for retirements, the pair judgment. The detail page has Accept (after an inline confirmation) and Reject (with a required reason); the pending list has checkboxes and an Accept selected bar that accepts several in one commit. |
+| Changes | Recent stash commits as a timeline by day, each tagged by origin (`improve-sync`, `accept`, `remember`, `sync`, `other`) with its changed paths. |
+| Search | A query box with type and bundle filters. A result opens the asset view: frontmatter, the body as safe markdown, links, and feedback counts and history. |
+
+The pages are plain HTML, CSS and JavaScript modules in `src/assets/ui/`: no framework, no build step, and no request
+beyond the local server. All text from the API is escaped before it reaches the page.
+
+```sh
+akm ui
+akm ui --port 8123 --no-open
+```
+
+| Flag | Description |
+| --- | --- |
+| `--port <n>` | Port to listen on. Default: a random free port. |
+| `--host <addr>` | Address to bind. Default `127.0.0.1`. Anything else is reachable from other machines and prints a warning. |
+| `--no-open` | Print the URL without opening a browser. A failed open also falls back to printing it. |
+
+The command prints `akm ui: http://127.0.0.1:<port>/?token=<token>` and keeps serving until Ctrl-C (SIGINT or SIGTERM).
+Each launch generates a new random token. Every `/api/` request must send it as the `X-Akm-Ui-Token` header or a `token`
+query parameter, otherwise it gets a 401; the page keeps it in `sessionStorage`. The `Host` header must be the address
+the server is bound to, which stops a web page from reaching it through DNS rebinding.
+
+Browsing is read-only: `state.db` and `index.db` are opened read-only and never created or migrated, searching and
+showing in the UI record no usage events (so browsing is never counted as demand) and build no index, and nothing is
+written to a bundle or to config. The only writes are accepting and rejecting proposals (and accepting several at once),
+through three `POST` routes that call the functions `akm proposal accept` and `reject` call, so a decision made in the
+UI is recorded and committed exactly like one made on the command line. Those routes need the token in the
+`X-Akm-Ui-Token` header (not the query string), a JSON content type and an `Origin` equal to the server's own address.
+A read is short and the server holds no lock between requests, so browsing never blocks `akm improve`, `akm index` or
+`akm sync`; a decision takes the same write lease the CLI takes and answers `409` at once if another process holds it. Secrets are redacted: config values under secret-like keys and URL credentials
+are masked, and env and secret assets are shown as a stub, never with their values. The endpoints are documented in
+[ui-api.md](ui-api.md). `--format` has no effect on this command.
+
 ### search
 
 Search bundle assets, registries, or both.
@@ -3058,6 +3107,7 @@ UUID, an 8-character UUID prefix, or an asset ref.
 
 ```sh
 akm proposal accept <id>
+akm proposal accept <id> <id> <id>             # several at once: one commit
 akm proposal accept 7c115132                  # 8-char UUID prefix
 akm proposal accept skills/akm-dream           # Asset ref
 akm proposal accept <id> --queue team-bundle
@@ -3081,10 +3131,19 @@ Bulk-accept all pending proposals from one generator with `--generator <name>`
 (e.g. `reflect`, `distill`) and no positional id. Bulk accept requires
 `-y`/`--yes` in non-interactive shells.
 
+Several ids accept in one process and return one `proposal-accept-batch`
+envelope (`accepted`, `failed`, and a `results` list in argument order). An id
+that fails appears as `{ ok: false, id, error }`, the command exits 1, and the
+others are still accepted and committed.
+
 When the destination bundle is a git repository (a `.git` directory, whatever
-its source kind), each accept is committed as it happens, with exactly the paths
-it wrote or removed and the subject `akm accept: <generator> <proposal-id-8>
-<ref>`. A retirement's archived copy and tombstone, and the source memory a
+its source kind), one accept is committed with exactly the paths it wrote or
+removed and the subject `akm accept: <generator> <proposal-id-8> <ref>`. A
+process that accepts several proposals (several ids, `--generator`, or
+`akm proposal drain`) commits them once at its end: the subject is
+`akm proposal accept: N accepted (<generator> n, ...)` (`akm proposal drain: ...`
+for a drain) and the body has one `<proposal-id-8> <generator> <ref>` line per
+proposal. A retirement's archived copy and tombstone, and the source memory a
 consolidate promotion retires, are part of the same commit. The commit is local:
 `akm sync`, or the end-of-run sync of `akm improve`, pushes it. A commit that
 fails warns and the accept stands.