@inneranimalmedia/agentsam-sdk 2.0.0-alpha.identity.9 → 2.0.0

package/DEVELOPMENT.md

@@ -1,96 +1,80 @@
-# Developing agentsam-sdk with Inner Animal Media
+# Developing AgentSam SDK
 
-## Local smoke test
+This is the canonical repository for portable AgentSam kits. Read
+[protocol/README.md](protocol/README.md) for ownership and host-adapter boundaries.
 
-```bash
-cd agentsam-sdk
-npm test
-npm run preview:auth-portal   # opens /auth/login at http://127.0.0.1:8791
-```
-
-## Link into a scaffolded project
+## Local verification
 
-```bash
-cd agentsam-sdk && npm link
-cd /path/to/your-project && npm link @inneranimalmedia/agentsam-sdk
-npm run dev
+```sh
+npm ci
+npm run verify
+npm run verify:knowledge-package
+npm run test:python
+npm run security:check
 ```
 
-## Link into inneranimalmedia (monorepo-style)
+`npm run verify:release` combines all four verification commands. The `prepublishOnly`
+hook runs it automatically before npm publication. `verify` covers SDK and identity
+tests, package invariants, scaffold/bootstrap checks, and a pack dry-run.
 
-From the platform repo:
+The installed-tarball proof generates and runs a fresh app, then initializes, indexes,
+searches, snapshots, and stages the Docker knowledge service in two unrelated repositories.
+It installs the candidate tarball so a release never accidentally tests an older registry
+version. Use `npm run verify:knowledge-package -- --offline` when dependencies are cached.
 
-```bash
-cd inneranimalmedia
-npm link ../agentsam-sdk
-```
+The Python suite uses unittest and bundled standard-library tooling. Rich is optional.
+Postgres/pgvector checks use development-only PGlite; no production database or embedding
+API call is required by the tests. Dependency scanning requires access to OSV.
 
-Then in any Worker or script:
+## Use in a consumer
 
-```js
-import { AgentSam } from '@inneranimalmedia/agentsam-sdk';
+```sh
+npm link
+cd /path/to/consumer
+npm link @inneranimalmedia/agentsam-sdk
+agentsam context --json
 ```
 
-## Non-interactive init (CI / smoke)
+Git context is derived from the checkout. Host authorization and credentials are supplied
+through explicit adapters. See [portable context](docs/PORTABLE_CONTEXT.md).
 
-```bash
-npx agentsam init \
-  --name my-agent \
-  --lane fullstack \
-  --provider cloudflare \
-  --agent orchestrator \
-  --yes
-```
+For a new local application:
 
-## Publish checklist
-
-1. Root `package.json` name is **`@inneranimalmedia/agentsam-sdk`** (never a workspace kit)
-2. `npm test` passes
-3. Bump version in root `package.json`
-4. Confirm `files` includes consumer surfaces (`src`, `bin`, `python`, `protocol`, …)
-5. `bash scripts/npm-publish-preflight.sh` — must print `npm whoami: inneranimalmedia`
-6. `npm publish --tag alpha --access public` (or `--tag latest` for stable)
-7. Tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
-8. Record pairing in [`docs/RELEASES.md`](./docs/RELEASES.md): `iam@<40-sha> ↔ @inneranimalmedia/agentsam-sdk@X.Y.Z`
+```sh
+agentsam init --name my-agent --lane fullstack --run-target local --yes
+```
 
-### Publish 404 (`PUT … Not found`)
+For an existing repository:
 
-npm returns **404** (not 403) when you are logged in as the **wrong user** for scope `@inneranimalmedia`.
+```sh
+agentsam init . --yes --include src,docs
+```
 
-- Registry maintainer for this package: **`inneranimalmedia`** (see `npm view @inneranimalmedia/agentsam-sdk maintainers`)
-- Fix: `npm whoami` must be `inneranimalmedia`
-  ```bash
-  npm logout
-  npm login   # npm user inneranimalmedia (org owner), not personal GitHub-linked account
-  bash scripts/npm-publish-preflight.sh
-  npm publish --tag alpha --access public
-  ```
-- If you use a team org on npmjs.com, invite your daily npm user as **Developer** on the org with publish rights.
-- Always pass `--access public` (already in `package.json` `publishConfig`; flag is harmless).
+## Publish
 
