akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

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

@@ -25,15 +25,18 @@ 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 "memory:projectA/"                 # List a typed subtree (ref-prefix query; trailing slash required)
 akm search "<query>" --source both            # Also search registries
 akm show <ref>                                # View asset details
 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 remember "note" --xref knowledge:auth-flow # Cite provenance in frontmatter xrefs (repeatable)
+akm remember "fix" --supersedes memory:old-note # Write a correction AND demote the superseded asset
 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 ingest <name>                        # Dispatch an agent to run the ingest workflow (uses defaults.engine or --engine)
 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 proposal accept 7c115132                  # Accept by UUID prefix
@@ -41,6 +44,7 @@ akm proposal reject skill: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 mv memory:old-note new-note               # Rename an asset: inbound refs rewritten, ranking history preserved
 akm sync                                      # Commit (and push if writable remote) changes in the primary stash (--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
@@ -60,7 +64,7 @@ akm registry search "<query>"                 # Search all registries
 | 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. |
+| 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 engine to execute the ingest workflow against the wiki's `raw/` directory. Run `akm wiki -h` for the full surface. |
 
 When an asset meaningfully helps or fails, record that with `akm feedback` so
 future search ranking can learn from real usage.

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

@@ -11,6 +11,7 @@
     "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": true },
     "extract": { "enabled": true, "triage": { "enabled": true, "minScore": 2 } },
+    "validation": { "enabled": true },
     "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 15 },
     "triage": { "enabled": false, "applyMode": "queue", "policy": "personal-stash" },
     "recombine": { "enabled": false },

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 },

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

@@ -3,10 +3,9 @@
   "processes": {
     "reflect": {
       "enabled": true,
-      "mode": "llm",
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
     },
-    "distill": { "enabled": true, "mode": "llm", "allowedTypes": ["memory"] },
+    "distill": { "enabled": true, "allowedTypes": ["memory"] },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },
     "graphExtraction": { "enabled": false },
@@ -17,7 +16,7 @@
       "policy": "personal-stash",
       "maxAcceptsPerRun": 100,
       "maxDiffLines": 200,
-      "judgment": { "mode": "llm" }
+      "judgment": {}
     },
     "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 100 }
   },

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

@@ -3,12 +3,11 @@
   "processes": {
     "reflect": {
       "enabled": true,
-      "mode": "llm",
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
     },
-    "distill": { "enabled": true, "mode": "llm", "allowedTypes": ["memory"] },
+    "distill": { "enabled": true, "allowedTypes": ["memory"] },
     "consolidate": { "enabled": false },
-    "memoryInference": { "enabled": true, "mode": "llm" },
+    "memoryInference": { "enabled": true },
     "graphExtraction": { "enabled": false },
     "extract": {
       "enabled": false,
@@ -22,7 +21,7 @@
       "policy": "personal-stash",
       "maxAcceptsPerRun": 15,
       "maxDiffLines": 200,
-      "judgment": { "mode": "llm" }
+      "judgment": {}
     },
     "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 15 }
   },

package/dist/assets/prompts/workflow-unit-preamble.md

@@ -0,0 +1,26 @@
+You are executing one unit of an akm workflow run.
+
+- Workflow run: {{RUN_ID}}
+- Step: {{STEP_ID}}
+- Unit: {{UNIT_ID}}
+- Run parameters: {{PARAMS_JSON}}
+
+Ground rules for this unit:
+
+1. Pull knowledge on demand instead of guessing: `akm search '<query>'` to find
+   relevant assets, `akm show <ref>` to read one, `akm curate '<query>'` to let
+   akm select the best match. Only pull what this unit actually needs.
+2. Environment values and secrets are provided through your process
+   environment when the workflow declares them. Never print secret values to
+   stdout or embed them in your answer. If you need an env file path, use
+   `akm env path <ref>`; never `cat` secrets.
+3. Do exactly the work described in the instructions below — no more. Other
+   units may be running concurrently on sibling items; do not touch files or
+   state outside the scope this unit was given.
+4. Your final output IS the unit result recorded by the engine. When a JSON
+   schema is requested, respond with ONLY the JSON value (no prose, no code
+   fences). Otherwise finish with a concise factual summary of what you did.
+
+Unit instructions follow.
+
+---

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

