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

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for lesson assets that capture compounding, hard-won judgment.
 when_to_use: Surfaced to authoring agents when they write or revise a lesson asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -40,4 +42,10 @@ Use a lesson to record:
 - Update an existing lesson when new feedback sharpens the same judgment.
 - 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.
+- When a lesson becomes broadly normative, consider promoting the stable rule into a `facts/conventions/...` asset.
+
+## Placement & linking
+
+- Lessons are **scope-born**: file them under the **project/client** they were
+  learned in (`lessons/projectA/token-refresh-gotcha`) and xref the asset the
+  lesson corrects or refines.

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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for memory assets using durable-context and provenance discipline.
 when_to_use: Surfaced to authoring agents when they write or revise a memory asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -36,3 +38,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 (`memories/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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for script assets using agent-safe CLI helper principles.
 when_to_use: Surfaced to authoring agents when they write or revise a script asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -41,3 +43,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 `facts/conventions/domains` (`scripts/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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for skill assets as reusable, just-in-time procedural rulebooks.
 when_to_use: Surfaced to authoring agents when they write or revise a skill asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -38,3 +40,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 `facts/conventions/domains`
+  (`skills/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

@@ -1,7 +1,9 @@
 ---
+type: fact
 category: convention
 description: Soft authoring conventions for workflow assets using explicit operations, logging, and lintable steps.
 when_to_use: Surfaced to authoring agents when they write or revise a workflow asset.
+updated: 2026-07-28
 ---
 
 <!--
@@ -41,3 +43,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 (`workflows/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,100 @@
+---
+type: fact
+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 asset that derives from, corrects, or relates to another asset.
+updated: 2026-07-28
+---
+
+<!--
+  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. (LLM-wiki bundles carry their own xref system in
+  their pages' frontmatter — this convention is for in-stash 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
+  - lessons/projectA/token-refresh-gotcha # one real associative link
+---
+```
+
+## Link rules
+
+- **One xref is mandatory when the asset derives from another: cite the source
+  ref** (`memories/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). LLM-wiki bundles enforce the
+  analogous rule mechanically (`sources:` frontmatter citations); in-stash
+  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
+  ingested raw material, vendored docs, and transcripts as
+  immutable-by-discipline: a hard-won fix is a new `lessons/` 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 `facts/conventions/domains` so agents don't
+fragment `postgres` / `postgresql` / `pg`.
+
+## Hubs are optional, not per-namespace obligations
+
+A hub (a `knowledge/` overview page that xrefs the key assets in a domain) is
+worth authoring for a **few genuinely high-traffic domains**. 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,64 @@
+---
+type: fact
+category: convention
+description: The closed vocabulary of domain prefixes for reuse-born assets (knowledge/skill/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.
+updated: 2026-07-28
+---
+
+<!--
+  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`, `fact`, `script`) take a
+**domain prefix** from this list, e.g. `knowledge/auth/oauth-refresh-races`,
+`skills/testing/flaky-test-triage`. 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) (`facts/policies/…`)
+- `conventions` — stash authoring house-rules (`facts/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. `facts/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,136 @@
+---
+type: fact
+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 asset and must decide its subdirectory/name.
+updated: 2026-07-28
+---
+
+<!--
+  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.
+  - `memories/projectA/auth-token-refresh`
+  - `lessons/clientX/migration-rollback-gotcha`
+  - `secrets/clientX/api-key`
+- **Reuse-born types → stable domain from a short vocabulary.**
+  `knowledge`, `skill`, `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>`.
+  - `knowledge/auth/oauth-refresh-races`
+  - `skills/testing/flaky-test-triage`
+  - `facts/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 `facts/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 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 renamed file
+  is a new index entry, so the asset's accumulated usage-ranking history
+  resets.
+- **A rename is delete plus create, and you do it by hand.** There is no
+  `akm mv` — moving the file strands every inbound ref and gives the
+  destination a fresh identity. If a rename is truly unavoidable:
+
+  ```sh
+  mv memories/old-note.md memories/new-note.md
+  # update any intentional refs (fully qualified: bundle//memories/old-note)
+  akm index
+  akm lint          # confirms nothing dangles
+  ```
+
+  A memory's `.derived.md` twin must move with its base. Citing files in
+  read-only sources cannot be fixed at all — another reason not to rename. The
+  asset's accumulated usage-ranking history resets unless you carry it over
+  with `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>` (a maintainer
+  script, run from a source clone after the move and before `akm index`).
+- 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/extract.yml

@@ -1,4 +1,5 @@
+version: 2
 schedule: "*/30 * * * *"
-command: akm extract
+command: akm proposal extract --auto
 enabled: true
-description: Extract insights from session files every 30 min
+description: Opt-in all-harness session extraction every 30 min

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

@@ -1,4 +1,5 @@
+version: 2
 schedule: "0 2 * * *"
-command: akm improve --auto-accept safe
+command: akm improve
 enabled: true
 description: Run improve pipeline nightly

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,4 +1,5 @@
+version: 2
 schedule: "0 9 * * 1"
-command: akm info --check-version
+command: akm upgrade --check
 enabled: true
 description: Weekly check for new akm releases

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

@@ -0,0 +1,5 @@
+version: 2
+schedule: "10 3 * * 0"
+command: akm improve --strategy graph-refresh --skip-if-locked
+enabled: true
+description: Full-corpus graph rebuild (weekly Sunday 3:10am)

package/dist/assets/tasks/improve/akm-improve-catchup.yml

@@ -0,0 +1,8 @@
+version: 2
+schedule: "0 4 * * *"
+command: akm improve --strategy catchup --skip-if-locked
+# Manual-recovery task: ships disabled (the retired registerDefaultTasks
+# marked it enableMode: "manual"). `akm task run` works while disabled;
+# opting into the schedule is `enabled: true` + `akm task sync`.
+enabled: false
+description: Manual recovery — consolidation + triage drain (run on demand via `akm task run akm-improve-catchup`)

package/dist/assets/tasks/improve/akm-improve-consolidate.yml

@@ -0,0 +1,5 @@
+version: 2
+schedule: "20 */4 * * *"
+command: akm improve --strategy consolidate --skip-if-locked
+enabled: true
+description: Consolidation-only pass (every 4h at :20)

package/dist/assets/tasks/improve/akm-improve-frequent.yml

@@ -0,0 +1,5 @@
+version: 2
+schedule: "40 * * * *"
+command: akm improve --strategy frequent --skip-if-locked
+enabled: true
+description: Frequent inference pass (hourly at :40; improve-stage extract off)

package/dist/assets/tasks/improve/akm-improve-nightly.yml

@@ -0,0 +1,5 @@
+version: 2
+schedule: "15 2 * * *"
+command: akm improve --strategy thorough --skip-if-locked
+enabled: true
+description: Full nightly quality sweep (daily 2:15am; suggested for server installs)

package/dist/assets/templates/html/health.html

@@ -4,9 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>%%REPORT_TITLE%%</title>
-  <!-- %%ECHARTS_TAG%% : either an inlined <script>…echarts…</script> (self-contained
-       / deterministic / offline) or a CDN <script src> when the renderer is run
-       with --echarts cdn. -->
+  <!-- %%ECHARTS_TAG%% : a <script src> pointed at the jsDelivr CDN (chunk-9
+       WI-9.4d) — viewing this report requires network access. -->
   %%ECHARTS_TAG%%
   <style>
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -391,7 +390,7 @@
       <div class="table-wrap">
       <table>
         <thead>
-          <tr><th>Started</th><th>Task</th><th>Wall</th><th>Promoted</th><th>Merged</th><th>Contradicted</th><th>MI Written</th><th>Entities</th><th>Lint Fixed</th><th>Status</th></tr>
+          <tr><th>Started</th><th>Task</th><th>Strategy</th><th>Wall</th><th>Promoted</th><th>Merged</th><th>Contradicted</th><th>MI Written</th><th>Entities</th><th>Lint Fixed</th><th>Status</th></tr>
         </thead>
         <tbody id="lastRunsTable"></tbody>
       </table>
@@ -683,12 +682,14 @@ tbody.innerHTML = '';
   const ts = `${d.getFullYear()}-${pad(d.getMonth()+1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
   const dur = r.wallTimeMs ? (r.wallTimeMs / 60000).toFixed(1) + 'm' : '—';
   const task = r.taskId || 'manual';
+  const strategy = r.strategy || '—';
   const badge = r.ok
     ? '<span class="badge-pill badge-pass" style="padding:2px 8px;font-size:11px;"><span class="dot dot-pass" style="width:6px;height:6px;"></span>&nbsp;ok</span>'
     : '<span class="badge-pill badge-fail" style="padding:2px 8px;font-size:11px;"><span class="dot dot-fail" style="width:6px;height:6px;"></span>&nbsp;failed</span>';
   tr.innerHTML = `
     <td style="font-family:monospace;font-size:12px;">${ts}</td>
     <td><code>${task}</code></td>
+    <td><code>${strategy}</code></td>
     <td>${dur}</td>
     <td style="color:var(--accent);font-weight:600;">${r.promoted || 0}</td>
     <td>${r.merged || 0}</td>

package/dist/assets/workflows/workflow-template.md

@@ -1,24 +1,40 @@
 ---
-description: Describe what this workflow accomplishes
-tags:
-  - example
+type: workflow
+description: One-sentence summary of what this workflow accomplishes.
+updated: 2026-01-01
+tags: [example]
 params:
-  example_param: Explain this parameter
+  example_param: { type: string, description: Explain this parameter }
+steps:
+  - id: first-step
+  - id: second-step
+    inputs: [steps.first-step.output]
 ---
 
-# Workflow: {{TITLE}}
+# {{TITLE}}
 
-## Step: {{FIRST_STEP_TITLE}}
-Step ID: {{FIRST_STEP_ID}}
+Free preamble prose describing what this workflow does. It is indexed for
+search and shown in `akm show`, but it is never dispatched to a step.
 
-### Instructions
-Describe what to do in this step.
+## first-step
 
-### Completion Criteria
-- Confirm the first step is complete
+Describe what to do in this step. Refer to run parameters in plain
+language — for example, "read the value given by the `example_param`
+parameter" — never as a template expression like `{{ example_param }}`.
 
-## Step: Second Step
-Step ID: second-step
+## second-step
 
-### Instructions
-Describe what happens next.
+Describe what happens next, using the first step's artifact — attached to
+this unit as context because this step declares
+`inputs: [steps.first-step.output]` above — referred to in prose as "the
+first step's attached artifact."
+
+### gate
+
+A `### gate` sub-heading is the step's completion rubric: the judge
+receives this whole section byte-exact when validation is available. Omit
+the heading or leave its text empty to skip validation. An unavailable or
+malformed judge also skips validation.
+
+- Confirm the step accomplished what it set out to do.
+- Confirm nothing required was silently skipped.