akm-cli 0.9.29 → 0.9.31

package/docs/guides/bundles.md

@@ -0,0 +1,321 @@
+# Bundles
+
+akm works toward two outcomes: bring the agent assets you already have into
+one library, and install (or share) reusable capability bundles with other
+people. Both go through the same primitive — a **bundle** — which can be a
+local directory, a git repo, an npm package, or a crawled website.
+**Registries** are discovery indexes that let you find bundles you haven't
+heard of yet. Together they give you a unified, searchable library that pulls
+from anywhere and grows over time.
+
+## Bring what you already have into one library
+
+If you already have skills, commands, or agent configs scattered across
+different tools, point akm at each of them. Nothing moves — akm indexes assets
+in place — and every asset becomes retrievable through the same search and
+curate commands regardless of which agent originally created it.
+
+```sh
+akm bundle add ~/.claude               # Claude Code's project/user assets
+akm bundle add ~/.config/opencode      # OpenCode's config directory
+akm index                              # Bring the search index up to date
+akm curate "plan a release"            # Pull the best matches from every bundle you added
+```
+
+This is the "one library for every agent" idea in practice: assets authored
+for one tool become discoverable — and usable — from any other.
+
+## akm bundle add
+
+`akm bundle add` connects a new bundle. The source kind is inferred from the
+input: known git hosts and URLs ending in `.git` are git bundles, while other
+HTTP(S) URLs are website bundles.
+
+```sh
+akm bundle add ~/.claude/skills                          # Local directory (filesystem)
+akm bundle add github:owner/team-bundle                  # GitHub repo (git)
+akm bundle add @scope/bundle                              # npm package
+akm bundle add npm:@scope/bundle@latest                  # npm with version pin
+akm bundle add github:owner/repo#v1.2.3                 # GitHub at a specific tag
+akm bundle add https://docs.example.com --name docs     # Crawled website (website)
+akm bundle add https://docs.example.com --max-pages 200 --max-depth 5
+
+# Add the official onboarding bundle:
+akm bundle add github:itlackey/akm-stash
+
+# Mark a git bundle as writable (enables akm sync to push):
+akm bundle add git@github.com:org/skills.git --provider git --name my-skills --writable
+
+# Authenticate an HTTPS Git bundle without storing a token in its URL:
+GIT_READ_TOKEN=... akm bundle add https://github.com/org/private.git --provider git \
+  --name private --credential '$GIT_READ_TOKEN'
+
+# Control secondary-bundle resolution priority (the default bundle is always first):
+akm bundle add github:owner/team-bundle --name team --before community
+```
+
+| Bundle kind | Input shape | Behavior |
+| --- | --- | --- |
+| `filesystem` | local path | Indexed in place, writable by default |
+| `git` | `github:`, known git-host URL, or URL ending in `.git` | Cloned into `~/.cache/akm/registry/`, read-only by default |
+| `npm` | `@scope/pkg` | Installed into cache, read-only |
+| `website` | Other HTTP/HTTPS URL | Crawled, converted to markdown, refreshed every 12 hours |
+
+`akm bundle add` materializes and indexes Git install refs before it reports
+success. A declarative `--provider git` add does the same, including writable
+checkouts. Other declarative provider entries are materialized by
+`akm bundle update`.
+
+**Bundle naming.** `--name` sets the bundle's key — akm's config, index, and
+every persisted ref hang off it. It is a contract, not a hint: it must be a
+legal bundle slug (no `:` `.` `#` `/` or whitespace), and it must not already
+be taken by a different bundle, or the add fails before writing anything.
+Re-adding a source that is already installed under a different `--name` than
+it already carries also fails, naming the existing key — use
+[`akm bundle rename`](#akm-bundle-rename) instead of trying to relabel it
+through `add`. Every `akm bundle add` result carries `bundleId` (its
+resolved key), so scripting against the JSON output never has to guess it
+back out of `sourceAdded`/`installed`. Without `--name`, akm derives one
+(the directory name, the package/repo name, or the hostname), falling back to
+a `-<hash>` suffix only on a collision — that forgiving fallback applies
+solely to a derived name, never to an explicit `--name`.
+
+Git credentials must be symbolic references: `$VAR`, `${VAR}`, or
+`secret://name`. AKM resolves the reference only at the Git subprocess boundary
+and sends it as an HTTPS bearer header; it does not put the token in the remote
+URL or `config.json`.
+
+**Website bundles.** A `website` URL is offered to a set of specialized
+fetchers (YouTube, Bluesky, X, RSS/Atom feeds) before falling back to a
+general crawl, and crawl behavior (page/depth limits, timeouts, robots.txt)
+is configurable. See the
+[website source recipe](recipes/website-source.md) for a walkthrough and
+[Website Sources](../reference/website-sources.md) for the full fetcher
+reference, X credential setup, and crawl-option details. Low-level knobs like
+`crawlTimeoutMs` and `respectRobots` live in the bundle's `website`
+descriptor — see [Configuration](../reference/configuration.md).
+
+**Example: add a team bundle from GitHub**
+
+```sh
+akm bundle add github:my-org/team-bundle --name team
+akm index
+akm search "deploy" --type script
+```
+
+## akm bundle list
+
+`akm bundle list` shows all configured bundles — local directories, managed
+packages, and remote providers — so you know what is in your library.
+
+```sh
+akm bundle list                          # All bundles
+akm bundle list --kind filesystem        # Only local directories
+akm bundle list --kind git               # Only git-cloned bundles
+akm bundle list --kind npm               # Only npm packages
+akm bundle list --kind filesystem,git    # Multiple kinds (comma-separated)
+```
+
+Valid `--kind` values are the four bundle providers: `filesystem`, `git`,
+`npm`, `website`.
+
+## akm bundle update / akm bundle remove
+
+`akm bundle update` refreshes git, npm, and website bundles. Each candidate is
+staged outside its active root, audited for dangerous environment keys, and
+only then published and indexed. `akm bundle remove` disconnects a bundle and
+re-indexes without it.
+
+Bundle refresh is deliberately explicit: Git bundles do not poll upstream on
+their own. Consumers that want automatic refresh should schedule
+`akm bundle update <name>` or `akm bundle update --all`. Scheduled invocations
+should pass `--skip-if-locked` so concurrent index or improve activity becomes
+a successful skip instead of exit 75.
+
+```sh
+# Update
+akm bundle update @scope/bundle          # One managed bundle
+akm bundle update --all                 # All managed bundles
+akm bundle update --all --force         # Force fresh download even if version unchanged
+akm bundle update --all --skip-if-locked # Scheduled refresh: exit 0 on DB contention
+akm bundle update @scope/bundle --allow-dangerous-env-keys  # Approve reviewed dangerous env keys
+
+# Remove
+akm bundle remove @scope/bundle          # By npm id
+akm bundle remove github:owner/repo     # By git ref
+akm bundle remove ~/.claude/skills      # By path
+akm bundle remove my-provider           # By name
+```
+
+Dangerous keys prompt in a terminal (default: No) and block non-interactive
+updates unless `--allow-dangerous-env-keys` is explicit. `--yes` only approves deletion
+of an obsolete moved install directory; it never approves security findings.
+For `--all`, blocked and failed bundles are reported separately and later
+bundles continue. A rejected or failed bundle keeps its prior bytes, lock/config
+state, and search-index generation.
+
+Private bundles that intentionally version every file under `env/` and
+`secrets/` can place this documented marker anywhere in their root
+`.gitignore`:
+
+```gitignore
+# akm: intentionally track env and secrets
+```
+
+The stash scaffold then leaves the ignore file unchanged. Use this only for a
+private remote whose exposure policy you have reviewed.
+
+During publication AKM holds a SQLite writer transaction across the index and
+the update-owned state work. Existing readers keep seeing the prior generation,
+but other writers may wait for a full index pass. This provides process-fault
+rollback for handled errors, not atomic durability across the filesystem and
+two WAL database files during `SIGKILL`, power loss, or storage failure. After
+such a failure, stop writers, run `akm health`, rerun the targeted update if its
+checkout/lock is not the intended revision, and run
+`akm index --full`. The `index-state-generation` advisory detects mismatched
+durable usage links; it cannot detect every theoretical cross-file split.
+
+**Example: keep bundles fresh**
+
+```sh
+akm bundle update --all && akm index
+```
+
+## akm bundle rename
+
+`akm bundle rename <old> <new>` is the one command allowed to change a
+configured bundle's key. A bundle id is a mass identity prefix: every ref this
+tool minted (`entries.item_ref`, `proposals.ref`, a pending proposal's write
+target, a workflow's `task_history.target_ref`, `scheduler.enabled[].ref`)
+carries it, so hand-editing the `bundles` key in `config.json` strands all of
+it — the rest of akm keeps reading the old prefix out of the index and state
+databases while config names the new one.
+
+```sh
+akm bundle rename old-name new-name --dry-run   # See the plan first
+akm bundle rename old-name new-name
+```
+
+`<new>` must be a legal, unused bundle slug — the same `--name` contract
+`akm bundle add` enforces. Rewritten: the config key,
+`defaultBundle`/`defaultWriteTarget` when they name the old id, every
+scheduler ref, the lockfile entry, every indexed entry's `bundle_id`, and
+this tool's own state rows that name the old bundle. Reported, never rewritten:
+refs inside the bundle's own content (cross-references, a task's `uses:`,
+`supersededBy`) — the command lists the files that still spell the old
+`<old>//` prefix so you can fix them by hand. A real run also re-syncs native
+scheduler bindings under the new name on its own, so scheduled tasks pick it
+up immediately — but the result's `taskSync.ok` is `false` when a binding
+fails to re-sync too, not only when the sync call itself fails, so a partial
+re-sync is never reported as clean; `--dry-run` lists the installed native
+rows that still name the old bundle, so you can see what that sync will
+replace.
+
+## akm clone
+
+`akm clone` copies a single asset from any bundle into your writable bundle
+(or a custom destination) for local editing. After cloning, your local copy
+wins in subsequent searches automatically.
+
+```sh
+akm clone scripts/deploy.sh
+akm clone skills/code-review --name my-code-review
+akm clone scripts/deploy.sh --dest ./project/.claude
+akm clone "npm:@scope/pkg//scripts/deploy.sh"   # From uninstalled package
+```
+
+Clone is non-destructive: use `--force` to overwrite an existing local copy.
+Skills (directories with `SKILL.md`) are copied recursively. All other types
+copy a single file.
+
+**Example: clone and customize a workflow**
+
+```sh
+akm clone workflows/ship-release --dest ./project/.claude
+# Edit ./project/.claude/workflows/ship-release.md
+# The local copy wins in searches from this directory forward
+```
+
+## akm sync
+
+`akm sync` stages, commits, and optionally pushes your writable bundle. It is
+the complement to `akm bundle add`: once you have made changes locally,
+`sync` persists them to git. (There is no `akm save` command — use
+`akm sync`.)
+
+```sh
+akm sync                          # Primary bundle, auto timestamp message
+akm sync -m "Add deploy skill"   # Custom commit message
+akm sync my-skills -m "Update"   # Named writable git bundle
+```
+
+Push behavior depends on configuration: if the bundle is a git repo with a
+remote and `writable: true`, sync also pushes. Otherwise it commits only.
+
+Writes that land on a writable git bundle via an explicit destination flag
+(e.g. `akm remember --bundle my-skills`, proposal accept/revert, consolidate)
+are committed automatically in a single batch at the end of the operation —
+one complete commit (staging `.akm/` + assets together), pushed under the
+same `writable + remote` gate as `akm sync`. `options.pushOnCommit` is
+rejected at config load; remove it and rely on `writable: true` + push
+instead.
+
+**Example: publish your own bundle**
+
+```sh
+# One-time setup (git-descriptor primary bundles only): mark it writable by
+# setting bundles.<name>.writable: true in ~/.config/akm/config.json.
+# A filesystem-type primary bundle is already writable by default.
+akm sync -m "Add deployment skills"
+# → stages, commits, and pushes to your configured remote
+```
+
+For the full workflow of turning a bundle into something others can install —
+manifest conventions, versioning, and publishing to a registry — see the
+[Bundle Author's Guide](author-bundles.md). For how a bundle's provider kind
+maps to the code that indexes and fetches it, see
+[Architecture](../architecture/architecture.md).
+
+## Install and share reusable capability bundles
+
+The other half of the bundle story is discovery: finding bundles other people
+have published, and publishing your own so others can install it. `akm bundle
+add` (above) is how you install one once you know where it lives; the
+registry (below) is how you find it in the first place.
+
+## akm registry
+
+The registry is a discovery index — it lets you find and install bundles you
+don't know about yet. The official registry ships pre-configured.
+
+```sh
+akm registry list                             # See configured registries
+akm search "deploy" --from registry           # Search registry bundles by topic
+akm search "code review" --from registry --assets  # Include asset-level hits
+akm registry add https://example.com/registry/index.json --name my-team
+akm registry remove my-team
+```
+
+Once you find an interesting bundle in the registry, install it with `akm bundle add`:
+
+```sh
+akm search "kubernetes" --from registry
+akm bundle add github:some-org/k8s-bundle
+akm index
+```
+
+For the registry index schema, hosting a private registry, and how entries
+get discovered, see [Registry](../reference/registry.md).
+
+## See also
+
+- [Discover & Load](discover-and-load.md) — querying the index after bundles are connected
+- [Knowledge Management](knowledge-management.md) — writing your own assets
+- [Use akm With Any Agent](use-with-any-agent.md) — using refs across bundles in prompts
+- [Website Source Recipe](recipes/website-source.md) — walkthrough for adding a crawled website bundle
+- [Website Sources](../reference/website-sources.md) — fetcher reference, X credentials, crawl options
+- [Configuration](../reference/configuration.md) — bundle descriptor fields including `website` crawl knobs
+- [CLI Reference](../reference/cli.md) — full flag documentation for `add`, `list`, `update`, `remove`, `clone`, `sync`, `registry`
+- [Registry](../reference/registry.md) — registry index format and private registry setup
+- [Bundle Author's Guide](author-bundles.md) — build and publish your own bundle
+- [Architecture](../architecture/architecture.md) — how bundle providers are implemented

package/docs/guides/capture-knowledge.md

@@ -0,0 +1,136 @@
+# Capture Knowledge
+
+Insights don't have to evaporate at the end of a session. `akm remember`
+captures a short observation or decision, `akm import` pulls an existing
+document into your library, `akm bundle add` keeps an external directory or
+repo connected on an ongoing basis, and an LLM wiki organizes captured
+material into a maintained, cross-referenced knowledge base. Once written,
+captured material is indexed like any other asset — the next agent to run
+`akm curate` or `akm search`, regardless of which tool it is, can find it.
+This is "one library for every agent" applied to what you and your agents
+learn along the way, not just what you started with.
+
+## Fast path
+
+```sh
+# Save a quick observation
+akm remember "Hot-fix deploys skip staging; always notify on-call first" \
+  --tag ops --tag deployment
+
+# Pull an existing document into the library
+akm import ./postmortem-2026-05.md --name postmortem-2026-05
+
+# Confirm it's there
+akm show knowledge/postmortem-2026-05
+```
+
+## How it works
+
+`akm remember` writes a context fragment — an observation, decision,
+snippet, or note — into `memories/` in your writable bundle. Pass a quoted
+string for short notes, or pipe markdown via stdin for longer content.
+
+```sh
+akm remember "Deployment needs VPN access"
+akm remember "Pair with ops before rotating prod secrets" --path ops --name prod-secrets
+
+# Structured metadata:
+akm remember "VPN required for staging deploys" \
+  --tag ops --tag networking \
+  --expires 90d \
+  --source "skills/deploy"
+
+# Heuristic tagging (zero-latency, pure TS):
+akm remember "Found this snippet: curl -fsSL ... | bash" --tag ops --auto
+
+# LLM-assisted enrichment (requires a configured LLM; fails soft):
+cat long-meeting-notes.md | akm remember --name meeting-2026-05 --enrich
+
+# Route to a named writable bundle:
+akm remember "Use staging cluster for blue-green" --bundle team-bundle
+```
+
+`--xref` cites related assets in the memory's frontmatter, and `--supersedes`
+writes a correction while demoting the stale asset it replaces in the same
+step. Scope flags (`--user`, `--agent`, `--run`, `--channel`) partition
+memories for multi-agent environments; a scoped memory is only returned when
+the same scope filter is supplied to `akm search` or `akm show`. Full flag
+reference, belief-state mechanics, and provenance detail live in
+[Memory](../reference/memory.md).
+
+`akm import` brings an existing document — a local file, a single URL, or
+stdin — into `knowledge/` as a searchable reference asset. Unlike
+`akm bundle add` (which registers a persistent source), `import` is a
+one-shot capture: a URL import fetches only the exact page you pass, converts
+it to markdown, and does not crawl linked pages or register a source.
+
+```sh
+akm import ./docs/auth-flow.md
+akm import ./notes/release.txt --name release-checklist
+akm import - --name scratch-notes < notes.md
+akm import https://example.com/docs/auth
+
+# Route to a named writable bundle:
+akm import ./docs/auth-flow.md --target team-bundle
+```
+
+Both commands accept `--xref <ref>` to cross-reference related assets and
+`--supersedes <ref>` to correct and demote an existing asset in one step —
+refs are validated before anything is written, so a typo fails fast instead
+of leaving a dangling reference. See [Memory](../reference/memory.md) for the
+belief-state and provenance model these flags drive.
+
+## Decision table
+
+| Need | Use |
+| --- | --- |
+| Save a short observation, decision, or gotcha from the current session | `akm remember` |
+| Copy one existing document into the writable library | `akm import` |
+| Keep an external directory or repo connected on an ongoing basis | `akm bundle add` |
+| Maintain a structured, agent-authored wiki with raw sources and cross-referenced pages | [Wikis](wikis.md) |
+
+## How captured material becomes available to every agent
+
+A memory or import is a normal asset the moment it's written: `akm index`
+(run automatically by most write paths, or explicitly when needed) folds it
+into the unified search database, and from then on any agent — Claude Code,
+OpenCode, or any other shell-capable assistant pointed at the same bundle —
+finds it through the same `akm search` / `akm curate` / `akm show` calls it
+uses for scripts and skills. Nothing about the capture path is
+tool-specific; the retrieval loop (connect, index, curate, show, use/run,
+feedback, proposal) treats a `akm remember` note the same way it treats a
+bundled skill.
+
+## Common problems
+
+**`akm remember` rejects the write with a tags-required error.** Passing
+`--expires`, `--source`, or `--description` without any `--tag` triggers a
+required-field check before anything is written. Either add at least one
+`--tag`, or drop those flags and use the zero-flag form
+(`akm remember "body"`), which writes bare with no frontmatter.
+
+**A URL import didn't pick up the rest of the site.** That's expected — an
+import fetches exactly the page you pass. To keep a whole site or repo in
+sync on an ongoing basis, use `akm bundle add` instead.
+
+**`--xref` or `--supersedes` fails with exit 2 before writing anything.**
+The cited ref doesn't resolve in the write target or any configured source.
+Fix the ref (check `akm search` for the correct one) and retry — validation
+runs before the write, so nothing partial is left behind.
+
+**A scoped memory isn't showing up in search.** Scoped memories
+(`--user`/`--agent`/`--run`/`--channel`) only surface when the same scope
+filter is passed to `akm search --filter` or `akm show --filter`.
+
+## See also
+
+- [Memory](../reference/memory.md) — belief state, corrections, and
+  provenance detail for `remember` and `import`
+- [Wikis](wikis.md) — the LLM-wiki bundle format for maintained, structured
+  knowledge
+- [Bundles](bundles.md) — connecting external directories and repos on an
+  ongoing basis
+- [Environment & Secrets](../reference/env-and-secrets.md) — protected
+  configuration and credential storage, not plain knowledge capture
+- [CLI Reference](../reference/cli.md) — full flag documentation for
+  `remember` and `import`

package/docs/guides/claude-code-vs-akm-workflows.md

@@ -0,0 +1,30 @@
+# Choosing between a session-native workflow and an AKM workflow
+
+Most coding assistants, Claude Code included, offer a native way to fan work
+out inside the current session — an in-context script or tool that spawns
+subagents, runs them concurrently, and reports back before the session ends.
+AKM workflows are a different thing: a portable procedure that any supported
+agent harness can run, with durable state, retries, gates, and resume built
+in. Peer workflow sources are Markdown `.md` and GitHub-shaped YAML `.yml`;
+both adapters lower to source IR version 1. Every run freezes the durable plan
+v4 family's executable `irVersion: 5` before execution; pre-`irVersion`-5
+stored plans are rejected.
+Neither replaces the other — they solve different problems, and the right
+choice depends on whether the work is a one-off inside a session or a
+procedure worth keeping. Use the table below to pick.
+
+| Use a session-native workflow when... | Use an AKM workflow when... |
+| --- | --- |
+| Work is temporary and belongs to one active assistant session | The procedure should survive sessions and be shared |
+| The assistant's native orchestration is the main value | Stable inputs, outputs, retries, gates, and resume matter |
+| Tool-specific behavior is acceptable | Portability and a durable source definition matter |
+| No long-lived run record is needed | Run state and verification need to persist |
+
+For the deep technical dive — representation, execution model, concurrency,
+persistence, and where the two approaches overlap and diverge — see the full
+comparison at
+[docs/architecture/comparisons/claude-code-vs-akm-workflows-full.md](../architecture/comparisons/claude-code-vs-akm-workflows-full.md).
+
+To run an existing AKM workflow, see
+[docs/guides/run-workflows.md](run-workflows.md). To author a new one, see
+[docs/guides/author-workflows.md](author-workflows.md).

package/docs/guides/concepts.md

@@ -0,0 +1,93 @@
+# Concepts
+
+AKM is a portable capability library for AI agents: one local index that
+holds every capability you've connected, and a small set of verbs any agent
+can use to find, load, and improve it. Four ideas cover the whole mental
+model.
+
+## 1. A capability is something an agent can discover and use
+
+A **capability** is any asset an agent can search for and act on: a script,
+skill, command, agent definition, knowledge document, instruction, env file,
+secret, workflow, lesson, memory, task, session summary, or fact. AKM
+classifies capabilities by **what they are** (file extension and content),
+not by which directory they live in — a `.sh` file is a script whether it
+lives in `scripts/`, `deploy/`, or the bundle root.
+
+See [Asset Types](../reference/asset-types.md) for the full taxonomy,
+directory layout, and metadata field reference.
+
+## 2. A bundle is a portable directory of capabilities
+
+A **bundle** is a directory of capabilities you can connect, share, and
+install — a local folder, a git repo, an npm package, or a crawled website.
+`akm bundle add` infers the bundle's kind from the input shape; you never
+pick it yourself. Every bundle materializes to a local directory that the
+indexer walks.
+
+Your **working bundle** (`~/akm`, created by `akm setup`) is the default
+destination for `akm remember`, `akm import`, and other writes — the one
+bundle guaranteed to be writable.
+
+See [Author Bundles](author-bundles.md) for how to build and share one, and
+[Registry](../reference/registry.md) for finding bundles other people have
+published.
+
+## 3. AKM builds a local index and uses progressive disclosure
+
+Every connected bundle is folded into one local FTS5 index — there's no
+per-bundle fan-out at query time. Two verbs work that index:
+
+```text
+search decides   -- a lean menu: type, name, action, score
+show delivers     -- the full dispatch envelope: run command, prompt, content
+```
+
+Search should not accumulate show-level detail, and show should not require
+a prior search call. When two bundles hold a capability with the same name,
+the working bundle wins by ranking convention rather than a fixed lookup
+order — `akm clone` copies a capability into your working bundle so your
+local edits override the upstream copy in subsequent searches.
+
+## 4. A ref is an opaque handle returned by discovery and consumed by show
+
+A **ref** is the compact identifier `akm search` returns and `akm show`
+consumes: `[bundle//]conceptId[#fragment]`. Treat it as an opaque token — get
+it from search or curate, and pass it straight to `show`. Don't parse it or
+construct one by hand; the structured `conceptId` and `bundle` fields on a
+search hit carry the same information in parseable form.
+
+See [Refs](../reference/refs.md) for the full grammar, rename semantics, and
+namespacing conventions.
+
+## How it fits together
+
+```text
+local folders / git / npm / websites
+              |
+              v
+           bundles
+              |
+              v
+        one local index
+              |
+              v
+   curate -> show -> use/run -> feedback -> proposals
+```
+
+This is the retrieval loop: **connect** a source, **index** it, **curate** a
+shortlist for a task, **show** the full payload, **use/run** it, send
+**feedback**, and let accumulated signal become a **proposal**. AKM
+retrieves every supported capability type. It directly orchestrates defined
+execution surfaces such as workflows, agent dispatch, tasks, and guarded
+subprocess injection. It does not blindly execute arbitrary indexed content
+merely because that content appears in search results.
+
+## See also
+
+- [Asset Types](../reference/asset-types.md) — the full capability taxonomy, directory layout, and metadata fields
+- [Refs](../reference/refs.md) — ref grammar, rename semantics, and namespacing
+- [Memory](../reference/memory.md) — belief states, capture modes, and derived memories
+- [Registry](../reference/registry.md) — finding and installing bundles
+- [Architecture](../architecture/architecture.md) — how indexing, search, and execution fit together
+- [Author Bundles](author-bundles.md) — how to build and share a bundle