akm-cli 0.9.0 → 0.9.1-beta.2

package/docs/reference/cli.md

@@ -7,7 +7,9 @@ different presentation. Errors include `error` and `hint` fields.
 
 This page is authoritative for the current CLI. For per-release behavior
 changes, see [`CHANGELOG.md`](../../CHANGELOG.md) and
-[`docs/migration/`](../migration/).
+[`docs/migration/`](../migration/). For the bundle formats akm recognizes
+(detection, ref shapes, indexing, validation, read/write), see
+[Bundle Types](bundle-types.md).
 
 ## Global Flags
 
@@ -356,7 +358,7 @@ tip names the conceptId spelling that replaces it.
 
 | Flag | Values | Default | Description |
 | --- | --- | --- | --- |
-| `--type` | `skill`, `command`, `agent`, `knowledge`, `instruction`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `any` | `any` | Filter by asset type. Free-form and unvalidated — an unknown type returns no hits. Also accepts any adapter-defined type (e.g. `website`). |
+| `--type` | `skill`, `command`, `agent`, `knowledge`, `instruction`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `any` | `any` | Filter by asset type. Free-form and unvalidated — an unknown type returns no hits. Also accepts any adapter-defined type (e.g. `website`) — see [Bundle Types](bundle-types.md) for the open types each adapter emits. |
 | `--limit` | number | `20` | Maximum results |
 | `--from` | `local`, `registry`, `all` | `local` | Where to search |
 | `--assets` | flag | `false` | Include asset-level registry results (only meaningful with `--from registry\|all`; folds in the retired `akm registry search --assets`) |
@@ -525,7 +527,7 @@ Returns type-specific payloads:
 | command | `template`, `description` |
 | agent | `prompt`, `description`, `modelHint` |
 | knowledge | `content` — the whole document, or one section via `#fragment` |
-| workflow | `workflowTitle`, `workflowParameters`, `steps` |
+| workflow | `workflowTitle`, `workflowParameters`, `steps` (each step's `orchestration` summary names its engine/model, or — for an [exec step](https://github.com/itlackey/akm/blob/main/docs/reference/workflow-schema.md#what-akm-show-reports-for-an-exec-step) — its `exec.command` and no engine at all) |
 | memory | `content` |
 | env | `keys` (key names only — values and comment text never returned) |
 | lesson | `content` plus `when_to_use` surfaced from frontmatter |
@@ -607,15 +609,34 @@ The old `--params <json>` bag is removed.
 
 | Flag | Description |
 | --- | --- |
-| `--max-steps <n>` | Stop after executing at most this many steps, leaving a partial run active. Must be at least 1. |
+| `--max-steps <n>` | Stop once this many steps have finished, leaving a partial run active. Must be at least 1. |
 | `--max-retries <n>` | When a step fails, reopen the same run and retry the failed step up to this many additional times. Range: 0 through 100; default 0. Gate rejection and interruption are not retried. |
 | `--timeout <duration>` | Abort the whole invocation after `N`, `Nms`, `Ns`, or `Nm`; bare `N` is milliseconds. The active step remains resumable. |
 
-The result includes the current `run`, an `executed` step report list, and
-optional `done`, `gateRejection`, `aborted`, or `timedOut` markers. A failed
-run, rejected verification gate, timeout, or interrupt exits nonzero. `SIGINT`
-and `SIGTERM` map to 130 and 143; a timeout maps to exit 1. Reaching
-`--max-steps` with an active resumable run is successful.
+The result includes the current `run`, an `executed` step report list, a
+`stepsProcessed` count of the steps that finished, and optional `done`,
+`gateRejection`, `aborted`, or `timedOut` markers. A failed run, rejected
+verification gate, timeout, or interrupt exits nonzero. `SIGINT` and `SIGTERM`
+map to 130 and 143; a timeout maps to exit 1. Reaching `--max-steps` with an
+active resumable run is successful. A `--timeout` that lands during the run's
+final bookkeeping is not reported as a timeout: a run that reached `completed`
+has nothing left to abort and nothing left to resume.
+
+**What `--max-steps` counts.** The budget is spent by the **steps that
+finish** — completed, failed, or gate-rejected with the loop budget spent — not
+by entries in the `executed` report, which gains one per gate-loop iteration
+and one per route-skip. So a step's whole bounded `gate.max_loops` loop costs
+one, a route-skipped step costs nothing (no work was dispatched for it), and a
+step the invocation left unfinished — an abort, a verification-judge outage —
+costs nothing either, because the next invocation still owes that work.
+`--max-retries` subtracts the same way: a reopened run's remaining budget is
+not shrunk by loops or skips.
+
+The budget is checked **between** steps, so it does not bound what any single
+step dispatches — a step's gate loop runs to its own limit no matter how little
+budget is left. `gate.max_loops` (1–100) is the per-step ceiling;
+`budget.max_units` and `budget.max_tokens` are the whole-run ceilings, seeded
+from the unit journal so they hold across resumes.
 
 `run` is Stable and does not consult `experimental.workflowEngine`. Every
 non-empty `### gate` requires `workflow.judgeEngine` to name a configured LLM
@@ -716,6 +737,10 @@ sources. Other HTTP(S) URLs are crawled as website sources.
 ### bundle add
 
 Add a source — a local directory, npm package, GitHub repo, git URL, or website.
+akm detects the bundle's **format** automatically (its own native workspace,
+a Claude Code or OpenCode tool directory, an OKF or LLM-wiki knowledge base,
+…) — see [Bundle Types](bundle-types.md) for how detection works and what
+each format gives you.
 
 ```sh
 akm bundle add ~/.claude/skills              # Local directory
@@ -775,7 +800,7 @@ akm bundle add github:owner/repo-with-sensitive-env
 akm bundle add github:owner/repo-with-sensitive-env --allow-insecure
 ```
 
