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

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

@@ -1,6 +1,6 @@
 # akm CLI
 
-You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, wikis, and memories via `akm`. Search your sources first before writing something from scratch.
+You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, env files, secrets, lessons, and memories via `akm`. Search your sources first before writing something from scratch.
 
 ## Agent Task Loop
 
@@ -8,15 +8,15 @@ 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 success
+4. `akm feedback <ref> --positive` — record success; use `--negative --reason "..."` when it fails
 
 For workflow tasks:
-1. `akm workflow next workflow:<name>` — get current step instructions
+1. `akm workflow next workflows/<name>` — get current step instructions
 2. Do the step work in your workspace
-3. `akm workflow complete <run-id> --step <step-id>` — mark done, get next step
+3. `akm workflow complete <run-id> --step <step-id> --summary "what was done"` — mark done, get next step
 
 Workflow runs are scoped to your current project/worktree/directory. Ref-based
-commands like `workflow next workflow:<name>`, `workflow status workflow:<name>`,
+commands like `workflow next workflows/<name>`, `workflow status workflows/<name>`,
 and `workflow list` operate within the current scope only.
 
 ## Quick Reference
@@ -25,26 +25,27 @@ and `workflow list` operate within the current scope only.
 akm search "<query>"                          # Search all sources
 akm curate "<task>"                          # Curate the best matches for a task
 akm search "<query>" --type workflow          # Filter to workflow assets
-akm search "<query>" --source both            # Also search registries
+akm search "memories/projectA/"               # List a subtree (conceptId prefix; trailing slash required)
+akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
+akm help <command>                            # Show a command's options and subcommands
 akm workflow next <ref>                       # Start or resume a workflow
-akm remember "Deployment needs VPN access"    # Record a memory in your stash
-akm remember "note" --target my-stash         # Route write to a named writable stash source
-akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
-akm import ./doc.md --target my-stash         # Route import to a named writable stash source
-akm wiki list                                 # List available wikis
-akm wiki ingest <name>                        # Dispatch an agent to run the ingest workflow (uses defaults.agent or --profile)
-akm wiki stash <name> ./paper.md --target my-stash # Route wiki stash write to a named source
-akm proposal diff skill:akm-dream             # Diff proposal by ref, UUID, or 8-char prefix
+akm remember "Deployment needs VPN access"    # Record a memory in your bundle
+akm remember "note" --bundle my-bundle         # Route write to a named writable bundle source
+akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)
+akm remember "fix" --supersedes memories/old-note # Write a correction AND demote the superseded asset
+akm import ./notes/release-checklist.md       # Import a knowledge doc into your bundle
+akm import ./doc.md --target my-bundle         # Route import to a named writable bundle source
+akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8-char prefix
 akm proposal accept 7c115132                  # Accept by UUID prefix
-akm proposal reject skill:my-skill --reason "..."  # Reject by ref
+akm proposal reject skills/my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive|--negative      # Record whether an asset helped
-akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
-akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
-akm sync                                      # Commit (and push if writable remote) changes in the primary stash (--no-push to commit only)
+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)
 akm improve --no-sync                         # Run improve without the end-of-run auto-commit
 akm improve --no-push                         # Auto-commit but skip push for this run
-akm registry search "<query>"                 # Search all registries
+akm search "<query>" --from registry          # Search all registries (registry search was folded into search)
 ```
 
 ## Primary Asset Types
@@ -55,14 +56,76 @@ akm registry search "<query>"                 # Search all registries
 | skill | Instructions to follow (read the full content) |
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
-| knowledge | A reference doc (use `toc` or `section "..."` to navigate) |
+| knowledge | A reference doc (append `#<heading-slug>` to the ref to read one section) |
 | workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
