akm-cli 0.8.0-rc2 → 0.8.0

package/dist/llm/memory-infer.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/.
 /**
  * LLM helper for the `akm index` memory-inference pass (#201).
  *
@@ -24,11 +27,35 @@ const MAX_BODY_CHARS = 4000;
 const SYSTEM_PROMPT = "You compress a developer memory into one high-signal derived memory for later retrieval. " +
     "Return only valid JSON. No prose outside the JSON object. No markdown fences.";
 const USER_PROMPT_PREFIX = `Compress the memory below into one derived memory. Output ONLY JSON:
-{"title":"string","description":"string","tags":["string"],"searchHints":["string"],"content":"string"}
-Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, max 3 sentences body, 3-8 tags, 3-6 searchHints.
+{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
+Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
 
 Memory:
 `;
+/**
+ * Strict JSON Schema for the derived-memory payload. Sent to providers that
+ * opt in via `LlmConnectionConfig.supportsJsonSchema = true`; the client
+ * silently drops the schema for providers that don't.
+ *
+ * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
+ * the memory-inference path. Mirrors the validation gate below
+ * (title/description/content + non-empty tags/searchHints) so a
+ * schema-compliant response is guaranteed to pass the downstream check
+ * — no more "incomplete derived memory payload from LLM; skipping memory"
+ * for shape-only failures.
+ */
+const DERIVED_MEMORY_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        content: { type: "string", minLength: 1 },
+        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
+        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
+    },
+    required: ["title", "description", "content", "tags", "searchHints"],
+    additionalProperties: false,
+};
 /**
  * Compress a single memory body into one derived memory via the configured LLM.
  *
@@ -53,6 +80,7 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
                 temperature: 0.1,
                 timeoutMs: llmConfig.timeoutMs,
                 signal,
+                responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
             });
             if (!raw)
                 return undefined;

package/dist/llm/metadata-enhance.js

@@ -1,10 +1,6 @@
-/**
- * LLM-driven metadata enhancement for stash entries.
- *
- * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
- * improve descriptions/tags/searchHints) lives separately from the low-level
- * transport client in `client.ts`.
- */
+// 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 { chatCompletion, parseJsonResponse } from "./client";
 import { tryLlmFeature } from "./feature-gate";
 const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;

package/dist/llm/prompts/extract-session.md

@@ -0,0 +1,80 @@
+You are extracting durable engineering insights from a software session transcript. Most sessions produce zero new durable insights — the agent already captures what's worth keeping via explicit `akm remember` / `akm feedback` calls during the session. Your job is to identify learnings that slipped through.
+
+## What counts as "durable insight"
+
+Things worth extracting:
+- Recovery patterns ("X fails when Y; the fix is Z")
+- Hidden constraints discovered mid-task ("this codebase requires X before deploy")
+- Architecture observations ("module A is consumed by B and C via the D bus")
+- Non-obvious workarounds for real defects
+- Domain knowledge the agent learned and would benefit a future session
+
+Things NOT to extract:
+- Successful command sequences (already in git history / shell history)
+- Tool counts / aggregates
+- The agent's own narrative about what it was doing
+- Restatements of what the user asked for
+- Generic platitudes ("test your code", "be careful with X")
+- Anything already preserved via the agent's explicit calls (see below)
+
+## Already preserved by the agent — DO NOT re-extract
+
+{{ALREADY_PRESERVED}}
+
+## Session metadata
+
+- Harness: {{HARNESS}}
+- Title: {{TITLE}}
+- Started: {{STARTED_AT}}
+- Ended: {{ENDED_AT}}
+- Project hint: {{PROJECT_HINT}}
+
+## Filtered session transcript
+
+The transcript below has already had read-only `akm` meta-ops and platform boilerplate stripped. Only content that might carry signal remains.
+
+{{TRANSCRIPT}}
+
+## Output contract
+
+Respond with EXACTLY one JSON object matching this shape:
+
+```
+{
+  "candidates": [
+    {
+      "type": "memory" | "lesson" | "knowledge",
+      "name": "<kebab-case-slug>",
+      "description": "<one sentence 20-400 chars>",
+      "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
+      "body": "<markdown body, 200-3000 chars typical>",
+      "confidence": <number 0.0-1.0>,
+      "evidence": "<one-line pointer to the moment in the session>"
+    }
+  ],
+  "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
+}
+```
+
+## Rules
+
+1. **Zero candidates is a valid and frequent answer.** Most sessions yield no new durable insight. When that's the case, return `{"candidates": [], "rationale_if_empty": "..."}` explaining what you saw and why it didn't rise to durable-knowledge level. Do not fabricate.
+
+2. **Pick the right type per candidate:**
+   - `memory` — a fact or short observation. Use for "X works on this codebase", "auth uses Y library version Z".
+   - `lesson` — a "do X / avoid Y" pattern, ALWAYS with `when_to_use`. Use for hard-won learnings about pitfalls, recovery patterns, or non-obvious gotchas.
+   - `knowledge` — substantive multi-section reference doc. Rare from one session.
+
+3. **Calibrate `confidence` honestly:**
+   - `0.9+` — high certainty this is a real durable insight a reviewer would clearly accept
+   - `0.7-0.89` — clear improvement, but a reviewer might prefer different framing or scope
+   - `0.5-0.69` — marginal / judgment call
+   - `<0.5` — don't include; prefer fewer-but-better candidates
+
+4. **`evidence` must reference the session** — a brief pointer like "agent's tool failure at ts=...", "user's correction at ...", "after the recovery in the Bash sequence around ...". Without evidence the candidate is hard to validate; default to lower confidence when evidence is vague.
+
+5. **Do not duplicate already-preserved content.** If a candidate substantively overlaps with anything in the "Already preserved" list above, skip it.
+
+6. **No speculation.** Only extract things the session genuinely demonstrates. If the agent struggled and didn't resolve, that may itself be a lesson (`when_to_use: "When attempting X, expect Y to fail"`) — but only if the failure mode is concrete enough to be useful next time.
+
+7. Respond with the JSON object only. No prose before or after. No code fences.

