akm-cli 0.9.30 → 0.10.261001-beta

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`.