-Workspace packages under `packages/*` (e.g. `@inneranimalmedia/agentsam-shell-kit`) stay
-`private: true` until separately ready — they are **not** the root publish identity.
+Use [the stable 2.0 release guide](docs/sdk-2.0-release.md). The root package is the only
+npm publication; identity and shell-kit workspaces remain private. Versions in the root
+manifest, lockfile and identity workspace must match. All export targets and the shipped
+knowledge-service runtime assets are checked before publication.
 
-## Python tooling (`agentsam_sdk`)
+`scripts/npm-publish-preflight.sh` checks package invariants and npm login. Package
+publishing rights are enforced by npm, not a hardcoded local username. Scoped public
+publication uses `--access public`.
 
-Portable stdlib audits live under [`python/`](./python/) (import path `agentsam_sdk.*`).
+Stable publishing is manual:
 
-```bash
-cd python
-python3 -m pip install -e ".[dev]"
-python3 -m pytest
-python3 -m agentsam_sdk.repository.inventory --json --root /path/to/repo
+```sh
+npm publish --tag latest --access public
 ```
 
-Inner Animal Media keeps a thin shim at `scripts/repo-size-inventory.py` that adds
-`AGENTSAM_SDK_ROOT/python` (or a sibling/`~/agentsam-sdk` checkout) to `sys.path`.
+Legacy `publish:identity-alpha` commands and the manual alpha workflow only accept alpha
+versions. They do not publish a stable version under the alpha tag.
 
-## Known gaps (roadmap)
+## Remaining integration work
 
-- `agentsam status`, `agentsam logs` — not implemented yet
-- `agentsam identity init` — scaffolds `app/frontend` + `backend` + D1 migrations
-- Gorilla Shell Phase 1 — PTY WebSocket bridge to ExecOS
-- CMS lane in README — CLI has 5 lanes (Full Stack, CMS, Data, CRM, Creative)
-- Published API route may differ; stub mode works without `AGENTSAM_SDK_TOKEN`
+The local status command is implemented. Hosted execution/orchestration, production
+knowledge-service routing, additional embedding adapters, scheduled indexing, and retention
+are separate host or feature work. The archived execution branch is mapped in
+[branch archive](docs/branch-archive-2026-09-02.md); it is not an implemented API surface.
 
-See [docs/CLI_SHELL.md](./docs/CLI_SHELL.md) for the game-feel terminal UX path.
+Gorilla remains a visual experiment. It is not the default scaffold or a production shell.

package/README.md

@@ -1,233 +1,117 @@
-# Agent Sam SDK
+# AgentSam SDK
 
-> The AI agent layer for developers who need more than a chatbot.
+Portable SDK modules and CLI kits for creating local projects, inspecting repositories,
+indexing selected code, integrating identity, and maintaining dependencies.
 
-Agent Sam is a full-stack autonomous agent SDK built on Cloudflare Workers, D1, Supabase, Durable Objects, and MCP — designed to converse, plan, and execute real work across your entire stack. CMS websites, full-stack applications, data pipelines, creative workflows, terminal execution, deployments, and multi-step agentic pipelines — all through one unified agent interface.
+**npm:** `@inneranimalmedia/agentsam-sdk` · **Source:** [GitHub](https://github.com/SamPrimeaux/agentsam-sdk)
 
-**Repo:** [github.com/SamPrimeaux/agentsam-sdk](https://github.com/SamPrimeaux/agentsam-sdk) · **npm:** `@inneranimalmedia/agentsam-sdk`
+Node 22.5+ is required. Docker is optional for container commands. Python 3.10+ is required
+for the bundled Python repository tools; Rich is optional for the richer terminal UI.
+See the [2.0 release guide](docs/sdk-2.0-release.md) for publication status and migration notes.
 
-**Protocol (dual-home, no drift):** [`protocol/README.md`](./protocol/README.md) — every tool/feature lands in this repo **and** `inneranimalmedia/agentsam-sdk/`; npm publish is manual after mirror. Python lane: [`python/`](./python/) (stdlib-only). Optional network Python package: [`packages/agentsam-site-scrape/`](./packages/agentsam-site-scrape/) (live experimental; does not break the stdlib core).
+## Install
 
----
-
-## What is Agent Sam?
-
-Agent Sam is a platform operator AI. It sits on top of your infrastructure and can:
-
-- **Understand intent** — natural language in, real actions out
-- **Execute across surfaces** — terminal, database, browser, CAD, deploy, MCP tools
-- **Route intelligently** — local machine, cloud VM, or sandboxed environment based on context
-- **Gate high-risk actions** — approval flows before anything destructive runs
-- **Leave an audit trail** — every tool call, command run, and decision is logged
-
-It is not a wrapper around a chat API. It is a command fabric with a conversation interface.
-
----
-
-## Quickstart (local-first — Node only)
-
-```bash
-npx @inneranimalmedia/agentsam-sdk init
+```sh
+npm install @inneranimalmedia/agentsam-sdk
+# Or install the CLI globally:
+npm install -g @inneranimalmedia/agentsam-sdk
 ```
 
