akm-cli 0.9.30 → 0.9.32

package/docs/architecture/workflow-engine.md

@@ -0,0 +1,274 @@
+# Architecture: The Workflow Engine
+
+A workflow compiles to a frozen plan, persists run and unit state, dispatches
+its work, verifies declared gates, and resumes without replaying completed
+units. This page is the architecture-level reference for that engine — how a
+run's plan is frozen and stored, how dispatch and resume actually work, how
+one engine owns a run, and how isolated file-mutating units execute. For the
+exact frontmatter/body syntax that produces the plan, see
+[Workflow Schema](../reference/workflow-schema.md). For the day-to-day
+commands that drive a run, see [Running Workflows](../guides/run-workflows.md).
+
+> **`akm workflow run` is Stable, ungated, and the only execution surface.**
+> It is the canonical start/resume/execute command; there is no separate
+> external-driver protocol.
+
+## Frozen plans
+
+The first `akm workflow run <ref>` compiles either peer source format
+(Markdown or GitHub-Actions-style YAML) straight to the one plan type and
+stores it as durable plan **`irVersion` 6** on the run row (`plan_json` +
+`plan_hash`); a new start never emits an older version. `plan_ir_version` and
+`plan_hash` are recorded provenance, not gates: a stored plan is decoded as it
+is — irVersion 4 and 5 plans included — and one frozen by an older or newer
+akm that still decodes simply runs (with one warning). A newer akm's plan that
+does not decode is refused with a message naming "Upgrade akm".
+
+The durable plan records `sourceHash`, the sha256 of the workflow source file
+at freeze. It is used only for the resume warning below, never to refuse a
+run.
+
+Dispatch-significant material is immutable. The resolved request is frozen,
+the resolved target is frozen, and runner selection is frozen.
+Working directory (`cwd`) identity is frozen.
+Git identity and its commit OID are frozen. The executable a unit runs is
+resolved at dispatch, so upgrading a CLI (say, `claude`) never strands a run.
+Exact models, inference, tools and authorization,
+execution limits, parameter snapshots, command/script bytes, and verifier
+selection therefore cannot drift under an in-flight run.
+
+Workflow environment asset values are the narrow live-value exception within
+authored workflow inputs.
+The environment owner key set and secret-token topology are frozen.
+Literal values remain frozen. Pass-through bindings
+materialize at dispatch from the current process, and env/secret references
+materialize their current values only after owner/topology checks. Durable
+plans never store secret values or enable whole-process `inheritEnv`.
+
+**A run executes the plan compiled at creation; edits to source need a new
+run.** Resuming a run re-reads its workflow source only to warn, once, when
+the source changed since the freeze — the run continues on the frozen plan.
+Orchestration decisions are pure functions of the frozen plan, run params,
+and journaled results.
+
+## Child workflows
+
+A step that composes another workflow — directly (`uses: workflows/<ref>`)
+or through a task whose own target is a workflow (`uses: tasks/<ref>`) —
+freezes to a `child-workflow` frozen target. Unlike the `command`/`shell`/
+`script` targets, a `child-workflow` target carries the child's **complete
+frozen plan, embedded**: compiling the parent recursively compiles,
+validates, and freezes each child in full — depth-first, all of it — before
+the parent run is ever published. Nothing about a child is re-read at
+dispatch time; the embedded plan is authoritative. See
+[Workflow Schema: Child workflows](../reference/workflow-schema.md#child-workflows)
+for the authoring-side view, including the three composition bounds (depth,
+cycle, aggregate embedded bytes) enforced at freeze.
+
+**Decoding.** An embedded child plan is decoded by the same structural
+decoder as its parent, recursively. Its `planHash` and the target's
+`contentHash` are recorded provenance, carried as data and never re-verified
+against the bytes.
+
+**The dispatch seam.** Dispatching a step whose target is
+`kind: "child-workflow"` is the one branch point in
+`dispatchJournaledAttempt` (`src/workflows/exec/native-executor.ts`) that
+does not call the ordinary unit dispatcher: it calls
+`driveChildWorkflowUnit` instead, with everything the composing unit already
+resolved — the frozen target, the parent's dispatch context, the child's
+resolved params, and the unit input hash. The branch sits **inside** the
+existing retry loop, after the parent unit's attempt row is already claimed
+`running` (so a crash between claiming that row and publishing the child
+leaves a recoverable `running` parent unit and no orphaned child) and
+**before** the ordinary post-dispatch journaling (redaction, attempt
+finishing, the worktree epilogue), which runs unchanged either way — a
+child-workflow unit is journaled exactly like any other.
+
+**The drive contract.** `driveChildWorkflowUnit` validates and resolves the
+child's params through the same input-binding
+resolution every frozen target uses, computes the child's identity key from
+`{parentRunId, parentUnitId, unitInputHash}`, and publishes the child run —
+idempotently: the same three inputs always resolve to the same child row,
+so a retried or resumed composing step re-drives the run it already started
+rather than starting a new one, and only a change to the composing step's
+own inputs (params, an upstream step output it reads, or gate feedback from
+a rejected verification loop) produces a different child. A child found
+already `blocked` or `failed` is not re-driven — driving happens once per
+call, and a terminal-but-unhealthy child surfaces through the status mapping
+below instead. The child's final status maps onto the composing unit, and
+from there onto the parent step and run, exactly as described in [Workflow
+Schema: Child execution](../reference/workflow-schema.md#child-execution).
+
+**Why `runWorkflowSteps` is reused, not a second executor.** The child drive
+calls the exact same exported entry point `akm workflow run` calls —
+`runWorkflowSteps(options)`, pointed at the child's run id as `target` —
+with no special-casing for "this target is a child": resolving a run id,
+decoding the stored plan, taking that run's own lock, and walking its spine
+through `completeWorkflowStep` are identical to the top-level path. That
+reuse is what makes child run locks arbitrate two-parent contention with no
+new mechanism, and what makes a resumed parent skip a completed child step
+with zero dispatcher calls. The child drive passes a no-op
+`disposeDispatchResources` (the parent's `finally` remains the sole owner of
+the process-lifecycle drain for the whole process) and no `maxSteps` or
+`maxRetries` (the parent's own budgets count only its own spine steps). The
+lower-level `driveRun` that `runWorkflowSteps` wraps stays module-private —
+reaching for it directly, instead of the public entry point, would be
+exactly the second executor this design avoids.
+
+**Why `hashVersion` is 7, and why child composition did not move it.** The
+version prefix mixed into a unit's input hash is 7
+(`src/workflows/exec/step-work.ts`); 0.9.2 bumped it — a single, durable
+5 → 7 step, since every released tag on the line carries 5 — when
+`taskInputs`, the resolved values of a composed task's reference-kind
+`inputBindings`, joined the preimage (see [ADR
+0002](decisions/0002-unit-reuse-and-input-hash-scope.md)). Child composition
+itself contributed nothing to that bump: the parent unit's input-hash
+preimage already covers everything the child drive depends on — the frozen
+target carries the child's ref, plan hash, content hash, binding mode, and
+its entire embedded plan, so any change anywhere in the child changes the
+parent unit's own input hash transitively. The child run id (minted at
+dispatch) and its exported result are unit *outputs*, not inputs, so neither
+belongs in the preimage — adding either would be a hashing-boundary
+violation, not a fix.
+
+### Run outputs
+
+A workflow may declare `outputs:` — a run-level export projected from its
+steps' own artifacts once every step has finished (see [Workflow Schema:
+Workflow outputs](../reference/workflow-schema.md#workflow-outputs) for the
+authoring grammar). Resolution happens inside the same write transaction
+that completes the run's final step, immediately after the run's terminal
+status is derived: each declared output is resolved from the persisted step
+evidence and, if declared, validated against its schema. If resolution or
+validation fails for any entry, the **whole completion rolls back** — the
+run stays `active`, its final step stays `pending`, and no completion event
+is emitted — rather than leaving a run `completed` with missing or invalid
+exports. A run with no `outputs:` declaration exports `{runId, status}`
+instead, synthesized on read and never persisted. This exported result is
+exactly what a parent composing this workflow as a child promotes as the
+composing unit's own result on `completed` — the same value, read through
+the same function, whether the caller is `akm workflow status` or a parent
+unit's dispatch.
+
+## Resume skips completed units
+
+Resume never re-reads config or the asset index, and reads the workflow
+source only for the drift warning above. It consumes the frozen plan plus
+the journaled attempts and results. A stored plan that this akm cannot
+decode is not an error to fix in place: `akm workflow run` marks such a run
+abandoned (status `failed`) and says to start a new run with
+`akm workflow run <ref>`; `akm workflow status`, `list`, and `abandon` never
+read the plan at all. A plan frozen by a newer akm that this one cannot
+decode is left untouched, and the message names upgrading akm.
+
+Every dispatched unit is journaled under a content-derived identity — the
+node id plus a hash of its item for a map unit (`<node>:solo` otherwise) —
+together with an input hash over everything the unit was asked to do (its
+frozen instructions and target, declared `inputs:` artifacts, the params
+snapshot, gate feedback). On
+re-run, a unit whose journal row is `completed` is **reused**, never
+re-dispatched; a failed or missing unit is dispatched live. The recorded
+input hash is informational: a completed unit stays completed even when the
+params row or an upstream artifact changed since — a fresh run is what
+recomputes it.
+
+## Durable attempts and at-least-once dispatch
+
+Workflow dispatch is at-least-once. Every unit has a stable content-derived
+unit id and an append-only sequence of attempts.
+A crash reclaim reuses the same stable dispatchId for the interrupted attempt.
+An explicit retry gets a new dispatchId under one stable unit id and increments the attempt number.
+
+One driver per run (below) keeps a second engine off a run, and a finished
+attempt accepts no second terminal write, but neither can prove whether an
+external process completed immediately before a crash. An ambiguous crash
+outcome may re-run and can produce a duplicate side effect. Workflow actions
+should be idempotent or use the stable dispatch identity as their own
+deduplication key.
+
+## One engine drives a run (the run lock)
+
+`akm workflow run` takes the run's **lock file** before reading the plan or
+dispatching anything: one `O_EXCL` file per run id under the data directory
+(`workflow-run-locks/<run id>.lock`, next to `state.db`), recording the
+holder's pid, released when the invocation exits. A second `workflow run`
+against a run another live process holds refuses up front with
+`RUN_LEASE_HELD` (exit 75), naming the holder pid. A lock whose holder pid is
+dead is reclaimed at once, so a crashed engine never wedges a run; nothing
+expires by age and nothing renews. `workflow status` and `list` never take
+the lock.
+
+## Worktree isolation
+
+A file-mutating unit can declare `isolation: worktree` in its `unit:` bag
+(agent and sdk runners) — see
+[Workflow Schema: Frontmatter keys](../reference/workflow-schema.md#frontmatter-keys).
+Each unit attempt gets a fresh **detached git worktree** of the run's base
+repository under a run-scoped temp directory; the worktree path is journaled
+on the unit row and passed to the harness as its working directory, so
+parallel fan-out units can never trample each other's working tree. After the
+unit finishes, a clean worktree (`git status --porcelain` empty) is removed
+automatically; a dirty one is retained and its path logged, so uncollected
+work is never destroyed. Declaring worktree isolation in a non-git directory
+fails the step cleanly before anything dispatches.
+
+> **Warning — outputs matched by `.gitignore` are treated as disposable.** A
+> worktree-isolated unit's output survives only if it lands on a
+> **collectible path**: a tracked file, or an untracked file your repository
+> does **not** `.gitignore`. Anything a unit writes to a `.gitignore`d path —
+> build outputs, caches, logs, dependency directories like
+> `node_modules`/`dist`, or a scratch file under an ignored directory — is
+> **discarded** when its clean worktree is auto-removed. If a unit produces an
+> artifact that must survive, write it to a non-ignored path, or report it as
+> a result (a structured `output` / free-text result), before the unit
+> returns.
+
+The clean probe deliberately does **not** pass `--ignored`, so "uncollected
+work" means tracked or untracked-*unignored* changes only. A worktree whose
+only residue is files your repository's own `.gitignore` matches is treated
+as clean and removed: those files are disposable by the repo's own
+declaration, and retaining a worktree after every package install or build
+would blow up disk under the temp root.
+
+## Concurrency limits
+
+Native fan-out (`akm workflow run`) uses the minimum of four limits: the
+map's declared `concurrency`, the run's frozen `workflow.maxConcurrency`, the
+selected frozen LLM engine's `concurrency` (including an SDK engine's
+fallback LLM), and the current host's CPU-derived safety limit. Reapplying
+host safety keeps a run safe when it resumes on a smaller machine.
+
+- **Unset (default):** the CPU-derived value `min(16, max(1, cores − 2))` — a
+  conservative default that leaves headroom on the host and matches the
+  original Claude-Code cap.
+- **Set:** an explicit positive integer, clamped when frozen to `[1, 64]`
+  (values above 64 are clamped down, never rejected, so one config shared
+  across machines with different core counts never hard-fails).
+
+```console
+$ akm config set workflow.maxConcurrency 8   # raise the frozen workflow limit
+$ akm config get workflow.maxConcurrency
+8
+```
+
+A workflow that fans out is authorizing **N parallel agents**, not one — see
+[Running Workflows: workflow sources are executed code](../guides/run-workflows.md#security-workflow-sources-are-executed-code)
+for what that means for trust.
+
+## Run scope and persistence
+
+Run state (`plan_json`, `plan_hash`, step statuses, and the unit journal)
+persists in the project's `state.db`; the per-run lock file sits beside it. Run state is scoped to
+the current project directory — the nearest `.akm/config.json`, git root,
+bundle root, or current directory — so the same workflow can run
+independently in separate projects, and `akm workflow list`/`status` without
+an explicit run id only ever see runs in that scope.
+
+## See also
+
+- [Workflow Schema](../reference/workflow-schema.md) — exact frontmatter,
+  refs, gates, and outputs syntax
+- [Running Workflows](../guides/run-workflows.md) — start, inspect, resume,
+  and abandon a run
+- [Author's Guide: Writing Workflows](../guides/author-workflows.md) — writing
+  and testing a workflow definition

package/docs/guides/README.md

@@ -0,0 +1,33 @@
+# Guides
+
+Task-oriented guides and command tours for using akm.
+
+## Getting going
+
+- [Getting Started](getting-started.md) -- Quick setup guide
+- [Concepts](concepts.md) -- Bundles, adapters, asset types, and refs
+
+## Command tours
+
+- [Use AKM With Any Agent](use-with-any-agent.md) -- Wire akm into Claude Code, OpenCode, Cursor, and other coding assistants
+- [Discover and Load](discover-and-load.md) -- Build the index, search, curate a shortlist, and load assets by ref
+- [Bundles](bundles.md) -- Connect local dirs, git repos, npm packages, and websites; browse the registry
+- [Capture Knowledge](capture-knowledge.md) -- Capture memories, import docs, and store protected env/secret assets
+- [Improve the Library](improve-the-library.md) -- Feedback, history, proposals, and automated asset improvement
+
+## Running workflows
+
+- [Running Workflows](run-workflows.md) -- Start, continue, check on, resume, and abandon a workflow run
+- [Author's Guide: Writing Workflows](author-workflows.md) -- Markdown structure, a minimal complete example, and common authoring mistakes
+- [Scheduling](scheduling.md) -- Run `akm improve` and other background tasks through cron / launchd / schtasks safely
+
+## Building and sharing
+
+- [Bundle Author's Guide](author-bundles.md) -- Build and share a bundle on GitHub, npm, or a network directory
+- [Wikis](wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
+- [Claude Code workflows vs. akm workflows](claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
+
+## Recipes
+
+- [Turn a Website into a Searchable Bundle](recipes/website-source.md) -- Crawl a documentation site into markdown knowledge assets
+- [Headless Install](recipes/headless-install.md) -- A precise, no-prompts install sequence for automated or agent-driven setup

package/docs/guides/author-bundles.md

@@ -0,0 +1,310 @@
+# Bundle Author's Guide
+
+This guide walks through building a bundle, making it discoverable, and
+sharing it so others can install it with `akm bundle add`. It assumes you
+already know what a bundle is; see [Bundles](bundles.md) for the concept and
+[Reference: Asset Types](../reference/asset-types.md) for the full catalog of
+asset types, directory conventions, and per-type examples.
+
+## Create a Bundle
+
+A bundle is just a directory of assets. akm classifies each asset by **file
+extension and content**, so directory names are hints, not requirements — a
+`.sh` file is a script whether it lives in `scripts/`, `deploy/`, or the
+bundle root, and nesting is fully supported.
+
+```sh
+mkdir my-bundle && cd my-bundle
+mkdir scripts skills commands agents knowledge
+# add your assets, then verify locally
+akm bundle add .
+akm index
+akm search "deploy"
+```
+
+For the preferred directory layout, the full set of supported asset types
+(scripts, skills, commands, agents, knowledge, memories, workflows, tasks,
+env files, and more), and worked examples of each, see
+[Reference: Asset Types](../reference/asset-types.md).
+
+Add a `.meta/` directory at the bundle root to orient readers to the bundle
+*as a whole* — what it's for, where to start, conventions to follow. `.meta/`
+is a dot-directory, so the indexer skips it: these docs never appear in
+`akm search` and never compete for ranking. They're read directly with
+`akm show meta[:<name>]` (or `akm show <bundle>//meta[:<name>]` once
+installed). See [Reference: Asset Types](../reference/asset-types.md) for the
+`.meta/` layout and an example `index.md`.
+
+## Write Metadata for Discovery
+
+Metadata is not documentation for humans skimming your repo — it is the
+signal an agent's search ranking runs on. Write descriptions that describe
+*what the asset does and when to reach for it*, not just what it's named.
+
+Prefer metadata that travels with the asset itself, so it can't drift out of
+sync with the code:
+
+- Markdown assets: a `description` in frontmatter is extracted automatically
+  with high confidence.
+- Scripts: header comments (`@param`, `@run`, `@setup`, `@cwd`) keep
+  execution metadata next to the code it describes.
+- Everything else: filenames and a nearby `package.json` provide fallback
+  metadata when `akm index` runs.
+
+If you still have a legacy `.stash.json` sidecar, migrate its fields into
+inline metadata before publishing — see the
+[v0.7 → v0.8 migration guide](../migration/v0.7-to-v0.8.md) for the full
+field mapping and a worked example.
+
+**Keep `show` payloads focused.** `akm show` returns the whole asset body by
+default (the whole document for a knowledge asset, the whole `SKILL.md` for a
+skill). An agent that calls `show` pays for every token you put in that
+payload. Split long reference material into headed sections so agents can
+request one slug at a time (`akm show knowledge/guide#rate-limits`) instead of
+the entire document, and keep skills and commands scoped to one task rather
+than a bundle of unrelated instructions.
+
+**Separate reusable instructions from project-specific memory.** Skills,
+commands, and agents should describe how to do something in a way that holds
+up across projects. Anything that's true only for *this* project or *this*
+run — a decision made in a retro, a fact about the current deployment, a
+lesson learned from a failure — belongs in `memories/`, `facts/`, or
+`lessons/`, not baked into a skill's instructions. Mixing the two makes the
+reusable asset harder to reuse elsewhere and makes the project-specific
+context harder to find and prune later.
+
+**Give scripts and workflows explicit safety and parameter metadata.** AKM
+retrieves every supported capability type, but it only orchestrates execution
+surfaces it can reason about — scripts run through `@run`/`@setup`/`@cwd`
+declarations, workflows through their declared steps. Undocumented
+parameters or missing execution hints don't make an asset safer to skip; they
+make it a worse citizen of that boundary, forcing an agent (or a human) to
+guess what a script does before running it. Document every parameter with
+`@param`, declare the interpreter and working directory explicitly, and
+describe destructive or irreversible steps in the body text.
+
+## Test Before You Publish
+
+Before sharing, install your bundle locally and confirm the assets are both
+present and *findable*:
+
+```sh
+# Install from the local directory
+akm bundle add ./my-bundle
+akm bundle list
+
+# Exact-name lookups
+akm show scripts/deploy.sh
+
+# Realistic queries -- not just the asset's own name
+akm search "ship a release"
+akm curate "deploy the app to staging"
+```
+
+Testing only exact-name search hides ranking problems your users will hit
+immediately: someone looking for "deploy" won't necessarily type `deploy.sh`.
+Search with the phrasing you expect users (and agents) to actually use, and
+with `akm curate` for task-shaped queries. If results are poor or your asset
+doesn't surface, improve the description, tags, and search hints rather than
+renaming the file to match the query.
+
+Run `akm lint` before you publish. It catches structural problems (missing
+`name`/`type` on commands and agents, broken refs, malformed workflow
+structure, invalid task YAML) as well as the dangerous-env-key scan described
+in [Env Security](#env-security) below.
+
+```sh
+akm lint
+```
+
+## Version Bundles and Document Compatibility
+
+Use npm versions or GitHub releases so users can pin to a known-good state
+instead of tracking your default branch:
+
+```sh
+akm bundle add npm:pkg@1.2.3
+akm bundle add github:owner/repo#v1.2.3
+```
+
+Note in your `README.md` which `akm-cli` version(s) your bundle targets,
+especially if you rely on a feature that shipped recently (a new asset type,
+a frontmatter field, a lint rule). Breaking changes to your own bundle's
+layout deserve the same treatment you'd want from akm itself: a note in your
+changelog and, if the change is large, a short migration note for anyone
+pinned to the old layout.
+
+## Design for Local Customization
+
+Users are expected to fork individual assets out of your bundle rather than
+edit your source tree directly. `akm clone` copies one asset (or, for a
+skill, its whole directory) into the user's writable bundle or a custom
+`--dest`, and the local copy wins in subsequent searches from that point
+forward:
+
+```sh
+akm clone scripts/deploy.sh
+akm clone scripts/deploy.sh --dest ./project/.claude
+```
+
+Design assets so a clone-and-edit workflow actually works: keep parameters
+and setup steps explicit rather than hard-coded, avoid assumptions about
+paths outside the bundle, and prefer one asset per concern so a user can
+clone the one thing they need to change without dragging in unrelated
+behavior. See [`akm clone`](bundles.md#akm-clone) for the full command
+reference.
+
+## Publish Your Bundle
+
+Detailed, provider-by-provider behavior for `akm bundle add` (git, npm,
+filesystem, website) lives in [Bundles](bundles.md); the summaries below
+cover only what changes when you're the one publishing.
+
+### Sharing on GitHub
+
+1. Push your bundle to a GitHub repository.
+2. Add the `akm-stash` topic to your repo so it appears in registry search
+   (`gh repo edit --add-topic akm-stash`, or from repository settings under
+   "Topics").
+3. Others can now install it: `akm bundle add github:your-username/my-bundle`.
+4. To pin a version, tag a release and install with a `#ref`:
+   `akm bundle add github:your-username/my-bundle#v1.0.0`. Installs are
+   git-based — an unpinned add tracks the default branch, a `#ref` pins that
+   tag/branch/commit — and the latest-release tarball is used only as a
+   fallback when git access fails.
+
+### Sharing on npm
+
+1. Add a `package.json` with `"akm-stash"` in `keywords`.
+2. If your repo contains files that shouldn't ship (source, tests, CI
+   config), use `akm.include` to declare which paths to publish:
+
+   ```json
+   {
+     "name": "@your-scope/my-bundle",
+     "version": "1.0.0",
+     "keywords": ["akm-stash"],
+     "akm": { "include": ["scripts", "skills", "knowledge", ".meta"] }
+   }
+   ```
+
+   Paths are relative to `package.json`; only listed directories/files are
+   copied into the install cache, and `.git` is always excluded. Remember to
+   include `.meta` explicitly — dot-directories are otherwise easy to leave
+   out of a published tarball (a GitHub tarball install includes `.meta/`
+   automatically, without needing an allowlist).
+
+3. `npm publish --access public`.
+4. Others can now install it: `akm bundle add @your-scope/my-bundle`.
+
+### Sharing on a Network Directory
+
+For teams sharing assets without a registry, mount a bundle directly:
+
+```sh
+akm bundle add /mnt/shared/team-bundle
+```
+
+Assets appear in search results immediately, no further install step needed.
+See [Bundles](bundles.md) for adding a mounted source to
+`~/.config/akm/config.json` directly, and for write-safety behavior when a
+mounted or git bundle is marked `writable`.
+
+### Submitting to the Registry
+
+The official [akm-registry](https://github.com/itlackey/akm-registry) lists
+your bundle three ways: an npm package with `akm-stash` in `keywords`, the
+`akm-stash` GitHub topic on your repo, or a PR against `manual-entries.json`
+for a curated entry or override. Auto-discovered entries merge into
+`index.json` on the registry's build cycle; curated entries are reviewed
+before inclusion. For the registry's entry schema and how auto-discovered
+and curated entries are reconciled, see
+[Reference: Registry](../reference/registry.md).
+
+CLI-based submission (`akm` driving the PR) is planned for a future release.
+
+## Write-Safety Expectations
+
+Publishing a bundle does not make it writable by default. `akm bundle add`
+installs git, npm, and website bundles read-only unless the source is
+explicitly marked `writable` (filesystem sources are the exception — local
+directories are writable by default, opt out with `writable: false`), and
+only the primary bundle or a source resolved as writable accepts changes back (via `akm sync`, `akm clone --dest`, or
+`akm remember --bundle`). If you're publishing a bundle you expect other
+teams to write back into — not just install and read — say so in your
+`README.md` and document the `writable: true` configuration your users need.
+See [`akm sync`](bundles.md#akm-sync) for exactly what gets committed and
+when a push happens.
+
+## Env Security
+
+> The `vault` asset type was removed in 0.9.0; `env` replaces it. See the
+> [0.8 → 0.9 migration guide](../migration/v0.8-to-v0.9.md).
+
+If your bundle includes env files under `env/`, be aware of how `akm` handles
+them during install.
+
+**Dangerous key detection.** `akm bundle add` and `akm lint` scan env files for
+environment variable names that can be used to hijack process execution when
+the file is loaded via `akm env run`. The flagged names include `LD_PRELOAD`,
+`PATH`, `DYLD_INSERT_LIBRARIES`, `NODE_OPTIONS`, and 37 others (41 literal
+keys total), plus two pattern-based families (`BASH_FUNC_*`, Shellshock-class
+injection; `GIT_CONFIG_*`, git config override injection). When these keys
+are found, `akm bundle add` pauses in interactive mode and asks the user to confirm
+before continuing. In non-interactive (CI) mode the install fails unless the
+user passes `--allow-dangerous-env-keys`. `akm env run` applies the same scan at
+run time: a third-party-sourced bundle is refused unless that reviewed run
+explicitly passes `--allow-dangerous-env-keys`; a first-party bundle warns and
+proceeds.
+
+This is not a ban — it is a speed bump. If your bundle legitimately needs one
+of these keys (for example, a `PATH` override for a hermetic toolchain), do
+the following before publishing:
+
+1. Document the reason clearly in your `README.md`. Explain which key is set,
+   why it is needed, and what the value does.
+2. Run `akm lint` against your bundle locally to see the `dangerous-env-key`
+   findings before your users do (suppress a specific key with a
+   `# akm-lint-ok: dangerous-env-key` comment on the preceding line):
+
+   ```sh
+   akm lint
+   ```
+
+3. Consider whether the value can be set by the user after install rather than
+   shipped in the env file. Env files that ship without values — just key names
+   and comments — do not trigger the audit.
+
+**Key names are metadata, not secrets.** Env key names appear in `akm env list`
+and search results by design. Only values are protected. The `--sensitive` flag
+on `akm env create` excludes a file from both `env list` output and the search
+index; its key names then surface only when the file is shown directly by ref.
+
+## Bundle Structure Tips
+
+- **Keep it focused.** A bundle with 5 great scripts is more useful than one
+  with 50 mediocre ones.
+
+- **Write good descriptions.** The `description` field (preferably in
+  frontmatter, otherwise in script comments or `package.json`) is the primary
+  signal for search ranking.
+
+- **Use frontmatter in markdown assets.** A `description` in frontmatter is
+  extracted automatically with high confidence (0.9), making your commands,
+  agents, and knowledge documents more discoverable.
+
+- **Use structured header comments for scripts.** `.sh`, `.ts`, `.py`, etc. get
+  strong results from good filenames plus leading comments and tags like
+  `@param`, `@run`, `@setup`, and `@cwd`.
+
+- **Test the search experience.** After installing your bundle, search for it
+  using the terms you expect users to try, not just the asset's own name. If
+  results are poor, improve the descriptions, tags, and search hints.
+
+- **Document usage in the asset itself.** For skills, put the instructions in
+  `SKILL.md`. For commands, put the workflow in the markdown body. The agent
+  reads these directly.
+
+- **Version your bundle.** Use npm versions or GitHub releases so users can pin
+  to a known-good state with `akm bundle add npm:pkg@1.2.3` or
+  `akm bundle add github:owner/repo#v1.2.3`.