akm-cli 0.9.17-alpha.7 → 0.9.17-alpha.9

package/docs/reference/cli.md

@@ -104,7 +104,7 @@ with an `INVALID_SHAPE_VALUE` usage error (exit 2) — an honest rejection rathe
 than a silent fallback. It returns a compact view suitable for capability
 discovery:
 
-- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `related`
+- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `links`
 
 ## Exit Codes and Error Envelope
 
@@ -195,8 +195,8 @@ akm setup
 The setup wizard configures AKM in two steps:
 
 **Step 1 — Small model connection** (for background processing)
-Configures the OpenAI-compatible endpoint and model used for `akm index`
-metadata enhancement and `akm remember --enrich`. Supports Ollama,
+Configures the OpenAI-compatible endpoint and model used for `akm improve`
+and `akm remember --enrich`. Supports Ollama,
 OpenAI, LM Studio, or any custom endpoint. Skipping disables enrichment features.
 
 **Step 2 — Agent connection** (for agentic commands)
@@ -300,10 +300,8 @@ invokes `akm index` directly should pass `--skip-if-locked` so it steps
 aside instead of piling up behind a longer rebuild (the shipped
 `index-refresh` task does this).
 
-`akm index` always rebuilds the search index and keeps metadata in the index.
-When a selected named LLM engine (`defaults.llmEngine` or an indexing-pass
-override) is configured and the per-pass gate allows it, metadata
-enhancement runs during indexing. In text mode, the default CLI UI shows a
+`akm index` always rebuilds the search index and keeps metadata in the
+index, generated deterministically. In text mode, the default CLI UI shows a
 spinner with processed-versus-total source counts; structured output modes
 (`json`, `yaml`, `jsonl`) stay clean and machine-readable.
 
@@ -331,7 +329,7 @@ Returns a JSON object with:
 | `semanticSearch` | Semantic search status: `mode`, `status`, and optional `reason`/`message` |
 | `registries` | Configured registries |
 | `sourceProviders` | Configured sources (filesystem, git, website, npm) |
-| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `lastBuiltAt`, `hasEmbeddings` |
+| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `links` (declared links per kind with `total` and `unresolved`; absent when the index holds none), `lastBuiltAt`, `hasEmbeddings` |
 
 `semanticSearch.status` values:
 - `"ready-js"` — every entry has a vector; semantic search is active (the name is historical: `"ready-vec"`, the sqlite-vec variant, is gone)
@@ -389,7 +387,7 @@ Primary result fields:
 | `improve` | Recent improve-loop counts derived from `improve_invoked`, `improve_skipped`, and `improve_completed` events |
 
 The `improve` section includes counts for planned refs, reflect/distill actions,
-memory-prune actions, memory-inference writes, graph-extraction refreshes,
+memory-prune actions, memory-inference writes,
 session-extraction outcomes (`sessionsScanned`, `sessionsExtracted`, `proposalsCreated`),
 dead-URL detections, and skip reasons observed in the selected time window.
 
@@ -432,12 +430,6 @@ for an infrastructure reason (`llm_unavailable`, `read_failed`, `exception`,
 `locked_concurrent`) — naming the reason and, when recorded, the engine — and
 `pass` otherwise, with per-outcome counts.
 
-The indexed entity graph (entities/relations extracted from bundle assets) has
-no dedicated inspection command; its summary counts surface as an info-level
-metric in `akm health`. Graph data is automatically re-extracted on the first
-`akm improve` cycle after a `DB_VERSION` upgrade. The graph backs `akm show`'s
-`related` list and curate's support refs; it does not affect search ranking.
-
 ### search
 
 Search bundle assets, registries, or both.