-Default path: **localhost**. No IAM login, no Cloudflare OAuth, no accounts. Under 2 minutes with Node 20+ installed.
+The identity workspace is included through `@inneranimalmedia/agentsam-sdk/identity`.
+It is not a separate npm installation. A container is not required to import SDK modules
+or use local scaffolding/indexing.
 
-```bash
-cd my-project
+## Create a local application
+
+```sh
+agentsam init --name my-agent --yes
+cd my-agent
 npm install
 npm run smoke
-npx agentsam start-local   # local PTY on ws://127.0.0.1:3099
-npx agentsam tunnel        # cloudflared → register with IAM (dashboard Local lane)
-npm run dev                # http://127.0.0.1:8787
-npm run db:migrate         # local D1 schema
-```
-
-`agentsam tunnel` (default `--quick`) starts a Cloudflare quick tunnel to `:3099` and POSTs the `wss://` URL to `/api/sdk/terminal/register-local` so `agentsam_terminal_local` can reach your machine. Use `--named --tunnel-name … --hostname … --zone-id …` for a stable BYOK named tunnel.
-When you're ready to ship to **your** Cloudflare account:
-
-```bash
-npx agentsam deploy
-```
-
-Cloudflare OAuth is prompted **only at deploy** — not at init.
-
-Non-interactive init:
-
-```bash
-npx @inneranimalmedia/agentsam-sdk init \
-  --name my-agent \
-  --lane fullstack \
-  --run-target local \
-  --yes
+npm run dev
 ```
 
-Run targets at init: `local` (default) · `cloudflare` · `gcp` — all scaffold locally first; cloud credentials come at deploy.
-
-See [DEVELOPMENT.md](./DEVELOPMENT.md) for linking the SDK into Inner Animal Media locally.
+This creates a Git repository, local SQLite database, environment templates, a Node API,
+and terminal commands. Local setup does not require an IAM account, cloud credentials,
+or a tunnel. `npm run status`, `npm run tui`, and `npm run pty` inspect or operate the
+generated project. A configured host/provider is required when selecting cloud operations.
 
----
+Without a global install, use `npx @inneranimalmedia/agentsam-sdk init --name my-agent --yes`.
 
-## CLI Shell Experience (Gorilla)
+## Index an existing repository
 
