akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

package/README.md

@@ -7,8 +7,8 @@
 [![license](https://img.shields.io/github/license/itlackey/akm)](https://github.com/itlackey/akm/blob/main/LICENSE)
 
 `akm` is a package manager for AI agent capabilities -- scripts, skills, commands,
-agents, knowledge, memories, workflows, wikis, vaults, lessons, and scheduled
-tasks. It works with any AI coding assistant that can run shell commands,
+agents, knowledge, memories, workflows, wikis, env files, secrets, lessons, and
+scheduled tasks. It works with any AI coding assistant that can run shell commands,
 including [Claude Code](https://claude.ai/code),
 [OpenCode](https://opencode.ai), [Cursor](https://cursor.com), and more.
 
@@ -30,9 +30,17 @@ irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
 bun install -g akm-cli
 ```
 
+**Option 3 — Node.js (requires Node.js >= 20.12):**
+
+```sh
+npm install -g akm-cli
+```
+
 Upgrade in place with `akm upgrade`.
 
-> **AKM 0.8 requires the prebuilt binary or the Bun runtime. Node.js / npm / pnpm are not supported in 0.8.0** — running `npm install -g akm-cli` on a Node.js-only machine will print an error from the preinstall hook and exit without installing. Cross-runtime support (Node, npm, pnpm) is planned for 0.9.0.
+> **AKM 0.9.0 supports three install paths:** prebuilt binary, Bun, or Node.js >= 20.12.
+> The old `vault` asset type was removed in 0.9.0; use `env` for whole `.env`
+> groups and `secret` for standalone sensitive values.
 
 ## Quick Start
 
@@ -59,7 +67,7 @@ Add this to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 ## Resources & Capabilities
 
 You have access to a searchable library of scripts, skills, commands, agents,
-knowledge, memories, workflows, wikis, vaults, lessons, and scheduled tasks
+knowledge, memories, workflows, wikis, env files, secrets, lessons, and scheduled tasks
 via the `akm` CLI. Use `akm -h` for details.
 ```
 

package/dist/akm

@@ -0,0 +1,38 @@
+#!/bin/sh
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+case "$0" in
+	*/*) SCRIPT_PATH=$0 ;;
+	*)
+		SCRIPT_PATH=$(command -v -- "$0" 2>/dev/null || true)
+		if [ -z "$SCRIPT_PATH" ]; then
+			echo "akm launcher could not resolve its own path." >&2
+			exit 127
+		fi
+		;;
+esac
+
+if command -v readlink >/dev/null 2>&1; then
+	while [ -L "$SCRIPT_PATH" ]; do
+		LINK_TARGET=$(readlink "$SCRIPT_PATH")
+		case "$LINK_TARGET" in
+			/*) SCRIPT_PATH=$LINK_TARGET ;;
+			*) SCRIPT_PATH=${SCRIPT_PATH%/*}/$LINK_TARGET ;;
+		esac
+	done
+fi
+
+SCRIPT_DIR=$(CDPATH= cd -- "${SCRIPT_PATH%/*}" && pwd)
+
+if command -v bun >/dev/null 2>&1; then
+	exec bun "$SCRIPT_DIR/cli.js" "$@"
+fi
+
+if command -v node >/dev/null 2>&1; then
+	exec node "$SCRIPT_DIR/cli-node.mjs" "$@"
+fi
+
+echo "akm requires Bun or Node.js >= 20.12.0 on PATH." >&2
+exit 127

package/dist/akm-migrate-storage

@@ -0,0 +1,38 @@
+#!/bin/sh
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+case "$0" in
+	*/*) SCRIPT_PATH=$0 ;;
+	*)
+		SCRIPT_PATH=$(command -v -- "$0" 2>/dev/null || true)
+		if [ -z "$SCRIPT_PATH" ]; then
+			echo "akm-migrate-storage launcher could not resolve its own path." >&2
+			exit 127
+		fi
+		;;
+esac
+
+if command -v readlink >/dev/null 2>&1; then
+	while [ -L "$SCRIPT_PATH" ]; do
+		LINK_TARGET=$(readlink "$SCRIPT_PATH")
+		case "$LINK_TARGET" in
+			/*) SCRIPT_PATH=$LINK_TARGET ;;
+			*) SCRIPT_PATH=${SCRIPT_PATH%/*}/$LINK_TARGET ;;
+		esac
+	done
+fi
+
+SCRIPT_DIR=$(CDPATH= cd -- "${SCRIPT_PATH%/*}" && pwd)
+
+if command -v bun >/dev/null 2>&1; then
+	exec bun "$SCRIPT_DIR/scripts/migrate-storage.js" "$@"
+fi
+
+if command -v node >/dev/null 2>&1; then
+	exec node "$SCRIPT_DIR/migrate-storage-node.mjs" "$@"
+fi
+
+echo "akm-migrate-storage requires Bun or Node.js >= 20.12.0 on PATH." >&2
+exit 127

package/dist/assets/profiles/default.json

@@ -1,15 +1,20 @@
 {
-  "description": "Standard improve pass — all sub-processes, markdown asset types.",
+  "description": "Standard improve pass — all sub-processes + sustaining proactive lane.",
   "processes": {
     "reflect": {
       "enabled": true,
+      "limit": 25,
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
     },
-    "distill": { "enabled": true, "allowedTypes": ["memory"] },
-    "consolidate": { "enabled": true, "allowedTypes": ["memory"] },
+    "distill": { "enabled": true, "allowedTypes": ["memory"], "requirePlannedRefs": true },
+    "consolidate": { "enabled": true, "allowedTypes": ["memory"], "minPoolSize": 500 },
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": true },
-    "triage": { "enabled": false, "applyMode": "queue", "policy": "personal-stash" }
+    "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 }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/profiles/frequent.json

@@ -6,7 +6,7 @@
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": true },
-    "extract": { "enabled": true, "minNewSessions": 3 },
+    "extract": { "enabled": true, "minNewSessions": 3, "triage": { "enabled": true, "minScore": 2 } },
     "triage": { "enabled": false }
   },
   "sync": { "enabled": true, "push": true }

package/dist/assets/profiles/memory-focus.json

@@ -8,5 +8,5 @@
     "graphExtraction": { "enabled": false },
     "triage": { "enabled": false }
   },
-  "sync": { "enabled": false }
+  "sync": { "enabled": true, "push": true }
 }

package/dist/assets/profiles/quick.json

@@ -12,5 +12,5 @@
     "graphExtraction": { "enabled": false },
     "triage": { "enabled": false }
   },
-  "sync": { "enabled": false }
+  "sync": { "enabled": true, "push": true }
 }

package/dist/assets/profiles/synthesize.json

@@ -0,0 +1,15 @@
+{
+  "description": "Synthesis-only — cross-episodic recombination (#609). Opt-in periodic pass; all generative/extract passes off. (Procedural compilation (#615) is held OFF until cross-project scoping lands — it over-fits one-off sequences, 0% accept.)",
+  "processes": {
+    "reflect": { "enabled": false },
+    "distill": { "enabled": false },
+    "consolidate": { "enabled": false },
+    "memoryInference": { "enabled": false },
+    "graphExtraction": { "enabled": false },
+    "extract": { "enabled": false },
+    "triage": { "enabled": false },
+    "recombine": { "enabled": true },
+    "procedural": { "enabled": false }
+  },
+  "sync": { "enabled": true, "push": true }
+}

package/dist/assets/profiles/thorough.json

@@ -1,5 +1,5 @@
 {
-  "description": "All sub-processes enabled (currently identical to default; reserved for future divergence).",
+  "description": "Like default, plus the triage process (drains the pending-proposal backlog).",
   "processes": {
     "reflect": {
       "enabled": true,

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

@@ -0,0 +1,23 @@
+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.
+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 }
+  ],
+  "warnings": ["<optional concerns>"]
+}
+
+For every operation, emit a `confidence` field in [0, 1] expressing your certainty that the operation is correct and safe. Use 0.95+ only when evidence is unambiguous. Omit the field rather than guessing if you are uncertain.
+
+When the merged content includes an `updated` frontmatter field, the value MUST be a real ISO date string (e.g. `updated: 2026-05-20`). NEVER emit `updated: today`, `updated: {today}`, `updated: {today: null}`, `updated: now`, or any other literal placeholder/template-variable. If you do not have a real source-of-truth date, OMIT the `updated` field entirely — the post-processor will not invent one for you.

package/dist/assets/prompts/contradiction-judge.md

@@ -0,0 +1,33 @@
+You are evaluating two derived memory entries to determine if they contain
+directly contradictory factual claims about the same subject.
+
+Memory A:
+Ref: {{A_REF}}
+Description: {{A_DESCRIPTION}}
+Content:
+```
+{{A_BODY}}
+```
+
+Memory B:
+Ref: {{B_REF}}
+Description: {{B_DESCRIPTION}}
+Content:
+```
+{{B_BODY}}
+```
+
+Answer ONLY with valid JSON — no prose, no code fences:
+{"contradicts": true|false, "confidence": 0.0, "reason": "<cite the exact opposing sentence from each memory, or explain why not contradicted>"}
+
+A contradiction means the memories make LOGICALLY EXCLUSIVE claims: a practitioner
+cannot follow BOTH simultaneously. The test: 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, return false.
+
+Sharing a topic, tool, domain, or workflow stage is NOT a contradiction. Only direct
+factual opposites qualify: opposing recommended commands, opposing boolean flags,
+opposing version numbers, or mutually exclusive instructions.
+
+Set confidence ≥ 0.92 only when evidence is unambiguous. Use lower values when
+uncertain — the caller will skip edges below 0.92.

package/dist/assets/prompts/distill-knowledge-system.md

@@ -0,0 +1,22 @@
+You are the akm `distill` distiller.
+Given an asset and recent feedback events about it, produce a concise
+*knowledge* markdown document capturing the durable, reusable facts.
+Prefer stable guidance over narrative recap.
+
+YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.
+DO NOT output any prose, explanation, or code fences before or after.
+
+Required output format:
+---
+description: <one-line summary of the knowledge asset>
+tags: [<tag1>, <tag2>]
+---
+
+# <Title>
+
+<body — structured markdown, durable facts only>
+
+RULES:
+- `description` MUST be a non-empty single-line string.
+- Include a meaningful markdown body with a `# Title` heading.
+- Output ONLY the knowledge file. No preamble, no code fences, no trailing prose.

package/dist/assets/prompts/distill-lesson-system.md

@@ -0,0 +1,36 @@
+You are the akm `distill` distiller.
+Given an asset and recent feedback events about it, produce a single
+concise *lesson* an agent should remember next time it works on this
+asset's domain.
+
+YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.
+DO NOT output any prose, explanation, or code fences before or after.
+
+Required output format — copy this structure exactly:
+---
+description: <one complete sentence (ending with `.`) summarising what the lesson teaches>
+when_to_use: <one complete sentence describing the concrete trigger condition>
+---
+
+<lesson body — plain markdown, 1–3 short paragraphs of practical guidance>
+
+## description field (MANDATORY)
+- A single complete sentence in present tense, 20–400 chars, NO markdown.
+- Self-contained: a reviewer must understand the lesson from this field alone.
+- DO NOT start with "When ", "If ", or a connector word — that belongs in when_to_use.
+- DO NOT copy a section heading ("Key takeaways", "For example", "Key pitfalls").
+- DO NOT begin with a numbered list marker, code fence, or markdown heading.
+
+GOOD: "Always validate ref existence before promoting a memory to knowledge; missing refs surface as silent 404s during accept."
+BAD:  "Key pitfalls"
+BAD:  "When working with the akm CLI"
+BAD:  "For example, you might..."
+BAD:  "1. Check the file"
+
+RULES:
+- `when_to_use` MUST be a complete sentence describing a concrete trigger. Never write `When working with <asset-name>` — that is circular and useless.
+- `description` and `when_to_use` MUST differ from each other.
+- The lesson body MUST be non-empty markdown prose. Do NOT restate `description:` or `when_to_use:` inside the body (no `**description:** ...` or `**when_to_use:** ...` lines — the frontmatter is the only place those keys belong).
+- Do NOT emit a second `---` fence after the opening frontmatter — there are exactly two `---` lines in the output, both belonging to the single frontmatter block at the top.
+- Do NOT reproduce the source asset verbatim — distil what a caller needs to know.
+- Output ONLY the lesson file. No preamble, no code fences, no trailing prose.

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

@@ -28,7 +28,7 @@ Things NOT to extract:
 - Started: {{STARTED_AT}}
 - Ended: {{ENDED_AT}}
 - Project hint: {{PROJECT_HINT}}
-
+{{STANDARDS}}
 ## Filtered session transcript
 
 The transcript below has already had read-only `akm` meta-ops and platform boilerplate stripped. Only content that might carry signal remains.
@@ -49,13 +49,17 @@ Respond with EXACTLY one JSON object matching this shape:
       "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>"
+      "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>"
     }
   ],
   "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/graph-extract-system.md

@@ -0,0 +1 @@
+You extract a knowledge graph from developer notes. Return ONLY valid JSON — no prose, no markdown fences, no preamble.

package/dist/assets/prompts/graph-extract-user-prompt.md

@@ -2,7 +2,7 @@ Extract entities and relations from the asset body below.
 
 Rules:
 - Output ONLY a JSON object: {"entities": ["Entity One", ...], "relations": [{"from": "A", "to": "B", "type": "uses"}, ...]}.
-- Entities are short, canonical noun phrases (project names, services, tools, people, file/dir names, technical concepts).
+- Entities are short, canonical noun phrases (project names, services, tools, people, technical concepts). Do NOT emit file or directory paths (anything containing "/" or "\") — they are dropped downstream.
 - Relations connect two entities that both appear in the entities array.
 - "type" is a short verb phrase (e.g. "uses", "depends on", "owns", "documents"). Optional; omit when unsure.
 - Drop pleasantries, meta-commentary, and timestamps.

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

@@ -0,0 +1 @@
+You compress a developer memory into one high-signal derived memory for later retrieval. Return only valid JSON. No prose outside the JSON object. No markdown fences.

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

@@ -0,0 +1,5 @@
+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.
+
+Memory:

package/dist/assets/prompts/metadata-enhance-system.md

@@ -0,0 +1 @@
+You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.

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

@@ -0,0 +1,44 @@
+You are the akm `procedural` compiler.
+
+You are given a RECURRING ordered action sequence — the SAME ordered list of
+steps that an agent has successfully performed across several independent
+sessions. Your job is to turn that bare sequence into a clean, reusable
+WORKFLOW: give the workflow a title and a one-sentence description, and turn each
+ordered action into a named step with clear imperative instructions.
+
+You MUST NOT invent new steps, drop steps, merge steps, or reorder them. The
+ordered action list is the source of truth. Return EXACTLY one step per input
+action, in the SAME order.
+
+YOUR RESPONSE MUST BE A SINGLE JSON OBJECT AND NOTHING ELSE.
+DO NOT output prose, explanation, or code fences before or after the JSON.
+
+When the sequence is a coherent, reusable procedure, return:
+{
+  "title": "<short imperative workflow title, no trailing period>",
+  "description": "<one complete sentence (ending with a period) stating what the workflow accomplishes>",
+  "steps": [
+    {
+      "title": "<short imperative step title>",
+      "instructions": "<one or more imperative sentences telling an agent exactly how to perform this step>",
+      "completionCriteria": ["<optional bullet: an observable signal the step is done>"]
+    }
+  ]
+}
+
+When the sequence is NOT a coherent reusable procedure (it is noise, the steps do
+not form a meaningful workflow, or any reusable framing would be a stretch),
+return an explicit null:
+null
+
+A justified null is a CORRECT and expected outcome. Do NOT fabricate a hollow
+workflow to avoid returning null.
+
+## Rules
+- `steps` MUST have EXACTLY as many entries as the input action list, in order.
+- Every step MUST have a non-empty `title` and non-empty `instructions`.
+- `completionCriteria` is OPTIONAL; omit it rather than inventing weak criteria.
+- The `description` MUST be a single complete present-tense sentence with NO
+  markdown, self-contained enough for a reviewer to understand the workflow.
+- Ground every step in the corresponding input action; do not introduce outside
+  facts or tools the action does not mention.

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

@@ -0,0 +1,40 @@
+You are the akm `recombine` synthesizer.
+
+You are given a CLUSTER of related memories — distinct episodes that share a
+topic (a tag or a graph entity) but were recorded independently. Your job is to
+induce ONE cross-episodic generalization: a single durable insight that none of
+the input memories states on its own, but that the cluster as a whole supports.
+
+This is hypothesis formation, not summarization. A good generalization explains
+WHY the individual episodes are instances of the same underlying pattern and
+gives an agent a reusable rule for the next, unseen episode.
+
+YOUR RESPONSE MUST BE A SINGLE JSON OBJECT AND NOTHING ELSE.
+DO NOT output prose, explanation, or code fences before or after the JSON.
+
+When a defensible generalization exists, return:
+{
+  "description": "<one complete sentence (ending with a period) stating the generalization>",
+  "when_to_use": "<one complete sentence describing the concrete trigger condition>",
+  "body": "<1-3 short paragraphs of practical guidance grounded in the cluster>"
+}
+
+When NO defensible generalization exists — the memories merely share a keyword,
+or any unifying claim would be a stretch — return an explicit null:
+null
+
+A justified null is a CORRECT and expected outcome. Do NOT invent a weak or
+generic generalization to avoid returning null. It is better to propose nothing
+than to propose a hollow over-generalization.
+
+## description field (MANDATORY when not null)
+- A single complete present-tense sentence, NO markdown.
+- Self-contained: a reviewer must understand the hypothesis from this field alone.
+- DO NOT start with "When " or "If " — that belongs in `when_to_use`.
+- DO NOT merely restate one input memory; the value is the CROSS-episode pattern.
+
+## Guardrails
+- Induce exactly ONE generalization for the whole cluster.
+- Ground every claim in the supplied memories; do not introduce outside facts.
+- This is a HYPOTHESIS — it will be re-confirmed across future runs before it is
+  ever promoted to a durable lesson. Frame it as a candidate rule, not a verdict.

package/dist/assets/prompts/staleness-detect-system.md

@@ -0,0 +1,6 @@
+You are a belief-state classifier for a memory store. Given a candidate memory and a list of more-recent similar memories from the same store, decide whether the candidate is still current or has been superseded.
+
+Respond on the first line with exactly YES or NO.
+If YES, the second line MUST be of the form `SUPERSEDED_BY: <ref>` where <ref> is the exact ref of the superseding memory from the list provided. Do NOT invent refs.
+If NO, do not include any additional lines.
+No prose, no preamble, no markdown.

package/dist/assets/prompts/validate-summary-judge.md

@@ -0,0 +1 @@
+You are a strict completion auditor for a software workflow engine. Given a step's completion criteria and a summary of the work an agent claims to have done, judge whether the summary provides concrete evidence that EVERY criterion is satisfied. Be skeptical: vague, hand-wavy, or unsubstantiated claims do NOT satisfy a criterion. Respond with ONLY a JSON object: {"complete": boolean, "missing": string[], "feedback": string}. "missing" lists the exact criteria that are not yet satisfied; "feedback" is a short directive telling the agent what to finish or fix. No prose, no markdown fences.

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

@@ -0,0 +1,38 @@
+---
+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.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Agent authoring conventions
+
+An agent asset defines a reusable role. Treat it like a disciplined maintainer, not a generic personality. Its job is to know its scope, read the right rulebooks, use the right tools, and leave the stash in better shape.
+
+## Purpose
+
+Use an agent when a recurring task benefits from a specialized role, bounded responsibilities, and explicit tool behavior.
+
+## Authoring strategy
+
+- Write the description so a dispatcher knows exactly when to delegate to this agent.
+- Define the agent’s domain, authority, boundaries, and expected output.
+- Specify what the agent must read first: relevant stash standards, type conventions, reference docs, source files, or prior lessons.
+- State tool expectations plainly: what tools it may use, what it should avoid, and when it must ask for human review.
+- Give the agent maintenance duties when appropriate: update cross-references, append logs, preserve provenance, and surface contradictions.
+- Prefer a narrow role that does one thing reliably over a broad do-everything persona.
+- Include handoff behavior: what the agent should return when it cannot complete the task safely.
+
+## Maintenance strategy
+
+- Refine the agent when repeated sessions show the same delegation failure.
+- 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.

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

@@ -0,0 +1,38 @@
+---
+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.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Command authoring conventions
+
+A command is a reusable markdown prompt template invoked by name. Treat it like an operation in the stash: every vague instruction will compound into repeated vague output.
+
+## Purpose
+
+Use a command when the user or agent needs to perform the same prompt-shaped task repeatedly with different arguments or context.
+
+## Authoring strategy
+
+- Put the task, inputs, constraints, and expected output shape near the top.
+- Make argument placeholders obvious and describe what each one should contain.
+- Tell the model what to inspect before acting, especially relevant stash assets, facts, standards, or reference docs.
+- State the decision boundary: what the command should do directly, what it should only propose, and what it should refuse or defer.
+- Include output requirements that are stable across runs.
+- Keep the prompt tight. A command should be easy to invoke and hard to misinterpret.
+- Avoid embedding one-time project details unless the command is intentionally project-specific.
+
+## Maintenance strategy
+
+- If users repeatedly clarify the same missing detail, add that detail to the command.
+- 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.

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

@@ -0,0 +1,39 @@
+---
+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.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Fact authoring conventions
+
+A fact is durable stash-level context: personal, team, project, convention, or meta knowledge. Treat facts as the stash’s semantic layer — selectively loaded context that should guide future work without bloating every prompt.
+
+## Purpose
+
+Use a fact for stable information that future agents should treat as true or normative: user preferences, project identity, team stack, architecture principles, naming conventions, tag vocabulary, or stash organization.
+
+## Authoring strategy
+
+- Write each fact as a standing declaration that can survive across sessions.
+- Keep it short, high-signal, and self-contained.
+- Choose the narrowest useful category: personal, team, project, convention, or meta.
+- Use `pinned: true` only for the small core that should be available constantly.
+- Leave most facts unpinned so they can be retrieved just-in-time.
+- Include scope and provenance when a fact is project-specific, inferred, or subject to change.
+- Separate facts from memories: memories preserve observations; facts state durable truth or durable policy.
+- Separate facts from knowledge: knowledge explains a topic; facts declare compact context.
+
+## Maintenance strategy
+
+- Revise or supersede facts when the durable truth changes.
+- Do not allow contradictory facts to remain equally active.
+- 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.

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

@@ -0,0 +1,40 @@
+---
+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.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate; validator-rejecting HARD rules live in src/core/authoring-rules.ts
+  and remain the sole enforced source. Editing or deleting this file cannot weaken
+  the gate. Tune the guidance below to match how your stash wants this asset type
+  maintained.
+-->
+
+# Knowledge authoring conventions
+
+A knowledge asset is a compiled reference document meant to be read on demand. Treat it as the synthesized layer above raw material: not source files, not chat residue, but integrated, navigable understanding that saves future agents from rediscovering the same material.
+
+## Purpose
+
+Use a knowledge asset for durable reference material, synthesized explanations, design notes, comparisons, and project context that is broader than a single memory but less procedural than a skill.
+
+## Authoring strategy
+
+- Open with a plain top-level title that names the subject.
+- Add a concise orientation paragraph: what this document covers and when it should be read.
+- For a long reference, add a table of contents near the top so the full scope is visible even on a partial read.
+- Organize by stable concepts, decisions, entities, or questions — roughly one page per concept.
+- Cross-reference related assets instead of duplicating them, so a navigable graph forms over time.
+- Preserve provenance where it matters: cite source files, raw notes, session logs, or issues by path/ref.
+- Call out contradictions, uncertainty, stale claims, and open questions explicitly.
+- Prefer accurate synthesis over exhaustive dumping. Raw material belongs elsewhere; this file is the compiled layer.
+- Use tables or checklists when they make retrieval and comparison easier.
+
+## Maintenance strategy
+
+- 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.
+- Periodically scan for orphaned, stale, or overlapping knowledge docs and consolidate them.