@@ -595,10 +587,13 @@ akm curate "learn the release workflow" --from all --format text
 | `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 
 `akm curate` takes the top `--limit` hits of one search, in search order, and
-enriches each with a preview, run details and up to two graph-related support
-refs. With `search.curateRerank.enabled`, a cross-encoder first reorders the
-top 30 fused candidates (`search.curateRerank.topN`) by name, description and
-the start of each asset's indexed content. Curate includes direct follow-up
+enriches each with a preview, run details and up to two support refs: the
+assets the hit's declared links name (`xrefs:`, `supersededBy:` and the other
+kinds `akm show` lists under `links`), what it links to before what links to
+it, skipping assets curate already selected. With
+`search.curateRerank.enabled`, a cross-encoder first reorders the top 30 fused
+candidates (`search.curateRerank.topN`) by name, description and the start of
+each asset's indexed content. Curate includes direct follow-up
 commands such as `akm show <ref>` or `akm bundle add <ref>` so you can
 immediately inspect or install what it found.
 `--detail` and `--shape agent` both work on curate output; `--shape summary`
@@ -691,6 +686,16 @@ returns a compact view with `type`, `name`, `ref`, `description`, `tags`,
 `parameters`, `workflowTitle`, `action`, `run`, `origin`, and `keys`, plus the
 optional fragment metadata described below.
 
+`links` lists the asset's declared links, grouped by kind: `outgoing` (the
+assets its own `xrefs:`, `supersededBy:`, `contradictedBy:`,
+`currentBeliefRefs:`, wiki `sources:`, `.derived` parent, page links, or
+workflow and task targets name), `incoming` (the assets that name it), and
+`unresolved` (tokens it names that match no indexed asset, as written). Each
+kind is `{ "total": n, "refs": [...] }` with at most 10 refs; `total` counts
+them all. The field is omitted when nothing links either way. Links are read
+from frontmatter and parsed structure at index time, with no model; they do
+not affect search ranking.
+
 Opaque fragment shows and `--context lead` keep `ref` as the canonical parent
 identity and add
 `selectedRef`, `parentRef`, one-based `fragmentOrdinal`, `fragmentCount`,
@@ -2513,7 +2518,7 @@ clock, or session-log changes.
 
 `plan.processes` (#947) is the resolved process -> engine -> model routing
 table: one row per improve process (`reflect`, `distill`, `consolidate`,
-`memoryInference`, `graphExtraction`, `extract`, `validation`, `triage`,
+`memoryInference`, `extract`, `validation`, `triage`,
 `proactiveMaintenance`), plus a `triage.judgment` row when the strategy
 configures a judgment engine. Each row carries `enabled`, the resolved
 `engine`/`model` (llm-backed processes only) and `engineKind`, this process's
@@ -2568,7 +2573,7 @@ field on the result (`result_json` in `improve_runs`, and in the
 `calls`, `failures`, `promptTokens`, `completionTokens`, `totalTokens`,
 `reasoningTokens`, and `totalDurationMs`. `noCalls` lists every LLM-backed
 process (`reflect`, `distill`, `consolidate`, `memoryInference`,
-`graphExtraction`, `extract`, `validation` — not `triage`/`proactiveMaintenance`,
+`extract`, `validation` — not `triage`/`proactiveMaintenance`,
 which never make an attributable LLM call themselves) the active strategy
 enabled but that ended the run with zero calls, each with a `reason` drawn
 from the existing skip-reason vocabulary: `"engine_unavailable"` (also in
@@ -2706,6 +2711,7 @@ akm proposal list
 akm proposal list --queue team-bundle
 akm proposal list --status pending|accepted|rejected|reverted
 akm proposal list --ref skills/deploy
+akm proposal list --generator consolidate-pair
 ```
 
 | Flag | Description |
@@ -2714,6 +2720,12 @@ akm proposal list --ref skills/deploy
 | `--status` | Filter by `pending`, `accepted`, `rejected`, or `reverted` |
 | `--ref` | Filter by asset ref. A qualified ref preserves bundle identity; a short ref matches that concept in the selected queue |
 | `--type` | Reserved type filter |
+| `--generator <name>` | Filter by generator/source (e.g. `reflect`, `distill`, `consolidate-pair`) — the same value `accept`/`reject --generator` take |
+
+Each retire proposal's `retirement.continuityRisk`, when present, also shows
+in the default listing (`⚠ continuity-risk` inline) and in `proposal show`'s
+text output (the specific failing/unverified queries) — see
+[Retirement continuity](https://github.com/itlackey/akm/blob/main/docs/architecture/improvement.md#retirement-continuity).
 
 Each proposal record carries an optional `confidence` field (0..1) emitted by
 reflect/propose runs. It is recorded for triage and ranking only — there is no

package/docs/reference/configuration.md

@@ -314,7 +314,7 @@ can select `engine`, `model`, `timeoutMs`, and LLM request overrides:
         "engine": "fast",
         "processes": {
           "reflect": { "llm": { "temperature": 0.2 } },
-          "graphExtraction": { "model": "qwen3-small" }
+          "memoryInference": { "model": "qwen3-small" }
         }
       }
     }
@@ -327,13 +327,6 @@ incompatible engine never falls back to another engine. Built-in strategies
 are complete presets. User-defined strategies inherit omitted fields from the
 built-in `default` strategy before applying their own overrides.
 
