akm-cli 0.9.7 → 0.9.8-beta.1

package/docs/migration/v0.9.0-troubleshooting.md

@@ -24,7 +24,17 @@ before that migration and tells you to run:
 akm upgrade --force
 ```
 
-Only a successful executable upgrade admits migration 018. Immediately before
+Where akm cannot reinstall itself — a container that ships the CLI globally,
+an unprivileged runtime user — that command fails at its install step
+(`EACCES` on the global module directory) before it ever reaches the
+migration. Use the install-free route instead:
+
+```sh
+akm upgrade --state-only
+```
+
+Both admit migration 018 and both take the same verified safety copy described
+below; `--state-only` simply skips the executable replacement. Immediately before
 the migration, AKM takes a SQLite writer-exclusion lock, rechecks the exact
 ledger, and writes a consistent SQLite snapshot beside the database as
 `state.db.pre-018-drop-dead-lane-schema.<UTC-digits>.<UUID>.bak`. The randomized
@@ -41,7 +51,7 @@ general storage migrator.
 
 An existing database with no applied migration IDs is never treated as a fresh
 install, whether its `schema_migrations` table is absent or empty. Ordinary
-commands reject it without writing. The explicit `akm upgrade --force` path
+commands reject it without writing. The explicit `akm upgrade --force` (or `--state-only`) path
 takes and verifies a descriptor-bound snapshot named
 `state.db.pre-001-initial-schema.<UTC-digits>.<UUID>.bak` before it creates the
 ledger or applies any migration from 001 through 022. A truly new database is

package/docs/reference/cli.md

@@ -1022,12 +1022,14 @@ computed, with a 256 MiB binary limit. Release/checksum metadata is capped at
 akm upgrade              # Download and replace the running binary
 akm upgrade --check      # Check for updates without installing
 akm upgrade --force      # Force upgrade even if already on latest
+akm upgrade --state-only # Apply pending state.db migrations; install nothing
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--check` | Check for updates without installing |
 | `--force` | Force upgrade even if on latest version |
+| `--state-only` | Apply pending `state.db` migrations without installing a new akm. For installs that cannot rewrite their own binary — a container shipping akm globally, an unprivileged runtime user — where the install step would fail `EACCES` before the migration could run. Takes the same verified safety copy as `--force`; it changes who may request the migration, not what it does. |
 | `--skip-post-upgrade` | Skip the post-upgrade index rebuild |
 
 Checksum verification is not optional and has no flag. If a release's

package/docs/reference/workflow-schema.md

@@ -572,6 +572,30 @@ that declares an `output` schema is unaffected — an empty response is not
 valid JSON, so it fails as a parse error and can never satisfy a schema as a
 silent `null`.
 
+### When a step declares no `output:` schema
+
+A step-level `output:` schema is **optional**, and omitting it is a supported
+mode, not a deficiency. The step artifact is then exactly the value described
+above — the unit's result for a solo step, the collected array for a `map`
+step — carried untyped and never validated.
+
+The shape is stable either way: it does not depend on whether a schema is
+present, and it does not vary between a live run and a resume. `steps.<id>.output`
+resolves the same in both cases, so downstream references work with or without
+a schema.
+
+What a schema adds is **enforcement**, not shape. With one, the promoted
+artifact is checked against it and the step fails on mismatch; without one, a
+downstream reference to a field the artifact happens not to carry surfaces at
+resolution time instead (`steps.X.output is not an object — cannot resolve
+property "y"`). Declare `output:` when you want that mismatch caught at the
+producing step rather than at the consuming one.
+
+akm does not warn about a missing step `output:` schema. It briefly did, and
+the advisory was removed: it fired on essentially every step, could not be
+enforced (advisories never reach `--fail-on-flagged`), and flagged a state
+that is legitimate.
+
 ## Workflow outputs
 
 A workflow can declare a run-level export: the values a **completed run**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.7",
+  "version": "0.9.8-beta.1",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [
@@ -77,15 +77,12 @@
     "test:integration": "bash scripts/test-integration.sh",
     "test:node-smoke": "bun scripts/node-smoke.ts",
     "test:node-compat": "AKM_NODE_COMPAT_TESTS=1 bun test --timeout=120000 tests/integration/node-compat.test.ts",
-    "test:time": "bun scripts/test-timing-report.ts",
     "lint:isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:doc-examples": "bun scripts/lint-doc-examples.ts",
     "lint:active-docs-terminology": "bun scripts/lint-active-docs-terminology.ts",
-    "lint:devto-posts": "bun scripts/lint-devto-posts.ts",
-    "lint:devto-posts:fix": "bun scripts/lint-devto-posts.ts --fix",
     "publish:devto": "npx -y @sinedied/devto-cli push \"docs/posts/**/*.md\" --token \"$DEVTO_TOKEN\" --repo \"$GITHUB_REPOSITORY\" --branch \"${GITHUB_REF_NAME:-main}\" --reconcile",
     "release:check": "./tests/release-check.sh",
-    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-write-source-chokepoint.ts && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-execution-boundary.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-golden-captured-at-head.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/gen-config-schema.ts --check && bun scripts/lint-active-docs-terminology.ts",
+    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts",
     "lint:runtime-boundary": "bun scripts/lint-runtime-boundary.ts",
     "lint:tests-isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:fix": "bunx biome check --write src/ tests/ scripts/",

package/dist/workflows/source-ir/compare.js

@@ -1,17 +0,0 @@
-// 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/.
-/**
- * Locale-independent code-point ordering, shared by the workflow source-IR
- * lane (job `needs` canonicalization) and `akm lint` (name sorting).
- *
- * Split out of the deleted `source-ir/ordering.ts` (P4 §3.3, docs/plans/specs/
- * p4-deletions-closeout.md): that file's other export,
- * `canonicalTopologicalJobs`, existed only to order MULTIPLE ready jobs —
- * moot once the adapter confines a workflow source to exactly one job. This
- * comparator has an unrelated consumer (`src/commands/lint/index.ts`) and
- * survives on its own.
- */
-export function compareWorkflowSourceCodePoints(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}