-The SDK ships a **game-feel terminal UX** alongside the scaffold CLI — consolidated from the Gorilla Mode experiment:
-
-```bash
-npx @inneranimalmedia/agentsam-sdk shell
+```sh
+agentsam init . --yes --include src,docs
+agentsam index plan
+agentsam index run
+agentsam search "configuration loading"
+agentsam repo snapshot --save
 ```
 
-| Piece | Location |
-|-------|----------|
-| Slash command registry | `src/lib/slash-commands.js` |
-| Phase 0 visual prototype | `templates/gorilla-shell/` (canonical; `examples/gorilla-shell/` is a pointer) |
-| Architecture + phases | [docs/CLI_SHELL.md](./docs/CLI_SHELL.md) |
-
-Run the prototype:
-
-```bash
-cd templates/gorilla-shell && npm install && npm run dev
+Choose literal files/directories that actually exist in your repository. Initial indexing
+is local AST/text work and makes no embedding calls. Unchanged content is cached; saved
+generations retain source provenance. Explicit Gemini embedding requests and Postgres
+storage are optional. See [portable knowledge](docs/portable-knowledge.md).
+
+The JavaScript/TypeScript parser records syntactic relationships, not a fully resolved
+semantic call graph. Model/dimension changes create a distinct embedding profile.
+Python-backed snapshots capture repository composition and Git churn.
+
+## Available kits
+
+| Capability | Entry point | Guide |
+| --- | --- | --- |
+| Git context and bridge client | `agentsam context --json`; `/git-context`, `/bridge-client` | [Portable context](docs/PORTABLE_CONTEXT.md) |
+| Identity contracts and adapters | `/identity`; `agentsam identity init` | [Identity](packages/identity/README.md) |
+| Repository knowledge | `agentsam index`, `search`, `repo`; `/knowledge` | [Knowledge](docs/portable-knowledge.md) |
+| File integrity | `agentsam merkle`; `/merkle` | [Merkle](docs/MERKLE.md) |
+| Dependency health and repair | `agentsam security`; `/security` | [Security](docs/SECURITY.md) |
+| Mini prototypes | `agentsam mini`; `/mini` | [Mini](docs/MINI.md) |
+| Local containers | `agentsam dockerize`; `/dockerize` | [Dockerize](docs/DOCKERIZE.md) |
+| Background indexing service | Docker `knowledge_service`; `/knowledge-service-client` | [Knowledge service](docs/knowledge-service.md) |
+| Local status, DB, terminal UI | `agentsam status`, `db`, `tui`, `start-local` | [Terminal UI](docs/CLI_SHELL.md) |
+
+Export suffixes such as `/identity` mean imports from
+`@inneranimalmedia/agentsam-sdk/identity`. Use `agentsam <command> --help` where supported.
+
+## Optional background service
+
+```sh
+agentsam dockerize --type knowledge_service --name agentsam-knowledge \
+  --repository app=/absolute/path/to/repository
 ```
 
----
+The preset builds a small runtime image, mounts source read-only, exposes an authenticated
+localhost job API, and preserves indexes/jobs in a Docker volume. Embeddings are disabled
+by default. It uses the same SDK indexing engine; CocoIndex is not a dependency.
 
-## Architecture (CORE default)
+The service is a separate deployment target. It does not automatically connect production
+Workers, ingest customer repositories, schedule scans, or supply end-user authorization.
+The fetch-only `/knowledge-service-client` export can be used by a Worker after the host
+authorizes its caller. Other local tooling uses Node APIs.
 
-`src/lib/core-client.js` defaults to `https://inneranimalmedia.com`. **Correct as designed** for serving many client projects: the npm package is a thin delivery/CLI client; intelligence, tool catalog, and policy live server-side on IAM CORE.
+## Host integration and ownership
 
-Without an IAM backend (or `IAM_CORE_URL` / `AGENTSAM_CORE_URL` override), strangers who `npm install` get **scaffold + local CLI only** — not a freestanding hosted Agent Sam.
+The root `AgentSam` helper supplies routing/session primitives. Full model orchestration,
+tool execution policy, provider credentials, user authorization, and production storage
+belong to the consuming host application. The npm package alone does not provide a hosted
+autonomous agent platform. The old `scaffoldProject()` export is deprecated; use the local
+CLI scaffold command.
 
----
+This repository owns portable code once. Applications import it and provide adapters;
+they do not mirror SDK trees. [Ownership protocol](protocol/README.md).
 
-## Installation
+## Development and releases
 