package/dist/llm/prompts/graph-extract-user-prompt.md

@@ -8,5 +8,28 @@ Rules:
 - Drop pleasantries, meta-commentary, and timestamps.
 - Limit to at most {{MAX_ENTITIES}} entities and {{MAX_RELATIONS}} relations per asset.
 - Return {"entities": [], "relations": []} if the body has no extractable graph content.
+- DO NOT return markdown code blocks, ONLY valid JSON objects.
+
+Examples:
+
+Input:
+## Deployment Notes
+The auth-service uses PostgreSQL for user sessions. It depends on the redis-cache
+for rate limiting. The terraform-provisioner deploys everything to the prod cluster.
+Owner: @alice.
+
+Output:
+{"entities":["auth-service","PostgreSQL","redis-cache","terraform-provisioner","prod cluster","@alice"],"relations":[{"from":"auth-service","to":"PostgreSQL","type":"uses"},{"from":"auth-service","to":"redis-cache","type":"depends on"},{"from":"terraform-provisioner","to":"prod cluster","type":"deploys"},{"from":"terraform-provisioner","to":"auth-service","type":"deploys"},{"from":"@alice","to":"auth-service","type":"owns"}]}
+
+Input:
+## Meeting: API Redesign
+Discussed moving from REST to GraphQL. The frontend team will use Apollo Client.
+Backend needs to implement resolvers. Timeline: Q2.
+
+Output:
+{"entities":["REST","GraphQL","Apollo Client","frontend team","backend","resolvers","Q2"],"relations":[{"from":"frontend team","to":"Apollo Client","type":"uses"},{"from":"backend","to":"resolvers","type":"implements"},{"from":"frontend team","to":"GraphQL","type":"migrates to"}]}
+
+===============
+
+Request:
 
-Asset body:

package/dist/output/cli-hints-full.md

@@ -16,12 +16,13 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 
 | Flag | Values | Default |
 | --- | --- | --- |
-| `--type` | `skill`, `command`, `agent`, `knowledge`, `workflow`, `script`, `memory`, `vault`, `wiki`, `any` | `any` |
+| `--type` | `skill`, `command`, `agent`, `knowledge`, `workflow`, `script`, `memory`, `env`, `secret`, `wiki`, `any` | `any` |
 | `--source` | `stash`, `registry`, `both` | `stash` |
 | `--limit` | number | `20` |
 | `--format` | `json`, `jsonl`, `text`, `yaml` | `json` |