-Graph extraction also reads `index.graph`. Its `engine`, `model`, `timeoutMs`
-and `llm` apply over the strategy-wide values, and `processes.graphExtraction`
-overrides them. `processes.graphExtraction.batchSize` and `includeTypes` win
-over `index.graph.graphExtractionBatchSize` and `graphExtractionIncludeTypes`;
-with neither set, the batch size is 4 and the types are `memory` and
-`knowledge`.
-
 `processes.triage.judgment` explicitly controls the optional judgment tier.
 Use `true` to enable it, `false` to disable it, or an object with `enabled`,
 `engine`, `model`, `timeoutMs`, and/or `llm` overrides. Existing object values
@@ -848,7 +841,23 @@ profile identities.
 config that still sets it is simply ignored — it still loads, unvalidated
 and without warning.
 
-`index.graph.lazyGraphExtraction` is retired in 0.9.17: `akm show` and
-`akm curate` no longer extract or queue graph work, and graph extraction runs
-only in `akm improve`. A config that still sets it loads; the key is named
-once as unknown, and `akm migrate apply` removes it.
+`index.graph.*` and every strategy's `processes.graphExtraction.*` are retired
+in 0.9.17-alpha.9: the LLM entity graph they configured is gone —
+`akm show`'s links come from declared links instead (see `## Strategies`
+above). A config that still sets them loads; each key is named once as
+unknown, and `akm migrate apply` removes it. The built-in `graph-refresh`
+strategy is retired too, but not the same way as an ordinary unknown name:
+naming it via `--strategy` or a task always fails with a message pointing at
+the retirement, even when `improve.strategies["graph-refresh"]` still has a
+leftover override from customizing the built-in (the message names it;
+`akm migrate apply` drops it — a leftover override is never resolved as a new
+custom strategy, which would silently run a full, unplanned improve pass).
+`defaults.improveStrategy: "graph-refresh"` still loads config successfully;
+the refusal happens lazily, when the strategy is actually resolved.
+
+`improve.strategies.<name>.processes.consolidate.incrementalSince` and
+`.neighborsPerChanged` are retired in 0.9.17-alpha.9: the consolidate pair
+pass is now the candidate generator, narrowing per initiator through the
+improve ledger rather than a global time window. A config that still sets
+either key loads; each is named once as unknown, and `akm migrate apply`
+removes it.

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

@@ -199,7 +199,6 @@ the set of types the code actually emits at HEAD (verified against every
 | `extract_triaged` | The pre-LLM extract triage gate evaluated at least one session | `evaluated`, `passed`, `triagedOut`, `sourceRun` (aggregated) |
 | `schema_repair_invoked` | The schema-repair pass inside `akm improve` (`runSchemaRepairPass`) attempts to patch missing frontmatter on an asset that failed schema validation. **There is no `akm lint --repair` flag** — `lint` has `--fix`/`--auto-fix`, unrelated to this event | `ref`, outcome |
 | `proactive_selected` | The proactive-maintenance selector runs (once per `akm improve` run) | `count`, `dueTotal`, `neverReflected` (aggregated) |
-| `improve_salience_rank_change` | Bundle-wide rank-change report, from the second improve run onward | `stashSize`, `totalChanged`, `forgettingCandidates`, `topDrops` |
 | `events_purged` | Old events deleted by improve maintenance (90-day default retention) | `purgedCount`, `retentionDays` |
 | `improve_runs_purged` | Old `improve_runs` rows deleted by improve maintenance (same retention window as events) | `purgedCount`, `retentionDays` |
 | `state_db_vacuumed` | state.db was VACUUMed after the retention purge because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.17-alpha.7",
+  "version": "0.9.17-alpha.9",
   "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": [

package/schemas/akm-config.json

@@ -334,15 +334,6 @@
             }
           },
           "additionalProperties": true
-        },
-        "metadataEnhance": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "type": "boolean"
-            }
-          },
-          "additionalProperties": true
         }
       },
       "additionalProperties": {
@@ -401,18 +392,6 @@
               }
             },
             "additionalProperties": true
-          },
-          "graphExtractionBatchSize": {
-            "type": "integer",
-            "exclusiveMinimum": 0
-          },
-          "graphExtractionIncludeTypes": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "minLength": 1
-            },
-            "minItems": 1
           }
         },
         "additionalProperties": true
@@ -975,13 +954,6 @@
                         "minimum": 1,
                         "maximum": 50
                       },
-                      "incrementalSince": {
-                        "type": "string"
-                      },
-                      "neighborsPerChanged": {
-                        "type": "integer",
-                        "minimum": 1
-                      },
                       "p90ChunkSecondsDefault": {
                         "type": "number",
                         "exclusiveMinimum": 0
@@ -1080,89 +1052,6 @@
                     },
                     "additionalProperties": true
                   },