-```bash
-npm install @inneranimalmedia/agentsam-sdk
+```sh
+npm ci
+npm run verify:release
 ```
 
----
-
-## Lanes
-
-| Lane | Best For |
-|------|----------|
-| **Full Stack** | End-to-end apps — agent chat, terminal, deploy, D1, R2, Durable Objects, KV |
-| **CMS** | Content-managed websites — pages, assets, themes, navigation, live edit |
-| **Data Solutions** | Database ops, migrations, queries, Supabase pgvector, Hyperdrive pipelines |
-| **Customer Management** | CRM, contacts, billing, client workflows, multi-tenant isolation |
-| **Creative & Design** | CAD, 3D, media generation, content pipelines |
-
----
-
-## Agents
-
-| Agent | Role |
-|-------|------|
-| **Orchestrator** | General purpose — routes across all lanes and tools |
-| **CMS Agent** | Pages, sections, assets, themes, publishing workflows |
-| **Data Agent** | D1, Supabase, Hyperdrive, migrations, vector search |
-| **CRM Agent** | Customer records, contacts, billing, client isolation |
-| **Creative Agent** | Design commands, 3D generation, CAD, media pipelines |
-
----
-
-## How It Works
-
-```
-User Intent (chat or CLI)
-        ↓
-   Agent Sam — intent classification + command match
-        ↓
-   Tool Catalog (D1) — policy check + approval gate
-        ↓
-   Execution — terminal / D1 / Supabase / R2 / KV / DO / browser / deploy / MCP
-        ↓
-   Telemetry — every action logged, measured, improvable
-```
-
-Capabilities are data-driven — new tools are added via D1, not Worker redeployments. The same tool catalog powers the dashboard, the CLI, and any MCP-connected client like Cursor or Claude Desktop.
-
----
-
-## Infrastructure
-
-Agent Sam scaffolds and operates across the full Cloudflare + Supabase stack:
-
-| Layer | Technology | Role |
-|-------|------------|------|
-| **Compute** | Cloudflare Workers | Edge runtime, API, agent dispatch |
-| **Relational DB** | D1 (SQLite) | Tool catalog, sessions, telemetry, CMS, auth |
-| **Vector DB** | Supabase pgvector via Hyperdrive | RAG, semantic search, agent memory |
-| **Object Storage** | R2 | Assets, media, bundles, CMS content |
-| **Key-Value** | Workers KV | Cache, CMS drafts, feature flags |
-| **Stateful Sessions** | Durable Objects | Terminal sessions, collab, real-time state |
-| **Terminal** | ExecOS over cloudflared tunnel | Shell execution, deploy, git, wrangler |
-| **AI Router** | Anthropic + OpenAI | Adaptive Thompson sampling across models |
-| **Protocol** | MCP (Model Context Protocol) | External agent surface for Cursor, Claude, etc. |
-
----
-
-## Execution Lanes
-
-Agent Sam routes work to the right environment automatically:
-
-| Lane | Environment | When |
-|------|-------------|------|
-| Local | Your machine | Fastest dev loop |
-| Cloud | Always-on VM via tunnel | Machine asleep or offsite |
-| Sandbox | Isolated workspace | Safe experiments, tenant isolation |
-
----
-
-## What Gets Scaffolded
-
-Running `agentsam init` generates a production-ready project for your lane:
-
-**All lanes include:**
-- `agentsam.config.js` — project config, lane, provider, agent
-- `wrangler.toml` — Worker, D1, R2, KV, Durable Object bindings
-- `.env.example` — all required secrets pre-listed
-- `src/index.js` — Worker entry point wired to your agent
-- `README.md` — setup and deploy instructions
-
-**CMS lane adds:** page/section/asset schema migrations and CMS worker scaffold.
-
-**Data lane adds:** D1 + Hyperdrive config and migration templates.
-
-**Full Stack adds:** Durable Object session scaffold, auth tables, full agent chat loop.
-
----
-
-## Multi-Tenant & Client Policy
-
-- Each user or client gets a scoped workspace
-- Terminal execution is path-isolated — no cross-tenant access
-- AI usage is policy-gated — BYOK, managed, or disabled per client
-- D1 and R2 are scoped per tenant at the binding level
-- Every action produces an audit trail
-
----
-
-## Roadmap
-
-- [x] `agentsam shell` — shell UX info + slash command registry
-- [x] Gorilla Shell Phase 0 prototype in `examples/gorilla-shell/`
-- [x] `agentsam deploy` — push your project from CLI
-- [x] Identity alpha — contracts, providers, auth portal preview (`agentsam identity preview`)
-- [ ] `agentsam status` — live agent and infrastructure health
-- [ ] `agentsam logs` — tail tool call and command logs
-- [ ] PTY bridge (Phase 1) — ExecOS WebSocket in shell
-- [ ] Kit marketplace — CMS, ecommerce, nonprofit, SaaS starters
-- [ ] BYOK AI key support per project
-
----
-
-## Built By
-
-[Inner Animal Media](https://inneranimalmedia.com) — Agent Sam is the operator brain behind the platform. The SDK is how we productize that infrastructure for other developers.
-
-**Legacy:** [InnerAnimal/gorilla-mode](https://github.com/InnerAnimal/gorilla-mode) → consolidated here.
-
----
-
-## License
+Release verification runs Node/identity tests, bootstrap and package checks, installed
+tarball fixtures in unrelated repositories, Python tests, and a complete dependency scan.
+[Development](DEVELOPMENT.md) · [Release guide](docs/sdk-2.0-release.md) ·
+[Branch archive](docs/branch-archive-2026-09-02.md).
 
-MIT
+License: MIT. Optional visual experiments and host-specific integrations retain their
+documented boundaries; they are not automatically installed into customer applications.

package/bin/tag

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# ============================================================================
+# bin/tag  (agentsam-sdk)
+#
+# WHAT THIS IS:
+#   Cross-repo hashtag ledger. Machine-random identifiers (commit SHAs,
+#   branch suffixes like "8edb", patch filenames, D1 UUIDs) are impossible
+#   to remember. This maps a human hashtag -> whatever the real ref is,
+#   across ALL your repos, in one file: tags/registry.json (in this repo,
+#   since agentsam-sdk is the one thing every project already touches).
+#
+#   Convention: #<repo-shorthand>-<theme>[-<seq>], lowercase, hyphenated.
+#   e.g. #remix-workmode, #sdk-allowscripts, #workmode-promote
+#
+# USAGE:
+#   bin/tag add "#name" --repo <repo> --ref <sha|branch|patch|url> --note "..."
+#   bin/tag find "#name"        (substring match on tag, repo, or note)
+#   bin/tag list                (everything, most recent first)
+#   bin/tag list --repo <repo>
+# ============================================================================
+set -euo pipefail
+
+SDK_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REGISTRY="$SDK_ROOT/tags/registry.json"
+mkdir -p "$(dirname "$REGISTRY")"
+[[ -f "$REGISTRY" ]] || echo "[]" > "$REGISTRY"
+
+norm_tag() {
+  local t="$1"
+  [[ "$t" == \#* ]] || t="#$t"
+  echo "$t" | tr '[:upper:]' '[:lower:]'
+}
+
+cmd_add() {
+  local tag="" repo="" ref="" note=""
+  tag="$(norm_tag "$1")"; shift
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --repo) repo="$2"; shift 2 ;;
+      --ref)  ref="$2"; shift 2 ;;
+      --note) note="$2"; shift 2 ;;
+      *) echo "Unknown arg: $1" >&2; exit 1 ;;
+    esac
+  done
+  local date
+  date="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  local tmp
+  tmp="$(mktemp)"
+  jq --arg tag "$tag" --arg repo "$repo" --arg ref "$ref" --arg note "$note" --arg date "$date" \
+    '. + [{tag:$tag, repo:$repo, ref:$ref, note:$note, date:$date}]' \
+    "$REGISTRY" > "$tmp" && mv "$tmp" "$REGISTRY"
+  echo "added $tag"
+}
+
+cmd_find() {
+  local q
+  q="$(echo "${1:-}" | tr '[:upper:]' '[:lower:]')"
+  jq -r --arg q "$q" '
+    [.[] | select(
+      (.tag | ascii_downcase | contains($q)) or
+      (.repo | ascii_downcase | contains($q)) or
+      (.note | ascii_downcase | contains($q))
+    )] | sort_by(.date) | reverse | .[] |
+    "\(.date)  \(.tag)  [\(.repo)]  \(.ref)\n    \(.note)\n"
+  ' "$REGISTRY"
+}
+
+cmd_list() {
+  local repo_filter=""
+  if [[ "${1:-}" == "--repo" ]]; then repo_filter="${2:-}"; fi
+  jq -r --arg repo "$repo_filter" '
+    (if $repo == "" then . else [.[] | select(.repo == $repo)] end)
+    | sort_by(.date) | reverse | .[] |
+    "\(.date)  \(.tag)  [\(.repo)]  \(.ref)\n    \(.note)\n"
+  ' "$REGISTRY"
+}
+
+case "${1:-list}" in
+  add)  shift; cmd_add "$@" ;;
+  find) shift; cmd_find "$@" ;;
+  list) shift; cmd_list "$@" ;;
+  *) echo "Usage: $0 {add \"#tag\" --repo R --ref REF --note N|find \"#tag\"|list [--repo R]}" >&2; exit 1 ;;
+esac