-| `--detail` | `brief`, `normal`, `full`, `summary`, `agent` | `brief` |
-| `--for-agent` | boolean (deprecated — use `--detail agent`) | `false` |
+| `--detail` | `brief`, `normal`, `full` | `brief` |
+| `--shape` | `human`, `agent`, `summary` (`summary` only on `show`) | `human` |
+| `--for-agent` | boolean (deprecated — use `--shape agent`) | `false` |
 
 ## Curate
 
@@ -59,7 +60,7 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
 | vault | `keys`, `comments` |
-| wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list` then `akm wiki ingest <name>` for the workflow. |
+| wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list`. To ingest sources, `akm wiki ingest <name>` dispatches the configured agent (defaults.agent or `--profile`) to execute the ingest workflow. |
 
 ## Capture Knowledge While You Work
 
@@ -102,13 +103,17 @@ akm wiki stash research https://example.com/paper # Fetch one URL into raw/<slug
 akm wiki stash research ./paper.md --target my-stash # Route write to a named writable stash source
 echo "..." | akm wiki stash research -         # stdin form
 akm wiki lint research                         # Structural checks: orphans, broken xrefs, uncited raws, stale index
-akm wiki ingest research                       # Print the ingest workflow for this wiki (no action)
-akm wiki remove research --force               # Delete pages/schema/index/log; preserves raw/
-akm wiki remove research --force --with-sources # Full nuke, including raw/
+akm wiki ingest research                       # Dispatch defaults.agent to run the ingest workflow on this wiki
+akm wiki ingest research --profile claude --model sonnet  # Override profile and model
+akm wiki ingest research --timeout-ms 600000   # Override agent CLI timeout (default: profile setting)
+akm wiki remove research -y                    # Delete pages/schema/index/log; preserves raw/ (--force is a deprecated alias for -y)
+akm wiki remove research -y --with-sources     # Full nuke, including raw/
 ```
 
-**For any wiki task, start with `akm wiki list`, then `akm wiki ingest <name>`
-to get the step-by-step workflow.** Wiki pages are also addressable as
+**For any wiki task, start with `akm wiki list`. Then `akm wiki ingest <name>`
+dispatches the configured agent (defaults.agent or `--profile`) to execute
+the wiki's ingest workflow end-to-end — schema read, source dedup, search,
+page create/update, log entry, lint, reindex.** Wiki pages are also addressable as
 `wiki:<name>/<page-path>` and show up in stash-wide `akm search` as
 `type: wiki`. Files under `raw/` and the wiki root infrastructure files
 `schema.md`, `index.md`, and `log.md` are not indexed and do not appear in
@@ -163,23 +168,40 @@ akm clone "npm:@scope/pkg//script:deploy.sh"  # Clone from remote package
 
 When `--dest` is provided, `akm init` is not required first.
 
-## Save
+## Sync
 
-Commit local changes in a git-backed stash. Behaviour adapts automatically:
+Commit local changes in a git-backed stash. Behaviour adapts automatically.
+(`akm save` is the deprecated 0.7 spelling — it still works but warns; removed
+in 0.9.0.)
 
-- **Not a git repo** — no-op (silent skip)
+- **No `.git` directory** — no-op (silent skip)
 - **Git repo, no remote** — stage and commit only (the default stash always falls here)
 - **Git repo, has remote, not writable** — stage and commit only
 - **Git repo, has remote, `writable: true`** — stage, commit, and push
+- **Any writable repo with `--no-push`** — stage and commit only
 
 ```sh