-Bundle publishers: see the [Stash Maker's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/stash-makers.md#env-security)
+Bundle publishers: see the [Author Bundles guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md#env-security)
 for guidance on env files that legitimately need these keys.
 
 #### Website sources
@@ -1827,15 +1852,25 @@ akm lint --fail-on-flagged      # CI-friendly: exit non-zero when summary.flagge
 
 | Flag | Description |
 | --- | --- |
-| `--fix` (alias `--auto-fix`) | Apply auto-fixes in place |
+| `--fix` (alias `--auto-fix`) | Apply auto-fixes in place. Refused with a usage error when the target bundle is configured `writable: false`. |
 | `--dir` | Override the bundle root directory (default: from config) |
-| `--type` | Only lint assets of this type (e.g. `workflows`, `tasks`, `memories`) |
+| `--type` | Only lint assets of this type (e.g. `workflows`, `tasks`, `memories`). **akm bundles only** — every other adapter validates the whole bundle and warns on stderr that the flag had no effect. |
 | `--fail-on-flagged` | Exit non-zero when `summary.flagged > 0`. Default: exit 0 regardless of findings. |
 
 Returns `fixed[]` and `flagged[]` arrays plus a `summary: { fixed, flagged }`
 count. Each entry carries `file`, `issue`, `detail`, and whether it was
 `fixed`.
 
+Task files are checked for more than their fields: a `tasks/*.yml` whose YAML
+does not parse is reported as `invalid-task-yaml` (it used to fall through as an
+empty mapping and lint clean), and a `tasks/*.yaml` file — a spelling akm never
+indexes or schedules — is flagged for the extension rather than skipped.
+
+`--fix` is transactional per file: a fix that cannot be written (read-only file,
+full disk) is reported as `fixed: "failed"` on that file and the sweep continues,
+so a mid-run write failure can no longer abort the command and hide the fixes
+that already landed.
+
 ### improve
 
 Improve existing assets and write the results to the proposal queue.
@@ -2241,13 +2276,67 @@ Each task targets exactly one of `--workflow <ref>`, `--prompt <text-or-ref>`,
 or `--command <shell>`. Task YAML is strict and begins with `version: 2`.
 Prompt targets dispatch through `--engine` or `defaults.engine` and may set
 `model`, `timeoutMs`, and LLM request overrides; command tasks may set only
-`timeoutMs`; workflow tasks may set only `params`. `task add` accepts
-`--engine`, `--model`, `--timeout-ms`, `--params`, `--name`, `--when-to-use`,
-`--description`, and `--tags`. A v1 task is diagnosed by sync and doctor
-but is never rewritten or executed.
+`timeoutMs`; workflow tasks may set `params`, `timeoutMs`, `maxSteps`, and
+`maxRetries`. `task add` accepts `--engine`, `--model`, `--timeout-ms`,
+`--params`, `--name`, `--when-to-use`, `--description`, and `--tags`
+(`maxSteps` / `maxRetries` are YAML-only — set them in the file and run `akm
+task sync`). A v1 task is diagnosed by sync and doctor but is never rewritten
+or executed.
+
+**Task-log redaction and `redact:`.** A task's persisted output — the run `.log`
+file and its `logs.db` rows — is scrubbed before it is written. Two passes run:
+credential *shapes* (`Bearer …`, `sk-…`, webhook URLs) are matched by pattern,
+and exact secret values are matched by value. akm knows a value is secret when
+the config declares it (`engines.<name>.apiKey`, `embedding.apiKey`, and the
+`AKM_ENGINE_<NAME>_API_KEY` / `AKM_LLM_API_KEY` / `AKM_EMBED_API_KEY` recipes),
+and it infers others from the variable name (`*_TOKEN`, `*_SECRET`, `*_API_KEY`,
+`*_PASSWORD`, …) provided the value is at least 8 characters — a short one is
+far more likely to be a flag than a credential, and redaction replaces
+substrings, so guessing wrong mangles the log.
+
+Any task kind may add `redact:` for a secret exported under a name none of those
+rules recognise:
+
+```yaml
+version: 2
+schedule: "0 3 * * *"
+command: ./deploy.sh
+redact: [ACME_DEPLOY_TOKEN]   # NAMES, never values — max 32
+```
+
+akm looks each name up in the environment the run is given; a name that is unset
+contributes nothing. **Names only.** A literal secret in a task file would leak
+far more widely than the redaction closes: task files are indexed into the search
+database, can be sent to an embedding provider, are printed verbatim by `akm
+show`, and ship inside bundles over git and npm. This is the same rule exec
+units' `pass_env:` follows.
 
 A workflow-target task executes the same native orchestration as `akm workflow
 run`; it does not stop after creating a run. Completion maps to task
 `completed`, while workflow failure or verifier rejection maps to task
 `failed`. The task schema's `params` mapping remains the non-CLI way a scheduled
 definition supplies its new-run parameter snapshot.
+
+**Workflow-task run bounds.** `timeoutMs`, `maxSteps`, and `maxRetries` are the
+task-file spellings of `akm workflow run --timeout`, `--max-steps`, and
+`--max-retries`. Unlike the interactive command, a scheduled workflow task gets
+a **default whole-run timeout of 6 hours**
+(`DEFAULT_WORKFLOW_TASK_TIMEOUT_MS`): nobody is at the terminal to Ctrl-C an
+unattended run, so without one a single wedged unit hangs the task forever. An
+explicit `timeoutMs` always wins, and `timeoutMs: null` opts out entirely. On
+expiry the runner aborts the run's signal, which the engine treats as a
+graceful break at the next step boundary — the journal is kept and the run
+stays resumable with `akm workflow resume <run-id>` (the run id is in the task
+run's `detail.error` and log). The attempt itself is recorded as `failed`, so
+the OS scheduler sees a non-zero exit.
+
+```yaml
+version: 2
+schedule: "@daily"
+workflow: workflows/nightly-report
+params:
+  region: us-east-1
+timeoutMs: 3600000   # 1h whole-run bound (omit for the 6h default, null for none)
+maxSteps: 20         # optional
+maxRetries: 1        # optional
+```

package/docs/reference/configuration.md

@@ -113,6 +113,16 @@ value is clamped to `1..64`. When absent, AKM derives the cap once from the CPU
 count (`min(16, max(1, cores - 2))`) and freezes it into the run plan, so resume
 does not change policy on a different host or after config edits.
 
+`workflow.defaultMapConcurrency` is the width a `map` step freezes when it
+declares no `concurrency:` of its own. Unset means **4** — map steps are
+parallel by default as of 0.9.1. An explicit value is clamped to `1..64`; set
+it to `1` to restore the pre-0.9.1 serial-by-default fan-out for every workflow
+on this machine. It is only a default: an authored `map.concurrency` always
+wins, and it never raises a step past `workflow.maxConcurrency`, the selected
+engine's `concurrency`, or the host CPU cap. An LLM engine that declares no
+`engines.<name>.concurrency` gets **1** on a loopback endpoint (a local model
+server holds one loaded model) and **4** on a remote one.
+
 `workflow.judgeEngine` names the LLM or agent engine used to verify every
 non-empty workflow `### gate` rubric. It is required when a workflow declares
 completion criteria and is frozen into each new run, so later config edits do
@@ -228,7 +238,10 @@ reference, same rules as engine `apiKey`), `dimension`, `localModel`,
 and `defaultBundle` are the 0.9 source configuration shape — see
 [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) and the [CLI reference](cli.md) for the
 full bundle model (`path`, `git`, `website`, `npm`, `writable`, `registryId`,
-`components`). `defaultBundle` must name a key in `bundles` when set.
+`components`). `defaultBundle` must name a key in `bundles` when set. A
+bundle's `components.<id>.adapter` key pins it to a specific format adapter
+instead of relying on auto-detection — see [Bundle Types](bundle-types.md)
+for the full adapter list and what each one reads/writes.
 
 ### defaultWriteTarget
 
@@ -333,7 +346,7 @@ generic walker.
 | `AKM_ENGINE_<NAME>_API_KEY` | Fallback credential for LLM engine `<name>` |
 | `AKM_LLM_API_KEY` | Fallback only for the selected `defaults.llmEngine` |
 | `AKM_EMBED_API_KEY` | Embedding credential |
-| `AKM_BUNDLE_DIR` | Override the stash directory |
+| `AKM_BUNDLE_DIR` | Override the bundle directory |
 | `AKM_DATA_DIR` | Override the data directory — durable `index.db`/`workflow.db`/`state.db`, `akm.lock`, config backups (or set `XDG_DATA_HOME`) |
 | `AKM_CACHE_DIR` | Override the cache directory — regenerable caches (or set `XDG_CACHE_HOME`) |
 | `AKM_STATE_DIR` | Override the state directory — task-scheduler invocation state (or set `XDG_STATE_HOME`) |

package/docs/reference/data-and-telemetry.md

@@ -13,7 +13,7 @@ AKM does not:
 AKM adds no network destinations of its own. The requests it *does* make all go to endpoints you chose or invoked, and those third parties receive whatever the request contains:
 
 1. **Your configured LLM/embedding provider** (e.g. Anthropic, OpenAI, a local Ollama, or any OpenAI-compatible endpoint) receives the prompts and asset content sent for reflect/propose/distill/embedding when you enable those features. If you point AKM at Anthropic, Anthropic receives those requests.
-2. **Registry metadata and stash packages** from sources you explicitly configure (GitHub, npm, git remotes, websites) — those hosts receive the fetch/clone/crawl requests, and website sources receive requests for the pages you crawl.
+2. **Registry metadata and bundle packages** from sources you explicitly configure (GitHub, npm, git remotes, websites) — those hosts receive the fetch/clone/crawl requests, and website sources receive requests for the pages you crawl.
 3. **`akm upgrade`** — fetches the latest release from GitHub releases (GitHub sees the request).
 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.
 5. **`akm improve` dead-link checks** — a full-scope improve run (the default for a bare `akm improve`) sends best-effort `HEAD` requests (following redirects, with a short timeout and a hard cap on URL count) to URLs found in the bodies of the knowledge assets it is improving, to flag dead links. The hosts of those URLs see a `HEAD` request; no asset content is sent. Keep URLs you don't want probed out of knowledge-asset bodies, or run improve with an explicit narrower scope.
@@ -30,7 +30,7 @@ AKM writes to these locations on your machine. All paths follow [XDG Base Direct
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
-| `config.json` | Your AKM configuration: engines, improve strategies, bundles (stash sources), and experimental opt-ins — see [Configuration](configuration.md) | **No** — deleting resets all settings |
+| `config.json` | Your AKM configuration: engines, improve strategies, bundles (bundle sources), and experimental opt-ins — see [Configuration](configuration.md) | **No** — deleting resets all settings |
 
 Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 
@@ -38,7 +38,7 @@ Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
-| `index.db` | Search index for all your stash assets (FTS5 + metadata) | Yes — rebuilds via `akm index --full` |
+| `index.db` | Search index for all your bundle assets (FTS5 + metadata) | Yes — rebuilds via `akm index --full` |
 | `state.db` | Events, local usage telemetry, proposals, task history, improve run results, and workflow run state/history (the former `workflow.db` was folded in during the 0.9.0 cutover) | **No** — deletes event/usage logs, proposal queue, improve history, and workflow run history |
 | `logs.db` | Structured, high-volume task/run log lines (`{ts, task_id, run_id, stream, level, line}`), joined to `state.db`'s `task_history` rows by `task_id@started_at`. Kept separate from `state.db` because log lines are append-only and freely purgeable, unlike durable state | Yes — log lines are regenerable per run; deleting loses historical run output only |
 | `akm.lock` | Inter-process write lock | Yes — recreated automatically |
@@ -46,6 +46,26 @@ Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 
 Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.
 
+These files take your **process umask** — akm does not set or change their
+permissions. They hold task history, captured command output, and indexed
+content, so on a shared machine you probably do not want them world-readable;
+set a tighter umask, or `chmod` the directory yourself. akm will not do it for
+you, and `akm health` will not nag about it either — `0644` under a default
+`022` umask is simply the expected state.
+
+If akm **cannot read** this directory — a uid/ownership mismatch, for instance
+when two accounts share one `$XDG_DATA_HOME` — commands fail loudly with a
+`DATA_DIR_UNREADABLE` config error (exit 78) naming the path, the errno, the
+mode and owner, and the uid you are running as. They do **not** report an empty
+index. `akm health` stays runnable in that state and reports it as a failing
+`state-db-readable` check, so it remains the command to reach for.
+
+> **0.9.1 note.** A pre-release build briefly chmodded this directory to `0700`
+> and the databases to `0600` on every open. That was reverted: it silently
+> changed the permissions of directories akm did not create, which broke installs
+> sharing `$XDG_DATA_HOME` between two uids. If a 0.9.1 pre-release tightened
+> your data directory and you need it shared again, `chmod` it back.
+
 ### 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.
@@ -54,16 +74,16 @@ Everything in the cache is regenerable. It is safe to delete the entire cache di
 |---|---|---|
 | `config-backups/config-<timestamp>.json` | Pre-save config snapshots (5 retained; owner-only permissions — file `0600`, dir `0700`, since 08-F4) | Yes |
 | `config-backups/config.latest.json` | Latest backup alias (owner-only `0600`) | Yes |
-| `registry/` | Downloaded registry tarballs (stash packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm bundle add` or `akm bundle update` |
+| `registry/` | Downloaded registry tarballs (bundle packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm bundle add` or `akm bundle 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/logs/` | Scheduled task log files. Written at your umask; they hold captured command/agent output, so tighten the directory yourself if the machine is shared | 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)
+### Bundle Directory (`~/akm/` by default, or user-configured)
 
 | Path | Contents | Safe to delete? |
 |---|---|---|
@@ -122,7 +142,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
 | `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
 | `sync` | `akm sync` (renamed from `save` in 0.9.0; historical rows keep `save`, and `akm log --type save`/`--type sync` are synonyms on read) | `ref` |
-| `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason` |
+| `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |
 | `env_access` | `akm env run <name> -- <command>` (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
 | `secret_access` | `akm secret run <ref> <VAR> -- <command>` (audit trail: var **name** only, value never recorded) | `ref`, `var` |
 
@@ -162,7 +182,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `proactive_selected` | The proactive-maintenance selector runs (once per `akm improve` run) | `count`, `dueTotal`, `neverReflected` (aggregated) |
 | `improve_replay_selected` | Bounded replay-budget selection ran | `count`, `budget`, `convergedSkipped`, `candidatePool` (aggregated) |
 | `improve_salience_first_run` | First improve run with no pre-existing salience baseline to compare against | `candidateCount`, `note` |
-| `improve_salience_rank_change` | Stash-wide rank-change report, from the second improve run onward | `stashSize`, `totalChanged`, `forgettingCandidates`, `topDrops` |
+| `improve_salience_rank_change` | Bundle-wide rank-change report, from the second improve run onward | `stashSize`, `totalChanged`, `forgettingCandidates`, `topDrops` |
 | `outcome_proxy_inverted` | Proxy-adequacy tripwire: `outcome_score` correlates *negatively* with accepted-change rate (corr < −0.3) | `correlation`, `n` |
 | `outcome_proxy_dead` | Proxy-adequacy tripwire: `outcome_score` is statistically unrelated to accepted-change rate (\|corr\| < 0.1, n ≥ 500) | `correlation`, `n` |
 | `collapse_detector_alert` | The collapse/churn detector trips an alert rule during an improve cycle | `kind` (collapse-recall\|collapse-entropy\|collapse-shrink\|churn\|merge-floor), `detail`, `metrics`, `canarySetId`, `runId` |
@@ -241,7 +261,7 @@ an identity that production indexing omitted.
 
 ### 3. Proposals Table
 
-The proposal queue: pending, accepted, and rejected improvement proposals for your stash assets. Generated by `akm improve`, `akm proposal new`, and related proposal-producing flows.
+The proposal queue: pending, accepted, and rejected improvement proposals for your bundle assets. Generated by `akm improve`, `akm proposal new`, and related proposal-producing flows.
 
 Contents:
 - Proposal UUID (primary key)
@@ -327,7 +347,7 @@ You can redirect any AKM directory to a custom path:
 | `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE`. Use `DELETE`/`TRUNCATE` on network filesystems (NFS/SMB) where WAL is impossible. When left at the `WAL` default, akm auto-detects a network FS for the data dir and falls back to `DELETE`. |
 | `AKM_STATE_DIR` | State directory (`~/.local/state/akm/`) |
 | `AKM_CACHE_DIR` | Cache directory (`~/.cache/akm/`) |
-| `AKM_BUNDLE_DIR` | Default stash directory (`~/akm/`) |
+| `AKM_BUNDLE_DIR` | Default bundle 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` |

package/docs/reference/supported-formats.md

@@ -0,0 +1,50 @@
+# Supported Formats
+
+AKM is a portable capability library for AI agents: one library for every
+agent. Interoperability is the point — AKM doesn't only manage its own asset
+library, it can point at a directory that already follows a *different*
+convention (a Claude Code project, an OKF knowledge base, a Karpathy-style LLM
+wiki, a crawled website, …) and index, search, and validate it in place,
+without you converting anything first.
+
+A directory AKM indexes this way is a **bundle**. AKM auto-detects which
+format a bundle uses — you never declare it yourself unless you want to pin
+one explicitly. 0.9.0 recognizes 11 formats.
+
+## Format compatibility
+
+| Format | What AKM indexes | Auto-detection marker | Current read/write support | Typical use |
+| --- | --- | --- | --- | --- |
+| `website-snapshot` | Crawled pages tagged `website` (name, description, full body, original crawl URL) | Root `manifest.json` with `url` + `fetchedAt` | Read-only | A website materialized locally via `akm bundle add <url>` |
+| `agent-skills` | Standalone Agent Skills packages as type `skill` (name, description, tags, body) | A direct child directory containing `SKILL.md` | Read-only | The [github.com/anthropics/skills](https://github.com/anthropics/skills) layout — one `<name>/SKILL.md` per package at the bundle root |
+| `claude` | `CLAUDE.md` as `instruction`; `commands/`, `agents/`, `skills/<name>/SKILL.md` as their matching types | Root `CLAUDE.md` plus at least one of `commands/`, `agents/`, `skills/` | Read-only | Point AKM at an existing Claude Code `.claude` tool directory |
+| `opencode` | Same shape as `claude`, rooted on `AGENTS.md` | `opencode.json`/`opencode.jsonc`, or root `AGENTS.md` plus a tool directory (plural or singular alias) | Read-only | Point AKM at an existing OpenCode `.opencode` tool directory |
+| `dotenv` | `env` entries as key names only (never values); `secret` entries as file names only (never content) | Every top-level directory is `env/` and/or `secrets/`, with at least one present | Writable, narrowly — `akm env create`/`env remove`/`secret set` only | A standalone env/secrets-only bundle |
+| `akm-workflow` | Workflow steps, name, description, tags | A top-level `.md` file with explicit `type: workflow` frontmatter | Writable — `akm workflow create` only | A standalone workflow bundle, one workflow per file |
+| `akm-task` | Tasks as type `task`, name, full raw YAML | A top-level `.yml` file that parses with a non-empty `schedule` key | Read-only | A standalone scheduled-task bundle |
+| `llm-wiki` | `raw/` sources as `wiki-source`; `pages/` as their `pageKind` (default `note`), with resolved cross-reference links | Root `schema.md` plus a `pages/` directory | Read-only (author by writing directly into `pages/`; AKM indexes and serves the result) | [Karpathy's LLM-wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — agent-authored reference wikis |
+| `akm` (native) | AKM's own 14 native asset types — see [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) | A `.stash` marker directory, or two-plus native subdirectories, or the fallback when nothing else matches | Fully writable — every AKM-native write command | Your working bundle, and any bundle authored as AKM's own format |
+| `okf` | Frontmatter `type` (defaults to `knowledge`); name, description, tags, links, body | A root `index.md`, or any `.md` file anywhere carrying a non-empty frontmatter `type` | Read-only | The [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) — the portable baseline every markdown-based format here is a superset of |
+| `generic-files` | Files classified by extension: scripts, markdown/text as `document`, everything else as `file` | None — only claimed via an explicit `components.<id>.adapter: "generic-files"` config override | Read-only | A catch-all for a directory that doesn't match any other format |
+
+**Read-only** here means AKM's own write commands (`akm remember`, `akm
+import`, `proposal accept`, and similar) won't create or edit files in a
+bundle of that format. Reading, searching, and `akm lint` validation work
+against every format in the table above regardless of write support.
+
+## Why this matters
+
+This table is the proof of the first pillar: **one library for every agent**.
+You don't migrate a Claude Code project, an OpenCode project, or an OKF
+knowledge base into AKM's own layout to get search, curation, and validation
+over it — AKM meets each format where it already lives. Writing new
+capabilities back into a foreign-format bundle is a separate, narrower
+guarantee; see [Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) for exactly which
+formats are writable today and why.
+
+## See also
+
+- [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) — the 14 native asset types AKM's own format recognizes
+- [Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) — how AKM picks a format, the write-path internals, and current caveats
+- [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) — the retrieval loop these formats feed
+- [Wikis](https://github.com/itlackey/akm/blob/main/docs/guides/wikis.md) — the `llm-wiki` authoring workflow