-                  "graphExtraction": {
-                    "type": "object",
-                    "properties": {
-                      "engine": {
-                        "type": "string",
-                        "maxLength": 63,
-                        "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
-                      },
-                      "model": {
-                        "type": "string",
-                        "minLength": 1
-                      },
-                      "llm": {
-                        "type": "object",
-                        "properties": {
-                          "temperature": {
-                            "type": "number"
-                          },
-                          "maxTokens": {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
-                          },
-                          "supportsJsonSchema": {
-                            "type": "boolean"
-                          },
-                          "extraParams": {
-                            "type": "object",
-                            "additionalProperties": {}
-                          },
-                          "contextLength": {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
-                          },
-                          "enableThinking": {
-                            "type": "boolean"
-                          },
-                          "reasoningEffort": {
-                            "type": "string",
-                            "minLength": 1
-                          }
-                        },
-                        "additionalProperties": true
-                      },
-                      "enabled": {
-                        "type": "boolean"
-                      },
-                      "timeoutMs": {
-                        "anyOf": [
-                          {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
-                          },
-                          {
-                            "type": "null"
-                          }
-                        ]
-                      },
-                      "topN": {
-                        "type": "integer",
-                        "exclusiveMinimum": 0
-                      },
-                      "includeTypes": {
-                        "type": "array",
-                        "items": {
-                          "type": "string",
-                          "minLength": 1
-                        },
-                        "minItems": 1
-                      },
-                      "batchSize": {
-                        "type": "integer",
-                        "exclusiveMinimum": 0
-                      },
-                      "fullScan": {
-                        "type": "boolean"
-                      },
-                      "maxChunksPerAsset": {
-                        "type": "integer",
-                        "exclusiveMinimum": 0
-                      }
-                    },
-                    "additionalProperties": true
-                  },
                   "extract": {
                     "type": "object",
                     "properties": {
@@ -1995,15 +1884,6 @@
                 }
               },
               "additionalProperties": true
-            },
-            "metadataEnhance": {
-              "type": "object",
-              "properties": {
-                "enabled": {
-                  "type": "boolean"
-                }
-              },
-              "additionalProperties": true
             }
           },
           "additionalProperties": {
@@ -2062,18 +1942,6 @@
                   }
                 },
                 "additionalProperties": true
-              },
-              "graphExtractionBatchSize": {
-                "type": "integer",
-                "exclusiveMinimum": 0
-              },
-              "graphExtractionIncludeTypes": {
-                "type": "array",
-                "items": {
-                  "type": "string",
-                  "minLength": 1
-                },
-                "minItems": 1
               }
             },
             "additionalProperties": true
@@ -2636,13 +2504,6 @@
                             "minimum": 1,
                             "maximum": 50
                           },
-                          "incrementalSince": {
-                            "type": "string"
-                          },
-                          "neighborsPerChanged": {
-                            "type": "integer",
-                            "minimum": 1
-                          },
                           "p90ChunkSecondsDefault": {
                             "type": "number",
                             "exclusiveMinimum": 0
@@ -2741,89 +2602,6 @@
                         },
                         "additionalProperties": true
                       },