-akm save                                      # Save primary stash (timestamp message)
-akm save -m "Add deploy skill"               # Save with explicit message
-akm save my-skills                            # Save a named writable git stash
-akm save my-skills -m "Update patterns"      # Save named stash with message
+akm sync                                      # Sync primary stash (timestamp message)
+akm sync -m "Add deploy skill"               # Sync with explicit message
+akm sync --no-push                            # Commit only; never push
+akm sync my-skills                            # Sync a named writable git stash
+akm sync my-skills -m "Update patterns"      # Sync named stash with message
 ```
 
-The `--writable` flag on `akm add` opts a remote git stash into push-on-save:
+`akm improve` also performs an end-of-run batch commit for git-backed stashes.
+The `--sync` / `--no-sync` and `--push` / `--no-push` flags control this:
+
+```sh
+akm improve                                   # auto-sync per profile default (default/thorough: on; quick/memory-focus: off)
+akm improve --no-sync                         # skip the end-of-run commit
+akm improve --no-push                         # commit but skip push for this run
+akm improve --sync                            # force sync even on profiles that disable it
+```
+
+Profile sync defaults: `default` and `thorough` auto-commit + push; `quick` and
+`memory-focus` skip sync entirely. Override with `--sync` / `--no-sync` flags.
+
+The `--writable` flag on `akm add` opts a remote git stash into push-on-sync:
 
 ```sh
 akm add git@github.com:org/skills.git --provider git --name my-skills --writable
@@ -193,8 +215,8 @@ akm add @scope/stash                            # From npm (managed)
 akm add owner/repo                            # From GitHub (managed)
 akm add ./path/to/local/stash                   # Local directory
 akm add git@github.com:org/repo.git --provider git --name my-skills --writable
-akm enable skills.sh                          # Enable the skills.sh registry
-akm disable skills.sh                         # Disable the skills.sh registry
+akm config enable skills.sh                   # Enable the skills.sh registry
+akm config disable skills.sh                  # Disable the skills.sh registry
 akm list                                      # List all sources
 akm list --kind managed                       # List managed sources only
 akm remove <target>                           # Remove by id, ref, path, or name
@@ -244,24 +266,29 @@ akm completions --install                     # Install completions
 ## Proposals & Improvement (0.8.0+)
 
 ```sh
-akm improve <ref>                              # Propose improvement for an asset
-akm proposals                                  # List pending proposals
-akm show proposal <id>                         # Render the proposal body
-akm diff <ref-or-id>                           # Diff by ref, UUID, or 8-char prefix (proposal positional optional)
-akm diff skill:akm-dream                       # Diff by asset ref
-akm accept 7c115132                            # Accept by UUID prefix
-akm accept <id> --target team-stash            # Accept to a named writable stash source
-akm reject skill:my-skill --reason "not ready" # Reject by asset ref
-akm reject <id> --reason "..."                 # Archive with a reason
+akm improve <ref>                                       # Propose improvement for an asset
+akm proposal list                                       # List pending proposals
+akm proposal show <id>                                  # Render the proposal body
+akm proposal diff <ref-or-id>                           # Diff by ref, UUID, or 8-char prefix
+akm proposal diff skill:akm-dream                       # Diff by asset ref
+akm proposal accept 7c115132                            # Accept by UUID prefix
+akm proposal accept <id> --target team-stash            # Accept to a named writable stash source
+akm proposal reject skill:my-skill --reason "not ready" # Reject by asset ref
+akm proposal reject <id> --reason "..."                 # Archive with a reason
+akm proposal revert <id>                                # Restore the pre-promotion content
 ```
 
+The flat verbs `akm proposals` / `akm show proposal` / `akm accept` /
+`akm reject` / `akm diff` / `akm revert` still work as deprecated aliases
+(warn on stderr; removed in 0.9.0).
+
 Per-task `timeoutMs`: task markdown frontmatter may set `timeoutMs: null` to
 disable the agent kill timer for long-running local-model tasks, or a number
 (milliseconds) to override `config.agent.timeoutMs` for that task only.
 
 ## Output Control
 
-All commands accept `--format` and `--detail` flags:
+All commands accept `--format`, `--detail`, and `--shape` flags:
 
 - `--format json` (default) — structured JSON
 - `--format jsonl` — one JSON object per line (streaming-friendly)
@@ -270,8 +297,9 @@ All commands accept `--format` and `--detail` flags:
 - `--detail brief` (default) — compact output
 - `--detail normal` — adds tags, refs, origins
 - `--detail full` — includes scores, paths, timing, debug info
-- `--detail summary` — metadata only (no content/template/prompt), under 200 tokens
-- `--detail agent` — agent-optimized output: strips non-actionable fields
-- `--for-agent` — deprecated alias for `--detail agent`
+- `--shape human` (default) — standard projection
+- `--shape agent` — agent-optimized output: strips non-actionable fields
+- `--shape summary` — metadata only (no content/template/prompt), under 200 tokens; only valid on `akm show`
+- `--for-agent` — deprecated alias for `--shape agent` (removed 0.9.0)
 
 Run `akm -h` or `akm <command> -h` for per-command help.

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