@@ -17,10 +17,38 @@ 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 |
+| `wikis/` | Wikis | Agent-maintained knowledge bases (see `akm wiki`) |
+| `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:
+
+- **`fact: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`, `wiki`, `fact`, `script`) go under a stable **domain**; global types
+  stay at the type root.
+- **`fact: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.
+- **`fact: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

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

@@ -36,3 +36,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 (`agent: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

@@ -36,3 +36,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

@@ -34,6 +34,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
+  (`fact: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

@@ -36,5 +36,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
+  `fact: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.

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

@@ -41,3 +41,9 @@ Use a lesson to record:
 - Create a new lesson only when the trigger or failure mode is meaningfully different.
 - Deprecate or revise stale lessons instead of allowing contradictory guidance to accumulate.
 - When a lesson becomes broadly normative, consider promoting the stable rule into a `fact:conventions/...` asset.
+
+## Placement & linking
+
+- Lessons are **scope-born**: file them under the **project/client** they were
+  learned in (`lesson:projectA/token-refresh-gotcha`) and xref the asset the
+  lesson corrects or refines.

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

@@ -36,3 +36,12 @@ Use a memory when a future agent would make a better decision by knowing a speci
 - Consolidate repeated memories into a clearer fact or knowledge asset.
 - Convert broad, stable conventions into `fact` assets.
 - Archive memories that are no longer current rather than letting stale context keep influencing agents.
+
+## Placement & linking
+
+- Memories are **scope-born**: file them under the **current project/client**
+  slug (`memory:projectA/auth-token-refresh`) — the working context is the
+  answer, so no per-asset judgment is needed. Add the subject as a tag
+  (`tags: [auth, projectA]`) for cross-cutting recall.
+- When a memory turns out to be domain-general, **append** a new
+  `knowledge:<domain>/…` asset that xrefs it — never rename the memory up a rung.

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

@@ -41,3 +41,10 @@ Use a script when a task is mechanical, repeatable, and better handled by a dete
 - Keep dangerous actions behind explicit flags.
 - When a script becomes a core operation, add or update a workflow that explains when to run it.
 - If the script encodes a convention, also document that convention in a fact or knowledge asset.
+
+## Placement & linking
+
+- Scripts are **reuse-born**: file a general helper under a tool/domain slug
+  from `fact:conventions/domains` (`script:build/release`). Use the project slug
+  only when the script hard-codes project-specific paths, endpoints, or
+  credentials.

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

@@ -38,3 +38,10 @@ Use a skill when the stash needs reusable procedural guidance for a recurring cl
 - Add companion knowledge docs when the skill needs background material that would bloat the main procedure.
 - Promote durable recurring corrections into the skill; leave one-off observations in memories or lessons.
 - Prefer small edits that preserve the skill’s operational shape over broad rewrites that erase tested guidance.
+
+## Placement & linking
+
+- Skills are **reuse-born**: place `skills/<domain>/<name>/SKILL.md` under a
+  stable **domain** prefix from `fact:conventions/domains`
+  (`skill:testing/flaky-test-triage`) so any project finds and reuses it instead
+  of duplicating the procedure.

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

@@ -41,3 +41,9 @@ Use a workflow when the task requires multiple steps, branching decisions, repea
 - Add logging expectations when the workflow creates durable state.
 - Extract reusable sub-procedures into skills or scripts when the workflow grows too broad.
 - Record recurring mistakes as lessons, then fold stable corrections back into the workflow.
+
+## Placement & linking
+
+- Workflows are usually **global**: keep them at the type root or under a
+  tool/domain slug (`workflow:release-train`). Scoping a workflow to one project
+  rarely improves retrieval and adds rename risk.

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

@@ -0,0 +1,98 @@
+---
+category: convention
+description: How to cross-link assets so retrieval compounds — a provenance xref when derived, sparse real associative xrefs, corrections as new assets, and canonical entity naming.
+when_to_use: Surfaced to authoring agents when they create or revise any non-wiki asset that derives from, corrects, or relates to another asset.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Back-linking here is a RETRIEVAL
+  mechanism, not decoration: `xrefs:` frontmatter folds into the search index;
+  the entity/relation graph is extracted from BODY prose (memory + knowledge),
+  never from frontmatter. Over-linking degrades ranking, so these rules are
+  deliberately conservative. Wikis have their own xref + lint system — this
+  convention is for non-wiki assets.
+-->
+
+# Back-linking conventions
+
+Cross-references are how knowledge compounds instead of being re-derived every
+session. In AKM they are also **indexed**: the strings in an asset's `xrefs:`
+frontmatter fold into its search-hint text, and knowledge/memory bodies feed an
+LLM-extracted entity/relation graph that boosts ranking. So links are a retrieval
+lever — which means both too few and too many hurt.
+
+```yaml
+---
+description: OAuth refresh-token race on token rotation
+tags: [auth, projectA]
+xrefs:
+  - knowledge:auth/vendor-x-token-api   # provenance: what this was synthesized from
+  - lesson:projectA/token-refresh-gotcha # one real associative link
+---
+```
+
+## Link rules
+
+- **One xref is mandatory when the asset derives from another: cite the source
+  ref** (`memory:projectA/token-quirk` xrefs `knowledge:auth/vendor-x-token-api`
+  — it also makes this asset findable from searches for its source). An
+  original observation with no source carries none — never invent provenance.
+  `akm remember`/`akm import` write this channel via `--xref <ref>`
+  (repeatable; refs are checked at write time). Wikis enforce the analogous
+  rule mechanically (`sources:` + `uncited-raw` lint); non-wiki provenance is
+  discipline only.
+- **Associative xrefs are discretionary — real relationships only.** Add one when
+  you already know a genuine load-bearing connection. Do **not** hit a link
+  quota by pointing at the topically-nearest sibling — a plausible-but-wrong
+  xref makes this asset a false search match for the other topic, and a wrong
+  relationship asserted in prose poisons the entity graph. A relationship you
+  want the graph to learn must be named in the body (e.g. open with "Corrects
+  knowledge:auth/oauth-refresh-races").
+- **Cap total xrefs at ~5 (a heuristic, not a measured threshold).** Each xref
+  folds its ref tokens into THIS asset's search hints — past a handful, the
+  asset matches queries about several other topics and its own ranking signal
+  blurs.
+- **Corrections are new assets; ingested material is immutable.** Treat wiki
+  `raw/`, vendored docs, and transcripts as immutable-by-discipline: a hard-won
+  fix is a new `lesson:` or `knowledge:` asset that xrefs what it corrects.
+  Synthesized `knowledge:` pages are the rewritable layer — update them in
+  place. When a correction supersedes a standalone asset (memory OR knowledge),
+  also set the old asset's `beliefState: superseded` and
+  `supersededBy: [<new ref>]` — a metadata edit, not a content edit — so the
+  ranker demotes the stale version instead of letting it outrank your fix.
+  `akm remember`/`akm import` do both writes in one step via
+  `--supersedes <old ref>` (adds the xref and demotes the old asset).
+- **Bidirectional back-links are best-effort.** Add a return xref only when you
+  are already editing the target in the same pass. Never require editing a
+  separate hot file just to add a back-xref — concurrent writes drop it under
+  last-writer-wins and no lint will notice.
+
+## Self-situating headers and canonical naming
+
+Put the one-line orientation in `description:` and the trigger conditions in
+`when_to_use:` — those are indexed fields; body prose is not indexed by
+default (only headings reach the index; the opt-in `index.indexBodyOpening`
+flag adds just the first body paragraph, at the lowest weight —
+`description:`/`when_to_use:` remain the primary orientation channel). Then
+open the body with a plain title plus a one-line
+orientation naming what it is, its scope/domain, and its key entities in
+canonical spelling (`Postgres`, `OAuth`, `TLS`, `Acme`) — the entity/relation
+graph is extracted from body prose, and readers land here from `akm show`.
+Keep the canonical-spelling list in `fact:conventions/domains` so agents don't
+fragment `postgres` / `postgresql` / `pg`.
+
+## Hubs are optional, not per-namespace obligations
+
+A hub (a `wiki:` overview page that xrefs the key assets in a domain) is worth
+authoring for a **few genuinely high-traffic domains** — wikis are the one type
+with real orphan/broken-xref/stale-index lint to keep a hub honest. Do **not**
+mandate a hub per namespace and do not edit a hub on every write: that is O(n)
+maintenance, a concurrent-write contention point, and it flattens the multi-hop
+graph into a namespace-wide star. Let the FTS index be the catalog; spend the
+effort on per-asset self-situating headers instead.
+
+## Keep assets atomic
+
+One concept per asset. If a note covers two concepts, write two assets and xref
+them — atomic assets give the ranker clean, single-topic targets and give you a
+real relationship to link rather than a blurred one to bury.

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

@@ -0,0 +1,63 @@
+---
+category: convention
+description: The closed vocabulary of domain prefixes for reuse-born assets (knowledge/skill/wiki/fact/script), plus canonical entity spellings. Edit this to match your stash.
+when_to_use: Surfaced to authoring agents alongside the other convention facts; consult it when picking a domain prefix for a knowledge, skill, fact, or script asset (for wikis, the domain names the wiki).
+---
+
+<!--
+  SOFT guidance only. This is the domain vocabulary that `organization.md` refers
+  to. It is intentionally SHORT and STARTER — replace these with the domains your
+  stash actually accumulates. A closed list keeps agents from coining a new
+  folder per session (which fragments the tree and splits slug search); the flat
+  type-root fallback in organization.md handles anything that doesn't fit yet.
+-->
+
+# Domain vocabulary
+
+Reuse-born assets (`knowledge`, `skill`, `wiki`, `fact`, `script`) take a
+**domain prefix** from this list, e.g. `knowledge:auth/oauth-refresh-races`,
+`skill:testing/flaky-test-triage` (for a wiki, the domain names the wiki:
+`wikis/auth/`). Pick the closest match. If two fit, take the one naming the
+SUBJECT of the doc (what it teaches, not where it was met) and put the other in
+tags; if still tied, the earlier entry in this list wins. If nothing fits, write
+the asset at the type root and propose an addition here — do **not** invent a
+one-off domain mid-task.
+
+## Starter domains
+
+Add, remove, and rename to fit your stash. Keep the list short (roughly a dozen)
+— the whole list rides along in every authoring prompt, and a short closed list
+is what keeps two agents picking the same slug. Add a subdomain only where
+volume justifies it.
+
+- `auth` — authentication, authorization, tokens, sessions
+- `networking` — protocols, TLS, DNS, proxies, connectivity
+- `databases` — storage engines, queries, migrations (subdomain e.g. `databases/postgres`)
+- `testing` — test strategy, fixtures, flaky-test triage, coverage
+- `build` — build systems, packaging, CI pipelines
+- `cloud` — infra, deploy targets, IaC (subdomain e.g. `cloud/aws`)
+- `observability` — logging, metrics, tracing, alerting
+- `security` — threat modeling, secrets handling, hardening
+- `frontend` — UI, rendering, client state
+- `data-pipelines` — ETL, streaming, batch processing
+- `tooling` — dev tooling, editor/agent integration, scripts
+- `policies` — organizational/business rules the work must obey (PII handling, licensing) (`fact:policies/…`)
+- `conventions` — stash authoring house-rules (`fact:conventions/…`; auto-surfaced to authoring agents — keep them in this directory)
+
+## Canonical entity spellings
+
+Pick ONE name per entity and use it everywhere in asset **bodies** — retrieval
+is case-insensitive but treats aliases as different entities, so alias variants
+fragment the entity graph. Extend as your stash grows.
+
+- Postgres (not postgresql / pg)
+- Kubernetes (not k8s)
+- TLS (not ssl when you mean TLS)
+- OAuth
+
+Project and client slugs are **not** listed here — those are scope slugs for
+scope-born types (`memory`, `lesson`, `task`, `env`, `secret`). Keep their
+canonical spellings in a `category: meta` fact (e.g. `fact:active-projects`) so
+they auto-inject at authoring time — not in `.meta/`, which is unindexed and
+invisible mid-task — and `akm search` for an existing spelling before minting a
+new one.

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

@@ -0,0 +1,127 @@
+---
+category: convention
+description: Where to place an asset in the stash — the one path partition axis, chosen by asset type, so refs stay stable and slug search (akm search "<slug>" --type <type>) co-locates related assets.
+when_to_use: Surfaced to authoring agents when they create or move any non-wiki asset and must decide its subdirectory/name.
+---
+
+<!--
+  SOFT guidance only — advice, not a contract. Nothing here is enforced by the
+  proposal gate. It steers WHERE assets go so that path-derived refs stay stable
+  and scoped search (`akm search "<slug>" --type <type>`) keeps working. Tune
+  the axis choices and the domain vocabulary to match how your stash is queried.
+-->
+
+# Stash organization conventions
+
+A file's path under its type directory **becomes part of its ref**
+(`knowledge/auth/oauth-refresh-races.md` → `knowledge:auth/oauth-refresh-races`).
+That ref is an address other assets cite, and its segments are search terms —
+`akm search "projectA" --type memory` reconstructs a project's memories. The
+path is therefore the one facet you **cannot express twice and cannot change
+without breaking the ref** — so spend it deliberately, on exactly one axis.
+
+Retrieval is search, not browse: no one walks these folders at query time. A
+subdirectory buys you three things: its tokens are indexed as part of the
+asset's **name** (the highest-weighted search field), they are auto-added to
+`tags` (even when you set `tags` explicitly), and for scope-born types a slug
+matching the current repo's name earns an automatic in-project ranking boost.
+Every other facet belongs in frontmatter, where the index can actually read it.
+
+## Choose the partition axis by asset TYPE, not per-asset judgment
+
+Deciding "project or domain?" per asset is non-deterministic — two agents guess
+differently and bake the wrong guess into an immutable ref. Decide by type:
+
+- **Scope-born types → current project / client / team slug.**
+  `memory`, `lesson`, `task`, `env`, `secret`. These are born bound to the work
+  in front of you, so the working context *is* the answer — no judgment needed.
+  When the scope is a single repo, use its repo/package name as the slug (as
+  `git remote`/package.json spell it) — ranking auto-boosts assets whose name
+  or tags match the current repo. Client/team slugs get no such boost; just
+  reuse the existing spelling.
+  - `memory:projectA/auth-token-refresh`
+  - `lesson:clientX/migration-rollback-gotcha`
+  - `secret:clientX/api-key`
+- **Reuse-born types → stable domain from a short vocabulary.**
+  `knowledge`, `skill`, `wiki`, `fact`, `script`. These are meant to be reused
+  across projects, so co-locate them by subject — any project retrieves them
+  with `akm search "<domain>" --type <type>`. For a wiki the domain names the
+  wiki itself (`wikis/auth/`); inside it, its `schema.md` and wiki lint govern
+  layout, not these rules.
+  - `knowledge:auth/oauth-refresh-races`
+  - `skill:testing/flaky-test-triage`
+  - `fact:policies/pii-handling`
+- **Global-by-nature types → type root or a tool slug.**
+  `command`, `agent`, `workflow`, and stash-wide `env`. Scoping these to a
+  project rarely improves precision and only adds rename risk. `env` defaults
+  to the project/client slug; only an env consumed by every project sits at
+  the type root — if any single project would break when it changes, it is
+  scope-born.
+
+**Why reuse types don't take the project axis:** project relevance is already
+recovered at query time — AKM blends a per-project usage signal into ranking
+(scoped utility, keyed off the current repo, not the asset's path). Free the
+scarce path segment for the domain — the *only* handle that co-locates
+cross-project reuse.
+
+## Placement rules
+
+- **One axis only.** Never encode two dimensions in the path
+  (`client/project/subsystem`, or `domain+status`). Second dimensions go in tags.
+- **Depth 1 by default, 2 max**, and only for strict stable containment
+  (`knowledge/databases/postgres/…`, `secret/clientX/projectA/…`). Never a third
+  semantic level — deeper axes go in frontmatter.
+- **Segments are lowercase-hyphen semantic tokens** that read as query terms
+  (`connection-pooling`, `tls-handshake-debugging`) — never opaque IDs, numbers,
+  or Johnny.Decimal-style codes, which carry no search signal.
+- **Never put a volatile facet in the path** — status, date, version, priority,
+  author, `wip`/`done`. Each one changes and forces a ref-breaking rename. They
+  belong in frontmatter tags.
+- **Flat fallback beats an invented folder.** If no domain fits a reuse-type
+  asset, write it at the type root (`knowledge:http-retry-basics`) rather than
+  coining a one-off domain. An unneeded folder is pure rename liability; propose
+  a vocabulary addition instead of fragmenting the tree.
+- **Reuse an existing slug before minting a new one.** Before coining a new
+  project/client/domain slug, `akm search` for the existing spelling
+  (`acme` vs `acme-corp`) so the prefix does not fragment. Keep the domain
+  vocabulary in `fact:conventions/domains`.
+- **Off-axis facets go in `tags:`, not a bare field.** The indexed FTS fields are
+  name, description, tags, hints, and content (headings only — body prose is
+  not indexed by default; the opt-in `index.indexBodyOpening` flag adds just
+  the first body paragraph, at the lowest weight) — there is **no `project`
+  field**, so `project: projectA` in
+  frontmatter is invisible to search. Put the off-axis facet in `tags` instead
+  (a project-scoped memory adds `tags: [auth]`; a domain-scoped asset genuinely
+  tied to a project adds `tags: [projectA]` sparingly).
+- **Directory tokens join `tags` on their own.** The scope/domain segments of
+  the path are always auto-added to `tags` — even when you set `tags`
+  explicitly — so there is no need to restate them; the tag-match ranking
+  boost fires for the scope token either way. Filename tokens are auto-added
+  only when `tags` is empty.
+
+## Renames and evolution
+
+- **A ref is chosen once. Default to not renaming.** A manual rename dangles
+  inbound xrefs silently at write time — nothing catches the breakage until
+  the next `akm lint` run flags the dead frontmatter refs (`missing-ref`) —
+  while the dead ref string keeps scoring in FTS, and a manually renamed file
+  is a new index entry, so the asset's accumulated usage-ranking history
+  resets.
+- If a rename is truly unavoidable, prefer `akm mv <ref> <new-name>`
+  (Experimental): it moves the file, rewrites inbound references across the
+  writable stash in the same pass, and keeps the asset's usage-ranking
+  history. Citing files in read-only sources are reported for manual
+  follow-up. On an older CLI without `akm mv`, treat the rename as an
+  xref-fixing operation: grep the stash for the old ref string and fix every
+  inbound reference in the same pass.
+- When a project-scoped note turns out to be domain-general, **append, don't
+  promote**: write a new `knowledge:<domain>/…` asset that xrefs the originating
+  memory. Never rename the memory up a rung — that breaks its ref. The atomic
+  note still serves factoid recall; the new synthesis serves reuse; the xref
+  bridges them.
+
+## Real isolation is a separate stash, not a folder
+
+A path prefix is a ranking scope, not a security boundary. When you need enforced
+isolation (client confidentiality, secret-leak containment), mount a **separate
+stash** and let source resolution keep it apart — don't rely on a subdirectory.

package/dist/assets/tasks/core/backup.yml

@@ -1,3 +1,4 @@
+version: 2
 schedule: "0 3 * * 0"
 command: akm db backups
 enabled: true

package/dist/assets/tasks/core/extract.yml

@@ -1,3 +1,4 @@
+version: 2
 schedule: "*/30 * * * *"
 command: akm extract
 enabled: true

package/dist/assets/tasks/core/improve.yml

@@ -1,3 +1,4 @@
+version: 2
 schedule: "0 2 * * *"
 command: akm improve --auto-accept safe
 enabled: true

package/dist/assets/tasks/core/index-refresh.yml

@@ -1,3 +1,4 @@
+version: 2
 schedule: "0 4 * * *"
 command: akm index
 enabled: true

package/dist/assets/tasks/core/sync.yml

@@ -1,3 +1,4 @@
+version: 2
 schedule: "*/15 * * * *"
 command: akm sync
 enabled: true

package/dist/assets/tasks/core/version-check.yml

@@ -1,3 +1,4 @@
+version: 2
 schedule: "0 9 * * 1"
 command: akm info --check-version
 enabled: true

package/dist/assets/tasks/graph-refresh-weekly.yml

@@ -1,10 +1,10 @@
-id: graph-refresh-weekly
+version: 2
 description: >
   Weekly full-corpus graph extraction pass. Rebuilds entity and relation
-  indexes across all stash files using the graph-refresh improve profile.
+  indexes across all stash files using the graph-refresh improve strategy.
   Complements the per-run improve pipeline which only extracts graph data
   for files touched by actionable refs.
-command: akm improve --profile graph-refresh
+command: akm improve --strategy graph-refresh
 schedule: "0 3 * * 0"
 enabled: false
-timeout: 3600000
+timeoutMs: 3600000