agentwheel 0.14.13 → 0.16.0

package/README.md

@@ -98,6 +98,7 @@ Fragments are Agentwheel composition inputs, not runtime file-drop targets.
 
 | Command | Meaning |
 |---|---|
+| `agentwheel search <query>` | Search configured registries and the public enriched/Vercel catalogue; supports stable JSON output for agent reranking. |
 | `agentwheel add <source>` | Validate and save a package entry in `.agentwheel/config.json`; does not touch runtimes. |
 | `agentwheel plan [name-or-source]` | Preview what `install` would reconcile without writing; supports `--profile <name>` and `--json`. |
 | `agentwheel install` | Reconcile configured packages into the current target or selected fleet. Uses the graph lock as input by default. |
@@ -152,6 +153,28 @@ agentwheel plan
 agentwheel install
 ```
 
+## Artifact Discovery
+
+Search configured registries and the complete public catalogue with one command:
+
+```bash
+agentwheel search "conversation memory"
+agentwheel search "telegram integration" --type skill
+agentwheel search "message recall" --json --limit 10
+```
+
+Use `--scope registry`, `--scope enriched`, or `--scope vercel` to restrict a query. The default
+`--scope all` combines every source, deduplicates equivalent artifacts, and reports every
+provenance plus the safe installation route.
+
+Search is deterministic and lexical. The companion skill adds semantic behavior at the agent
+layer: it can generate a small set of related queries, merge and rerank the JSON results against
+the original request, and suggest at most three artifacts. Search never installs or changes
+configuration by itself.
+
+Registry maintenance remains available through `agentwheel registry update` and
+`agentwheel registry list`. Registry short names continue to resolve during add/install.
+
 ## Source Inputs
 
 Agentwheel can install from explicit local paths, Git sources, catalogue short names, provider
@@ -378,6 +401,28 @@ be deselected:
 }
 ```
 
+### Root version policy
+
+Workspace packages can combine source movement with an npm-style release policy:
+
+```jsonc
+{
+  "name": "agent-pack",
+  "source": "github:your-org/agent-pack",
+  "driver": "git",
+  "mode": "tracking",
+  "version": "^1.4.0"
+}
+```
+
+`mode: pinned` never advances automatically. `mode: tracking` may advance to the newest release
+allowed by an exact version, `~`, `^`, comparator range, or `*`. Status always reports installed,
+locked, latest allowed, and latest overall versions, including newer releases outside the selected
+policy. Version discovery uses a 24-hour cache by default; `--refresh` bypasses it and `--offline`
+uses cached metadata marked stale when its TTL has expired. Git packages use semver tags as
+enumerable releases. A branch without tags can report a changed HEAD but cannot select an older
+compatible release; explicit refs and commits remain pins.
+
 ### Project-owned selection exports
 
 Workspace configuration `schemaVersion: 2` can export named artifact selections. This is useful
@@ -662,6 +707,7 @@ Built-in runtime targets:
 - [`llms.txt`](llms.txt) — LLM-oriented map of the public docs.
 - [`docs/spec/openpack.md`](docs/spec/openpack.md) — OpenPack package spec.
 - [`docs/fleet-config.md`](docs/fleet-config.md) — named agents, SSH targets, and profiles.
+- [`docs/design/federated-fleet-clusters.md`](docs/design/federated-fleet-clusters.md) — federating autonomous workspaces under one doctor/update control plane.
 - [`docs/design/artifact-harness-compatibility.md`](docs/design/artifact-harness-compatibility.md) — artifact/harness compatibility matrix and rule semantics.
 - Resource catalogue: https://nestdevlab.github.io/agentwheel/catalogue.html.
 - [`DESIGN.md`](DESIGN.md) — architecture and module layout.