akm-cli 0.10.261016-beta → 0.10.261017-beta

package/docs/reference/env-and-secrets.md

@@ -1,22 +1,21 @@
 # Environment & Secrets
 
-Reference for `akm env` and `akm secret` — the two protected-value asset
-types. For task-oriented guidance on capturing knowledge in general, see
-[Capture Knowledge](../guides/capture-knowledge.md); this page states exact
-contract, defaults, and security behavior.
+Reference for `akm env` and `akm secret`, the two asset types for values that
+should not be printed. For task-oriented guidance on capturing knowledge in
+general, see [Capture Knowledge](../guides/capture-knowledge.md); this page
+states the exact behavior and defaults.
 
 ## env vs secret
 
 `akm env` manages a `.env`-backed group of configuration (a whole `.env` file
-loaded wholesale). `akm secret` manages a single standalone sensitive value —
-one value per file, mirroring Docker's secret model. There is no `akm vault`
-command; use `env` or `secret`.
+loaded wholesale). `akm secret` manages a single standalone sensitive value,
+one value per file, mirroring Docker's secret model.
 
 | | `env` | `secret` |
 | --- | --- | --- |
-| Purpose | configuration — related settings for an app/service | authentication — one sensitive value |
+| Purpose | configuration: related settings for an app or service | authentication: one sensitive value |
 | Holds | a `.env` file of many `KEY=value` pairs | one value per file |
-| Discoverable | key *names* (not values) | name only (the whole file is the value) |
+| Listed as | key *names* | name only |
 | Injects | many vars at once (`env run`) | one var (`secret run <ref> <VAR>`) |
 
 ## Addressing: the akm ref
@@ -29,28 +28,30 @@ the full ref (`secrets/<name>`, `env/<name>`). An unqualified ref resolves the
 way every unqualified ref does: the default bundle first, then installation
 priority.
 
-## Core security guarantee
+## What each command prints
 
-Values never appear in akm's structured output. `env list` and `akm show
-env/<name>` surface key names only — comment text is never surfaced either,
-since comments routinely contain commented-out credentials and are treated
-like values. `secret list` surfaces the secret's name only; the file content
-is never shown. Values reach a process only through the safe injection
-paths, `akm env run` and `akm secret run`, which pass values directly into
-the child process — never through akm's own stdout, the index, or `akm
-show`.
+- `akm env list` and `akm show env/<name>` print key names only: no values and
+  no comment text.
+- `akm secret list` prints secret names only.
+- `akm env path <ref>` prints the absolute path of the env file.
+- `akm env export <ref> --out <file>` writes a sourceable `export KEY='value'`
+  script to the file (mode 0600), single-quoting each value so shell
+  substitutions in the source `.env` become literal strings. It requires
+  `--out` and prints no values to stdout.
+- Values reach a process through `akm env run` and `akm secret run`, which
+  place them in the child process's environment.
 
 ```sh
 akm env create env/prod                   # create an empty .env group
 akm env create env/prod --from-file ./.env  # or ingest an existing .env
 
-# akm does not manage individual keys — edit the whole file with your own editor:
+# akm does not manage individual keys; edit the whole file with your editor:
 $EDITOR "$(akm env path env/prod --quiet)"
 
 akm env list
-akm show env/prod                         # key names only
+akm show env/prod                         # key names only (see "Indexing" below)
 
-# Inject the whole .env into a subprocess (never onto stdout):
+# Inject the whole .env into a subprocess:
 akm env run env/prod -- ./deploy.sh
 akm env run env/prod -- $SHELL            # interactive session with the env loaded
 akm env run env/prod --only DATABASE_URL -- ./migrate
