akm-cli 0.9.30 → 0.10.261001-beta

package/docs/posts/intro-part-04.md

@@ -0,0 +1,221 @@
+---
+title: Your Agent Doesn't Know What the Community Already Figured Out
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: How to connect your agent to curated community knowledge with the Context Hub integration
+tags:
+  - ai
+  - agents
+  - cli
+  - skills
+published: true
+id: 3363736
+date: '2026-03-18T18:09:15Z'
+---
+
+> 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 four in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. In [part one](https://dev.to/itlackey/your-ai-agents-skill-list-is-getting-out-of-hand-32ck), I covered why progressive disclosure beats dumping everything into context. [Part two](https://dev.to/itlackey/you-already-have-dozens-of-agent-skills-you-just-cant-find-them) showed how `akm` unifies your local assets across platforms into one searchable stash. [Part three](https://dev.to/itlackey/your-agents-memory-shouldnt-disappear-when-the-session-ends) added remote context via OpenViking for teams that need persistent, shared knowledge. *(note: OpenViking is not supported in akm v1 — see Part three's deprecation notice for details)*
+
+All of that assumed you were building your own library from scratch. Your skills. Your knowledge docs. Your team's accumulated context. That's fine — and it's necessary — but it ignores a much larger resource: everything everyone else has already built.
+
+Right now, there are high-quality skills and knowledge documents sitting in public repositories that solve problems you're going to hit next week. Prompt-chaining patterns. API integration guides. Framework-specific coding conventions. Stuff that experienced practitioners have refined and published, ready to use. Your agent has no idea any of it exists.
+
+That's what the [Context Hub](https://github.com/andrewyng/context-hub) integration fixes.
+
+## What Is Context Hub?
+
+Context Hub is a public GitHub repository — originally curated by Andrew Ng's team — structured specifically for agent consumption. It organizes community-contributed knowledge and skills into a browsable, searchable hierarchy under a `content/` directory. Each entry is either a `DOC.md` (knowledge) or a `SKILL.md` (skill), with frontmatter metadata for descriptions, tags, languages, and versions.
+
+Think of it like a curated package registry, except instead of code libraries, it's agent context. Each document is a self-contained piece of knowledge or a skill definition that any agent can pick up and use immediately. No installation, no dependencies, no build step.
+
+The structure is intentionally simple:
+
+```
+content/
+  openai/
+    docs/
+      chat-api/
+        python/
+          DOC.md
+    skills/
+      prompt-chaining/
+        SKILL.md
+  anthropic/
+    docs/
+      tool-use/
+        typescript/
+          DOC.md
+```
+
+Every entry gets indexed into the same search pipeline as your local assets, which means `akm` can search and display it the same way it handles anything else in your stash.
+
+## One Command to Connect
+
+If you already have `akm` installed:
+
+```bash
+akm add context-hub  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+That's the full setup. Under the hood, this adds the default Context Hub repository as a git source. It downloads the repo as an archive, extracts it into a local cache, and on the next `akm index`, every `DOC.md` and `SKILL.md` gets indexed into the same FTS5 search pipeline as your local assets.
+
+The cache refreshes automatically every 12 hours. If the network is down, it falls back to stale cache for up to 7 days. Your local stash still works regardless — the Context Hub provider degrades gracefully without taking anything else down with it.
+
+Verify it's registered:
+
+```bash
+akm list  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+You should see `context-hub` in the list alongside your local stash directories and any other providers you've configured.
+
+## Search Works the Same Way
+
+Here's what changes in practice: nothing about your workflow. You still run `akm search`. The difference is that results now include entries from Context Hub alongside your local assets.
+
+```bash
+akm search "prompt chaining patterns"
+```
+
+This might return a local skill you wrote last month *and* a community-contributed skill from Context Hub. The results are unified — same ranking, same format, same `type:name` refs. Context Hub assets go through the same scoring pipeline as everything else. No special handling, no second-class results.
+
+Want to narrow it down to just skills?
+
+```bash
+akm search "api integration" --type skill
+```
+
+Or just knowledge documents?
+
+```bash
+akm search "coding standards" --type knowledge
+```
+
+The type filter applies across all sources — local, remote, and Context Hub alike.
+
+## Show Works Too
+
+When you find something useful, load it the same way you'd load any other asset:
+
+```bash
+akm show skill:prompt-chaining
+```
+
+Your agent gets the full content — frontmatter, description, the complete skill definition — in the same format as every other `akm show` result. It doesn't need to know the asset lives on GitHub. It doesn't need a GitHub token. It just works. The ref is `type:name`, same as a local asset.
+
+Context Hub assets support the same view modes as local knowledge docs:
+
+```bash
+# Table of contents
+akm show knowledge:chat-api toc
+
+# A specific section
+akm show knowledge:chat-api section "Authentication"
+
+# A line range
+akm show knowledge:chat-api lines 10 25
+```
+
+For large documents, the `toc` and `section` views keep context lean. Your agent can scan the table of contents first, then pull only the section it needs. Progressive disclosure all the way down.
+
+## Custom Context Hub Repositories
+
+The default `akm add context-hub` points at Andrew Ng's repository, but you're not limited to that. Any GitHub repository works as a git source — you don't need to follow a specific directory convention. `akm` walks the repo, classifies files by type, and indexes everything.
+
+Say your organization maintains an internal knowledge base for agent context — API references, architecture decisions, coding standards:
+
+```bash
+akm add https://github.com/your-org/team-knowledge --provider git --name "team-knowledge"  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+Now `akm search` queries your team's knowledge base alongside the public Context Hub and your local stash. All in one search. You can add as many git sources as you want — each gets its own cache and index.
+
+Need a specific branch instead of `main`?
+
+```bash
+akm add https://github.com/your-org/team-knowledge/tree/staging --provider git --name "team-staging"  # doclint:ignore (historical — pre-0.9.0 command spelling)
+```
+
+The provider parses the GitHub URL and pulls the right branch automatically.
+
+## What Your Agent Actually Sees
+
+This is where the pieces from the whole series come together. After four posts, here's what a fully-wired `akm search` looks like from your agent's perspective:
+
+```bash
+akm search "deploy containers to production"
+```
+
+Results might include:
+
+1. A local script from your primary stash — the deploy script you wrote last month
+2. A team skill from an installed GitHub stash — the Docker Compose workflow your teammate packaged
+3. A knowledge doc from OpenViking — the architecture decision about container orchestration from last sprint *(note: OpenViking is not supported in akm v1 — see Part three's deprecation notice for details)*
+4. A community skill from Context Hub — a battle-tested container deployment pattern that 50 other people have already vetted
+
+Four different sources. One result set. One `akm show` command to load whichever one the agent needs. Everything else stays out of context.
+
+The agent doesn't need to care about where an asset lives. Local file, managed source, OpenViking server, git repo — every result uses the same `type:name` ref. The agent searches, picks, loads, and gets to work.
+
+## The Full Stack
+
+Here's what the complete setup looks like after four posts:
+
+```bash
+# Install
+curl -fsSL https://raw.githubusercontent.com/itlackey/akm/main/install.sh | bash
+akm setup
+
+# Local platform assets
+akm add ~/.claude/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add .opencode/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add .cursor/rules  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Community and team stashes
+akm add github:your-org/team-agent-toolkit  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add @scope/deploy-skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Community knowledge (Context Hub is just a git repo)
+akm add context-hub  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Team knowledge (any git repo works)
+akm add https://github.com/your-org/team-knowledge --provider git --name team-knowledge  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Remote context server
+akm add https://your-viking.internal:1933 --provider openviking --name team-context --options '{"apiKey":"..."}'  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Build the local index
+akm index
+```
+
+Drop the `AGENTS.md` snippet into every project:
+
+```markdown
+## Resources & Capabilities
+
+You have access to a searchable library of scripts, skills, commands, agents,
+knowledge, and memories via the `akm` CLI. Use `akm -h` for details.
+```
+
+And your agent has access to everything: local skills, platform assets, team stashes, community registries, remote knowledge, persistent memories, and curated community context. One search, one interface.
+
+## Why This Matters
+
+The value of agent skills and knowledge compounds when it's shared. A prompt-chaining pattern that one person refines over a weekend becomes infrastructure when a thousand agents can find it. A coding standard document that one team writes becomes a community resource when it's discoverable from any stash.
+
+Context Hub isn't the only way this will happen — community registries, marketplace-style discovery, and decentralized skill sharing are all coming. But it's working today, it's open source, and it plugs directly into the same `akm search` / `akm show` workflow you're already using.
+
+If you've written skills or knowledge docs worth sharing, consider contributing them to [Context Hub](https://github.com/andrewyng/context-hub). Structure them with frontmatter, put them in a `content/` directory, and they become searchable for every agent running `akm`.
+
+The repo is at [github.com/itlackey/akm](https://github.com/itlackey/akm). Context Hub is at [github.com/andrewyng/context-hub](https://github.com/andrewyng/context-hub). If you've got a team knowledge base in a git repo, add it as a git source and let me know how it holds up.
+
+---
+
+*__Update (March 2026):__ This post was updated to reflect akm's current CLI. `akm add` replaces the earlier `akm stash add` for adding sources (including git and OpenViking providers), `akm setup` replaces `akm init`, and `akm list` replaces `akm stash list`. Sources (formerly "stash sources") are now managed through a single `akm add` / `akm remove` interface. If you're following along with an older version, `akm upgrade` will get you current.*
+
+
+---
+
+> **Note (2026-04-23):** This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a *kit* and the *Kit Maker's Guide*; those terms have been renamed to *stash* and *Stash Maker's Guide* throughout. The pre-rename text is preserved in this repository's git history.

package/docs/posts/llm-mode-reflect-13.md

@@ -0,0 +1,166 @@
+---
+title: 'From 30 Minutes to 8: How LLM-Mode Reflect Works'
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-knowledge
+description: 'The reflect pass inside akm improve dropped from ~35 minutes to ~8 minutes per 69-ref run. Here is what changed: direct HTTP calls, multi-turn self-refine, and structured JSON output — with no agent subprocess in sight.'
+tags:
+  - ai
+  - agents
+  - performance
+  - localai
+published: true
+id: 3814543
+date: '2026-06-04T00:32:02Z'
+---
+
+> 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 thirteen in a series about managing the growing pile of skills, scripts, and context that AI coding agents depend on. [Part ten](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d) covered the full improve pipeline — all five phases and how they connect. [Part fourteen](https://dev.to/itlackey/your-agent-has-a-memory-that-runs-while-you-sleep-20oh) covers what 48 runs per day looks like in practice, including hardware benchmarks and the reliability bugs that surface at that frequency.
+
+The reflect pass inside `akm improve` has three execution modes. Most installs are still running the slowest one.
+
+Agent mode — the original — spawns an opencode or claude subprocess for each reflect call. The subprocess starts cold, acquires a session, assembles context, makes its LLM call, and exits. That cold-start overhead is real: each call takes approximately 30 seconds on a quiet machine. Run `akm improve` against a 69-ref stash and the reflect phase alone costs about 35 minutes.
+
+SDK mode eliminated the subprocess. The reflect call runs in-process, cutting per-call latency to 10–15 seconds. A 69-ref run drops to 12–17 minutes — better, but still bounded by round-trip overhead that the reflect task does not actually need.
+
+LLM mode removes the round trip entirely. The context for reflect is statically pre-assembled — no live tool calls, no file reads, no external context needed. A direct HTTP call to the LLM endpoint is sufficient, and it costs 6–10 seconds per call. A 69-ref run completes in 8–10 minutes.
+
+| Mode | Per-call latency | 69-ref run |
+|------|-----------------|------------|
+| agent (CLI subprocess) | ~30s | ~35 min |
+| sdk (in-process) | ~10–15s | ~12–17 min |
+| llm (direct HTTP) | ~6–10s | ~8–10 min |
+
+The 3–4× end-to-end improvement is from eliminating overhead that was never necessary for what reflect does.
+
+## Why Reflect Does Not Need an Agent
+
+The reflect pass takes a stash asset, examines its current content, and proposes a refined version. The inputs are fixed before the pass starts: the asset text, its metadata, and the improvement prompt. Nothing changes mid-call. No files need to be opened. No search queries need to fire. No external context needs to be pulled in.
+
+Agent mode was useful when akm's improve pipeline was first built — the agent subprocess was already the primary execution model, and reflect rode along. But the properties that make agents valuable (tool use, live context access, multi-step reasoning over changing state) are not exercised by reflect. Spawning a full agent process for a stateless inference call trades 20+ seconds of overhead for no quality benefit.
+
+LLM mode makes the execution match the task: assemble the context once, make one HTTP call, get the result.
+
+## Multi-Turn Self-Refine
+
+LLM mode adds a capability that agent mode does not have: multi-turn self-refine.
+
+When reflect runs in LLM mode, it sends the initial draft back as an assistant turn. The model sees its own prior output and the refine prompt together in the same context window. This is a standard multi-turn pattern for iterative generation — the model can catch inconsistencies, tighten reasoning, and improve the draft without requiring a second top-level call.
+
+Agent mode, by contrast, passes context forward through prompt text. Each subprocess run starts fresh. There is no conversation history to reason against.
+
+The practical difference shows on longer or more complex assets, where a single forward pass produces a draft with inconsistencies the model catches immediately when it sees its own output. Multi-turn self-refine handles this inside the single reflect call.
+
+## Structured Output
+
+For providers that advertise `supportsJsonSchema: true` in their profile config, LLM mode requests structured JSON output. The response is validated against the reflect output schema before being accepted as a proposal.
+
+This eliminates a class of parse failures that occurs when a model returns well-formed prose but with section markers or formatting that does not align with the expected output shape. The model knows the schema before it generates the response, so the output conforms rather than being post-hoc parsed.
+
+Agent mode produces unstructured text that the pipeline parses with heuristics. LLM mode with `supportsJsonSchema: true` eliminates the heuristics.
+
+## Config to Enable LLM Mode
+
+LLM mode requires Config v2 (`configVersion: "0.8.0"`). If you have not migrated yet:
+
+```sh
+# Preview the transformation
+akm config migrate --dry-run  # doclint:ignore (0.7.x→0.8.0 config-schema migration command, not present in 0.9.0)
+
+# Apply (writes a timestamped backup first)
+akm config migrate  # doclint:ignore (0.7.x→0.8.0 config-schema migration command, not present in 0.9.0)
+```
+
+With v2 in place, add a named LLM profile and point the reflect process at it:
+
+```jsonc
+{
+  "configVersion": "0.8.0",
+  "profiles": {
+    "llm": {
+      "openai-mini": {
+        "endpoint": "https://api.openai.com/v1/chat/completions",
+        "model": "gpt-4o-mini",
+        "apiKey": "${OPENAI_API_KEY}",
+        "supportsJsonSchema": true
+      }
+    },
+    "improve": {
+      "default": {
+        "processes": {
+          "reflect": { "mode": "llm", "profile": "openai-mini" }
+        }
+      }
+    }
+  },
+  "defaults": { "llm": "openai-mini" }
+}
+```
+
+That is the complete change. On the next `akm improve` run, reflect dispatches HTTP calls to the `openai-mini` profile instead of spawning subprocesses. The proposal queue, review workflow, and everything downstream are unchanged.
+
+## Local Models and LM Studio
+
+The profile config is an endpoint and a model name. Nothing in the LLM mode path is OpenAI-specific — it issues standard chat completions requests. Any OpenAI-compatible server works, including LM Studio running locally.
+
+To point reflect at a local LM Studio instance:
+
+```jsonc
+{
+  "configVersion": "0.8.0",
+  "profiles": {
+    "llm": {
+      "local-reflect": {
+        "endpoint": "http://192.168.1.100:1234/v1/chat/completions",
+        "model": "your-local-model-name",
+        "supportsJsonSchema": false
+      }
+    },
+    "improve": {
+      "default": {
+        "processes": {
+          "reflect": { "mode": "llm", "profile": "local-reflect" }
+        }
+      }
+    }
+  }
+}
+```
+
+Set `supportsJsonSchema: false` unless you have confirmed that the local model and LM Studio version support structured output. Most local models handle the reflect task correctly through standard chat completions without schema enforcement — the output is smaller and more predictable than consolidation plans, so parse failures are rare.
+
+For a machine running a 9B model on an RTX 4060 Ti, LLM mode reflect benchmarks in the 8–12 second range per call — comparable to the cloud figures in the table above, with no API costs and no data leaving your network.
+
+## When to Stay on Agent Mode
+
+LLM mode is appropriate for reflect because reflect has static inputs. Other improve processes do not share that property.
+
+Stay on agent mode when the process needs live tool calls. If you have a custom improve workflow that reads files, calls `akm search`, or pulls external context mid-run, that process requires an agent that can execute tools. LLM mode does not have tool dispatch — it is a direct HTTP call to a completions endpoint, nothing more.
+
+Stay on agent mode when the reflect task for a specific asset type requires context that is assembled dynamically — search results, graph lookups, or file reads that depend on the asset's content. Those lookups require a running agent.
+
+The standard reflect pass — refining an existing asset based on its content and metadata — does not require either of these. LLM mode is the right default for it.
+
+## What Changes in Practice
+
+A 69-ref `akm improve` run that used to block for 35 minutes now completes in under 10. The reflect proposals are the same quality — in some cases better, because multi-turn self-refine catches first-draft inconsistencies. Structured output for cloud providers eliminates parse failures that previously required manual retries.
+
+The change is a config update:
+
+```sh
+# Migrate config if still on v1
+akm config migrate  # doclint:ignore (0.7.x→0.8.0 config-schema migration command, not present in 0.9.0)
+
+# Then add the llm profile + reflect process entry (see snippet above)
+# Preview what the next run would process without writing anything
+akm improve --dry-run
+```
+
+The next improve run after that shows reflect calls completing in the 6–10 second range instead of 30.
+
+---
+
+LLM mode reflect is available in akm 0.8.0. The full configuration reference is in [configuration reference](../reference/configuration.md). The Config v2 key mapping is in the [v0.7 to v0.8 migration guide](../migration/v0.7-to-v0.8.md#config-080-migration-unified-profiles).
+
+For a broader view of the improve pipeline — all five phases, scheduling, and how reflect feeds the downstream consolidation and distill passes — see [The Improvement Loop: How akm Keeps Your Agent Sharp](https://dev.to/itlackey/the-improvement-loop-how-akm-keeps-your-agent-sharp-2d4d). For debugging improve runs when something goes wrong (stale DB entries, hallucinated merge plans, pre-flight filters), see [Your Agent Has a Memory That Runs While You Sleep](https://dev.to/itlackey/your-agent-has-a-memory-that-runs-while-you-sleep-20oh).

package/docs/posts/openpalm-built-on-akm.md

@@ -0,0 +1,86 @@
+---
+title: "OpenPalm Used to Run a Container for Everything. Now It Runs on AKM."
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-skills
+description: A self-hosted AI assistant accumulated a container for memory, one for scheduling, one for secrets. The 0.11.0 release deleted most of them by making the agent's knowledge stash the foundation instead.
+tags:
+  - ai
+  - agents
+  - selfhosted
+  - akm
+published: false
+date: '2026-06-07T00:00:00Z'
+---
+
+> 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).
+
+If you've ever stood up a self-hosted AI assistant, you know how the container list grows.
+
+You start with the assistant itself. Then it needs memory, so you add a memory service. It should run scheduled tasks, so you add a scheduler. You need a place to put secrets, so you stand up a vault. The web UI gets its own container. A reverse proxy goes out front. A socket proxy guards the Docker socket. Before long `docker ps` is a wall of services, and every one of them is a thing that can break, drift, or need its own upgrade path.
+
+OpenPalm — a self-hosted, LAN-first AI assistant platform — grew up exactly like this. By the 0.10 line it was running a dedicated memory container (a Python mem0 service), a scheduler container, an admin-UI container, a Caddy reverse proxy, and a docker-socket-proxy, on top of the assistant, the guardian, and the channel adapters. Each one solved a real problem. Together they were a lot of platform to keep alive just to talk to your own assistant.
+
+The 0.11.0 release deleted most of them. Not by cramming the features into fewer images — by noticing they were the same problem wearing different costumes.
+
+## The Real Problem Wasn't the Services. It Was the Substrate.
+
+Look at what those containers were actually *doing*:
+
+- The memory service stored and recalled facts the assistant learned.
+- The scheduler ran recurring jobs the assistant defined.
+- The vault held the secrets and settings the assistant needed.
+- The skills/lessons machinery managed the knowledge the assistant could draw on.
+
+That's not five unrelated systems. That's one system — **the agent's knowledge and state** — split across five runtimes because no single thing owned it.
+
+This is the same trap the akm series keeps coming back to. Skills scattered across `~/.claude/`, `.cursor/rules/`, and `~/.codex/` aren't a storage problem, they're a discovery problem. Containers scattered across a Compose file aren't a packaging problem, they're a *foundation* problem. When there's no shared substrate for the agent's knowledge, every capability invents its own.
+
+So 0.11.0 picked a substrate: the [akm](https://github.com/itlackey/akm) stash. One searchable, versioned, file-based knowledge base — the same one the agent already uses for skills — and moved memory, scheduling, secrets, and knowledge onto it.
+
+## Memory: A Whole Service Became a Stash
+
+The old way was a mem0 container: a Python service, a vector store, an embedding pipeline, a database to back it up, and a network hop between the assistant and its own memories.
+
+The new way is `akm`. The assistant's memory/skills/lessons tools come from the `akm-opencode` plugin, and "remembering" is just writing a memory asset into the stash — the same stash that holds everything else the agent knows. Recall is `akm search` / `akm curate`. There's no separate memory service to run, no second database to back up, no embedding service to keep in sync with the model config.
+
+The win isn't only "one less container." It's that memory stops being a black box. A memory is a markdown file with frontmatter. You can read it, grep it, edit it, version it, and — this is the good part — **share it**. Which leads to the part that surprised us.
+
+## The Operator and the Assistant Share One Brain
+
+Because memory and knowledge now live in a plain akm stash, the host and the assistant can point at the *same* one.
+
+The host's stash can be shared, symmetric and writable, with the assistant. Something you teach the assistant shows up in your own `akm curate` on the host. Something you drop into your stash is available to the assistant on its next task. There's no export step, no sync job, no "push my notes to the bot." It's one knowledge base with two readers.
+
+You don't get that when memory is trapped inside a service whose only interface is an API the assistant calls.
+
+## Scheduling: The Scheduler Container Just… Left
+
+OpenPalm used to run a separate scheduler service to fire recurring automations.
+
+In 0.11.0, scheduled work is an akm **task asset** — a markdown file describing a job and its cron. The assistant container runs `crond` at boot and `akm tasks sync` to register those tasks with the OS scheduler; `akm tasks run` executes them and writes history. The scheduler container is gone. Automations are now the same kind of file as everything else in the stash: discoverable, versioned, editable, and owned by the knowledge layer instead of a bespoke daemon.
+
+## Secrets and Config: Stop Inventing a Vault
+
+The old stack had its own vault concept and a pile of `OP_CAP_*` capability variables and a `stack.yml` to wire it all together.
+
+akm 0.8.0 grew first-class `env` and `secret` asset types, so OpenPalm stopped inventing its own. User settings live as an `env` asset; service secrets as `secret` files with the right permissions; LLM and embedding configuration moved into akm's own `config.json`. The capability variables and the `stack.yml` block they fed are gone. One fewer dialect to learn, one fewer file format to migrate, one substrate that already knew how to store this stuff.
+
+## What's Left (Because Honesty Matters)
+
+This isn't a magic-wand story where everything collapses into a single binary. The pieces that earn their isolation kept it:
+
+- **The guardian** still fronts all channel traffic — HMAC, replay protection, rate limiting, optional content moderation. Security boundaries should be their own process.
+- **The assistant** still runs the OpenCode runtime with its tools.
+- **Channel adapters** still translate Discord/Slack/API into validated requests.
+- The reverse proxy and socket proxy didn't move to akm — they were *removed*. OpenPalm is LAN-first; services bind localhost, and the web UI became a host process instead of a container, so there was nothing left to proxy.
+
+What changed is everything that was really just "the agent's knowledge and state" wearing a container costume. That collapsed onto akm.
+
+## The Pattern, One More Time
+
+The akm thesis started with skills: don't scatter them across tools, index them in one place and let the agent find what it needs. OpenPalm 0.11.0 is the same idea at the platform level. Don't scatter the agent's memory, schedule, secrets, and knowledge across a fleet of services. Put them on one substrate the agent already speaks, and delete the services that only existed to hold them.
+
+Fewer containers is the headline. The real result is a simpler mental model: there's the stack that *runs* the assistant, and there's the stash that *is* its knowledge — and the stash is something you can read, share, and own.
+
+If you're building anything with a long-lived agent, it's worth asking which of your services are solving a genuinely separate problem, and which are just holding the agent's knowledge because nothing else would. The second kind are containers you might not need.

package/docs/posts/progressive-disclosure-06.md

@@ -0,0 +1,129 @@
+---
+title: Your Agent Loads 47 Skills at Startup. It Needs Three.
+cover_image: 'https://raw.githubusercontent.com/itlackey/akm/main/docs/posts/akm-logo-sized.webp'
+series: akm-skills
+description: 'The napkin math behind progressive disclosure, and how akm makes it work across every platform you use.'
+tags:
+  - ai
+  - agents
+  - cli
+  - skills
+published: true
+id: 3426244
+date: '2026-04-21T03:24:25Z'
+---
+
+> 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).
+
+Quick recap if you're joining mid-series. In [part one](https://dev.to/itlackey/your-ai-agents-skill-list-is-getting-out-of-hand-32ck), I introduced the problem: your agent's skill list is growing faster than you can manage it, and dumping everything into context makes things worse, not better. [Part two](https://dev.to/itlackey/you-already-have-dozens-of-agent-skills-you-just-cant-find-them-bpo) showed how `akm` unifies your existing Claude Code, Cursor, and Codex assets into one searchable stash. [Part three](https://dev.to/itlackey/your-agents-memory-shouldnt-disappear-when-the-session-ends) covered persistent memory across sessions. [Part four](https://dev.to/itlackey/your-agent-doesnt-know-what-the-community-already-figured-out) connected your agent to community knowledge through a shared git stash.
+
+This post zooms in on the pattern that makes all of that work: progressive disclosure. I've mentioned it in every post so far, but I haven't really shown the math or walked through what actually happens under the hood. Let's fix that.
+
+## You're Paying for Context You Don't Use
+
+Say you've got 47 skills across three platforms. That's not a crazy number — if you've been building with agents for a few months, you're probably there already. The average skill file runs about 1,000 tokens.
+
+Now do the napkin math.
+
+**Load everything at startup:** 47,000 tokens. Your agent sees all of it, whether the current task needs zero skills or five. Those extra 42,000 tokens aren't free. They degrade response quality, increase latency, and cost real money on metered APIs.
+
+**Search first, load second:** A search query comes back with 20 results at ~100 tokens each. That's 2,000 tokens. Your agent reads the summaries, decides it needs one skill, and loads it: 1,000 tokens. Total: 3,000 tokens.
+
+That's a 94% reduction. Not by being clever with compression or prompt engineering. Just by not loading stuff you don't need.
+
+The math alone justifies the pattern. But the implementation is where it gets interesting.
+
+## How It Actually Works
+
+There are three steps. Search, load, and drill down. Here's what each one looks like.
+
+### Search
+
+```sh
+akm search "deploy to staging"
+```
+
+This returns a ranked list of matching assets across all your sources. Each result has the asset type and name (`skill:deploy-staging`), where it came from, a description snippet, and a relevance score.
+
+Total cost: ~100 tokens per result. Your agent scans this list and decides what's relevant. Most of the time, it needs one or two assets out of twenty results. The other eighteen never enter the context window.
+
+### Load
+
+```sh
+akm show skill:deploy-staging
+```
+
+Now the agent loads the full content of a single asset. The complete skill definition, instructions, examples — everything it needs to act. This is the only moment the full content enters the context window, and only for the assets the agent specifically chose.
+
+Cost: ~500-1,500 tokens per asset, depending on complexity.
+
+### Drill Down
+
+```sh
+akm show knowledge:api-guide toc
+akm show knowledge:api-guide section "Authentication"
+```
+
+For knowledge assets — documentation, guides, API references — `akm` supports table-of-contents navigation. The agent can see the structure of a document and request a specific section instead of loading the whole thing.
+
+A 10,000-token API guide becomes a 200-token table of contents, then a 1,500-token section load. The agent never sees the eight sections it doesn't need.
+
+## It Works Across All Your Tools
+
+Here's the part that most implementations miss. Claude Code does progressive disclosure for skills in `~/.claude/skills/`. That's great — for Claude Code. But what about your Cursor rules? Your Codex agents? Your team's shared Git repository of skills?
+
+Every platform implements this pattern within its own silo. `akm` implements it *across* silos.
+
+```sh
+# One-time setup: point akm at everything
+akm add ~/.claude/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add ~/.codex/skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add .cursor/rules  # doclint:ignore (historical — pre-0.9.0 command spelling)
+akm add github:your-org/team-skills  # doclint:ignore (historical — pre-0.9.0 command spelling)
+
+# Every search hits all sources
+akm search "database migration"
+```
+
+That single search query returns ranked results from every source. The scoring pipeline treats local filesystem assets and remote Git-hosted assets fairly — no source gets artificially boosted or suppressed. The best match wins, regardless of where it lives.
+
+## What a Real Session Looks Like
+
+Your agent gets a task: "Deploy the staging environment with the new database migration."
+
+1. **Search.** The agent runs `akm search "deploy staging database migration"`. Gets 15 results across three sources.
+
+2. **Evaluate.** The agent reads the result summaries (~1,500 tokens). Identifies two relevant assets: `skill:deploy-staging` and `knowledge:migration-runbook`.
+
+3. **Load.** The agent runs `akm show skill:deploy-staging` and `akm show knowledge:migration-runbook`. Loads ~2,500 tokens of directly relevant content.
+
+4. **Act.** The agent executes the deployment using the loaded skill and references the runbook for the migration steps.
+
+Total context cost: ~4,000 tokens. Without progressive disclosure, the agent would've loaded all 47 skills (47,000 tokens) and still might not have found the migration runbook because it lives in a different source than the deployment skill.
+
+## Setting It Up
+
+The agent integration is a two-line addition to your `AGENTS.md`:
+
+```markdown
+## Agent Stash
+
+Search for skills, commands, and knowledge using `akm search <query>`.
+View full details with `akm show <ref>`.
+```
+
+That's the entire interface. The agent knows how to search, knows how to load, and handles the progressive disclosure pattern on its own. No configuration, no routing rules, no platform-specific adapters.
+
+## This Is What Makes Teams Work
+
+Progressive disclosure becomes even more valuable at team scale. When your team has hundreds of shared skills plus each developer's personal collection, front-loading is physically impossible. Search-then-load isn't just an optimization — it's the only viable approach.
+
+In the [next post](https://dev.to/itlackey), I'll cover how teams can share skills across a group while preserving individual customization. The progressive disclosure pattern is the foundation that makes team-scale skill management work.
+
+If you want to see this in action, the repo is at [github.com/itlackey/akm](https://github.com/itlackey/akm). Point it at your skill directories, run a search, and see how much context you've been wasting.
+
+
+---
+
+> **Note (2026-04-23):** This post has been updated to align with akm 0.6.0 terminology. Earlier wording referred to a *kit* and the *Kit Maker's Guide*; those terms have been renamed to *stash* and *Stash Maker's Guide* throughout. The pre-rename text is preserved in this repository's git history.