-                      "graphExtraction": {
-                        "type": "object",
-                        "properties": {
-                          "engine": {
-                            "type": "string",
-                            "maxLength": 63,
-                            "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
-                          },
-                          "model": {
-                            "type": "string",
-                            "minLength": 1
-                          },
-                          "llm": {
-                            "type": "object",
-                            "properties": {
-                              "temperature": {
-                                "type": "number"
-                              },
-                              "maxTokens": {
-                                "type": "integer",
-                                "exclusiveMinimum": 0
-                              },
-                              "supportsJsonSchema": {
-                                "type": "boolean"
-                              },
-                              "extraParams": {
-                                "type": "object",
-                                "additionalProperties": {}
-                              },
-                              "contextLength": {
-                                "type": "integer",
-                                "exclusiveMinimum": 0
-                              },
-                              "enableThinking": {
-                                "type": "boolean"
-                              },
-                              "reasoningEffort": {
-                                "type": "string",
-                                "minLength": 1
-                              }
-                            },
-                            "additionalProperties": true
-                          },
-                          "enabled": {
-                            "type": "boolean"
-                          },
-                          "timeoutMs": {
-                            "anyOf": [
-                              {
-                                "type": "integer",
-                                "exclusiveMinimum": 0
-                              },
-                              {
-                                "type": "null"
-                              }
-                            ]
-                          },
-                          "topN": {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
-                          },
-                          "includeTypes": {
-                            "type": "array",
-                            "items": {
-                              "type": "string",
-                              "minLength": 1
-                            },
-                            "minItems": 1
-                          },
-                          "batchSize": {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
-                          },
-                          "fullScan": {
-                            "type": "boolean"
-                          },
-                          "maxChunksPerAsset": {
-                            "type": "integer",
-                            "exclusiveMinimum": 0
-                          }
-                        },
-                        "additionalProperties": true
-                      },
                       "extract": {
                         "type": "object",
                         "properties": {
@@ -3585,13 +3363,6 @@
           "minimum": 1,
           "maximum": 50
         },
-        "incrementalSince": {
-          "type": "string"
-        },
-        "neighborsPerChanged": {
-          "type": "integer",
-          "minimum": 1
-        },
         "p90ChunkSecondsDefault": {
           "type": "number",
           "exclusiveMinimum": 0
@@ -3614,29 +3385,6 @@
           "type": "integer",
           "minimum": 0
         },
-        "topN": {
-          "type": "integer",
-          "exclusiveMinimum": 0
-        },
-        "includeTypes": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "minLength": 1
-          },
-          "minItems": 1
-        },
-        "batchSize": {
-          "type": "integer",
-          "exclusiveMinimum": 0
-        },
-        "fullScan": {
-          "type": "boolean"
-        },
-        "maxChunksPerAsset": {
-          "type": "integer",
-          "exclusiveMinimum": 0
-        },
         "defaultSince": {
           "type": "string",
           "minLength": 1
@@ -4105,13 +3853,6 @@
                   "minimum": 1,
                   "maximum": 50
                 },
-                "incrementalSince": {
-                  "type": "string"
-                },
-                "neighborsPerChanged": {
-                  "type": "integer",
-                  "minimum": 1
-                },
                 "p90ChunkSecondsDefault": {
                   "type": "number",
                   "exclusiveMinimum": 0
@@ -4210,89 +3951,6 @@
               },
               "additionalProperties": true
             },
-            "graphExtraction": {
-              "type": "object",
-              "properties": {
-                "engine": {
-                  "type": "string",
-                  "maxLength": 63,
-                  "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
-                },
-                "model": {
-                  "type": "string",
-                  "minLength": 1
-                },
-                "llm": {
-                  "type": "object",
-                  "properties": {
-                    "temperature": {
-                      "type": "number"
-                    },
-                    "maxTokens": {
-                      "type": "integer",
-                      "exclusiveMinimum": 0
-                    },
-                    "supportsJsonSchema": {
-                      "type": "boolean"
-                    },
-                    "extraParams": {
-                      "type": "object",
-                      "additionalProperties": {}
-                    },
-                    "contextLength": {
-                      "type": "integer",
-                      "exclusiveMinimum": 0
-                    },
-                    "enableThinking": {
-                      "type": "boolean"
-                    },
-                    "reasoningEffort": {
-                      "type": "string",
-                      "minLength": 1
-                    }
-                  },
-                  "additionalProperties": true
-                },
-                "enabled": {
-                  "type": "boolean"
-                },
-                "timeoutMs": {
-                  "anyOf": [
-                    {
-                      "type": "integer",
-                      "exclusiveMinimum": 0
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "topN": {
-                  "type": "integer",
-                  "exclusiveMinimum": 0
-                },
-                "includeTypes": {
-                  "type": "array",
-                  "items": {
-                    "type": "string",
-                    "minLength": 1
-                  },
-                  "minItems": 1
-                },
-                "batchSize": {
-                  "type": "integer",
-                  "exclusiveMinimum": 0
-                },
-                "fullScan": {
-                  "type": "boolean"
-                },
-                "maxChunksPerAsset": {
-                  "type": "integer",
-                  "exclusiveMinimum": 0
-                }
-              },
-              "additionalProperties": true
-            },
             "extract": {
               "type": "object",
               "properties": {

package/dist/assets/improve-strategies/graph-refresh.json

@@ -1,15 +0,0 @@
-{
-  "description": "Full-corpus graph extraction pass — rebuilds graph relationships across all stash files. Disables all other sub-processes. Use via `akm improve --strategy graph-refresh` or the embedded `graph-refresh-weekly` task.",
-  "processes": {
-    "reflect": { "enabled": false },
-    "distill": { "enabled": false },
-    "consolidate": { "enabled": false },
-    "memoryInference": { "enabled": false },
-    "graphExtraction": { "enabled": true, "fullScan": true },
-    "extract": { "enabled": false },
-    "triage": { "enabled": false },
-    "validation": { "enabled": false },
-    "proactiveMaintenance": { "enabled": false }
-  },
-  "sync": { "enabled": true, "push": true }
-}