akm-cli 0.9.29 → 0.9.31

package/docs/reference/registry.md

@@ -0,0 +1,489 @@
+# Registry
+
+A registry is a searchable source of bundles that `akm` can discover and
+install from. The default registry type is a static JSON index, but akm
+supports pluggable **registry providers** that can connect to different
+ecosystems (e.g. skills.sh).
+
+## Official Registry
+
+akm ships with the official registry pre-configured:
+
+```text
+https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json
+```
+
+The [akm-registry](https://github.com/itlackey/akm-registry) repo publishes
+a static `index.json` (v3 format). It merges three sources:
+
+- npm packages with the `akm-stash` keyword
+- GitHub repos with the `akm-stash` topic
+- `manual-entries.json` for curated additions and overrides
+
+To submit a bundle, either tag your repo/package as above (auto-discovery)
+or open a pull request against `manual-entries.json` for a curated entry.
+
+### Official onboarding bundle
+
+In addition to the registry, akm has an official onboarding bundle —
+[itlackey/akm-stash](https://github.com/itlackey/akm-stash) — that ships
+skills, commands, knowledge, workflows, and a librarian subagent for
+working with akm itself. Install it with:
+
+```bash
+akm bundle add github:itlackey/akm-stash
+akm index
+akm show skills/akm-quickstart
+```
+
+## Managing Registries
+
+Use the `akm registry` subcommand group to manage configured registries:
+
+```bash
+# List configured registries
+akm registry list
+
+# Add a third-party registry (static index)
+akm registry add https://example.com/registry/index.json --name my-team
+
+# Add a skills.sh registry
+akm registry add https://skills.sh --name skills.sh --provider skills-sh
+
+# Remove a registry by URL or name
+akm registry remove my-team
+```
+
+Registries are stored in the `registries` array in your config file:
+
+```jsonc
+{
+  "registries": [
+    // Static index (default provider)
+    { "url": "https://raw.githubusercontent.com/itlackey/akm-registry/main/index.json", "name": "official" },
+    { "url": "https://example.com/registry/index.json", "name": "my-team", "enabled": true },
+    // skills.sh provider
+    { "url": "https://skills.sh", "name": "skills.sh", "provider": "skills-sh" }
+  ]
+}
+```
+
+Each entry supports:
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | string | (required) | URL of the registry index or API base |
+| `name` | string | -- | Human-friendly label |
+| `enabled` | boolean | `true` | Whether this registry is active |
+| `provider` | string | `"static-index"` | Provider type (see [Registry Providers](#registry-providers)) |
+| `options` | object | -- | Provider-specific options (passed through to the provider) |
+
+Set `enabled: false` to temporarily disable a registry without removing it.
+
+Registry URLs must be credential-free: AKM rejects URL userinfo such as
+`https://user:password@example.com/index.json` before it can be saved. The
+built-in `static-index` and `skills-sh` providers do not currently support
+authenticated registry requests, including through `options`; publish the
+index/API at a credential-free HTTPS endpoint or place an authenticated proxy
+in front of it. AKM does not translate URL credentials into request headers.
+
+Registry HTTP requests must also resolve to public network addresses. AKM
+rejects loopback, private, link-local, metadata, and reserved destinations on
+the initial URL and every redirect hop. This intentionally means a
+`static-index` or `skills-sh` registry hosted only on localhost or an intranet
+is no longer reachable in 0.9.2; publish it at a publicly routable HTTPS
+endpoint. The only private-network compatibility exception is an npm mirror
+explicitly selected with `AKM_NPM_REGISTRY`; metadata and tarball requests may
+reach that configured mirror, but not link-local or cloud-metadata addresses.
+See [Registry network boundary](../architecture/internals/registry-network-boundary.md)
+for the complete policy and DNS guarantee.
+
+## Searching Registries
+
+Search registries alongside or instead of the local bundle:
+
+```bash
+# Search registries only
+akm search "deploy" --from registry
+
+# Search both the local bundle library and registries
+akm search "deploy" --from all
+
+# Include asset-level results from v3 indexes
+akm search "deploy" --from registry --assets
+```
+
+### Search Results
+
+Each registry hit includes:
+
+| Field | Description |
+| --- | --- |
+| `type` | Always `"registry"` |
+| `name` | Bundle display name |
+| `id` | Unique identifier (e.g. `npm:@scope/bundle`) |
+| `description` | Summary from the registry |
+| `action` | Ready-to-run next step such as `akm bundle add ... -> then search again` |
+| `quality` | Optional provenance marker — `"generated"`, `"curated"`, or `"proposed"`. Replaces the legacy `curated` boolean removed in 0.7.0 |
+
+Use `--detail full` to include ranking metadata like `score`.
+
+### The `--assets` Flag
+
+When a registry publishes a v3 index (see below), `akm search --from
+registry` can return individual asset-level hits in addition to bundle-level
+hits. Pass `--assets` to enable this:
+
+```bash
+akm search "code review" --from registry --assets
+```
+
+Asset hits include `assetType`, `assetName`, `description`, and the parent
+`stash` information, so you can install the right bundle and immediately know
+which asset to use.
+
+## Discovery Filtering
+
+Not every npm package or GitHub repo is an akm bundle. To keep results
+relevant, the registry enforces tag-based filtering:
+
+- **npm** -- Only packages whose `keywords` array includes `"akm-stash"` appear in search results.
+- **GitHub** -- Only repositories with the topic `akm-stash` appear in search results.
+
+> **0.6.0 breaking change:** `akm-cli >= 0.6.0` indexes only the
+> `akm-stash` keyword / topic. The pre-0.6.0 `akm-kit` and `agentikit`
+> keywords/topics are **not** honored as fallbacks. Publishers migrating
+> from 0.5.x must add the new tag — see the
+> [migration guide](../migration/v0.5-to-v0.6.md) for the step-by-step
+> publisher checklist.
+
+If you are publishing a bundle, add these tags so it can be discovered:
+
+```jsonc
+// package.json
+{
+  "keywords": ["akm-stash", "your-other-tags"]
+}
+```
+
+For GitHub repos, add topics via the repository settings page or the
+`gh repo edit --add-topic akm-stash` command.
+
+## Installing
+
+Install a bundle with `akm bundle add` using any supported ref format:
+
+```bash
+# npm package
+akm bundle add npm:@scope/my-bundle
+
+# npm package (shorthand)
+akm bundle add @scope/my-bundle
+
+# GitHub repo
+akm bundle add github:owner/repo
+
+# GitHub repo at a specific tag or branch
+akm bundle add github:owner/repo#v1.2.0
+
+# GitHub URL
+akm bundle add https://github.com/owner/repo
+
+# Any git repo (GitLab, Bitbucket, Gitea, self-hosted, etc.)
+akm bundle add git+https://gitlab.com/org/bundle
+akm bundle add git+https://gitlab.com/org/bundle#v1.0
+akm bundle add git+ssh://git@gitlab.com/org/bundle.git
+
+# URLs on known git hosts are treated as git repos
+akm bundle add https://gitlab.com/org/my-bundle
+
+# Local directory (path or file: URI)
+akm bundle add ./path/to/local/bundle
+akm bundle add file:../relative/bundle
+akm bundle add file:///absolute/path/to/bundle
+```
+
+### What Happens During Install
+
+1. **Ref parsing** -- The ref is classified as npm, GitHub/git, website, or
+   local directory. Known git hosts and `.git` URLs are git sources; other
+   HTTP(S) URLs are website sources.
+2. **Artifact resolution** -- For npm, the latest (or requested) version
+   tarball URL is resolved. GitHub/git refs prefer a shallow clone at the
+   resolved revision so normal git credentials work; GitHub API tarballs are a
+   fallback when clone resolution is unavailable.
+3. **Download and extract** -- The tarball is downloaded (or repo cloned) to a
+   cache directory under `~/.cache/akm/registry/` and extracted securely
+   (path traversal is rejected).
+4. **Security audit** -- Before install completes, the extracted bundle's
+   `env`/`secret` asset **key names** are checked against a denylist of
+   process-execution-hijacking variables -- dynamic-linker hooks
+   (`LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, ...), `PATH`, shell/runtime startup
+   hooks (`BASH_ENV`, `PROMPT_COMMAND`, `NODE_OPTIONS`, `PYTHONSTARTUP`, ...),
+   and interactive-tool overrides (`EDITOR`, `PAGER`, `GIT_SSH_COMMAND`, ...).
+   `akm bundle add` **blocks the install** when a dangerous key is present unless
+   `--allow-dangerous-env-keys` is set (or you confirm at an interactive prompt).
+   This is a **key-name audit only** (plus the path-traversal rejection in step
+   3) -- akm does **not** scan source files, prompts, metadata, or install
+   scripts for prompt-injection phrases, shell pipes, or lifecycle hooks.
+5. **Bundle root detection** -- The extracted contents are scanned for asset
+   type directories (`scripts/`, `skills/`, etc.) or a `.stash/` marker. If the
+   bundle nests its bundle under an `opencode/` subdirectory, that is detected
+   automatically.
+6. **Selective include** -- If the package's `package.json` contains an
+   `akm.include` array, only the listed paths are copied into the
+   install cache. This lets a bundle ship a subset of its repo as the bundle.
+7. **Config registration** -- The desired source descriptor (`path`/`git`/
+   `website`/`npm`, `writable`, the original `registryId`) is saved to
+   `config.bundles.<key>`. Resolved cache state -- id, source, ref, resolved
+   version/revision, integrity, local materialized root, and install
+   timestamp -- is recorded separately in `<dataDir>/akm.lock`, never
+   duplicated into `config.json`.
+8. **Re-index** -- `akm index` runs automatically so the new assets appear in
+   search immediately.
+
+### Selective Include
+
+A bundle can declare which paths to include via `package.json`:
+
+```jsonc
+{
+  "akm": {
+    "include": [
+      "scripts",
+      "skills",
+      "commands"
+    ]
+  }
+}
+```
+
+Only the listed paths are copied into the install cache. Paths must be
+relative to the package root and cannot escape it. The `.git` directory is
+always excluded.
+
+## Managing Managed Sources
+
+```bash
+# List all managed sources with their status
+akm bundle list
+
+# Update a specific bundle to its latest version
+akm bundle update npm:@scope/my-bundle
+
+# Update all managed sources
+akm bundle update --all
+
+# Force fresh download even if version is unchanged
+akm bundle update npm:@scope/my-bundle --force
+akm bundle update --all --force
+
+# Remove a bundle
+akm bundle remove npm:@scope/my-bundle
+```
+
+### Cloning Assets
+
+Managed sources are cache-managed and may be overwritten by `akm bundle update`.
+To edit an asset from a managed source, clone it into the working bundle:
+
+```bash
+akm clone "npm:@scope/my-bundle//scripts/deploy.sh"
+
+# Clone with a new name
+akm clone "npm:@scope/my-bundle//scripts/deploy.sh" --name my-deploy.sh
+```
+
+The cloned asset lives in the working bundle and takes priority over the
+installed version in search and show.
+
+Use `--dest` to clone to a custom directory instead of the working bundle:
+
+```bash
+# Deploy a script directly into a project's .claude directory
+akm clone "npm:@scope/my-bundle//scripts/deploy.sh" --dest ./project/.claude
+```
+
+The type subdirectory (`scripts/`, `skills/`, etc.) is appended automatically,
+so the example above produces `./project/.claude/scripts/deploy.sh`.
+
+**Remote clone without install:** If the origin in the ref points to a
+package that is not yet installed, `akm clone` fetches it to the cache
+automatically. Unlike `akm bundle add`, this does **not** register the package as
+a managed source -- it only extracts the single requested asset.
+
+## Search Priority
+
+`akm search` and `akm show` query a single local FTS5 index that covers
+every configured source's directory. There is no fixed lookup order —
+results are ranked by relevance and utility, and precedence is expressed
+through ranking rather than a per-source fan-out (see
+[concepts.md](../guides/concepts.md#3-akm-builds-a-local-index-and-uses-progressive-disclosure)).
+
+When two sources contain an asset with the same name, the working bundle
+typically wins by convention because its files are usually more recent.
+Use `akm clone` to copy an asset into your working bundle for local
+editing — your edits then override the upstream copy in subsequent
+searches.
+
+## Registry Providers
+
+akm uses a pluggable provider system for registries. Each registry entry can
+specify a `provider` type that determines how it is searched. When omitted,
+the provider defaults to `"static-index"`.
+
+Registries discover installable source bundles. They never store
+asset content directly — installing a bundle creates a regular `bundles`
+entry that the indexer walks like any other source.
+
+### Built-in Providers
+
+#### `static-index` (default)
+
+Fetches a static JSON v3 index from the configured URL and performs
+client-side scoring. The index is cached locally with a 1-hour TTL. There is
+currently no fallback to a stale cache row past that TTL on fetch failure —
+`fetchCachedJson` (`src/storage/repositories/registry-index-cache-repository.ts`) only
+consults the cache row that its own `getRegistryIndexCache` lookup returned
+under the same TTL, and that lookup returns nothing once the row is older
+than `maxAgeMs`, so a fetch failure after the TTL expires surfaces as an
+error rather than serving older data.
+
+```bash
+akm registry add https://example.com/registry/index.json --name my-team
+```
+
+#### `skills-sh`
+
+Searches the [skills.sh](https://skills.sh) registry using its server-side
+search API. Results are skills from GitHub repositories indexed by skills.sh.
+
+```bash
+akm registry add https://skills.sh --name skills.sh --provider skills-sh
+```
+
+Key behaviors:
+- Server-side search via `GET {url}/api/search?q={query}&limit={limit}`
+- Hit IDs are namespaced with `"skills-sh:"` prefix to avoid collisions
+- Scores are normalized from install counts (0-1 range)
+- Per-query response caching with 15-minute TTL
+- No stale-cache fallback past that TTL on network failure — same shared
+  cache mechanism as `static-index`, see the note there
+- No authenticated-registry transport is currently supported
+- Toggle on/off via `akm registry add https://skills.sh --name skills.sh --provider skills-sh` / `akm registry remove skills.sh` (the bare `akm enable` / `akm disable` aliases and `akm config enable|disable` were removed in 0.9.0 — use `akm registry add|remove`, the general mechanism)
+
+To install a skill found via skills.sh, use the `ref` field (GitHub
+`owner/repo`) with `akm bundle add`:
+
+```bash
+akm bundle add vercel-labs/agent-skills
+```
+
+## Hosting Your Own Registry
+
+A registry is a static JSON file conforming to the registry index schema.
+You can host one on any static file server, CDN, or GitHub Pages.
+
+Minimal example:
+
+```json
+{
+  "version": 3,
+  "updatedAt": "2026-03-12T00:00:00Z",
+  "stashes": [
+    {
+      "id": "github:your-org/deploy-bundle",
+      "name": "deploy-bundle",
+      "description": "Deployment scripts and skills",
+      "ref": "your-org/deploy-bundle",
+      "source": "github",
+      "tags": ["deploy", "infrastructure"],
+      "assetTypes": ["script", "skill", "memory"]
+    }
+  ]
+}
+```
+
+Host the file at a stable URL and have team members add it:
+
+```bash
+akm registry add https://your-server.com/akm-registry/index.json --name team
+```
+
+To generate the index automatically, use the maintainer script in the akm
+repository:
+
+```bash
+bun scripts/build-registry-index.ts --out dist/index.json
+```
+
+This does not scan the current directory. It fans out to three discovery
+sources -- a manually curated `manual-entries.json`, an npm registry keyword
+search for `akm-stash`, and a GitHub topic search for `akm-stash` -- and
+deduplicates the results into a v3 index with bundle and asset entries. You
+can also use the tooling in the
+[akm-registry](https://github.com/itlackey/akm-registry) repository used by the
+official registry.
+
+## Registry Index v3
+
+Version 3 of the registry index schema is the only format `akm-cli >=
+0.6.0` parses. It carries an `assets` array on each bundle entry so
+clients can perform asset-level search without installing the bundle
+first.
+
+```json
+{
+  "version": 3,
+  "updatedAt": "2026-03-12T00:00:00Z",
+  "stashes": [
+    {
+      "id": "npm:@scope/my-bundle",
+      "name": "my-bundle",
+      "description": "Scripts and skills for deployment",
+      "ref": "@scope/my-bundle",
+      "source": "npm",
+      "tags": ["deploy"],
+      "assetTypes": ["script", "skill", "memory"],
+      "assets": [
+        { "type": "script", "name": "deploy.sh", "description": "Deploy to production" },
+        { "type": "skill", "name": "code-review", "description": "Structured code review process" }
+      ]
+    }
+  ]
+}
+```
+
+Each asset entry supports:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `type` | yes | AKM's own asset type keys (`skill`, `command`, `agent`, `knowledge`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `instruction` — the authority is `KNOWN_TYPES` in `src/core/recognition-util.ts`), or a foreign/adapter-owned type (e.g. an `llm-wiki` page kind). This field is not a strict validation gate, so an unrecognized type still round-trips. Note: `wiki` was retired as an AKM-owned type — the LLM Wiki structure now lives in the first-class `llm-wiki` adapter, whose page kinds are foreign types rather than an AKM-owned `wiki` type. |
+| `name` | yes | Asset name |
+| `description` | no | One-line summary |
+| `tags` | no | Searchable keywords |
+
+The 0.6.0 release dropped support for the legacy v1 / v2 indexes;
+publishers must regenerate `index.json` with the
+`scripts/build-registry-index.ts` maintainer script
+or the [akm-registry](https://github.com/itlackey/akm-registry) tooling
+(see the [v0.5 → v0.6 migration guide](../migration/v0.5-to-v0.6.md)). akm
+treats unknown fields inside a v3 entry as forward-compatible.
+
+## Cache Layout
+
+Installed bundles are cached under `~/.cache/akm/registry/`
+(`buildInstallCacheDir`, `src/sources/providers/provider-utils.ts`):
+
+```
+~/.cache/akm/registry/
+  npm-@scope-my-bundle/
+    1.2.3/                 # the resolved version — reused across installs
+      artifact.tar.gz      # Downloaded archive
+      extracted/           # Extracted contents
+      selected/             # Subset from akm.include (if applicable)
+```
+
+The version segment is the resolved version string for `npm`/`git` sources
+(so re-installing the same version reuses the cache), or a random UUID for
+`local` sources, which are always isolated per install.

package/docs/reference/website-sources.md

@@ -0,0 +1,141 @@
+# Website Sources
+
+`akm import <url>` and every other URL-based knowledge read path pass through
+a pluggable fetcher seam before the built-in website scraper.
+
+akm ships five built-in fetchers, probed in this order (host-specific
+fetchers before the deliberately loose path-shaped RSS matcher; any fetcher
+returning `null` falls through to the generic website crawler):
+
+| Fetcher | Handles | What it extracts |
+| --- | --- | --- |
+| `github-repository` | `github.com/<owner>/<repo>` URLs | The repository README, rendered to markdown |
+| `youtube-transcript` | YouTube watch/short URLs | The video description and transcript when captions are available |
+| `bluesky-profile` | `bsky.app` profile URLs | Public profile and recent posts via the unauthenticated AT Protocol API |
+| `x` | `x.com`/`twitter.com` profiles, posts, and articles | Post/article content; profile timelines need a bearer token (below) |
+| `rss-feed` | Feed-shaped paths (`.rss`/`.atom`/`.xml`, `?feed=`) | Feed items as markdown sections |
+
+## X credentials
+
+The `x` fetcher reads public post/article pages without credentials. Profile
+timelines require an API bearer token, resolved in order from the
+`X_BEARER_TOKEN` environment variable, then the `secrets/x-bearer-token` akm
+secret (`akm secret set secrets/x-bearer-token`). Alternatively, set `X_RSS_TEMPLATE`
+to an RSS-bridge URL containing `{username}` to fetch profiles through the
+`rss-feed` path instead.
+
+## Crawl options
+
+When no fetcher claims a URL, the generic crawler applies the `website`
+source descriptor's knobs (see the config schema): `maxPages` (default 50),
+`maxDepth` (default 3), `respectRobots` (default `true`; set `false` to
+bypass robots.txt for that source), and `crawlTimeoutMs` per request.
+
+## Why
+
+Some sites need custom extraction logic that the generic HTML-to-markdown path
+cannot provide well.
+
+Examples:
+
+- YouTube: fetch the transcript instead of the video description page chrome
+- GitHub issues: fetch the issue body plus comments instead of the repository shell
+- PDF-heavy sites: extract the underlying text instead of scraping an embed page
+
+## Discovery
+
+Drop fetcher modules into:
+
+```text
+<stashDir>/scripts/wiki-fetchers/
+```
+
+`<stashDir>` is the active bundle for the current operation. When a command has a
+resolved write target (for example `akm import --target ...`), akm loads
+fetchers from that target bundle before falling back to the built-in website
+scraper.
+
+Files ending in `.ts`, `.js`, or `.mjs` are loaded in alphabetical order.
+The first fetcher whose `matches()` returns `true` gets a chance to handle the
+URL.
+
+If a fetcher:
+
+- returns `null`, akm falls through to the next fetcher or the built-in website scraper
+- throws, akm logs a warning and falls through to the next fetcher or the built-in website scraper
+
+## Interface
+
+Fetchers should export a default object with this shape:
+
+```ts
+export interface WikiSnapshotResult {
+  url: string;
+  title: string;
+  markdown: string;
+  preferredName?: string;
+  tags?: string[];
+}
+
+export interface FetcherContext {
+  stashDir: string;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  /**
+   * Resolve a secret by ref (e.g. `secrets/x-bearer-token`) from akm's
+   * secret store, or null when absent. Injected rather than imported so
+   * fetchers stay leaves in the import graph; never log the returned value.
+   */
+  resolveSecret?: (ref: string) => string | null;
+}
+
+export interface WikiSnapshotFetcher {
+  name: string;
+  matches(url: URL, context: FetcherContext): boolean;
+  fetch(url: URL, context: FetcherContext): Promise<WikiSnapshotResult | null>;
+}
+```
+
+`markdown` should contain only the body content. akm still wraps the result in
+the standard raw snapshot frontmatter (`name`, `description`, `sourceUrl`,
+`title`, `updated`, a `lint_skip` entry for `stale-path`, and `tags`) so
+downstream wiki tooling continues to work normally.
+
+Custom `tags` are appended to the default snapshot tags (`website` and the
+resolved hostname). They do not replace those defaults.
+
+## Example
+
+```ts
+export default {
+  name: "youtube-transcript",
+  matches(url: URL, _context: FetcherContext) {
+    return (
+      (url.hostname === "www.youtube.com" && url.pathname === "/watch") ||
+      url.hostname === "youtu.be"
+    );
+  },
+  async fetch(url: URL, _context: FetcherContext) {
+    const videoId = url.hostname === "youtu.be" ? url.pathname.slice(1) : url.searchParams.get("v");
+    if (!videoId) return null;
+
+    const transcript = await getTranscript(videoId);
+    return {
+      url: url.toString(),
+      title: `Video ${videoId}`,
+      markdown: `## Transcript\n\n${transcript}`,
+      preferredName: `videos/${videoId}`,
+      tags: ["video", "transcript"],
+    };
+  },
+};
+```
+
+## Notes
+
+- The fetcher seam is shared by `akm import <url>` and other URL-based
+  knowledge reads that use `fetchWebsiteMarkdownSnapshot()`.
+- The built-in website scraper remains the default path when no custom fetcher
+  matches.
+- Bundle-local fetchers are loaded before built-ins, so you can override any
+  built-in fetcher's behavior for your own workflow when needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.29",
+  "version": "0.9.31",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [
@@ -46,20 +46,17 @@
     "SECURITY.md",
     "STABILITY.md",
     "LICENSE",
-    "docs/migration/release-notes",
-    "docs/migration/v0.7-to-v0.8.md",
-    "docs/migration/v0.8-to-v0.9.md",
-    "docs/migration/v0.9.0-troubleshooting.md",
-    "docs/migration/v0.9.1-to-v0.9.2.md",
-    "docs/integration/bundling-akm.md",
-    "docs/reference/bundle-types.md",
-    "docs/reference/cli.md",
-    "docs/reference/configuration.md",
-    "docs/reference/data-and-telemetry.md",
-    "docs/reference/supported-formats.md",
-    "docs/reference/tasks.md",
-    "docs/reference/workflow-schema.md",
-    "docs/reference/workflows.md",
+    "ROADMAP.md",
+    "docs/agents",
+    "docs/architecture",
+    "docs/guides",
+    "docs/integration",
+    "docs/maintainers",
+    "docs/migration",
+    "docs/posts",
+    "docs/reference",
+    "docs/product-surface.md",
+    "docs/plans/0.9.2-agent-command-workflow-plan.md",
     "schemas"
   ],
   "bin": {