@@ -33,15 +33,17 @@ akm remember "note" --target my-stash         # Route write to a named writable
 akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
 akm import ./doc.md --target my-stash         # Route import to a named writable stash source
 akm wiki list                                 # List available wikis
-akm wiki ingest <name>                        # Print the ingest workflow for a wiki
+akm wiki ingest <name>                        # Dispatch an agent to run the ingest workflow (uses defaults.agent or --profile)
 akm wiki stash <name> ./paper.md --target my-stash # Route wiki stash write to a named source
-akm diff skill:akm-dream                      # Diff proposal by ref, UUID, or 8-char prefix
-akm accept 7c115132                           # Accept by UUID prefix (proposal positional optional)
-akm reject skill:my-skill --reason "..."      # Reject by ref (proposal positional optional)
+akm proposal diff skill:akm-dream             # Diff proposal by ref, UUID, or 8-char prefix
+akm proposal accept 7c115132                  # Accept by UUID prefix
+akm proposal reject skill:my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive|--negative      # Record whether an asset helped
 akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
-akm save                                      # Commit (and push if writable remote) changes in the primary stash
+akm sync                                      # Commit (and push if writable remote) changes in the primary stash (--no-push to commit only)
+akm improve --no-sync                         # Run improve without the end-of-run auto-commit
+akm improve --no-push                         # Auto-commit but skip push for this run
 akm registry search "<query>"                 # Search all registries
 ```
 
@@ -56,8 +58,9 @@ akm registry search "<query>"                 # Search all registries
 | knowledge | A reference doc (use `toc` or `section "..."` to navigate) |
 | workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
-| vault | Key names only; use `akm vault path` or `akm vault run` to use values safely |
-| wiki | A page in a multi-wiki knowledge base. For any wiki task, start with `akm wiki list`, then `akm wiki ingest <name>` for the workflow. Run `akm wiki -h` for the full surface. |
+| env | A `.env` file of related CONFIGURATION (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). `vault` is the deprecated alias. |
+| secret | A single sensitive value for AUTHENTICATION (token, key, cert); name only. Use `akm secret path` / `akm secret run`. |
+| wiki | A page in a multi-wiki knowledge base. For any wiki task, start with `akm wiki list`. To ingest sources, run `akm wiki ingest <name>` — it dispatches the configured agent profile to execute the ingest workflow against the wiki's `raw/` directory. Run `akm wiki -h` for the full surface. |
 
 When an asset meaningfully helps or fails, record that with `akm feedback` so
 future search ranking can learn from real usage.

package/dist/output/cli-hints.js

@@ -1,11 +1,14 @@
+// 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/.
 /**
  * Embedded "agent CLI hints" rendered by `akm hints` when no other source
  * is available.
  *
  * Extracted from `src/cli.ts` so it does not bloat the CLI module and so
  * docs/CI tooling can re-use the same constants. Two flavors:
- * `EMBEDDED_HINTS` (default reference, ~40 lines) and
- * `EMBEDDED_HINTS_FULL` (`--detail full`, ~250 lines).
+ * `EMBEDDED_HINTS` (`--detail brief`, short reference, ~40 lines) and
+ * `EMBEDDED_HINTS_FULL` (`--detail normal|full`, ~250 lines).
  */
 import EMBEDDED_HINTS_FULL from "./cli-hints-full.md" with { type: "text" };
 import EMBEDDED_HINTS from "./cli-hints-short.md" with { type: "text" };

package/dist/output/context.js

@@ -1,7 +1,10 @@
+// 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/.
 /**
  * Process-level output mode singleton.
  *
- * Output mode (format + detail + forAgent) is parsed once at startup from
+ * Output mode (format + detail + shape) is parsed once at startup from
  * `process.argv` and the persisted user config. All subsequent `output()`
  * calls read from this in-memory singleton instead of re-scanning argv and
  * re-loading config on every call.
@@ -9,8 +12,9 @@
  * Initialized from `cli.ts` before `runMain`.
  */
 import { UsageError } from "../core/errors";
-export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl"];
-export const DETAIL_LEVELS = ["brief", "normal", "full", "summary", "agent"];
+export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md"];
+export const DETAIL_LEVELS = ["brief", "normal", "full"];
+export const SHAPE_MODES = ["human", "agent", "summary"];
 export function parseOutputFormat(value) {
     if (!value)
         return undefined;
@@ -25,6 +29,13 @@ export function parseDetailLevel(value) {
         return value;
     throw new UsageError(`Invalid value for --detail: ${value}. Expected one of: ${DETAIL_LEVELS.join("|")}`, "INVALID_DETAIL_VALUE");
 }
+export function parseShapeMode(value) {
+    if (!value)
+        return undefined;
+    if (SHAPE_MODES.includes(value))
+        return value;
+    throw new UsageError(`Invalid value for --shape: ${value}. Expected one of: ${SHAPE_MODES.join("|")}`, "INVALID_SHAPE_VALUE");
+}
 export function parseFlagValue(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -62,11 +73,52 @@ export function getHyphenatedBoolean(args, key) {
  */
 export function resolveOutputMode(argv, defaults = {}) {
     const format = parseOutputFormat(parseFlagValue(argv, "--format")) ?? defaults?.format ?? "json";
-    const detail = parseDetailLevel(parseFlagValue(argv, "--detail")) ?? defaults?.detail ?? "brief";
-    // `--detail=agent` is the preferred preset. `--for-agent` is kept for one
-    // release cycle as an alias so existing scripts and docs keep working.
-    const forAgent = detail === "agent" || hasBooleanFlag(argv, "--for-agent");
-    return { format, detail, forAgent };
+    const rawDetail = parseFlagValue(argv, "--detail");
+    const rawShape = parseFlagValue(argv, "--shape");
+    const usedForAgent = hasBooleanFlag(argv, "--for-agent");
+    // Back-compat: the projection presets `summary`/`agent` used to live on
+    // `--detail`. They moved to `--shape` in 0.8 (removed from `--detail` in
+    // 0.9.0). Map the legacy spellings onto `--shape` + warn, and treat the
+    // verbosity axis as `normal` (the prior effective behaviour).
+    let detailForVerbosity = rawDetail;
+    let shapeFromLegacyDetail;
+    if (rawDetail === "summary" || rawDetail === "agent") {
+        // Only nudge toward `--shape` when the caller did not already pass an
+        // explicit `--shape` (which wins below). Otherwise the "use --shape <x>"
+        // advice would name a projection the caller did not request.
+        if (rawShape === undefined)
+            emitDetailShapeDeprecation(rawDetail);
+        shapeFromLegacyDetail = rawDetail;
+        detailForVerbosity = "normal";
+    }
+    else if (rawDetail === "per-run") {
+        // Legacy `akm health --detail per-run` (→ `--group-by run`). The health
+        // command owns the back-compat warning + mapping; the global singleton must
+        // not reject the value here, so fall through to the default verbosity.
+        detailForVerbosity = undefined;
+    }
+    if (usedForAgent) {
+        emitForAgentDeprecation();
+    }
+    const detail = parseDetailLevel(detailForVerbosity) ?? defaults?.detail ?? "brief";
+    // Precedence: explicit `--shape` wins; then legacy `--detail summary|agent`;
+    // then legacy `--for-agent`; default `human`.
+    const shape = parseShapeMode(rawShape) ?? shapeFromLegacyDetail ?? (usedForAgent ? "agent" : "human");
+    return { format, detail, shape, forAgent: shape === "agent" };
+}
+/** Suppress deprecation warnings under `--quiet` (mirrors the rest of the CLI). */
+function isQuietArgv() {
+    return process.argv.includes("--quiet") || process.argv.includes("-q");
+}
+function emitDetailShapeDeprecation(value) {
+    if (isQuietArgv())
+        return;
+    process.stderr.write(`warning: '--detail ${value}' is deprecated; use '--shape ${value}'. Removed in 0.9.0.\n`);
+}
+function emitForAgentDeprecation() {
+    if (isQuietArgv())
+        return;
+    process.stderr.write("warning: '--for-agent' is deprecated; use '--shape agent'. Removed in 0.9.0.\n");
 }
 let _mode;
 /**