akm-cli 0.9.30 → 0.10.261001-beta

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/supported-formats.md

@@ -20,7 +20,7 @@ one explicitly. 0.9.0 recognizes 11 formats.
 | `claude` | `CLAUDE.md` as `instruction`; `commands/`, `agents/`, `skills/<name>/SKILL.md` as their matching types | Root `CLAUDE.md` plus at least one of `commands/`, `agents/`, `skills/` | Read-only | Point AKM at an existing Claude Code `.claude` tool directory |
 | `opencode` | Same shape as `claude`, rooted on `AGENTS.md` | `opencode.json`/`opencode.jsonc`, or root `AGENTS.md` plus a canonical plural tool directory | Read-only | Point AKM at an existing OpenCode `.opencode` tool directory |
 | `dotenv` | `env` entries as key names only (never values); `secret` entries as file names only (never content) | Every top-level directory is `env/` and/or `secrets/`, with at least one present | Writable, narrowly — `akm env create`/`env remove`/`secret set` only | A standalone env/secrets-only bundle |
-| `akm-workflow` | Workflow steps, name, description, tags | Either a top-level `.md` file with explicit `type: workflow` frontmatter or a peer top-level GitHub-shaped `.yml` workflow | Writable — `akm workflow create` only | A standalone workflow bundle, one workflow per file |
+| `akm-workflow` | Workflow steps, name, description, tags | A top-level `.md` file with explicit `type: workflow` frontmatter | Writable — `akm workflow create` only | A standalone workflow bundle, one workflow per file |
 | `akm-task` | Task source v4 (`version: 4`) `.yml` sources as type `task`, including local schedules/manual triggers and the exact authored YAML | A top-level `.yml` file accepted by the task source v4 parser (`version: 4`, one `uses`/`run` executable selector, optional top-level `schedule:`) | Read-only | A standalone scheduled-task bundle; `.yaml` is rejected |
 | `llm-wiki` | `raw/` sources as `wiki-source`; `pages/` as their `pageKind` (default `note`), with resolved cross-reference links | Root `schema.md` plus a `pages/` directory | Read-only (author by writing directly into `pages/`; AKM indexes and serves the result) | [Karpathy's LLM-wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — agent-authored reference wikis |
 | `akm` (native) | AKM's own 14 native asset types — see [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) | A `.stash` marker directory, or two-plus native subdirectories, or the fallback when nothing else matches | Fully writable — every AKM-native write command | Your working bundle, and any bundle authored as AKM's own format |
@@ -50,9 +50,8 @@ indexed, scheduled, or executed. See [Tasks](tasks.md).
 
 ## Workflow formats
 
-Workflow sources are the one intentional peer-format case inside the native
-AKM workspace: workflows may be `.md` or `.yml`, and both compile to the same
-source IR. Task sources remain `.yml` only, authored as task source v4. See
+Workflow sources are `.md` and compile to source IR. Task sources are `.yml`
+only, authored as task source v4. See
 [Tasks](tasks.md) and [Workflow Schema](workflow-schema.md).
 
 ## Why this matters

package/docs/reference/tasks.md

@@ -251,10 +251,9 @@ redact: [TOKEN]
   consumer — a native run's status comes from its exit code alone — so
   declaring `output:` on them fails parsing with `TASK_SOURCE_INVALID`
   instead of silently recording a contract nothing enforces.
-- A task source v4 document **can** be the target of a workflow step's
-  `uses: tasks/<ref>` — see the
-  [GitHub-shaped YAML subset](workflow-schema.md#github-shaped-yaml-subset)
-  for how a workflow step's `with:` binds a v4 task's declared `inputs:`.
+- A workflow step cannot target a task: the GitHub-shaped YAML workflow format
+  that carried `uses: tasks/<ref>` was removed in 0.10. A task runs a workflow
+  (`uses: workflows/<ref>`), not the other way round.
 
 ### Input flags
 
@@ -280,10 +279,8 @@ workflow step's own composition uses); for every other target — `run:`
 shell, `scripts/<ref>`, `commands/<ref>` — the values are validated and then
 **discarded**. `akm task run`'s own flags never populate an
 `AKM_TASK_INPUTS` environment variable or a `## Task inputs` prompt block.
-Those two surfaces are a *different* delivery path: they exist only when a
-**workflow step** composes this task through `uses: tasks/<ref>` and a
-`with:` binding, resolved fresh for that step's own dispatch — see
-[`with:` on a task-composed step](workflow-schema.md#github-shaped-yaml-subset).
+Those two surfaces existed only for a workflow step composing a task through
+`uses: tasks/<ref>`, which was removed in 0.10.
 A scheduled run (`schedule[].inputs`, above) reaches the target through this
 same `akm task run` path, so it inherits the identical rule: delivered as
 params for a `workflows/<ref>` target, otherwise validated and discarded.
@@ -401,21 +398,17 @@ for full before/after examples and recovery guidance.
 
 ## Operations
 
-- `akm search --type task` (or its alias `akm task list`) and
+- `akm search --type task` and
   `akm show tasks/<id>` inspect task assets.
 - `akm task explain <ref>` prints a task's declared inputs, resolved target,
   effective execution settings, and schedule bindings without running
   anything — see [`akm task explain`](#akm-task-explain) above.
-- `akm task validate <path>` parses one task file by filesystem path (the
-  file need not live in a configured bundle) and reports the same
-  `valid`/`blocked`/`invalid`/`not-a-task` diagnostic
-  `akm task sync` would produce for it — including sync's own cron-dialect
-  check and its per-schedule-entry input-contract check — without touching
-  the scheduler and without requiring a configured engine, even for a
-  command-kind task. The envelope's own `sourceVersion` field names the
-  file's declared schema version. A version 2/3 file, and a `version: 4`
-  file still carrying a retired `schedule[].enabled`, report `blocked`
-  (exit 1) naming `akm migrate apply`, which converts them.
+- `akm lint --type tasks` reports what `akm task sync` would refuse for a task
+  file: a document that does not parse as task source v4, a version 2/3 file or
+  a `version: 4` file still carrying a retired `schedule[].enabled` (the finding
+  names `akm migrate apply`, which converts them), a cron the local scheduler
+  backend cannot parse, and a schedule entry whose `inputs` leave a required
+  input unsatisfied. It is read-only and needs no configured engine.
 - `akm task add` validates a task source v4 document, writes it, adds its ref
   to local scheduler activation, and syncs its bundle. `--params` renders
   typed `inputs:` declarations instead of a `with:` bag; `--schedule` is