@@ -63,11 +64,6 @@ akm secret run secrets/deploy-token GITHUB_TOKEN -- gh release create v1.0.0
 akm secret set secrets/deploy-token --bundle team --from-file ./token
 ```
 
-`env export --out <file>` writes a safe, sourceable `export KEY='value'`
-script (re-serialised single-quoted, so shell substitutions in the source
-`.env` become literal strings) — it requires `--out` and never prints values
-to stdout.
-
 ## The `${ref}` token
 
 Wherever akm substitutes a reference into a string it hands to a process or a
@@ -119,16 +115,40 @@ env file is bundle content and is not rewritten; write the full ref.
 config still reads it as `${secrets/name}` and names the key once, and `akm
 migrate apply` rewrites the file.
 
-## File modes and storage
+## Running commands
+
+`akm env run <ref> -- <command>` and `akm secret run <ref> <VAR> -- <command>`
+spawn the command directly (no shell) with the values added to its environment.
+They exit with the command's status and are exempt from `--format`.
+
+- `env run` takes `--only KEY,KEY` or `--except KEY,KEY` to choose which
+  variables are injected.
+- `--clean` starts the child with a minimal inherited environment (`PATH`,
+  `HOME`, locale and terminal basics) instead of the full parent environment;
+  `--inherit NAME,NAME` adds parent variables back (only with `--clean`).
+- A value in an env file may contain a `${ref}` token, which `env run` replaces
+  (see [The `${ref}` token](#the-ref-token)).
+- Injected values stay in the child's environment for its whole lifetime, so its
+  own subprocesses can read them, and the child decides what it writes to
+  stdout and stderr. For a long-lived process, point it at the secret file
+  (`<bundle>/secrets/<name>`) directly instead.
+- Installing a bundle is the trust decision: `env run`, `secret run` and
+  workflow `env:` bindings inject what the bundle's files define, including
+  keys such as `PATH` or `LD_PRELOAD`, from any bundle, with no warning, block
+  or flag. `akm lint` still reports such keys (`dangerous-env-key`,
+  non-blocking) so an author can review their own files.
+- Each run records an `env_access` or `secret_access` event with the key or
+  variable names.
+
+## Files and storage
 
-`.env` files are stored at mode 0600 under `env/` in the target bundle;
-standalone secrets are stored at mode 0600 under `secrets/`. A secret write
-is atomic under an exclusive per-secret lock held in akm's data directory;
-maximum secret size is 5 MB.
-Values never cross argv (no `/proc/cmdline` exposure). An `env` file or
-secret can carry a sibling `.sensitive` marker that excludes it from `list`
-output and from the search index entirely; the value remains usable via
-`run`.
+Env files live under `env/` and secrets under `secrets/` in the target bundle,
+with mode 0600. A secret is written under an exclusive per-secret lock held in
+akm's data directory. `akm secret set` reads the value from stdin by default,
+or from `--from-file` (byte-exact, multi-line allowed) or `--from-env <VAR>`,
+so the value is not on the command line. `akm env create --sensitive` adds a
+sibling `.sensitive` marker; an env file or secret with that marker is left
+out of `list` output and the search index, and `run` still works on it.
 
 An env file or secret may be a symlink to a file anywhere else, such as a
 container's `/run/secrets/<name>`: `akm env`, `akm secret`, `${secrets/name}`
@@ -136,59 +156,36 @@ substitution and a workflow `env:` binding follow it. A name still cannot climb
 out of `env/` or `secrets/` with `..` or an absolute path. Writes never follow
 a symlink out of the bundle.
 
-## Write-target resolution
+### Indexing
 
-Env/secret **mutations** (`env create`, `env remove`, `secret set`) choose
-their write destination like every other write command: an explicit
-`--bundle <source>` wins, else `defaultWriteTarget`, else the working
-bundle. The chosen source must be writable — a non-writable target fails
-with a `ConfigError` before anything is written — and a git-backed writable
-target commits the mutation at a single operation boundary. Reads (`list`,
-`show`, `path`, `run`, `export`) still span all configured sources.
-
-## Subprocess residency
-
-`akm env run` and `akm secret run` inject values directly into the child
-process — never through a shell — but the child controls its own
-stdout/stderr, so a command that prints its own environment will still leak
-values into your terminal or agent transcript. Injected values live in the
-child process environment for its entire lifetime and are visible to every
-subprocess the child spawns.
-
-- Prefer `akm secret run secrets/<name> <VAR> -- <command>` over `akm env
-  run` when a command only needs one value.
-- Avoid `env run` / `secret run` for long-lived daemon or server processes;
-  for those, point the process at the secret file directly
-  (`<bundle>/secrets/<name>`) so the value never sits in a process
-  environment variable at all.
-- Avoid running commands that print the environment (`env`, `printenv`,
-  shell tracing, verbose diagnostics) in agent contexts unless you
-  explicitly intend to expose the child environment.
-- Installing a bundle is the trust decision: `env run`, `secret run` and
-  workflow `env:` bindings inject what the bundle's files define, including
-  keys such as `PATH` or `LD_PRELOAD`, from any bundle, with no warning, block
-  or flag. `akm lint` still reports such keys (`dangerous-env-key`,
-  non-blocking) so an author can review their own files.
+`akm bundle create` makes the bundle a git repository whose `.gitignore` lists
+`env/` and `secrets/`, so those files are never committed. The indexer skips
+git-ignored files everywhere else, but it still indexes the files under a
+bundle's `env/` and `secrets/` directories when git ignores them: `akm search
+--type env` and `akm show env/<name>` find an env file of a default bundle after
+`akm index`. The index holds key names only for an env file and the name for a
+secret; values are never indexed. `env list`, `env path`, `env export`,
+`env run`, `secret list` and `secret run` read the files directly and do not
+need the index.
 
-## Stability
+## Write-target resolution
 
-`env list`, `env path`, `env export`, `env run`, `secret list`, and `secret
-run` — the read-and-inject surface — are Stable. `env create`, `env remove`,
-and `secret set` — the write verbs — are Experimental. Check
-[STABILITY.md](../../STABILITY.md) for the current tier of any command
-before depending on its exact output shape.
+Env and secret mutations (`env create`, `env remove`, `secret set`) choose their
+destination like every other write command: an explicit `--bundle <source>`,
+else `defaultWriteTarget`, else the working bundle. The chosen source must be
+writable, or the command fails with a `ConfigError` before anything is written;
+a git-backed writable target commits the mutation at a single operation
+boundary. Reads (`list`, `show`, `path`, `run`, `export`) span all configured
+sources.
 
-## What this page does not cover
+## Stability
 
-This page documents akm's own guarantees for these two asset types, not the
-broader threat model (what a compromised bundle or malicious script could
-still do, what filesystem-level exposure remains, how this compares to a
-dedicated secrets manager). See [SECURITY.md](../../SECURITY.md) for that
-fuller picture, including plaintext-at-rest scope and rotation guidance.
+`env list`, `env path`, `env export`, `env run`, `secret list` and `secret run`
+are Stable. `env create`, `env remove` and `secret set` are Experimental. See
+[STABILITY.md](../../STABILITY.md).
 
 ## See also
 
-- [Capture Knowledge](../guides/capture-knowledge.md) — `remember`, `import`,
-  and when to reach for each
-- [CLI Reference](cli.md) — full flag documentation for `env` and `secret`
-- [SECURITY.md](../../SECURITY.md) — full threat model
+- [Capture Knowledge](../guides/capture-knowledge.md): `remember`, `import`, and
+  when to reach for each
+- [CLI Reference](cli.md): the `env` and `secret` commands

package/docs/reference/memory.md

@@ -115,7 +115,7 @@ automation keeps working — agents that want the deeper summary follow
 - `akm search --belief` and `akm curate --belief` default to `current`; pass
   `--belief all` (API `belief: "all"`) for every belief state.
 
-## Security / persistence implications
+## Storage
 
 - Memories are plain markdown files inside a bundle directory; there is no
   separate memory store. `akm improve` and `akm lint` only operate on

package/docs/reference/refs.md

@@ -6,10 +6,9 @@ rename semantics, and namespacing conventions.
 ## Contract
 
 A **ref** is a compact handle identifying one capability. Agents should
-treat refs as opaque tokens — get them from search or curate, pass them to
-show. The structured `conceptId` and `bundle` fields in search results
-provide the same information in parseable form; never parse a ref string by
-hand.
+treat refs as opaque tokens: get them from search or curate, pass them to
+show. Search hits do not carry the bundle and conceptId as separate fields;
+pass `ref` to `akm show` as it is instead of parsing it by hand.
 
 ## Grammar
 
@@ -21,21 +20,18 @@ hand.
 | --- | --- | --- |
 | `bundle` | no | Narrows lookup to one installed bundle, separated from the rest of the ref by `//`. Omit it and the ref resolves against the workspace `defaultBundle`, then the remaining bundles in installation-priority order. |
 | `conceptId` | yes | Subdir-qualified within its bundle: the placement subdirectory followed by the item's canonical name (extension stripped for markdown-like types; scripts and secrets keep their natural filename). `type` is not part of a ref — the subdirectory carries that signal. |
