akm-cli 0.9.30 → 0.10.26101001-alpha

package/docs/posts/workflows-vaults-09.md

@@ -0,0 +1,321 @@
+---
+title: Agents That Remember Where They Were
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-workflows
+description: 'akm 0.5.0 adds workflow assets, vault assets, and a writable synced stash.'
+tags:
+  - ai
+  - agents
+  - cli
+  - workflows
+published: true
+id: 3538935
+date: '2026-05-05T02:19:50Z'
+---
+
+> This is a dated article from AKM's publishing archive. For current product behavior, see the
+> [documentation index](https://github.com/itlackey/akm/blob/main/docs/README.md).
+
+This is part nine in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. [Part one](https://dev.to/itlackey/your-ai-agents-skill-list-is-getting-out-of-hand-32ck) introduced progressive disclosure. [Part two](https://dev.to/itlackey/you-already-have-dozens-of-agent-skills-you-just-cant-find-them-bpo) unified your local assets across platforms. [Part seven](https://dev.to/itlackey) covered shared team skills via Git repos.
+
+Ask an agent to ship a release and it will start confidently. It runs the build, opens the changelog, checks the branch. Then something interrupts the session — you close the terminal, the context window fills up, you need to switch tasks. When you come back, the agent has no idea where it left off. You either restart from scratch or spend time reconstructing what happened.
+
+This is the central problem with agents and multi-step work. They're good at individual tasks. They're not naturally good at procedures — sequences of steps that span time, accumulate state, and need to be resumable when interrupted.
+
+`akm` ships three features that address this directly: workflow assets for stored, resumable procedures; vault assets for secret-aware environment config; and a writable git stash that keeps your skill collection in sync across machines. This post explains what each one does and how they fit together.
+
+## The Problem: Tasks Versus Procedures
+
+A task is "write this function." A procedure is "ship this release." Tasks have a beginning and end that fit inside a single context window. Procedures have steps, dependencies between steps, and state that persists across sessions.
+
+When agents handle procedures today, the state lives only in the conversation. That's fine for a five-minute task. It breaks down for anything that takes an hour, involves multiple sessions, or needs to be audited later. If something fails at step four of seven, there's no standard way to resume at step five without replaying the whole context.
+
+The workaround most developers reach for is a checklist in a markdown file. The agent checks off items as it goes. This works, but it's manual, fragile, and the state isn't queryable. You can't ask "which deployments are currently in-progress" if the state is scattered across markdown checkboxes in different files.
+
+Workflow assets are the structured version of that checklist.
+
+## Workflow Assets: Stored Procedures Your Agent Can Step Through
+
+Workflows live in `workflows/` in your stash. Each workflow is a markdown file with frontmatter declaring the procedure's parameters and a standard step format. You write the workflow once; the agent follows it on every run.
+
+Here's what a release workflow looks like:
+
+```markdown
+---
+description: Ship a production release
+params:
+  version: "The version to release (e.g. 1.2.3)"
+---
+# Workflow: Ship Release
+
+## Step: Validate inputs
+Step ID: validate
+### Instructions
+Check that version follows semver and that the release branch exists.
+### Completion Criteria
+- Version matches x.y.z
+- Branch release/{{ version }} exists
+
+## Step: Build
+Step ID: build
+### Instructions
+Run `bun run build` and verify dist/ was generated.
+
+## Step: Deploy to staging
+Step ID: staging
+### Instructions
+Run `./scripts/deploy.sh staging` and verify the health check passes.
+
+## Step: Deploy to production
+Step ID: production
+### Instructions
+Run `./scripts/deploy.sh production` after staging health check is green.
+```
+
+The workflow defines the procedure. To run it, the agent creates a *run* — an instance of that procedure with a specific set of params:
+
+```sh
+akm workflow start workflow:ship-release --params '{"version":"1.2.3"}' # doclint:ignore (historical workflow lifecycle removed in 0.9)
+# Returns a run ID: run-abc123
+```
+
+Now the procedure has state. The agent calls `akm workflow next` to get the current actionable step:
+
+```sh
+akm workflow next workflow:ship-release # doclint:ignore (historical workflow lifecycle removed in 0.9)
+# Returns: Step "validate" — Check that version follows semver...
+```
+
+When the agent completes a step, it marks it done with notes:
+
+```sh
+akm workflow complete run-abc123 --step validate --state completed --notes "Version 1.2.3, branch release/1.2.3 confirmed" # doclint:ignore (historical workflow lifecycle removed in 0.9)
+```
+
+`--state` defaults to `completed` when omitted, so the `--state completed` above is redundant but explicit.
+
+And the next call to `akm workflow next` returns the following step. The run persists independently of the conversation. If the session ends, a new agent picks up exactly where the previous one left off:
+
+```sh
+akm workflow next workflow:ship-release # doclint:ignore (historical workflow lifecycle removed in 0.9)
+# Returns: Step "build" — still in progress from the interrupted session
+```
+
+Want to see the full state of a run?
+
+```sh
+akm workflow status run-abc123
+```
+
+`workflow status` also accepts a workflow ref directly, resolving to the most-recently-updated run:
+
+```sh
+akm workflow status workflow:ship-release
+```
+
+Ref-based workflow commands are scoped to the current working context, not all
+workflow runs on the machine. In practice akm groups runs by the current
+project/worktree/directory, so an active run in one repo or sandbox does not
+block a different directory from starting its own run of the same workflow.
+
+That shows each step with its status and any notes the agent recorded. You can list all active runs:
+
+```sh
+akm workflow list --active
+```
+
+The procedure is now auditable. You know which step failed, when, and what the agent noted. You can hand the run off to a different agent or a different developer. The state is outside the context window where it's durable.
+
+If you need a starting point, `akm workflow template` prints a starter workflow doc you can adapt.
+
+### Resuming blocked or failed runs
+
+Sometimes a run gets blocked — a step requires human input, an external dependency is unavailable, or a tool call fails. When that happens, the run transitions to `blocked` or `failed`. Use `workflow resume` to flip it back to `active` without discarding progress:
+
+```sh
+akm workflow resume run-abc123
+```
+
+Completed runs cannot be resumed. Use `workflow list` to find runs by status.
+
+## Vault Assets: The Agent Knows What It Needs, Not What the Values Are
+
+Procedures that touch production environments need secrets — database URLs, API keys, deploy tokens. Putting those secrets in a skill file or a prompt is an obvious problem. But the agent still needs to know *which* secrets a given procedure requires.
+
+Vault assets solve this. A vault is a `.env` file stored in `vaults/` in your stash. The design has one rule: values are never surfaced in structured output. The agent can inspect a vault and learn what keys exist. It never sees what those keys are set to.
+
+```sh
+akm show vault:production
+# Returns keys/comments only, never values
+```
+
+This is enough for the agent to confirm "yes, the right secrets are configured for this environment" without the secrets appearing anywhere in the conversation or the context window.
+
+When a script actually needs the values — at runtime, not at planning time — the agent runs the command through `vault run`:
+
+```sh
+akm vault run vault:production -- ./deploy.sh  # doclint:ignore (historical — akm 0.5.0 release-era post; `vault` type removed in 0.9.0, see `env`/`secret`)
+```
+
+The values are loaded into the child process environment. They never pass through the agent's structured output. The agent's conversation log is clean.
+
+Combined with a workflow, this fits naturally into an environment verification step. The agent calls `akm show vault:production` to confirm all required keys are present, marks the step complete, then later calls `akm vault run vault:production -- <command>` when a command actually needs the secrets. The workflow knows what's required. The agent confirms it. The command gets what it needs.
+
+## Writable Git Stash: Your Skills Sync Like Code
+
+So far in this series, stashes have been read-only: you pull in a team repo or a remote source, and `akm` indexes it. In 0.5.0, a stash can be writable.
+
+When you create a stash with `--writable`, `akm save` will stage, commit, and push your changes back to the remote:
+
+```sh
+akm add git@github.com:your-org/skills.git --provider git --name team-skills --writable  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+```sh
+# After editing or adding an asset
+akm save team-skills -m "Add deploy workflow"  # doclint:ignore (historical — akm 0.5.0 release-era post; `save` renamed `sync` in 0.9.0, `-m` survives as `sync`'s own alias)
+```
+
+The behavior depends on the stash configuration:
+
+| State | What happens |
+| --- | --- |
+| Not a git repo | Skipped |
+| Git repo, no remote | Stage and commit only |
+| Git repo, has remote, writable: false | Stage and commit only |
+| Git repo, has remote, writable: true | Stage, commit, and push |
+
+Your default stash — the one `akm init` creates — is auto-initialized as a local git repo. So by default, `akm save` gives you a commit history of every change you've made to your skill collection, without requiring a remote. Add a remote and flip `writable: true` when you're ready to sync across machines.
+
+This changes how you think about managing your personal stash. It's not a pile of files in `~/.akm`. It's a versioned repository. You can see when you wrote a skill, what it looked like before you changed it, and whether your teammates have made updates since you last pulled.
+
+## How These Three Features Work Together
+
+Consider a deployment procedure that a team runs regularly. Before 0.5.0, you'd write a deploy skill and hope the agent followed the steps in the right order. With 0.5.0:
+
+**Step 1: Write the workflow once.**
+
+```sh
+akm workflow create ship-release
+# Edit workflows/ship-release.md with your team's exact steps
+```
+
+**Step 2: Add a vault with the production secrets.**
+
+The vault file lives at `vaults/production.env` in your stash. The keys are there; the values are managed separately through whatever secret management you use.
+
+**Step 3: Save both to the team stash.**
+
+```sh
+akm save team-skills -m "Add ship-release workflow and production vault"  # doclint:ignore (historical — akm 0.5.0 release-era post; `save` renamed `sync` in 0.9.0, `-m` survives as `sync`'s own alias)
+```
+
+Every developer on the team pulls the update with `akm update --all`. Now everyone has the same workflow and the same vault definition.
+
+**Step 4: When it's time to deploy, the agent runs the procedure.**
+
+```sh
+# Agent starts a run
+akm workflow start workflow:ship-release --params '{"version":"2.0.0"}' # doclint:ignore (historical workflow lifecycle removed in 0.9)
+
+# Gets the first step
+akm workflow next workflow:ship-release # doclint:ignore (historical workflow lifecycle removed in 0.9)
+# → "Validate inputs: confirm version and vault keys"
+
+# Checks the vault without reading secrets
+akm show vault:production
+# → keys/comments only, never values
+
+# Marks the step complete
+akm workflow complete run-xyz --step validate --notes "All keys present" # doclint:ignore (historical workflow lifecycle removed in 0.9)
+
+# Gets the next step
+akm workflow next workflow:ship-release # doclint:ignore (historical workflow lifecycle removed in 0.9)
+# → "Build: run bun run build..."
+```
+
+If the session ends at the staging step, a fresh agent picks up with:
+
+```sh
+akm workflow next workflow:ship-release # doclint:ignore (historical workflow lifecycle removed in 0.9)
+# → "Deploy to staging" — still pending from the previous session
+```
+
+No context reconstruction. No "where did we leave off?" The procedure state is in the workflow run, not the conversation.
+
+When the deploy is done, commit any skill or workflow improvements back to the team repo:
+
+```sh
+akm save team-skills -m "Improve staging health check step"  # doclint:ignore (historical — akm 0.5.0 release-era post; `save` renamed `sync` in 0.9.0, `-m` survives as `sync`'s own alias)
+```
+
+The team gets the improvement on next `akm update`.
+
+## Security Model
+
+Vault assets have a clear security contract. Understanding it prevents both
+false confidence and unnecessary alarm.
+
+**Values never leave disk via akm commands.** This is the core invariant.
+`akm show`, `akm vault list`, `akm search`, and every other structured output
+command expose only key names and comments — never values. The two supported
+paths that actually use values are `source "$(akm vault path vault:name)"` (the
+shell loads the file directly) and `akm vault run vault:name -- <command>`
+(values are injected into the child process environment). Neither path passes
+values through akm's structured output.
+
+**Key names are metadata — they are intentionally discoverable.** Key names
+appear in `vault list`, `vault show`, search results, and agent context by
+design. This is how an agent can confirm "yes, `DATABASE_URL` is configured in
+this vault" without seeing its value. Do not treat key names as secrets.
+
+**The `--sensitive` flag hides a vault from `vault list` only.** Creating a
+vault with `akm vault create prod --sensitive` prevents it from appearing in
+the default `vault list` output. It does not prevent key names from showing up
+in search results or when the vault is shown directly with `akm show
+vault:prod`. Use `--sensitive` to reduce noise, not to enforce secrecy.
+
+**Dangerous key detection.** Vault keys with names like `LD_PRELOAD`, `PATH`,
+`DYLD_INSERT_LIBRARIES`, or `NODE_OPTIONS` can be used to hijack process
+execution when the vault is loaded via `akm vault run`. `akm add` and
+`akm lint` both scan for these names. During install, `akm add` pauses and
+asks for confirmation when dangerous keys are found (non-interactive mode fails
+unless `--allow-dangerous-env-keys` is passed). The full list of 23 flagged key names is
+documented in the [CLI reference](../reference/cli.md#dangerous-env-key-audit).
+
+**When to use `--allow-dangerous-env-keys`.** Pass it to `akm bundle add` when
+you have reviewed a bundle manually and confirmed that a dangerous environment
+key is legitimate (for example, a hermetic toolchain that overrides `PATH`).
+Plain-HTTP transport is a separate decision and requires
+`--allow-insecure-transport`. Neither flag is a global config setting; each
+applies only to the single invocation.
+
+## Getting Started
+
+If you're on `akm` already, upgrade to the latest version:
+
+```sh
+npm install -g akm-cli@latest
+# or
+akm upgrade
+```
+
+The npm package requires Node.js >= 22. It prefers a working Bun >= 1.0 on
+`PATH` and otherwise uses Node.js; the standalone binary is runtime-free.
+
+To try workflows:
+
+```sh
+akm workflow template  # doclint:ignore (historical — akm 0.5.0 release announcement; `template` folded into `workflow create --print` in the 0.9.0 CLI overhaul)
+# Copy the output to workflows/your-first-workflow.md and edit it
+akm workflow create your-first-workflow
+akm workflow start workflow:your-first-workflow # doclint:ignore (historical workflow lifecycle removed in 0.9)
+```
+
+To add a vault, drop a `.env` file in `vaults/` in your stash. The format is standard `.env` — one `KEY=value` per line, comments with `#`.
+
+To make your default stash writable, add a remote to the git repo in `~/.akm/stash` and update your stash config with `--writable`. Run `akm save -m "Initial commit"` to verify it pushes.
+
+The repo is at [github.com/itlackey/akm](https://github.com/itlackey/akm). The [Getting Started guide](../guides/getting-started.md) covers initial setup if you're coming in new.
+
+Agents are most useful when they can handle real work end-to-end. Real work usually involves multiple steps, sensitive configuration, and sessions that get interrupted. Workflows, vaults, and a writable stash close those gaps. Give them a try on the next multi-step task you'd normally hand off with a checklist.

package/docs/product-surface.md

@@ -0,0 +1,54 @@
+# Product Surface
+
+Every akm feature, with its status. Status meanings are in
+[STABILITY.md](../STABILITY.md).
+
+> [!NOTE]
+> The 0.10 series makes every feature Stable or removes it.
+
+## Library
+
+- [Bundles](guides/bundles.md): add local folders, git repos, npm packages and websites. *Stable*
+- [Supported formats](reference/supported-formats.md): akm bundles, Claude Code and OpenCode folders, Agent Skills, wikis, websites. *Evolving*
+- [Registries](reference/registry.md): find bundles others publish. *Evolving*
+- Sync: commit and push a git-backed bundle. *Stable*
+
+## Find and load
+
+- [Search, curate, show](guides/discover-and-load.md): find assets and load one by ref. *Stable*
+
+## Capture
+
+- [Remember, import, clone](guides/capture-knowledge.md). *Stable*
+- Feedback: rate an asset or attach a fix. *Stable*
+- Lessons. *Experimental*
+
+## Improve
+
+- [`akm improve` and proposals](guides/improve-the-library.md): reviewable changes from feedback and usage. *Evolving*
+- Improve settings and strategies other than `default` and `consolidate`. *Experimental*
+- Automatic acceptance (opt-in). *Experimental*
+- Session extraction. *Evolving*
+
+## Monitor
+
+- Health. *Evolving*
+- Metrics. *Experimental*
+- Log, lint. *Evolving*
+
+## Run work
+
+- [Tasks and scheduling](guides/scheduling.md). *Evolving*
+- [Workflows](guides/run-workflows.md). *Experimental*
+- Agent dispatch and harnesses (Claude Code, Codex, OpenCode and others). *Evolving*
+- Model aliases. *Evolving*
+
+## Environment and secrets
+
+- [Read and inject](reference/env-and-secrets.md). *Stable*
+- Create and change. *Experimental*
+
+## Setup and maintenance
+
+- Install, setup, config, help, completions. *Stable*
+- Upgrade, including agent plugins and `--next`. *Evolving*

package/docs/reference/README.md

@@ -2,7 +2,8 @@
 
 Authoritative reference documentation for the akm CLI and its data.
 
-- [Bundle Types](bundle-types.md) -- Pointer page: where the bundle-format compatibility table and adapter internals now live
+- [Programmatic API](api.md) -- `akm-cli/api`: in-process `curate()` for the akm plugins
+- [Bundle Types](bundle-types.md) -- Supported bundle formats and compatibility
 - [CLI](cli.md) -- All `akm` commands and flags
 - [Configuration](configuration.md) -- Engines, strategies, bundles, and settings
 - [Supported Formats](supported-formats.md) -- Formats akm can index, from its own bundle layout to other tools' existing asset directories
@@ -17,4 +18,3 @@ Authoritative reference documentation for the akm CLI and its data.
 - [Website Sources](https://github.com/itlackey/akm/blob/main/docs/reference/website-sources.md) -- The pluggable fetcher API behind `akm import <url>` and other URL-based knowledge reads
 - [Data & Telemetry](data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
 
-See also: [akm-eval](https://github.com/itlackey/akm-eval) -- the evals and benchmarks for measuring whether `akm improve` is working, and the repo-root [Roadmap](https://github.com/itlackey/akm/blob/main/ROADMAP.md) -- high-level focus for upcoming releases.

package/docs/reference/api.md

@@ -0,0 +1,65 @@
+# Programmatic API (`akm-cli/api`)
+
+`akm-cli` is a CLI package. The one supported programmatic entry point is
+`akm-cli/api`, which exists so the akm plugins (OpenCode, Claude Code, ...) can
+do their automatic recall in-process instead of starting an `akm` process per
+prompt. Everything else in the package stays CLI-only: deep imports of
+`akm-cli/dist/*` are not an API, and the CLI is still the way to run every
+other command.
+
+```ts
+import { curate } from "akm-cli/api";
+
+const text = await curate("deploy to prod", { limit: 4, type: "skill", format: "text" });
+```
+
+## `curate(query, options?)`
+
+```ts
+function curate(
+  query: string,
+  options?: { limit?: number; type?: string; format?: "text" | "json" },
+): Promise<string>;
+```
+
+- **Result.** Exactly the stdout of
+  `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`,
+  including the trailing newline, computed in-process. `format` defaults to
+  `"json"`, as the CLI does. It runs the same code as the command (argument
+  validation, search, ranking, shaping and rendering are shared, not copied), so
+  the two cannot drift.
+- **Failure.** It rejects with an `Error` whose `message` is the CLI's error
+  text and whose `code` is the CLI's error code (`MISSING_REQUIRED_ARGUMENT`,
+  `INVALID_FLAG_VALUE`, `INVALID_CONFIG_FILE`, ...) wherever the CLI would have
+  failed. An unexpected internal failure rejects with a plain `Error` without a
+  `code`.
+- **No side effects on the host.** No child process; nothing is written to
+  stdout or stderr; `process.chdir` is never called; `process.env` and
+  `process.argv` are not modified; the host's quiet and verbose state is
+  unchanged afterwards. As with `akm curate`, the call records its usage
+  event in `state.db`.
+- **Repeated calls.** Config is re-validated against `config.json` on every
+  call (its path, size and modification time), so an edit on disk is seen by
+  the next call exactly as a separate CLI run would see it. Database handles are
+  opened and closed within each call. The local embedding model and the embedding
+  cache are kept for the life of the process, which is what makes a warm call
+  cheaper than a CLI run. Overlapping calls are safe. Under Bun the SQLite file
+  descriptors of a finished call are released when the garbage collector
+  finalizes its statements, so they can briefly outlive the call.
+
+## Loading it
+
+`package.json` `exports` maps `akm-cli/api` to `dist/api.js` under Bun and to
+`dist/api-node.mjs` under Node (which registers the loader hook for the
+package's embedded `.md`/`.xml` assets before loading `dist/api.js`), with
+`dist/api.d.ts` for types. `akm-cli/package.json` and `akm-cli/dist/*` are also
+exported, so a plugin can locate the `akm` bin with
+`require.resolve("akm-cli/package.json")` and published plugin versions that
+deep-import `akm-cli/dist/commands/read/*.js` keep working.
+
+## Stability
+
+Evolving (see [STABILITY.md](../../STABILITY.md)): the export list only grows,
+and `curate()`'s parameters and result keep the contract above; the text it
+returns is the CLI's agent-shaped output and changes whenever that does.
+`tests/contracts/api-surface.test.ts` pins the export list.

package/docs/reference/asset-types.md

@@ -0,0 +1,166 @@
+# Asset Types
+
+Reference for the capability taxonomy the native `akm` adapter recognizes,
+the bundle directory layout, and the metadata every asset carries.
+
+## Contract
+
+- akm's own native format (the `akm` adapter) recognizes **fourteen asset
+  types**: script, skill, command, agent, knowledge, instruction, env,
+  secret, workflow, lesson, memory, task, session, and fact.
+- Scripts, knowledge, commands, agents, skills, and workflows are classified
+  by **file extension and content**, not by directory name. A `.sh` file is
+  a script whether it lives in `scripts/`, `deploy/`, or the bundle root; for
+  these types the conventional directory names below are an **opt-in
+  convention that improves indexing confidence**. The remaining types are
+  **directory-required**: env, secret, memory, lesson, fact, session, task,
+  and instruction assets are only discovered under their placement
+  directories (a memory-shaped `.md` outside `memories/` indexes as plain
+  knowledge).
+- `type` is not part of an asset's ref — the placement subdirectory carries
+  that signal. See [Refs](refs.md).
+- Ten additional *bundle formats* beyond akm's own (Claude Code and OpenCode
+  tool directories, OKF, LLM wikis, and more) are recognized, indexed, and
+  validated in place by their own adapters — see
+  [Bundle Types](bundle-types.md) for the full type-by-type table (purpose,
+  what the agent gets, and example ref) and the other-format read/write
+  picture.
+
+## Directory layout
+
+There's no required structure, but this skeleton is the opt-in convention:
+
+```text
+my-bundle/
+  scripts/        # Executable scripts (.sh, .ts, .js, .py, .rb, .go, etc.)
+  skills/         # Skill definitions (directories with SKILL.md)
+  commands/       # Slash commands (.md with $ARGUMENTS or agent frontmatter)
+  agents/         # Agent definitions (.md with model/tools frontmatter)
+  knowledge/      # Reference documents (.md)
+  instructions/   # Project guidance (.md)
+  env/            # Environment files (.env) — groups of related config, loaded whole
+  secrets/        # Secrets — one sensitive value per file (auth tokens, keys, certs)
+  workflows/      # Workflow sources (.md)
+  lessons/        # Distilled lessons (.md, see akm improve / proposals)
+  memories/       # Recalled context fragments (.md, see Memory reference)
+  facts/          # Durable bundle-level facts (.md)
+  tasks/          # Task source v4 scheduled or on-demand automation (.yml only)
+  sessions/       # Machine-placed indexed session summaries (.md)
+  .meta/          # Optional bundle orientation, not indexed (see "Bundle orientation" below)
+```
+
+LLM Wikis are a related but separate concept: a wiki is its own installable
+bundle (`akm bundle add github:team/research-wiki`), not a type-subdirectory
+inside a regular bundle. See [Wikis](../guides/wikis.md) for how akm
+recognizes and indexes them.
+
+## Classification taxonomy
+
+Scripts and knowledge are classified by **what they are**: a `.sh` file is a
+script; a plain `.md` file is knowledge. Commands and agents are classified
+by **how an LLM should use them**: a `.md` file with `$ARGUMENTS`
+placeholders is a command template; one with `tools` in its frontmatter is an
+agent definition. Workflow assets are `.md`, classified by `type: workflow`
+or placement. Skills are a
+**packaging convention**: a directory containing a `SKILL.md` file.
+
+See [Classification](../architecture/internals/classification.md) for the
+full specificity-based matching system.
+
+## Metadata field reference
+
+Metadata lives with the asset itself, not in a separate sidecar file:
+frontmatter for markdown assets, and structured comments for scripts. The
+indexer derives metadata from filenames, code comments, frontmatter, and
+`package.json`.
+
+See [Filesystem Layout](../architecture/internals/storage-locations.md) for
+the full field reference.
+
+### Bundle orientation: the `.meta/` convention
+
+A bundle may carry an optional `.meta/` directory at its root holding
+human-authored orientation for the bundle *as a whole* — purpose, key
+assets, conventions, maintainer. This is distinct from per-asset metadata,
+which still lives with each asset: `.meta/` never describes individual
+assets, only the bundle itself.
+
+```text
+my-bundle/
+  .meta/
+    index.md          # shown by `akm show meta` — the default orientation doc
+    about.md          # shown by `akm show meta:about`
+    conventions.md     # shown by `akm show meta:conventions`
+```
+
+Because `.meta/` is a dot-directory, the indexer skips it — these docs never
+appear in `akm search` and never compete for ranking. They are **direct-read
+on demand**:
+
+```sh
+akm show meta                       # working bundle's .meta/index.md
+akm show meta:about                 # working bundle's .meta/about.md
+akm show akm//meta                  # the primary bundle explicitly
+```
+
+`akm show <origin>//meta:<name>` resolves `<name>.md` first, then an
+extensionless `<name>`. The convention is open-ended: bundle owners add new
+docs by dropping files into `.meta/` — no configuration or code changes
+required. `akm bundle create` scaffolds a starter `.meta/index.md`.
+
+**Known gap:** an install-ref origin (`akm show github:owner/repo//meta`)
+does not currently resolve even for an installed bundle — origin resolution
+matches only derived installation ids, not raw install refs. Use `akm//meta`
+for the primary bundle, or the bundle key you gave it in `bundles`
+(`config.json`), not the original install ref.
+
+## Script execution (ExecHints)
+
+For script assets, akm resolves execution hints in this order:
+
+1. Header comment tags (`@run`, `@setup`, `@cwd`)
+2. Auto-detection from extension and nearby dependency files
+
+## Defaults
+
+- Directory placement is advisory for scripts, knowledge, commands, agents,
+  skills, and workflows; it is required for env, secret, memory, lesson,
+  fact, session, task, and instruction discovery.
+- A memory asset with no source directory pointed at it is written to the
+  working bundle by `akm remember`.
+- `facts/` holds durable bundle-level facts, including the organization,
+  backlink, and domain convention facts the bundle skeleton ships with (see
+  [Refs — namespacing](refs.md#namespacing)).
+
+## Security / persistence implications
+
+- `env` and `secret` assets carry protected values: key names are
+  discoverable, but values are never written to stdout, the index, or
+  structured output. See `STABILITY.md`'s "Protected env & secret values"
+  entry for the exact contract and the safe injection path
+  (`akm env run` / `akm secret run`).
+- All asset content is plain files inside the bundle directory — the search
+  index (`index.db`) is a derived, regenerable cache rebuilt by `akm index`;
+  it is never the source of truth for asset content.
+- `akm lint` only operates on writable sources, and `akm improve` on one of
+  them: the bundle it writes to (`--bundle`, else `defaultWriteTarget`, else the
+  working bundle). Read-only registry caches (`git`, `npm`, `website`) are
+  excluded from improvement and lint passes even when they are indexed.
+
+## Stability
+
+Per `STABILITY.md`: asset `type` is a free-form, open string — `--type`
+filtering is exact-match against an open set and deliberately unvalidated
+(an unrecognized type returns zero hits, not an error). The `lesson` asset
+type's schema (`when_to_use`, `description`) is stable, but its
+distillation triggers and ranking are Experimental tuning targets. See
+`STABILITY.md` for the full command- and surface-level tier index.
+
+## See also
+
+- [Concepts](../guides/concepts.md) — the four core ideas asset types fit into
+- [Refs](refs.md) — how a conceptId is built from an asset's placement
+- [Memory](memory.md) — the memory asset type's belief-state and derived-memory model
+- [Bundle Types](bundle-types.md) — every bundle format akm recognizes, not just its own
+- [Classification](../architecture/internals/classification.md) — the specificity-based matcher
+- [Filesystem Layout](../architecture/internals/storage-locations.md) — full metadata field reference

package/docs/reference/bundle-types.md

@@ -3,8 +3,7 @@
 This page has moved. AKM's bundle-format documentation is now split in two:
 the public compatibility table lives at
 [Supported Formats](supported-formats.md), and the adapter internals — probe
-order, the `BundleAdapter` interface, `placeNew()` wiring status, and the
-write allowlists — live at
+order, the `BundleAdapter` interface, and the write allowlists — live at
 [Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md).
 
 - [Supported Formats](supported-formats.md) — the format-by-format table:
@@ -13,7 +12,6 @@ write allowlists — live at
   `llm-wiki`, `claude`, `opencode`, `agent-skills`, `dotenv`,
   `akm-workflow`, `akm-task`, `website-snapshot`, `generic-files`).
 - [Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) — how AKM picks an
-  adapter for a bundle, the `BundleAdapter` interface contract, the current
-  `placeNew()` wiring status, the write allowlists that actually gate
+  adapter for a bundle, the `BundleAdapter` interface contract, the write allowlists that actually gate
   `akm remember`/`import`/`proposal accept`/etc., and per-adapter
   implementation caveats.