akm-cli 0.9.29 → 0.9.31

package/docs/posts/release-0.8.0.md

@@ -0,0 +1,332 @@
+---
+title: 'akm 0.8.0: CLI Redesign, Task Assets, and Belief-Aware Memory'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-releases
+description: 'akm 0.8.0 introduces a redesigned `improve` command, task assets for persistent agent workflows, and belief-aware memory for more accurate stash updates.'
+tags:
+  - ai
+  - agents
+  - cli
+  - release
+published: true
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+akm 0.8.0 is out. This release combines the storage reorganization and CLI redesign with the final improve-owned maintenance migration: plain `akm index` now keeps metadata current, while slower memory inference and graph extraction maintenance run from `akm improve` after consolidation.
+
+If you are on 0.7.x, the v1 migration guide covers the per-surface delta. The upgrade requires updating scripts and agent instructions due to breaking CLI changes.
+
+## TL;DR
+
+- **`akm improve`** — unified command for agent-driven asset refinement and post-loop maintenance.
+- **Improve-owned maintenance** — memory inference and graph extraction now run from `akm improve`, not `akm index`.
+- **End-of-run auto-sync** — `akm improve` now auto-commits git-backed stashes; `--sync`/`--no-sync`/`--push`/`--no-push` flags + token-based commit messages.
+- **Task assets** — first-class asset type for defining persistent agent workflows with cron scheduling and manual invocation.
+- **Belief-aware memory** — stash updates now incorporate the agent's belief state to prevent overwriting correct information.
+- **Proposal queue commands renamed** — old flat commands (`akm proposals`, `akm show proposal`, `akm diff proposal`, `akm accept`, `akm reject`) are now (`akm proposal list`, `akm proposal show`, `akm proposal diff`, `akm proposal accept`, `akm proposal reject`).
+- **`akm health`** — runtime health report for `state.db`, task execution logs, agent availability, and recent improve telemetry.
+- **CLI breaking changes** — proposal queue workflows are consolidated around `akm improve`, `akm propose`, `akm proposal list`, `akm proposal show`, `akm proposal diff`, `akm proposal accept`, and `akm proposal reject` (old flat aliases deprecated); update your automation.
+- **Release hardening** — empty-query search is a structured error again, `remember --enrich` now truly fail-softs, improve lock-leak on initialization errors fixed, and the Docker install matrix is green for Bun and binary paths.
+
+---
+
+## `akm improve`: The New Self-Improvement Surface
+
+The `akm improve` command consolidates asset refinement workflows. It can operate on a specific asset type (generating a new asset) or an existing asset ref (refining that asset). Under the hood, it uses the same proposal queue as before, ensuring all changes are reviewable before promotion.
+
+```sh
+akm improve <type>                 # scope the run to all assets of that type
+akm improve <ref>                  # refine an existing asset and produce a proposal
+```
+
+This consolidates the main proposal-oriented improvement workflow. It also now owns the slow maintenance passes that used to be coupled to indexing: after distill and consolidation settle the corpus, improve runs memory inference, reindexes if inference wrote new facts, and then refreshes graph extraction against the final post-improve state.
+
+## End-of-Run Git Sync and Commit Templating
+
+For git-backed stashes (detected by `.git` directory presence), `akm improve`
+now commits all changes as a single batch at the end of the run. Two new flags
+control the behavior:
+
+```sh
+akm improve              # default/thorough profiles: auto-commit + push
+akm improve --no-sync    # skip the end-of-run commit for this run
+akm improve --no-push    # commit but skip push
+akm improve --sync       # force sync even on profiles that disable it
+```
+
+**Sync defaults by profile:**
+
+| Profile | Sync | Push |
+|---------|------|------|
+| `default` | ✓ | ✓ |
+| `thorough` | ✓ | ✓ |
+| `quick` | — | — |
+| `memory-focus` | — | — |
+
+Lightweight passes (`quick`, `memory-focus`) opt out of auto-sync to avoid
+auto-committing partial results.
+
+**Commit message templates:** The `sync.message` config field supports `{token}`
+placeholders — `{timestamp}`, `{date}`, `{time}`, `{scope}`, `{refs}`,
+`{accepted}` — so the commit log can carry run context:
+
+```jsonc
+"sync": { "message": "akm improve {scope} — {refs} refs ({date})" }
+```
+
+The improve result includes a `sync` field (`{ committed, pushed, skipped,
+reason? }`) and a `stash_synced` event is emitted to `state.db`. Sync failures
+are non-fatal — they never fail a successful run.
+
+## Consolidate Reliability Improvements
+
+The consolidate pass received two reliability fixes:
+
+- **Pre-flight stale-DB filter**: entries that have gone stale in the DB since
+  the run started are filtered out before any LLM calls, eliminating wasted
+  tokens on already-processed content.
+- **Defense-in-depth merge guards**: four layers of guards now prevent
+  incorrect merges, improving correctness on edge cases.
+
+## Task Assets: Persistent Agent Workflows
+
+Task assets (`tasks/<name>.yml`) allow you to define persistent agent workflows that can be triggered on a schedule or manually. Each task runs using the configured agent runtime.
+
+Key features:
+- **Cron-based scheduling** (with proper escaping for special characters)
+- **Manual invocation** via `akm tasks run <id>`
+- **Proposal-driven updates** (task agents propose changes via `akm improve`, which go through the proposal queue)
+
+Example task asset:
+```yaml
+name: daily-code-review
+schedule: '0 9 * * *'  # every day at 9 AM
+command: opencode
+prompt: "Review the staged changes and suggest improvements"
+```
+
+## Belief-Aware Memory
+
+Memory assets now carry a `beliefState` frontmatter field (values: `active`, `asserted`, `deprecated`, `superseded`, `contradicted`, `archived`). The consolidation and improve passes use this field to track and transition belief state — for example, marking a memory `contradicted` when a newer fact conflicts with it. This reduces the chance of outdated or incorrect beliefs persisting in the stash after new information arrives.
+
+## Proposal Queue: Renamed Commands
+
+The proposal queue itself is unchanged, but the CLI surfaces have been reorganized under a `proposal` subcommand:
+
+| Old Command (0.7.x)  | New Command (0.8.0+)      |
+|----------------------|---------------------------|
+| `akm proposals`      | `akm proposal list`       |
+| `akm show proposal`  | `akm proposal show`       |
+| `akm diff proposal`  | `akm proposal diff`       |
+| `akm accept`         | `akm proposal accept`     |
+| `akm reject`         | `akm proposal reject`     |
+
+All commands retain the same functionality and flags (e.g., `akm proposal reject <id> --reason "..."`). The old flat verbs still work as deprecated aliases (they warn on stderr) and will be removed in 0.9.0 — update your scripts and documentation before then.
+
+## `akm health`: Runtime Checks in One Command
+
+`akm health` provides a quick operator-facing snapshot of whether the local akm
+runtime is healthy.
+
+```sh
+akm health
+akm health --since 24h
+akm health --since 7d --format text
+```
+
+It checks that `state.db` is readable and writable, verifies that required
+tables exist, inspects `task_history` for missing log files or stale active
+runs, probes the default agent profile, and summarizes recent `akm improve`
+activity from `improve_invoked`, `improve_skipped`, and `improve_completed`
+events.
+
+This makes it easier to validate an upgraded installation after migration or to
+spot regressions in task execution and improve-loop maintenance without querying
+SQLite tables directly.
+
+## Agent Command Builder: Platform-Aware Dispatch
+
+`akm agent` can now embody a stash agent asset — setting the system prompt, model, and tool policy automatically from the asset's metadata:
+
+```sh
+akm agent opencode agent:code-reviewer --prompt "review src/commands/"
+akm agent claude agent:planner --model sonnet --prompt "plan the next sprint"
+```
+
+The `<agent-ref>` positional resolves the agent asset's content as the system prompt, its `model:` frontmatter as the model, and its `tools:` frontmatter as the allowed tool set. Each platform gets the exact flags its CLI expects:
+
+- **opencode**: `opencode run --system-prompt "..." --model opencode/claude-opus-4-7 "<prompt>"`
+- **claude**: `claude --system-prompt "..." --model claude-opus-4-7 --allowedTools read,edit --print "<prompt>"`
+
+Built-in model aliases (`opus`, `sonnet`, `haiku`) resolve to the correct model string per platform. Add custom aliases in `agent.profiles.<name>.modelAliases`. Override any asset's model for a single run with `--model`.
+
+Without a prompt or agent-ref, `akm agent opencode` still launches the agent interactively — unchanged.
+
+## Graph Extraction: Faster, Cleaner, Schema-Stable
+
+0.8.0 reshapes how graph extraction is stored, queried, and refreshed. The
+visible wins:
+
+- **Schema cascade fix.** `graph_files` now keys on `entry_id INTEGER PRIMARY
+  KEY REFERENCES entries(id) ON DELETE CASCADE`, and the child tables
+  (`graph_file_entities`, `graph_file_relations`) cascade through. Removing a
+  stash or deleting an entry now correctly cleans up the graph rows — no more
+  orphans accumulating in `index.db`.
+- **Incremental refreshes.** Graph extraction now filters on a
+  `candidatePaths` set, so each `akm improve` cycle revisits only touched
+  assets instead of the whole stash. The default `graphExtractionBatchSize`
+  rose from 1 to 4 (auto-tuned against `llm.contextLength`).
+- **Fewer writes.** `replaceStoredGraph` is now incremental — unchanged entries
+  skip, changed entries swap their child rows in place, removed entries
+  cascade out. Roughly 700× fewer row writes per pass on typical re-extractions.
+- **Faster lookups.** `listRelatedPathsForFile` is a scoped SQL self-join
+  instead of a full snapshot load: ~30ms → ~2ms on a typical stash.
+- **New commands.** `akm graph entity <name>` inverts the entities view (every
+  asset that mentions a given entity, by confidence). `akm graph orphans`
+  surfaces assets that produced zero entities — quality-triage candidates.
+  See the 0.8.0 migration guide's
+  [graph extraction section](../migration/v0.7-to-v0.8.md#memory-inference-and-graph-extraction-moved-out-of-index).
+- **Better output.** `akm graph relations` and `akm graph entities` now show
+  per-row confidence. Search hits annotate the graph-boost contribution in
+  `whyMatched`. Related results end with a `Next: akm show '<ref>'` hint
+  pointing at the top neighbor.
+- **Ref-form output.** Related results now show canonical refs
+  (e.g. `memory:incident-2026-05-12`) instead of raw file paths.
+
+**DB_VERSION bumped to 17.** The schema change uses the existing
+DROP+rebuild upgrade path: non-graph tables (`entries`, embeddings, FTS) rebuild
+automatically the first time akm opens `index.db`; graph tables repopulate on
+the next `akm improve` cycle, which makes LLM calls. The first improve cycle
+after upgrade is slower than steady state, but the Phase 1 / Phase 2
+improvements above make it dramatically faster than equivalent re-extraction
+on 0.7.x. See the migration guide section
+[Graph extraction will re-run after upgrade](../migration/v0.7-to-v0.8.md#graph-extraction-will-re-run-after-upgrade).
+
+## Config v2 and reflect LLM mode
+
+0.8.0 introduces a new config shape (`configVersion: "0.8.0"`) that replaces
+the scattered v1 keys with a unified `profiles` + first-class feature tree.
+Named LLM connections live under `profiles.llm.<name>` and named agent
+connections under `profiles.agent.<name>`, each declared once and referenced
+by name from process entries on `profiles.improve.<name>`. The old
+`llm.features.*` boolean flags and `agent.processes` map are replaced by
+`profiles.improve.<name>.processes.*` (improve-bound work), plus top-level
+`index.metadataEnhance`, `index.stalenessDetection`, and `search.curateRerank`
+sections (non-improve features) — each entry using a unified `{mode, profile,
+timeoutMs, options}` shape. Configs without `configVersion` are auto-migrated
+at first run; a timestamped backup is written before any in-place rewrite.
+
+With the new config in place, the reflect pass inside `akm improve` can now
+run as a direct LLM call instead of spawning an opencode subprocess. For reflect, the context is statically pre-assembled, so a direct
+HTTP call captures the full quality benefit at a fraction of the cost. LLM mode
+also adds multi-turn self-refine (the prior draft is sent back as an assistant
+turn) and structured JSON output for providers that set `supportsJsonSchema:
+true`. The performance difference is significant:
+
+| Mode | Time per reflect call | 69-ref improve run |
+| --- | --- | --- |
+| agent (CLI subprocess) | ~30s | ~35 min |
+| sdk (in-process opencode) | ~10–15s | ~12–17 min |
+| llm (direct HTTP) | ~6–10s | ~8–10 min |
+
+To opt in to LLM mode for reflect:
+
+```jsonc
+// Opt in to LLM mode for reflect (3-5x faster)
+{
+  "configVersion": "0.8.0",
+  "profiles": {
+    "llm": {
+      "openai-mini": {
+        "endpoint": "https://api.openai.com/v1/chat/completions",
+        "model": "gpt-4o-mini",
+        "apiKey": "${OPENAI_API_KEY}",
+        "supportsJsonSchema": true
+      }
+    },
+    "improve": {
+      "default": {
+        "processes": {
+          "reflect": { "mode": "llm", "profile": "openai-mini" }
+        }
+      }
+    }
+  },
+  "defaults": { "llm": "openai-mini" }
+}
+```
+
+To migrate an existing config:
+
+```sh
+# Preview the transformation
+akm config migrate --dry-run  # doclint:ignore (historical — akm 0.8.0 release announcement; config-schema migration command not present in 0.9.0)
+
+# Apply (writes a timestamped backup first)
+akm config migrate  # doclint:ignore (historical — akm 0.8.0 release announcement; config-schema migration command not present in 0.9.0)
+```
+
+Full reference: [configuration reference](../reference/configuration.md).
+Full key mapping: [v0.7 to v0.8 migration guide — Config 0.8.0 migration](../migration/v0.7-to-v0.8.md#config-080-migration-unified-profiles).
+
+## Migration Guidance
+
+Breaking changes in 0.8.0:
+- Consolidated around: `akm improve`, `akm propose`, `akm proposal list`, `akm proposal show`, `akm proposal diff`, `akm proposal accept`, `akm proposal reject`, `akm proposal revert` (old flat aliases deprecated)
+- Added: task assets, renamed proposal commands
+- Added: `akm health` for runtime and improve telemetry checks
+- Added: end-of-run auto-sync for git-backed stashes (`--no-sync` to opt out)
+- Removed: `akm index --enrich` and `akm index --re-enrich`
+- Changed: plain `akm index` now owns metadata enhancement only; slow LLM maintenance moved to `akm improve`
+- Windows task path parsing now correctly handles absolute paths and drive letters
+- Cron expressions with apostrophes are now properly escaped in schtasks XML
+
+To upgrade:
+1. Update any scripts or automation that still target the pre-0.8 proposal queue and indexing workflow.
+2. Prefer `akm improve` for the main refinement/maintenance workflow.
+3. Stop calling `akm index --enrich`; use plain `akm index` plus `akm improve` maintenance flows.
+4. Use `akm health --since 24h` after upgrade to confirm state-db and task-history health.
+5. Rename proposal queue commands as per the table above.
+6. Review task definitions for Windows path compatibility if using absolute paths.
+7. Run `akm config migrate` to upgrade your config to the v2 shape and unlock LLM-mode reflect.
+
+No manual data migration is required. The proposal queue and existing stash assets remain compatible.
+
+## Try the New Surfaces
+
+```sh
+# Scope an improve run to all memory assets
+akm improve memory --task "Summarize today's debugging session"
+
+# List improvement proposals
+akm proposal list
+
+# Show one proposal
+akm proposal show <id>
+
+# Accept a proposal (after review)
+akm proposal accept <id>
+
+# Define and run a task
+akm tasks run daily-code-review  # doclint:ignore (historical — akm 0.8.0 release announcement; `tasks` renamed `task` in 0.9.0)
+
+# Run improve with a specific profile (reflect mode comes from the profile)
+akm improve memory:my-note --profile fast-llm  # doclint:ignore (historical — akm 0.8.0 release announcement; `--profile` renamed `--strategy` in 0.9.0)
+```
+
+## Verification
+
+After upgrading:
+```sh
+akm info --format text     # version 0.8.x
+akm health --since 24h     # runtime + improve telemetry checks
+akm proposal list         # queue starts empty — that's expected
+akm task list              # shows your defined tasks — doclint:ignore (historical — akm 0.8.0 release announcement; `tasks list` inspection moved to `akm search`/`akm show` by 0.9.0)
+akm config get configVersion  # "0.8.0" after akm config migrate
+```
+
+Full details in the [v0.7 to v0.8 migration guide](../migration/v0.7-to-v0.8.md) and the [configuration reference](../reference/configuration.md).
+
+Full changelog at [CHANGELOG.md](https://github.com/itlackey/akm/blob/main/CHANGELOG.md).

package/docs/posts/scattered-skills-05.md

@@ -0,0 +1,100 @@
+---
+title: 'Stop Copying Skills Between Claude Code, Cursor, and Codex'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-skills
+description: Your agent skills are scattered across three tools. Here's why indexing in place beats copying or syncing.
+tags:
+  - ai
+  - agents
+  - cli
+  - skills
+published: true
+id: 3426225
+date: '2026-03-29T16:31:49Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+This is part five in a series about wrangling the growing pile of skills, scripts, and context that AI coding agents depend on. In [part one](https://dev.to/itlackey/your-ai-agents-skill-list-is-getting-out-of-hand-32ck), I covered why progressive disclosure beats dumping everything into context. [Part two](https://dev.to/itlackey/you-already-have-dozens-of-agent-skills-you-just-cant-find-them-bpo) showed how `akm` unifies your local assets across platforms into one searchable stash. [Part three](https://dev.to/itlackey/your-agents-memory-shouldnt-disappear-when-the-session-ends) added remote context via OpenViking for teams. And [part four](https://dev.to/itlackey/your-agent-doesnt-know-what-the-community-already-figured-out) plugged in community knowledge through Context Hub.
+
+All of that assumed you were picking one tool. But you're probably not. You've got Claude Code at work, Codex for side projects, Cursor for quick edits. Each one has its own skills directory — `~/.claude/skills/`, `~/.codex/skills/`, `.cursor/rules/` — and none of them can see each other.
+
+So you rebuild the same deploy skill twice. You forget where the good version of your testing scaffold lives. You copy files between directories and they drift within a week. You end up grepping across three different paths trying to find the one that handled database migrations correctly.
+
+This isn't a tooling problem. It's a discovery problem. And in the past week alone, three separate products launched to fix it — a macOS GUI for browsing skill files, a web-based editor for organizing them, a designer's viral Medium post about layered architecture for skills. People are clearly hurting here.
+
+But every one of those solutions wants you to *move* your files somewhere. Copy them into a central location. Sync them between directories. Maintain one source of truth that you manually keep updated.
+
+There's a better approach: don't move anything. Just make everything searchable.
+
+## Copy and Sync (The Obvious Way)
+
+Pick a canonical directory, copy everything into it, keep it updated. Tools like ClaudeMDEditor make this easier with a GUI, and symlinks can automate some of it.
+
+Works great — until it doesn't. You update the original and forget to sync. The copy drifts. You end up with two versions of the same skill, slightly different, and no way to tell which is current. The maintenance overhead scales linearly with every new skill and every new platform.
+
+## GUI Discovery (The Pretty Way)
+
+Tools like Chops give you a nice interface for browsing your skill files. You can see what's where, organize them visually, tag them.
+
+But your agent can't use a GUI. When Claude Code is mid-task and needs a deployment skill, it can't open an Electron app and browse around. It needs something it can *call* — a programmatic interface that returns results without human intervention.
+
+## Index in Place (The akm Way)
+
+This is the approach [akm](https://github.com/itlackey/akm) takes. Don't move your files. Don't copy them. Don't sync them. Just point at them and build an index.
+
+Your skills stay exactly where each tool expects them. Claude Code still finds its skills in `~/.claude/skills/`. Cursor still reads `.cursor/rules/`. Nothing breaks. But now there's a single search layer across all of them.
+
+When your agent needs something, it searches once and gets results from every source. When you update a skill in its original location, the index picks up the change. No sync step. No drift.
+
+## Five Commands and You're Done
+
+Here's the full setup. Takes about 30 seconds.
+
+```sh
+# Install
+curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
+
+# Initialize
+akm setup
+
+# Point at your existing skill directories
+akm add ~/.claude/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add ~/.codex/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add .cursor/rules  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Search across all of them
+akm search "deploy"
+```
+
+That last command returns results from every source, ranked by relevance. Each result shows the asset type, name, source, and a snippet. Your agent — or you — can load the full content:
+
+```sh
+akm show skill:deploy-to-production
+```
+
+Only the skill you need gets loaded into context. Everything else stays out.
+
+## Tell Your Agent About It
+
+Here's the part that ties it all together. Drop this into your `AGENTS.md`, `CLAUDE.md`, or system prompt:
+
+```markdown
+## Resources & Capabilities
+
+Search for skills, commands, and knowledge using `akm search <query>`.
+View full details with `akm show <ref>`.
+```
+
+That's the entire integration. No plugins, no SDKs, no integration code. Any model that can run shell commands can use `akm`. Claude Code, Codex, Cursor — if it has a terminal, it works.
+
+The agent runs `akm search` to find what it needs, `akm show` to load the content, and gets to work. Everything else stays out of context. Progressive disclosure — the agent discovers what exists, then activates only what it needs. If that pattern sounds familiar, I covered the architecture behind it in [part one](https://dev.to/itlackey/your-ai-agents-skill-list-is-getting-out-of-hand-32ck).
+
+## What's Next
+
+This post covered the individual developer workflow — one person, multiple tools, skills everywhere. But what happens when a team of five developers each has their own skills across three platforms? That's where things get interesting, and where akm's source model, Git integration, and private registry support come into play.
+
+For now: install akm, point it at your directories, and run `akm search`. You'll be surprised how many skills you already have.
+
+Give it a look at [github.com/itlackey/akm](https://github.com/itlackey/akm). If you've got agent assets scattered across platforms, give it a shot and let me know what breaks.

package/docs/posts/task-assets-persistent-workflows-11.md

@@ -0,0 +1,222 @@
+---
+title: 'Task Assets: Agent Workflows That Run While You Sleep'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: 'Task assets in akm 0.8.0 are the first-class way to define persistent, scheduled agent workflows. This post covers the YAML schema, scheduling, manual invocation, environment injection, and logging — with the Discord health report as a worked example.'
+tags:
+  - ai
+  - agents
+  - cli
+  - automation
+published: true
+id: 3814542
+date: '2026-06-04T00:32:02Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+This is part eleven in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. [Part nine](https://dev.to/itlackey/agents-that-remember-where-they-were-1koe) covered workflow assets and resumable procedures. [Part ten](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d) introduced the improve pipeline that continuously curates your stash. Earlier parts addressed teams, distributed stashes, and community knowledge.
+
+Most automation with AI agents is reactive. You open a session, give the agent a task, wait for the result, close the session. The agent's clock runs when you run it.
+
+Task assets flip that model. A task is a YAML file in your stash that defines a workflow — what to run, when to run it, what environment it needs, and how long it's allowed to take. Once registered, the task runs on schedule without your involvement. The OS scheduler calls `akm tasks run <id>`, which executes the task and writes the result to `state.db`. You find out what happened when you check `akm health` or look at the log.
+
+This is the piece of akm 0.8.0 that makes continuous operation possible. The improve loop runs twice an hour because a task asset says it does. The hourly Discord health report fires because a task asset says it does. Neither requires an open terminal.
+
+## The Task Asset Format
+
+Task assets live at `<stash>/tasks/<id>.yml`. The filename is the task ID. A minimal task looks like this:
+
+```yaml
+schedule: 0 * * * *
+command: akm improve --auto-accept 90  # doclint:ignore (historical — akm 0.8.0-era task assets post; `--auto-accept` removed in 0.9.0)
+enabled: true
+```
+
+That's enough to install a cron entry and run `akm improve` at the top of every hour. The full schema adds metadata and per-task timeout control:
+
+```yaml
+schedule: "7,37 * * * *"
+command: akm improve --auto-accept 90 --timeout-ms 1620000  # doclint:ignore (historical — akm 0.8.0-era task assets post; `--auto-accept` removed in 0.9.0)
+enabled: true
+timeoutMs: 1800000
+name: akm-improve
+description: Run the improve pass at :07 and :37 — reflect, distill, consolidate, lint, and eval.
+when_to_use: Twice per hour; leaves ~23 minutes of idle headroom between completions.
+tags:
+  - improve
+  - maintenance
+```
+
+The fields that matter most:
+
+| Field | Required | Purpose |
+|---|---|---|
+| `schedule` | yes | Standard cron expression. Maps to crontab on Linux, launchd plist on macOS, schtasks XML on Windows. Wrap expressions containing special characters in quotes. |
+| `command` or `prompt` | one of the two | `command` runs as a plain shell command. `prompt` dispatches through the configured agent profile. A third option, `workflow`, targets a stash workflow ref directly. |
+| `enabled` | yes | `false` keeps the task definition in your stash without installing a scheduler entry. |
+| `timeoutMs` | no | Per-task timeout in milliseconds, overriding whatever the agent profile sets globally. `null` removes the kill timer entirely — useful for long-running local-model tasks. |
+| `name`, `description`, `when_to_use`, `tags` | no | Metadata. `name` appears in `akm show` and search results; the others exist for your own records and for search. |
+
+## command: vs prompt:
+
+The distinction between `command` and `prompt` reflects two different execution models.
+
+A `command` task is a shell invocation. `akm tasks run` executes the string directly in a child process. There is no agent involved. The command can call `akm`, run a shell script, invoke any binary. The exit code is what gets logged.
+
+```yaml
+command: akm improve --auto-accept 90  # doclint:ignore (historical — akm 0.8.0-era task assets post; `--auto-accept` removed in 0.9.0)
+```
+
+A `prompt` task dispatches to the agent configured in your default agent profile (or the profile specified in `--profile`). The value of `prompt` becomes the task instruction. The agent runs autonomously, can use `akm` commands, write files, and call tools according to its allowed tool set. The result is determined by whether the agent exits cleanly.
+
+```yaml
+prompt: |
+  Run akm wiki ingest research and then run akm wiki lint research.
+  Fix any orphan pages the lint step reports.
+```
+
+The practical split: use `command` for tasks where the execution is fully scripted and the outcome is deterministic. Use `prompt` when you want the agent to exercise judgment — synthesizing content, triaging output, making decisions based on what it finds. The curate-to-wiki task is a good example of the latter: it runs a multi-step workflow where the agent reads each step's instructions, substitutes parameters, and advances the workflow run through to completion. Workflow assets themselves are covered in [part nine](https://dev.to/itlackey/agents-that-remember-where-they-were-1koe) of this series.
+
+## Registering Tasks
+
+There are two ways to get a task into the scheduler.
+
+The first way is `akm tasks add`, which creates the YAML file and installs it in one step:
+
+```sh
+akm tasks add my-task \
+  --schedule "0 9 * * *" \
+  --command "akm improve --auto-accept 80" \
+  --name "Morning improve pass" \
+  --description "Daily improve at 9 AM"
+```
+
+The second way is to write the YAML file directly into your stash's `tasks/` directory and then call:
+
+```sh
+akm tasks sync  # doclint:ignore (`tasks` was renamed to singular `task` in 0.9.0)
+```
+
+`sync` reconciles all `.yml` files in `tasks/` against the OS scheduler. Any task that's `enabled: true` and not yet installed gets a scheduler entry. Any task that's `enabled: false` or missing gets its entry removed. This is the right command to run after pulling stash changes that include new or updated task files.
+
+Other task management commands:
+
+```sh
+akm search --type task                # all defined tasks (any bundle)
+akm show tasks/<id>                    # parsed YAML + scheduler state
+akm tasks run <id>                    # execute immediately  # doclint:ignore (`tasks` renamed `task` in 0.9.0)
+akm tasks enable <id>                 # install the scheduler entry  # doclint:ignore (`tasks enable` removed in 0.9.0; use a file edit + `task sync`)
+akm tasks disable <id>                # remove the scheduler entry, keep the file  # doclint:ignore (`tasks disable` removed in 0.9.0; use a file edit + `task sync`)
+akm tasks history [--id <id>]         # recent runs from state.db  # doclint:ignore (`tasks` renamed `task` in 0.9.0)
+akm tasks doctor                      # scheduler backend + cron path  # doclint:ignore (`tasks` renamed `task` in 0.9.0)
+```
+
+To unschedule a task entirely, delete its `.yml` from the bundle and run `akm
+tasks sync` (which uninstalls scheduler entries that no longer have a backing
+file). `enable`, `disable`, `run`, and `sync` also accept `--target <bundle>`
+to act on a task that lives in a non-default bundle.
+
+`akm tasks run` is the same command the scheduler calls. You can run a task immediately to test it before committing it to a schedule.
+
+## Environment Injection with akm env run
+
+Tasks that need secrets or environment-specific configuration use `akm env`. An env asset is an encrypted `.env` file stored in your stash under `env/<name>.env`. You inject it into a child process using `akm env run`:
+
+```sh
+akm env run env:fwdslsh -- bash ./scripts/post-to-discord.sh
+```
+
+The `env:` prefix is the canonical ref form. In task YAML, akm also resolves bare env names — the worked example below uses the bare name to match the production file exactly.
+
+In a task `command` field, the same pattern applies directly:
+
+```yaml
+command: akm env run fwdslsh -- bash /home/founder3/akm/scripts/akm-health-discord.sh
+```
+
+This injects every variable in the `fwdslsh` environment group into the shell process that runs the script. The variables live only in that child process — they are never written to disk or exported to the parent environment. The task definition itself contains no secrets, only the environment group reference. You can commit task YAML to your stash and share it without exposing credentials.
+
+If a task needs only a subset of the environment group variables, `--only` narrows the injection:
+
+```sh
+akm env run env:fwdslsh --only DISCORD_WEBHOOK_URL -- bash ./post.sh
+```
+
+`--only` accepts a single key or a comma-separated list. Use `--except` to inject everything in the environment group except specific keys.
+
+## Worked Example: The Discord Health Report
+
+This is the health report task used in production to monitor the improve pipeline:
+
+```yaml
+# ~/akm/tasks/akm-health-report.yml
+schedule: 0 * * * *
+command: akm env run fwdslsh -- bash /home/founder3/akm/scripts/akm-health-discord.sh
+enabled: true
+name: AKM Health Report → Discord
+description: "Hourly: post a 4h rolling health report to Discord. Driven by
+  akm health --since=4h — same data source as manual reports."
+tags:
+  - health
+  - discord
+  - monitoring
+```
+
+The task fires at the top of every hour. It injects the `fwdslsh` environment group (which contains the Discord webhook URL and any other credentials the script needs), then runs the health report script. The script calls `akm health --since=4h` and `akm health --since=8h`, computes deltas between the two windows for trend context, and posts a formatted embed to Discord.
+
+The embed has three inline fields — Output (promoted refs, merged memories, memory inference yield), Failures (chunk failures, skip reason anomalies), and Latency (median, P95, prior-window comparison) — plus a Needs Attention section that only appears when something is actually off. The footer includes the hostname and run timestamp so reports from multiple machines are distinguishable at a glance.
+
+To register the task after writing the YAML:
+
+```sh
+akm tasks sync  # doclint:ignore (`tasks` was renamed to singular `task` in 0.9.0)
+# → installed: akm-health-report
+```
+
+Run it once immediately to confirm the script works before relying on the scheduled version:
+
+```sh
+akm tasks run akm-health-report  # doclint:ignore (`tasks` was renamed to singular `task` in 0.9.0)
+```
+
+Check the result:
+
+```sh
+akm tasks history --id akm-health-report --limit 5  # doclint:ignore (`tasks` was renamed to singular `task` in 0.9.0)
+```
+
+## Logging
+
+Every task run is recorded in `state.db` under the `task_history` table. `akm tasks history` surfaces that data. For log output, each run writes to:
+
+```
+~/.cache/akm/tasks/logs/<id>.log
+```
+
+`akm health` inspects `task_history` for missing log files, stale active runs (tasks that started but never completed), and recent failure rates. A task run that never wrote a `tasks_completed` event shows up in `akm health` output as a stuck active run — a reliable signal that something went wrong even if the log file doesn't say much.
+
+```sh
+akm health --since 4h
+```
+
+The health check correlates the `task_history` events with the log files on disk. If a log file is missing for a completed run, `logBackingRate` drops below 1.0, which flags as a warning. This is the `task-log-backing` hard check — one of the deterministic checks that `akm health` runs before it looks at any metrics.
+
+## Building a Task-Driven Operation
+
+The pattern that emerges from several tasks working together is an operation that runs itself. The improve loop consolidates and curates the stash twice an hour — what that pipeline does internally is covered in [part ten](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d). The health report surfaces the results every hour. A daily curation task pulls new articles from configured sources and ingests them into the research wiki. None of these require an open terminal.
+
+Adding a new automated behavior follows the same steps regardless of what the task does:
+
+1. Write the YAML to `<stash>/tasks/<id>.yml`.
+2. Run `akm tasks sync` to install the scheduler entry.
+3. Run `akm tasks run <id>` to test it immediately.
+4. Confirm the output with `akm tasks history` and check the log.
+5. Add the task file to git if you want it version-controlled with your stash.
+
+The task YAML is the contract between what you want to happen and when it happens. The log and `state.db` are the record of what actually did.
+
+---
+
+Task assets are available in akm 0.8.0. The full command reference is in [Tasks](../reference/tasks.md). The environment vault documentation is in [Environment & Secrets](../reference/env-and-secrets.md). If you're upgrading from 0.7.x, task `.md` files from the old format are not auto-discovered — check the migration guide for the conversion path.