-| env | A `.env` file of related CONFIGURATION (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |
-| secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Use `akm secret path` / `akm secret run`. |
-| wiki | A page in a multi-wiki knowledge base. For any wiki task, start with `akm wiki list`. To ingest sources, run `akm wiki ingest <name>` — it dispatches the configured agent profile to execute the ingest workflow against the wiki's `raw/` directory. Run `akm wiki -h` for the full surface. |
+| env | A `.env` file of configuration an app loads together (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |
+| secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Inject with `akm secret run <ref> <VAR> -- <cmd>`. |
+| lesson | A distilled feedback lesson: `content` plus `action` (rendered from the `when_to_use` frontmatter). Read both before applying a related skill. Generated by the improve pipeline and promoted through the proposal queue. |
 
 When an asset meaningfully helps or fails, record that with `akm feedback` so
 future search ranking can learn from real usage.
 
-Run `akm -h` for the full command reference.
+## Error Shapes and Exit Codes
+
+Every command returns JSON by default. On failure, the shape is always
+emitted on **stderr** (stdout is normally left empty):
+
+```json
+{"ok": false, "error": "<message>", "code": "<optional machine-readable code>", "hint": "<optional remediation hint>"}
+```
+
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Not found or command-reported failure |
+| 2 | Usage / bad input |
+| 4 | Health warning (`akm health` only) |
+| 70 | Internal / unclassified error |
+| 78 | Configuration error |
+
+Check `ok === false` or a non-zero exit code to detect failure. The `hint`
+field, when present, describes a corrective action. `search`/`curate`
+success results also carry an additive `tip` field (a plain-text suggestion)
+when the result set is empty.
+
+`env run`, `secret run`, and `migrate` preserve the spawned process's exact
+status. `task run` preserves configuration failures as exit 78; other failed
+task results and failed `agent` dispatches map to exit 1 while retaining the
+child status in their result envelope.
+
+`akm lint` is the exception: it exits **0 on every successful run regardless
+of findings**. Read `summary.flagged` to detect issues, or pass
+`--fail-on-flagged` to opt into "exit 1 when findings exist":
+
+```sh
+akm lint | jq '.summary.flagged'              # always exit 0; read the count
+akm lint --fail-on-flagged && deploy          # exit 1 if any flagged issues
+```
+
+## Proposals & improvement (0.8.0+)
+
+`akm` ships a proposal queue so reflective edits, new asset drafts, and
+feedback-distilled lessons land out-of-band before they touch the live
+bundle. None of these commands mutate bundle content directly — they always
+go through `akm proposal accept`.
+
+```sh
+akm improve <ref>                              # Produce an improvement proposal for an existing asset
+akm improve <ref> --task "tighten the description"
+akm proposal new <type> <name> --task "..."    # Draft a new asset proposal from a description
+akm proposal new lesson docker-cleanup --task "consolidate cleanup feedback"
+akm proposal list                              # List pending proposals
+akm proposal list --status pending|accepted|rejected|reverted
+akm proposal show <id>                          # Render the proposal body
+akm proposal diff <ref-or-id>                   # Diff by ref, UUID, or 8-char prefix
+akm proposal accept 7c115132                    # Accept by UUID prefix
+akm proposal reject skills/my-skill --reason "not ready" # Reject by asset ref
+akm search "<query>" --include-proposed        # Surface proposal-queue entries in search
+```
+
+Run `akm help <command>` for that command's options and subcommands. Run
+`akm --help` for the command overview or `akm hints --detail full` for the
+complete agent guide.

package/dist/assets/{profiles → improve-strategies}/catchup.json

@@ -7,7 +7,9 @@
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
-    "triage": { "enabled": true, "applyMode": "queue", "policy": "personal-stash", "maxAcceptsPerRun": 100 }
+    "triage": { "enabled": true, "applyMode": "queue", "policy": "personal-stash", "maxAcceptsPerRun": 100 },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/{profiles → improve-strategies}/consolidate.json

@@ -7,7 +7,9 @@
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
-    "triage": { "enabled": false }
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/{profiles → improve-strategies}/default.json

@@ -1,20 +1,19 @@
 {
-  "description": "Standard improve pass — all sub-processes + sustaining proactive lane.",
+  "description": "Standard improve pass — reflect, distill, advisory consolidation, graph extraction, and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract and proactive maintenance off.",
   "processes": {
     "reflect": {
       "enabled": true,
       "limit": 25,
-      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
     },
     "distill": { "enabled": true, "allowedTypes": ["memory"], "requirePlannedRefs": true },
     "consolidate": { "enabled": true, "allowedTypes": ["memory"], "minPoolSize": 500 },
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": true },
-    "extract": { "enabled": true, "triage": { "enabled": true, "minScore": 2 } },
-    "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 15 },
-    "triage": { "enabled": false, "applyMode": "queue", "policy": "personal-stash" },
-    "recombine": { "enabled": false },
-    "procedural": { "enabled": false }
+    "extract": { "enabled": false, "triage": { "enabled": true, "minScore": 2 } },
+    "validation": { "enabled": true },
+    "proactiveMaintenance": { "enabled": false, "dueDays": 30, "maxPerRun": 15 },
+    "triage": { "enabled": false, "applyMode": "queue", "policy": "personal-stash" }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/frequent.json

@@ -0,0 +1,15 @@
+{
+  "description": "Frequent inference pass — memory inference, graph extraction, and reflect; improve-stage extract off.",
+  "processes": {
+    "reflect": { "enabled": true },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": false },
+    "memoryInference": { "enabled": true },
+    "graphExtraction": { "enabled": true },
+    "extract": { "enabled": false, "minNewSessions": 3, "triage": { "enabled": true, "minScore": 2 } },
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/{profiles → improve-strategies}/graph-refresh.json

@@ -1,5 +1,5 @@
 {
-  "description": "Full-corpus graph extraction pass — rebuilds graph relationships across all stash files. Disables all other sub-processes. Use via `akm improve --profile graph-refresh` or the embedded `graph-refresh-weekly` task.",
+  "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 },
@@ -7,7 +7,9 @@
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": true, "fullScan": true },
     "extract": { "enabled": false },
-    "triage": { "enabled": false }
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/{profiles → improve-strategies}/memory-focus.json

@@ -6,7 +6,10 @@
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": false },
-    "triage": { "enabled": false }
+    "extract": { "enabled": false },
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/{profiles → improve-strategies}/proactive-maintenance.json

@@ -1,23 +1,23 @@
 {
-  "description": "Proactive-maintenance pass — reflect, distill, proposal triage (promote, high budget), and the proactive-maintenance lane (maxPerRun 100); consolidate/memoryInference/graphExtraction/extract off. Sync disabled: an interrupted run would otherwise leave an uncommitted backlog.",
+  "description": "Opt-in proactive-maintenance pass — reflect, distill, proposal triage (promote, high budget), and the proactive-maintenance lane (maxPerRun 100); consolidate/memoryInference/graphExtraction/extract off. Sync disabled: an interrupted run would otherwise leave an uncommitted backlog.",
   "processes": {
     "reflect": {
       "enabled": true,
-      "mode": "llm",
-      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
     },
-    "distill": { "enabled": true, "mode": "llm", "allowedTypes": ["memory"] },
+    "distill": { "enabled": true, "allowedTypes": ["memory"] },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
     "extract": { "enabled": false },
+    "validation": { "enabled": false },
     "triage": {
       "enabled": true,
       "applyMode": "promote",
       "policy": "personal-stash",
       "maxAcceptsPerRun": 100,
       "maxDiffLines": 200,
-      "judgment": { "mode": "llm" }
+      "judgment": {}
     },
     "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 100 }
   },

package/dist/assets/{profiles → improve-strategies}/quick.json

@@ -3,14 +3,16 @@
   "processes": {
     "reflect": {
       "enabled": true,
-      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
     },
     "extract": { "enabled": false },
     "distill": { "enabled": false },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
-    "triage": { "enabled": false }
+    "triage": { "enabled": false },
+    "validation": { "enabled": false },
+    "proactiveMaintenance": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/improve-strategies/reflect-distill.json

@@ -0,0 +1,30 @@
+{
+  "description": "Reflect + distill pass — reflect, distill, memoryInference, and proposal triage (promote); proactiveMaintenance/consolidate/graphExtraction/extract off. Sync disabled: an interrupted run would otherwise leave an uncommitted backlog.",
+  "processes": {
+    "reflect": {
+      "enabled": true,
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
+    },
+    "distill": { "enabled": true, "allowedTypes": ["memory"], "requirePlannedRefs": false },
+    "consolidate": { "enabled": false },
+    "memoryInference": { "enabled": true },
+    "graphExtraction": { "enabled": false },
+    "extract": {
+      "enabled": false,
+      "timeoutMs": 300000,
+      "triage": { "enabled": true, "minScore": 2 },
+      "minNewSessions": 1
+    },
+    "validation": { "enabled": false },
+    "triage": {
+      "enabled": true,
+      "applyMode": "promote",
+      "policy": "personal-stash",
+      "maxAcceptsPerRun": 15,
+      "maxDiffLines": 200,
+      "judgment": {}
+    },
+    "proactiveMaintenance": { "enabled": false, "dueDays": 30, "maxPerRun": 15 }
+  },
+  "sync": { "enabled": false }
+}

package/dist/assets/{profiles → improve-strategies}/thorough.json

@@ -3,7 +3,7 @@
   "processes": {
     "reflect": {
       "enabled": true,
-      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
+      "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "workflow"]
     },
     "distill": { "enabled": true, "allowedTypes": ["memory"] },
     "consolidate": { "enabled": true, "allowedTypes": ["memory"] },

package/dist/assets/prompts/consolidate-system.md

@@ -3,17 +3,17 @@ You are the akm consolidate assistant analyzing memory assets.
 Rules:
 1. MERGE: Two or more memories are substantially duplicated or closely related → propose merging. Return the primary ref to keep and secondary refs to delete. Do NOT include mergedContent — the merge will be executed in a separate step.
 2. DELETE: Memory is clearly outdated, contradicted, or redundant → propose deletion. NEVER propose delete for memories annotated `(captureMode: hot)` — they are user-explicit and only the user can retire them. The downstream guard will refuse these regardless, so proposing them just wastes tokens.
-3. PROMOTE: Memory expresses a stable, reusable fact suitable as a `knowledge:` asset → propose promotion. Do NOT delete the source memory. NEVER propose promote / merge / contradict for memories annotated `(already queued)` — they have a pending proposal whose body matches; a duplicate will be deterministically dropped, so proposing them just wastes tokens.
+3. PROMOTE: Memory expresses a stable, reusable fact suitable as a `knowledge/` asset → propose promotion. Do NOT delete the source memory. NEVER propose promote / merge / contradict for memories annotated `(already queued)` — they have a pending proposal whose body matches; a duplicate will be deterministically dropped, so proposing them just wastes tokens.
 4. CONTRADICT: Two memories assert logically exclusive facts such that following BOTH simultaneously is impossible — not merely related or overlapping. You MUST cite the exact sentence from Memory A and the exact sentence from Memory B that are in direct conflict. If you cannot cite specific opposing sentences, use KEEP instead. Sharing a topic, tool, domain, or workflow stage is NOT sufficient. Only direct factual opposites qualify: opposing recommended commands, opposing boolean flags, opposing version numbers, or mutually exclusive instructions. Use confidence ≥ 0.92 only; omit the op entirely if below that threshold.
 5. KEEP: Memory is unique and current → omit from output.
 
 Return ONLY JSON (no prose, no code fences):
 {
   "operations": [
-    { "op": "merge", "primary": "memory:<name>", "secondaries": ["memory:<name>", ...], "mergeStrategy": "synthesize", "confidence": 0.95 },
-    { "op": "delete", "ref": "memory:<name>", "reason": "<brief reason>", "confidence": 0.90 },
-    { "op": "promote", "ref": "memory:<name>", "knowledgeRef": "knowledge:<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset>", "confidence": 0.92 },
-    { "op": "contradict", "ref": "memory:<name>", "contradictedByRef": "memory:<name>", "reason": "<brief reason>", "confidence": 0.88 }
+    { "op": "merge", "primary": "memories/<name>", "secondaries": ["memories/<name>", ...], "mergeStrategy": "synthesize", "confidence": 0.95 },
+    { "op": "delete", "ref": "memories/<name>", "reason": "<brief reason>", "confidence": 0.90 },
+    { "op": "promote", "ref": "memories/<name>", "knowledgeRef": "knowledge/<suggested-slug>", "reason": "<brief reason>", "description": "<one sentence describing the new knowledge asset>", "confidence": 0.92 },
+    { "op": "contradict", "ref": "memories/<name>", "contradictedByRef": "memories/<name>", "reason": "<brief reason>", "confidence": 0.88 }
   ],
   "warnings": ["<optional concerns>"]
 }

package/dist/assets/prompts/extract-session.md

@@ -46,22 +46,18 @@ Respond with EXACTLY one JSON object matching this shape:
   "candidates": [
     {
       "type": "memory" | "lesson" | "knowledge",
-      "name": "<kebab-case-slug>",
+      "name": "<kebab-case name, e.g. jwt-token; optionally under one kebab-case scope, e.g. auth/jwt-token>",
       "description": "<one sentence 20-400 chars>",
       "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
       "body": "<markdown body, 200-3000 chars typical>",
       "confidence": <number 0.0-1.0>,
-      "evidence": "<one-line pointer to the moment in the session>",
-      "orderedActions": ["<action-1>", "<action-2>", ...],
-      "outcomeData": "<one sentence describing the outcome of the action sequence>"
+      "evidence": "<one-line pointer to the moment in the session>"
     }
   ],
   "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
 }
 ```
 
-`orderedActions` and `outcomeData` are **optional**. Include them only when the candidate represents a recurring action sequence (e.g. a recovery procedure, a build-fix recipe, a deployment checklist) where preserving the ordered steps adds future value. When present, `outcomeData` is required and must describe what happened when the sequence completed (success or failure). Omit both fields entirely for standalone facts, observations, or lessons that are not action-sequence-shaped.
-
 ## Rules
 
 1. **Zero candidates is a valid and frequent answer.** Most sessions yield no new durable insight. When that's the case, return `{"candidates": [], "rationale_if_empty": "..."}` explaining what you saw and why it didn't rise to durable-knowledge level. Do not fabricate.

package/dist/assets/prompts/memory-infer-user.md

@@ -1,5 +1,4 @@
-Compress the memory below into one derived memory. Output ONLY JSON:
-{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
-Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
+Compress the memory below into one derived memory. Output ONLY a JSON object with exactly these fields: title, description, tags, searchHints, and content.
+Rules: title must be specific and short; description must be one sentence; tags must contain 3-8 specific tags; searchHints must contain 3-6 useful retrieval phrases; content must be a plain string with 2-3 sentences. Avoid vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), and merge related points. Never return field descriptions or placeholder values.
 
 Memory:

package/dist/assets/prompts/reflect-llm-framed-contract.md

@@ -0,0 +1,11 @@
+Respond with exactly this plain-text frame, with no prose or code fence around it:
+
+{{REF_LINE}}AKM_REFLECT_CONFIDENCE: <number from 0 to 1>
+AKM_REFLECT_FRONTMATTER_PATCH: {"description": null, "when_to_use": null}
+AKM_REFLECT_CONTENT_BEGIN
+<complete improved markdown body>
+AKM_REFLECT_CONTENT_END
+
+The first begin marker and final end marker delimit the body; marker lines between them are literal content. Put the complete markdown body between those outer markers. Quotes, Markdown fences, and backslashes inside the body are literal content; do not JSON-escape them. Emit the body only, without YAML frontmatter, because AKM preserves and merges the source frontmatter itself.
+
+The frontmatter patch must be a one-line JSON object with exactly `description` and `when_to_use`. Keep a field `null` when it should not change. Supply a non-empty string only when adding or correcting that field; AKM merges those values through its existing sanitizer.

package/dist/assets/prompts/reflect-llm-schema-contract.md

@@ -0,0 +1,3 @@
+Respond only through the provider's native JSON schema. {{FIELD_RULE}}
+
+`content` must contain the complete improved markdown body only, without YAML frontmatter. `frontmatterPatch` must contain exactly `description` and `when_to_use`; set either field to `null` when it should not change, or to a non-empty string when adding or correcting it. AKM merges that narrow patch with the source frontmatter and preserves target identity itself. `confidence` is your honest self-rated quality confidence from 0 to 1. Do not add prose or Markdown fences around the JSON response.

package/dist/assets/prompts/reflect-output-repair.md

@@ -0,0 +1,3 @@
+Your previous response could not be extracted using the required output contract. Reformat that response exactly once using the contract below. Preserve its proposed markdown verbatim: do not revise, summarize, or add content. Return only the repaired envelope.
+
+{{OUTPUT_CONTRACT}}

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

@@ -1,7 +1,7 @@
 # AKM Stash
 
 This is an **AKM stash** — a structured knowledge repository that stores reusable
-assets for you and your AI agents. AKM (Agent Knowledge Management) indexes, ranks,
+assets for you and your AI agents. AKM (Agent Knowledge Manager) indexes, ranks,
 and surfaces these assets at the right moment during coding sessions, improving
 consistency and reducing repeated context-setting.
 
@@ -17,10 +17,37 @@ consistency and reducing repeated context-setting.
 | `workflows/` | Workflows | Multi-step orchestration sequences |
 | `tasks/` | Tasks | Scheduled or on-demand automation tasks |
 | `lessons/` | Lessons | Durable lessons extracted from past sessions |
+| `facts/` | Facts | Durable stash-level context; the house conventions in `facts/conventions/` are auto-surfaced to authoring agents |
+| `scripts/` | Scripts | Executable helpers agents and humans can run |
+| `env/`, `secrets/` | Env & Secrets | Configuration groups and single credentials; values are never content-indexed |
 
 Add your own assets to any of these directories. AKM will index them automatically
 on the next `akm index` run (or when the background improve pipeline picks them up).
 
+## How to organize assets
+
+A file's path under its type directory becomes part of its ref
+(`knowledge/auth/oauth-refresh-races.md` → `knowledge/auth/oauth-refresh-races`),
+and its segments are search terms: `akm search "auth" --type knowledge` narrows
+to that subtree. Retrieval is search, not folder-browse, so pick subdirectories
+deliberately. The house rules live in three convention facts under
+`facts/conventions/` and are surfaced to agents automatically when they author
+assets:
+
+- **`facts/conventions/organization`** — the single path axis, chosen by asset
+  type. **Scope-born** types (`memory`, `lesson`, `task`, `env`, `secret`) go
+  under the current **project/client** slug; **reuse-born** types (`knowledge`,
+  `skill`, `fact`, `script`) go under a stable **domain**; global types
+  stay at the type root.
+- **`facts/conventions/backlinks`** — how to cross-link: a provenance xref
+  whenever an asset derives from another, sparse real associative links,
+  corrections as new assets, canonical entity naming.
+- **`facts/conventions/domains`** — the (editable) domain vocabulary for
+  reuse-born assets, plus canonical entity spellings.
+
+Per-type nuances live in `facts/conventions/assets/<type>.md`. All of these are
+soft guidance — edit them to match how your stash is queried.
+
 ## For agents: how to access this stash
 
 All assets in this stash are searchable via the `akm` CLI. Use these commands to
@@ -35,15 +62,16 @@ akm search "<query>"
 akm search "<query>" --type skill
 akm search "<query>" --type knowledge
 
-# Show a specific asset by ref
-akm show skill:<name>
-akm show knowledge:<name>
-akm show memory:<name>
-akm show command:<name>
+# Show a specific asset by ref ([bundle//]conceptId)
+akm show skills/<name>
+akm show knowledge/<name>
+akm show memories/<name>
+akm show commands/<name>
 
-# List available assets by type
-akm list --type skill
-akm list --type knowledge
+# Browse available assets by type (a trailing slash lists the subtree)
+akm search "skills/"
+akm search "knowledge/"
+akm search "<query>" --type skill
 ```
 
 ### Recording feedback and new knowledge
@@ -73,4 +101,4 @@ akm proposal accept <id>
 
 ---
 
-*Created by `akm init`. See `akm --help` for full command reference.*
+*Created by `akm bundle create`. See `akm --help` for full command reference.*

package/dist/assets/stash-skeleton/facts/conventions/assets/agent.md

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for agent assets using scoped role, tool, and maintenance rules.
 when_to_use: Surfaced to authoring agents when they write or revise an agent asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -36,3 +38,9 @@ Use an agent when a recurring task benefits from a specialized role, bounded res
 - Add explicit negative guidance when the agent overreaches.
 - Keep role instructions stable and concise; move large background material into knowledge assets.
 - Use lessons to capture operational improvements, then promote stable ones into the agent when they become part of the role.
+
+## Placement & linking
+
+- Agent definitions are usually **global**: keep them at the type root or under a
+  role/domain slug (`agents/reviewer`). Point the agent at the standards and type
+  conventions it must read first via xrefs.

package/dist/assets/stash-skeleton/facts/conventions/assets/command.md

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for command assets using repeatable LLM operation patterns.
 when_to_use: Surfaced to authoring agents when they write or revise a command asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -36,3 +38,9 @@ Use a command when the user or agent needs to perform the same prompt-shaped tas
 - If command output regularly becomes useful durable knowledge, instruct the agent to file the result into the right asset type.
 - If the command starts handling multiple unrelated tasks, split it into smaller commands.
 - Preserve a clear invocation contract so future agents can call the command safely.
+
+## Placement & linking
+
+- Commands are usually **global**: keep them at the type root or under a
+  tool/domain slug. Scope to a project only when the command is genuinely
+  project-specific.

package/dist/assets/stash-skeleton/facts/conventions/assets/fact.md

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for fact assets using pinned-core and just-in-time context principles.
 when_to_use: Surfaced to authoring agents when they write or revise a fact asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -34,6 +36,17 @@ Use a fact for stable information that future agents should treat as true or nor
 ## Maintenance strategy
 
 - Revise or supersede facts when the durable truth changes.
-- Do not allow contradictory facts to remain equally active.
+- Do not allow contradictory facts to remain equally active: mark the loser
+  `beliefState: superseded` / `supersededBy: [<new ref>]` so ranking demotes it.
 - Promote repeated memories or lessons into facts only when they become stable context.
 - Keep convention and meta facts especially clear, because they steer future asset creation.
+
+## Placement & linking
+
+- Facts are **reuse-born**: give a policy/standard fact a domain-like prefix
+  (`facts/policies/pii-handling`) or the type root for personal/meta facts.
+- Facts are also the **delivery layer** for stash-wide conventions:
+  `category: convention` or `category: meta` facts are surfaced to every non-wiki
+  author, so this is where naming, placement, and linking house-rules live. Keep
+  each one short — they inject into authoring prompts. Reserve `pinned: true` for
+  the small always-injected core.

package/dist/assets/stash-skeleton/facts/conventions/assets/knowledge.md

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for knowledge assets as compiled, on-demand reference documents.
 when_to_use: Surfaced to authoring agents when they write or revise a knowledge asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -36,5 +38,15 @@ Use a knowledge asset for durable reference material, synthesized explanations,
 
 - Update the existing page when new information changes the same topic; append a dated note rather than silently rewriting when provenance matters.
 - Create a new page when the concept deserves its own durable entry.
-- Add links both ways when a new relationship matters.
+- Add a return link when you are already editing the related page in the same pass.
 - Periodically scan for orphaned, stale, or overlapping knowledge docs and consolidate them.
+
+## Placement & linking
+
+- Knowledge is **reuse-born**: file it under a stable **domain** prefix from
+  `facts/conventions/domains` (`knowledge/auth/oauth-refresh-races`), not under a
+  project — that domain slug is what any project searches to reuse it.
+- Knowledge pages are the rewritable synthesized layer — update them in place.
+  Ingested source material stays immutable; corrections to it are new assets
+  that xref the source. Carry a provenance xref when derived, and a
+  self-situating header.