akm-cli 0.7.5 → 0.8.0-rc.11

package/dist/workflows/runs.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import { parseAssetRef } from "../core/asset-ref";
@@ -13,64 +16,72 @@ import { formatWorkflowErrors } from "./authoring";
 import { closeWorkflowDatabase, openWorkflowDatabase } from "./db";
 import { parseWorkflow } from "./parser";
 import { getCurrentWorkflowScopeKey } from "./scope-key";
-export async function startWorkflowRun(ref, params = {}) {
-    const asset = await loadWorkflowAsset(ref);
-    const workflowDb = openWorkflowDatabase();
+async function withWorkflowDb(fn) {
+    const db = openWorkflowDatabase();
     try {
+        return await Promise.resolve(fn(db));
+    }
+    finally {
+        closeWorkflowDatabase(db);
+    }
+}
+export async function startWorkflowRun(ref, params = {}, options) {
+    const asset = await loadWorkflowAsset(ref);
+    return withWorkflowDb(async (db) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
         const scopeKey = getCurrentWorkflowScopeKey();
         const currentStepId = asset.steps[0]?.id ?? null;
         const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref);
-        workflowDb.transaction(() => {
-            workflowDb
-                .prepare(`INSERT INTO workflow_runs (
+        // Concurrency guard (#485): if an active run already exists in this
+        // (workflow_ref, scope_key) pair, refuse to create a parallel run unless
+        // `force: true` is set. Previously every call inserted unconditionally,
+        // so two terminals running `akm workflow start <ref>` left two runs
+        // racing; `akm workflow next` then non-deterministically picked one.
+        if (!options?.force) {
+            const existing = db
+                .prepare("SELECT id, current_step_id FROM workflow_runs WHERE workflow_ref = ? AND scope_key = ? AND status = 'active' ORDER BY updated_at DESC LIMIT 1")
+                .get(asset.ref, scopeKey);
+            if (existing) {
+                throw new UsageError(`Workflow ${asset.ref} already has an active run in this scope (id=${existing.id}, step=${existing.current_step_id ?? "—"}). ` +
+                    `Use 'akm workflow next ${asset.ref}' to resume it, 'akm workflow abandon ${existing.id}' to give up on it, or pass --force to start a parallel run.`, "RESOURCE_ALREADY_EXISTS");
+            }
+        }
+        db.transaction(() => {
+            db.prepare(`INSERT INTO workflow_runs (
           id, workflow_ref, scope_key, workflow_entry_id, workflow_title, status, params_json, current_step_id, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`)
-                .run(runId, asset.ref, scopeKey, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
-            const insertStep = workflowDb.prepare(`INSERT INTO workflow_run_steps (
+        ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?)`).run(runId, asset.ref, scopeKey, workflowEntryId, asset.title, JSON.stringify(params), currentStepId, now, now);
+            const insertStep = db.prepare(`INSERT INTO workflow_run_steps (
           run_id, step_id, step_title, instructions, completion_json, sequence_index, status
         ) VALUES (?, ?, ?, ?, ?, ?, 'pending')`);
             for (const step of asset.steps) {
                 insertStep.run(runId, step.id, step.title, step.instructions, step.completionCriteria ? JSON.stringify(step.completionCriteria) : null, step.sequenceIndex ?? 0);
             }
         })();
-        const result = getWorkflowStatus(runId);
+        const result = await getWorkflowStatus(runId);
         appendEvent({
             eventType: "workflow_started",
             ref: ref,
             metadata: { runId: result.run.id, title: result.run.workflowTitle },
         });
         return result;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function getWorkflowStatus(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const run = readWorkflowRun(workflowDb, runId);
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+export async function getWorkflowStatus(runId) {
+    return withWorkflowDb((db) => {
+        const run = readWorkflowRun(db, runId);
+        const steps = readWorkflowRunSteps(db, run.id);
         return buildWorkflowRunDetail(run, steps);
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function hasWorkflowRun(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const row = workflowDb.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
+export async function hasWorkflowRun(runId) {
+    return withWorkflowDb((db) => {
+        const row = db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
         return !!row;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function listWorkflowRuns(input) {
-    const workflowDb = openWorkflowDatabase();
-    try {
+export async function listWorkflowRuns(input) {
+    return withWorkflowDb((db) => {
         const filters = [];
         const params = [];
         const scopeKey = getCurrentWorkflowScopeKey();
@@ -88,20 +99,16 @@ export function listWorkflowRuns(input) {
             filters.push("status IN ('active', 'blocked')");
         }
         const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
-        const rows = workflowDb
+        const rows = db
             .prepare(`SELECT * FROM workflow_runs ${where} ORDER BY updated_at DESC, created_at DESC`)
             .all(...params);
         return { runs: rows.map(toWorkflowRunSummary) };
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
 export async function getNextWorkflowStep(specifier, params) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const { run, autoStarted } = await resolveRunSpecifier(workflowDb, specifier, params);
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+    return withWorkflowDb(async (db) => {
+        const { run, autoStarted } = await resolveRunSpecifier(db, specifier, params);
+        const steps = readWorkflowRunSteps(db, run.id);
         const currentStep = resolveCurrentStep(run, steps);
         const done = run.status === "completed" ? true : undefined;
         return {
@@ -115,54 +122,44 @@ export async function getNextWorkflowStep(specifier, params) {
             ...(done ? { done } : {}),
             ...(autoStarted ? { autoStarted } : {}),
         };
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function resumeWorkflowRun(runId) {
-    const workflowDb = openWorkflowDatabase();
-    try {
-        const run = readWorkflowRun(workflowDb, runId);
+export async function resumeWorkflowRun(runId) {
+    return withWorkflowDb((db) => {
+        const run = readWorkflowRun(db, runId);
         if (run.status === "completed") {
             throw new UsageError(`Workflow run ${run.id} is already completed and cannot be resumed.`);
         }
         if (run.status === "active") {
-            const steps = readWorkflowRunSteps(workflowDb, run.id);
+            const steps = readWorkflowRunSteps(db, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
         // blocked or failed → flip back to active and re-open the current step so
         // it can be reclassified (completed, failed, skipped) after resuming.
         const now = new Date().toISOString();
-        workflowDb.transaction(() => {
+        db.transaction(() => {
             if (run.current_step_id) {
-                workflowDb
-                    .prepare(`UPDATE workflow_run_steps
+                db.prepare(`UPDATE workflow_run_steps
              SET status = 'pending', notes = NULL, evidence_json = NULL, completed_at = NULL
-             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`)
-                    .run(run.id, run.current_step_id);
+             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`).run(run.id, run.current_step_id);
             }
-            workflowDb.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
+            db.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
         })();
         const updated = { ...run, status: "active", updated_at: now };
-        const steps = readWorkflowRunSteps(workflowDb, run.id);
+        const steps = readWorkflowRunSteps(db, run.id);
         return buildWorkflowRunDetail(updated, steps);
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
-export function completeWorkflowStep(input) {
-    const workflowDb = openWorkflowDatabase();
-    try {
+export async function completeWorkflowStep(input) {
+    return withWorkflowDb((db) => {
         let updatedRun;
         let refreshedSteps = [];
-        workflowDb.transaction(() => {
-            const run = readWorkflowRun(workflowDb, input.runId);
+        db.transaction(() => {
+            const run = readWorkflowRun(db, input.runId);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
-            const existing = workflowDb
+            const existing = db
                 .prepare("SELECT * FROM workflow_run_steps WHERE run_id = ? AND step_id = ?")
                 .get(run.id, input.stepId);
             if (!existing) {
@@ -175,18 +172,14 @@ export function completeWorkflowStep(input) {
                 throw new UsageError(`Step "${input.stepId}" is not the current step for workflow run ${run.id}. Complete "${run.current_step_id}" first.`);
             }
             const completedAt = new Date().toISOString();
-            workflowDb
-                .prepare(`UPDATE workflow_run_steps
+            db.prepare(`UPDATE workflow_run_steps
            SET status = ?, notes = ?, evidence_json = ?, completed_at = ?
-           WHERE run_id = ? AND step_id = ?`)
-                .run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
-            refreshedSteps = readWorkflowRunSteps(workflowDb, run.id);
+           WHERE run_id = ? AND step_id = ?`).run(input.status, input.notes?.trim() || null, input.evidence ? JSON.stringify(input.evidence) : null, completedAt, run.id, input.stepId);
+            refreshedSteps = readWorkflowRunSteps(db, run.id);
             const state = deriveRunState(refreshedSteps);
-            workflowDb
-                .prepare(`UPDATE workflow_runs
+            db.prepare(`UPDATE workflow_runs
            SET status = ?, current_step_id = ?, updated_at = ?, completed_at = ?
-           WHERE id = ?`)
-                .run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
+           WHERE id = ?`).run(state.status, state.currentStepId, completedAt, state.completedAt, run.id);
             updatedRun = {
                 ...run,
                 status: state.status,
@@ -205,10 +198,7 @@ export function completeWorkflowStep(input) {
             appendEvent({ eventType: "workflow_finished", ref: detail.run.workflowRef, metadata: { runId: input.runId } });
         }
         return detail;
-    }
-    finally {
-        closeWorkflowDatabase(workflowDb);
-    }
+    });
 }
 async function resolveRunSpecifier(db, specifier, params) {
     const explicitRun = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(specifier);
@@ -262,7 +252,7 @@ async function loadWorkflowAsset(ref) {
     if (!assetPath) {
         throw new NotFoundError(`Workflow not found for ref: workflow:${parsed.name}`);
     }
-    const resolvedSourcePath = sourcePath ?? loadConfig().stashDir ?? assetPath;
+    const resolvedSourcePath = sourcePath ?? config.stashDir ?? assetPath;
     const fullRef = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
     const cached = readWorkflowDocumentFromIndex(resolvedSourcePath, fullRef);
     const document = cached ?? loadWorkflowDocumentFromDisk(assetPath);
@@ -452,18 +442,13 @@ function parseJsonArray(value) {
     }
     return undefined;
 }
-export function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
-    try {
-        const workflowDb = openWorkflowDatabase();
-        const row = workflowDb
+export async function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
+    return withWorkflowDb((db) => {
+        const row = db
             .query("SELECT id, current_step_id, workflow_ref FROM workflow_runs WHERE scope_key = ? AND status IN ('active', 'blocked') ORDER BY updated_at DESC LIMIT 1")
             .get(scopeKey);
-        closeWorkflowDatabase(workflowDb);
         if (!row)
             return null;
         return { runId: row.id, stepId: row.current_step_id, workflowRef: row.workflow_ref };
-    }
-    catch {
-        return null; // fail-open: never crash show output due to DB error
-    }
+    }).catch(() => null); // fail-open: never crash show output due to DB error
 }

package/dist/workflows/schema.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Validated JSON shape for a workflow asset.
  *

package/dist/workflows/scope-key.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";

package/dist/workflows/validator.js

@@ -1,12 +1,8 @@
-/**
- * Cross-cutting semantic checks over an assembled WorkflowDocument draft.
- *
- * The parser handles per-line shape checks; this module runs rules that need
- * the whole document or the raw frontmatter at once: duplicate step IDs,
- * step-id format, and the frontmatter key whitelist.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params"]);
+const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
     checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
     checkStepIdFormat(draft, errors);

package/dist/workflows/workflow-template.md

@@ -0,0 +1,24 @@
+---
+description: Describe what this workflow accomplishes
+tags:
+  - example
+params:
+  example_param: Explain this parameter
+---
+
+# Workflow: {{TITLE}}
+
+## Step: {{FIRST_STEP_TITLE}}
+Step ID: {{FIRST_STEP_ID}}
+
+### Instructions
+Describe what to do in this step.
+
+### Completion Criteria
+- Confirm the first step is complete
+
+## Step: Second Step
+Step ID: second-step
+
+### Instructions
+Describe what happens next.

package/docs/README.md

@@ -10,8 +10,9 @@
 
 ## Upgrading
 
+- [Roadmap](roadmap.md) -- High-level focus for the 0.9 and 1.0 releases
 - [v1 migration guide](migration/v1.md) -- The path from 0.x to v1.0, including the `.stash.json` removal scheduled for v0.8.0
-- [Release notes (latest: 0.7.0)](migration/release-notes/0.7.0.md) -- Per-release notes drop into `migration/release-notes/`, including current pre-release removals
+- [Release notes (latest: 0.8.0)](migration/release-notes/0.8.0.md) -- Per-release notes drop into `migration/release-notes/`, including current pre-release removals
 - [v0.5 → v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
 
 ## Reference
@@ -28,17 +29,24 @@
 - [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for tools like OpenCode
 - [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark and evaluation repo for akm
 
+## Operations
+
+- Analyzing `akm improve` runs -- use [`akm health`](../src/commands/health.ts) (0.8.0+): `--since`, `--detail per-run`, `--window-compare`, `--windows`. See [health-command-enhancements.md](technical/health-command-enhancements.md).
+
 ## Internals
 
 - [Search](technical/search.md) -- Hybrid search architecture and scoring
 - [Indexing](technical/indexing.md) -- How the search index is built
 - [Classification](technical/classification.md) -- Matcher and renderer behavior
+- [Functional Contract Patterns](technical/functional-contract-patterns.md) -- Quick reference for contributor pipelines and small process contracts
+- [Implementation Plan: Functional Contract Refactor](technical/implementation-plan-functional-contract-refactor.md) -- Phased plan to move behavior from type-centric switchboards to process-local contributors
+- [Architecture Cleanup Checklist](technical/architecture-cleanup-checklist.md) -- Living checklist for executing the cleanup plan with parity gates, reviews, and git hygiene
 - [Show Response](technical/show-response.md) -- `akm show` output fields by asset type
 - [Testing Workflow](technical/testing-workflow.md) -- End-to-end, Docker, deployment, and upgrade validation
 - [Ref Format](technical/ref.md) -- Wire format for asset references
 - [Test Coverage Guide](technical/test-coverage-guide.md) -- High-value testing areas
 - [Core Principles](technical/akm-core-principles.md) -- Design principles and constraints
-- [akm-bench](technical/benchmark.md) -- Search-quality benchmark suite
+- `technical/benchmark.md` (planned) -- Search-quality benchmark suite
 
 ## Posts
 

package/docs/data-and-telemetry.md

@@ -0,0 +1,225 @@
+# AKM Data & Telemetry
+
+AKM stores data locally on your machine. **It has no remote telemetry.** No data is sent to Anthropic, the AKM project, or any third party. This document describes exactly what AKM reads and writes on your machine.
+
+## No Remote Data Collection
+
+AKM does not:
+- Send usage data, events, or crash reports to any server
+- Contact any AKM-operated endpoint at runtime (only your own configured LLM/embedding endpoints)
+- Include any analytics SDK or beacon
+- Collect email, name, or any personally-identifying information
+
+The only network requests AKM makes are:
+1. Fetching registry metadata and stash packages from sources you explicitly configure (GitHub, npm, websites)
+2. Calls to your configured LLM/embedding endpoint (if you enabled those features)
+3. `akm upgrade` — fetches the latest release from GitHub releases
+4. `akm setup` — a single DNS lookup for `github.com` to decide whether to skip network-dependent steps (Ollama detection, remote embedding probes) when offline. No HTTP request is made by this probe; if it succeeds, akm proceeds with the network-dependent steps you already configured.
+
+---
+
+## Local On-Disk Surface
+
+AKM writes to these locations on your machine. All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions on Linux/macOS and Windows conventions on Windows.
+
+### Config Directory (`$XDG_CONFIG_HOME/akm` or `~/.config/akm/`)
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `config.json` | Your AKM configuration: LLM endpoints, stash paths, feature flags, profiles | **No** — deleting resets all settings |
+
+Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
+
+### Data Directory (`$XDG_DATA_HOME/akm` or `~/.local/share/akm/`)
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `index.db` | Search index for all your stash assets (FTS5 + metadata) | Yes — rebuilds via `akm index --full` |
+| `workflow.db` | Workflow run state and history | Caution — deletes run history |
+| `state.db` | Events, proposals, task history, improve run results | **No** — deletes event log, proposal queue, improve history |
+| `akm.lock` | Inter-process write lock | Yes — recreated automatically |
+| `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
+
+Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.
+
+### Cache Directory (`$XDG_CACHE_HOME/akm` or `~/.cache/akm/`)
+
+Everything in the cache is regenerable. It is safe to delete the entire cache directory; AKM will recreate what it needs on next use.
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `config-backups/config-<timestamp>.json` | Pre-migration config snapshots (5 retained) | Yes |
+| `config-backups/config.latest.json` | Latest backup alias | Yes |
+| `registry/` | Downloaded registry tarballs (stash packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm add` or `akm update` |
+| `registry-index/` | Legacy per-URL JSON cache (v0.7 artifact) | Yes — fully replaced by `index.db` in 0.8.0 |
+| `semantic-status.json` | Semantic index build status marker | Yes |
+| `bin/` | Downloaded AKM binary cache (used by `akm upgrade`) | Yes |
+| `tasks/logs/` | Scheduled task log files | Yes — ephemeral logs |
+| `tasks/history/` | Legacy task history JSONL (v0.7 migration artifact) | Yes |
+
+Override: set `AKM_CACHE_DIR` or `XDG_CACHE_HOME`.
+
+### Stash Directory (`~/akm/` by default, or user-configured)
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `<stash>/` | All your asset files: agents, skills, commands, knowledge, workflows, memories, vaults, wikis, lessons | **No** — this is YOUR data |
+| `<stash>/.akm/` | Hidden AKM metadata (v0.7 proposals, legacy runs) | Caution — check for pending proposals first |
+
+Override: set `AKM_STASH_DIR` (or configure `stashDir` in `config.json`).
+
+---
+
+## What Is Stored in `state.db`
+
+`state.db` holds three categories of non-regenerable data:
+
+### 1. Events Table
+
+An append-only log of every mutating action you perform with AKM. Events are stored locally for self-improvement (the improve loop uses them to surface usage patterns) and for inspection via `akm events`.
+
+**What is recorded:**
+- `event_type` — what action was taken (see full list below)
+- `ts` — ISO-8601 UTC timestamp
+- `ref` — the asset ref affected (e.g. `skill:code-review`), if applicable
+- `metadata` — structured payload specific to the event type (e.g. query text for `search`, score for `feedback`)
+
+**What is NOT recorded:**
+- File contents
+- LLM prompts or responses
+- API keys or secrets (config is not stored in events)
+- Personal information
+
+**Retention:** Events older than 90 days are purged automatically when `akm improve` runs its maintenance pass. Purge is controlled by `purgeOldEvents()` with a 90-day default.
+
+**Full event type list:**
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `add` | `akm add <source>` | `ref`, `provider` |
+| `remove` | `akm remove <source>` | `ref` |
+| `update` | `akm update [source]` | `ref` |
+| `remember` | `akm remember <text>` | `ref` |
+| `import` | `akm import <file>` | `ref` |
+| `save` | `akm save <ref>` | `ref` |
+| `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
+| `search` | `akm search <query>` | `query`, `source`, `signal` |
+| `curate` | `akm curate <prompt>` | `query`, `source` |
+| `show` | `akm show <ref>` | `ref`, `type`, `name` |
+| `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
+| `promoted` | `akm proposal accept <id>` | `ref` |
+| `rejected` | `akm proposal reject <id>` | `ref` |
+| `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, profile |
+| `reflect_completed` | Reflect phase produced a proposal | `ref` |
+| `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
+| `propose_invoked` | `akm propose` | `ref` |
+| `distill_invoked` | `akm distill` | |
+| `improve_skipped` | Asset skipped by cooldown or budget | `ref`, `reason` |
+| `improve_completed` | `akm improve` run finished | run stats |
+| `improve_failed` | `akm improve` run errored | error |
+| `improve_lock_recovered` | Stale lock cleared at startup | |
+| `proposal_orphan_purge` | Stale proposals pruned | `checked`, `rejected` |
+| `proposal_creation_rejected` | `createProposal()` validation failed | `ref`, `reason`, `source` |
+| `proposal_expired` | Proposal expired | `ref` |
+| `events_purged` | Old events deleted by maintenance | `purgedCount`, `retentionDays` |
+| `workflow_started` | `akm workflow start <ref>` | `ref`, `runId` |
+| `workflow_step_completed` | `akm workflow next` | `ref`, `runId`, `stepId` |
+| `workflow_finished` | `akm workflow complete` | `ref`, `runId` |
+| `schema_repair_invoked` | `akm lint --repair` triggered schema repair | `ref` |
+| `archive_cleanup` | Archive cleanup during consolidation | |
+
+### 2. Proposals Table
+
+The proposal queue: pending, accepted, and rejected improvement proposals for your stash assets. Generated by `akm reflect` and the improve loop.
+
+Contents:
+- Proposal UUID (primary key)
+- Target asset ref
+- Status (pending/accepted/rejected)
+- Source (which process generated it — e.g. `reflect`, `distill`)
+- Full proposal content (Markdown text)
+- Created/updated timestamps
+
+### 3. Task History Table
+
+A record of scheduled task runs (from `akm tasks`):
+- Task ID, status, start/end times
+- Log file path (the log content stays in `$CACHE/tasks/logs/`)
+
+---
+
+## How to Inspect and Clear Local Data
+
+### Inspect events
+
+```sh
+# List recent events
+akm events list
+
+# Stream live events (tail)
+akm events tail
+
+# Filter by type
+akm events list --type search --limit 20
+
+# Filter by asset ref
+akm events list --ref skill:code-review
+```
+
+### Inspect proposals
+
+```sh
+# List pending proposals
+akm proposals
+
+# Show a specific proposal
+akm proposals show <id>
+```
+
+### Clear specific data
+
+```sh
+# Delete the search index (safe — rebuilds with akm index --full)
+rm ~/.local/share/akm/index.db
+
+# Delete all cached registry downloads
+rm -rf ~/.cache/akm/registry/
+
+# Delete config backups
+rm -rf ~/.cache/akm/config-backups/
+
+# Delete the events log from state.db (non-reversible)
+# There is no akm CLI command to do this directly in 0.8.0.
+# Use SQLite directly:
+sqlite3 ~/.local/share/akm/state.db "DELETE FROM events;"
+
+# Delete all proposals
+sqlite3 ~/.local/share/akm/state.db "DELETE FROM proposals;"
+```
+
+### Start completely fresh (nuclear reset)
+
+```sh
+rm -f ~/.config/akm/config.json
+rm -rf ~/.local/share/akm/
+rm -rf ~/.cache/akm/
+# Your stash files in ~/akm/ are NOT touched by the above.
+```
+
+---
+
+## Environment Variable Overrides
+
+You can redirect any AKM directory to a custom path:
+
+| Variable | Overrides |
+|---|---|
+| `AKM_CONFIG_DIR` | Config directory (`~/.config/akm/`) |
+| `AKM_DATA_DIR` | Data directory (`~/.local/share/akm/`) |
+| `AKM_STATE_DIR` | State directory (`~/.local/state/akm/`) |
+| `AKM_CACHE_DIR` | Cache directory (`~/.cache/akm/`) |
+| `AKM_STASH_DIR` | Default stash directory (`~/akm/`) |
+| `XDG_CONFIG_HOME` | XDG base — akm appends `/akm` |
+| `XDG_DATA_HOME` | XDG base — akm appends `/akm` |
+| `XDG_STATE_HOME` | XDG base — akm appends `/akm` |
+| `XDG_CACHE_HOME` | XDG base — akm appends `/akm` |

package/docs/migration/release-notes/0.7.0.md

@@ -90,7 +90,7 @@ until the user opts in. Seven keys ship in 0.7.0:
 | `feedback_distillation` | `akm distill <ref>` |
 | `embedding_fallback_score` | scorer fallback when embeddings unavailable |
 | `memory_inference` | indexer split of pending memories into atomic facts |
-| `graph_extraction` | indexer entity/relation extraction → `graph.json` |
+| `graph_extraction` | indexer entity/relation extraction → SQLite graph tables |
 
 Every gated call site uses `tryLlmFeature(feature, config, fn, fallback)`
 from `src/llm/feature-gate.ts`. The wrapper guarantees:

package/docs/migration/release-notes/0.7.5.md

@@ -15,6 +15,6 @@ No manual migration is required for most users, but note these operator-facing d
 
 1. If you were relying on ref-based workflow runs being globally shared across repos or directories, that behavior is gone. Use direct run IDs when you intentionally need to resume a specific run created elsewhere.
 2. Existing older workflow runs created before the new workspace scope key was introduced are still accessible by direct run ID, but ref-based commands now prefer runs created in the current scope.
-3. `akm help migrate latest` now resolves to 0.7.5 and uses the published `.github/CHANGELOG.md` path.
+3. `akm help migrate latest` now resolves to 0.7.5 and uses the published `CHANGELOG.md` path.
 
-Full changelog: https://github.com/itlackey/akm/blob/main/.github/CHANGELOG.md
+Full changelog: https://github.com/itlackey/akm/blob/main/CHANGELOG.md