-| `fragment` | no | A selector for part of the item. Input-only — never stored. |
+| `fragment` | no | A selector for part of the item, such as a markdown heading. `akm show` is the only command that accepts it; every other command rejects a ref that carries one. Input-only, never stored. |
 
 Examples: `scripts/deploy.sh`, `agents/reviewer`, `knowledge/api-guide`,
 `workflows/ship-release`, `team-catalog//scripts/deploy.sh`,
 `personal//knowledge/guide`, `knowledge/api-guide#authentication`.
 
 Source locators like `github:owner/repo` and `npm:@scope/pkg` are **install
-refs**, a distinct grammar accepted only by `akm bundle add` and `akm
-clone`. They are not asset refs and are never addressable through `akm
-show`.
+refs**, a distinct grammar for `akm bundle add` and `akm clone`. They are not
+asset refs and `akm show` does not accept them.
 
-This reference page is deliberately non-normative prose over the same
-grammar; [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md)
-is the normative spec, including the `parseBundleRef` grammar, fragment
-resolution rules, and reserved-name handling.
+The full grammar, fragment resolution rules and reserved names are in
+[`docs/architecture/specs/ref.md`](../architecture/specs/ref.md).
 
 ## Namespacing
 
@@ -51,8 +47,8 @@ knowledge/clientX/api-guide.md   →  knowledge/clientX/api-guide
 ```
 
 This works for **any** asset type. The subpath segments become part of the
-conceptId, so `akm search "projectA" --type memory` narrows results to that
-subtree, and `akm show memories/projectA/auth-tip` resolves the full ref.
+conceptId, so `akm search "memories/projectA/"` lists that subtree and
+`akm show memories/projectA/auth-tip` resolves the full ref.
 
 There is also a **ref-prefix query syntax** — a query that is a conceptId
 prefix ending in `/` enumerates that subtree instead of keyword-matching:
@@ -72,8 +68,7 @@ output and paste it back as a query. A complete ref
 (`memories/projectA/auth-tip`, no trailing `/`) stays an ordinary keyword
 search — resolving a single ref is `akm show`'s job.
 
-**Recommendation:** use physical subdirectories now to organize multi-project
-or multi-team bundles. They sort cleanly on disk and require no
+Use physical subdirectories to organize multi-project or multi-team bundles. They sort cleanly on disk and require no
 configuration.
 
 **Which subdirectory?** Choose the partition axis by asset **type**:
@@ -84,8 +79,7 @@ current **project/client** slug; reuse-born types (`knowledge`, `skill`,
 limits, no-volatile-facets, off-axis facets as tags, and how to cross-link
 for retrieval — ship as the `facts/conventions/organization`,
 `facts/conventions/backlinks`, and `facts/conventions/domains` convention
-facts in the bundle skeleton, and are surfaced to agents automatically at
-authoring time.
+facts in the bundle skeleton.
 
 ## Renames and moves
 
@@ -102,16 +96,13 @@ akm lint          # confirms nothing dangles
 ```
 
 Moving an item between bundles is copy/import followed by deletion from the
-source — both the bundle and the concept identity change. `akm mv`, which
-promised identity-preserving renames, was removed in 0.9.0: its inbound-ref
-rewriting targeted bare conceptIds rather than the anchored
-`bundle//conceptId` prose form, so it could rewrite non-refs while leaving
-real refs dangling. The procedure above is the only supported path today.
+source; both the bundle and the concept identity change. There is no
+`akm mv`.
 
-To carry an asset's earned signal (feedback, usage, salience/outcome
-history) across a rename, the maintainer script `scripts/rekey-asset-ref.ts`
-re-keys those rows onto the new ref before `akm index` runs; it is Internal
-tooling, not a supported command surface.
+To carry an asset's earned signal (feedback, usage, salience/outcome history)
+across a rename, the maintainer script `scripts/rekey-asset-ref.ts` re-keys
+those rows onto the new ref before `akm index` runs. It is internal tooling,
+not a supported command.
 
 ## Refs in prose
 
@@ -122,18 +113,14 @@ conceptId in prose is ordinary text, not a ref, and no akm tool rewrites it.
 
 ## Stability
 
-Per `STABILITY.md`, this is **Stable** surface: the
-`[bundle//]conceptId[#fragment]` grammar (durable state always stores the
-fully-qualified `bundle//conceptId`; the short form is accepted input only),
-conceptId-prefix enumeration, and the rename-is-delete-plus-create procedure
-are all named explicitly in the Stable tier, and the ref grammar is called
-out as frozen at 1.0 alongside the supported source model, search behavior,
-and write-target rules. See `STABILITY.md` for the full command- and
-surface-level tier index.
+The `[bundle//]conceptId[#fragment]` grammar, conceptId-prefix enumeration and
+the rename procedure are Stable per [STABILITY.md](../../STABILITY.md). Durable
+state always stores the fully-qualified `bundle//conceptId`; the short form is
+accepted input only.
 
 ## See also
 
 - [Concepts](../guides/concepts.md) — where refs fit in the retrieval loop
 - [Asset Types](asset-types.md) — how a conceptId's subdirectory maps to an asset type
 - [Memory](memory.md) — parent/derived-memory provenance backrefs
-- [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the normative ref grammar spec
+- [`docs/architecture/specs/ref.md`](../architecture/specs/ref.md) — the ref grammar spec