caplets 0.16.0 → 0.17.0

package/README.md

@@ -30,6 +30,10 @@ Instead of exposing a flat wall of tools, Caplets shows one top-level tool per c
 The agent chooses a domain first, then uses scoped operations like `search_tools`,
 `get_tool`, and `call_tool` only when it needs more detail.
 
+For MCP-backed Caplets, the scoped operation set also includes resource discovery/reading,
+prompt listing/rendering, resource-template discovery, and completion for prompt or template
+arguments. Non-MCP backends continue to expose only tool/action operations.
+
 ## Quick Start
 
 Caplets requires Node.js 22 or newer.
@@ -76,10 +80,47 @@ caplets list-tools context7
 caplets get-tool context7.resolve-library-id
 caplets call-tool context7.resolve-library-id --args '{"libraryName":"react"}'
 caplets call-tool context7.resolve-library-id --args '{"libraryName":"react"}' --field result.id --format json
+caplets list-resources docs
+caplets read-resource docs file:///repo/README.md
+caplets list-prompts linear
+caplets get-prompt linear.review_issue --args '{"issueId":"CAP-123"}'
+caplets complete docs --resource-template 'file:///repo/{path}' --argument path --value src/
 ```
 
 Direct CLI operation commands print Markdown summaries by default. Add `--format plain` for plain text or `--format json` for machine-readable JSON (`md` is accepted as an alias for `markdown`). If a downstream tool returns `isError: true`, Caplets still exits with status code 1.
 
+### Shell completions
+
+The npm package ships shell completion generators for Bash, Zsh, Fish, PowerShell, and cmd. Installation is explicit: `npm install -g caplets` does not modify shell startup files or system completion directories.
+
+```sh
+# Bash
+mkdir -p ~/.local/share/bash-completion/completions
+caplets completion bash > ~/.local/share/bash-completion/completions/caplets
+
+# Zsh
+mkdir -p ~/.zsh/completions
+caplets completion zsh > ~/.zsh/completions/_caplets
+# Ensure ~/.zsh/completions is on fpath before compinit, then reload your shell:
+# echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+# echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
+
+# Fish
+mkdir -p ~/.config/fish/completions
+caplets completion fish > ~/.config/fish/completions/caplets.fish
+
+# PowerShell
+caplets completion powershell | Out-String | Invoke-Expression
+
+# cmd.exe
+caplets completion cmd > %USERPROFILE%\caplets-completion.cmd
+%USERPROFILE%\caplets-completion.cmd
+```
+
+Completions include command names, options, common enum values, configured Caplet IDs, and cache-backed downstream names for qualified targets such as `caplets call-tool repo.<TAB>`. Downstream discovery is bounded by the `completion` config timeouts and a platform-native cache directory. Generated shell scripts suppress completion stderr; run the underlying CLI command directly when debugging completion behavior.
+
+Backends that require OAuth or token auth may need `caplets auth login <server>` before live downstream completions can return richer results. Completion never starts interactive login flows.
+
 ## Agent Plugins
 
 Use Caplets as a normal MCP server everywhere, or install a native agent integration when
@@ -124,6 +165,46 @@ With `CAPLETS_SERVER_URL=http://127.0.0.1:5387/caplets`, the derived endpoints a
 
 `caplets serve --transport http` serves plain HTTP. For non-loopback or network access, expose it only through HTTPS/TLS (for example, a reverse proxy or secure tunnel) and enable Basic Auth; Basic Auth over plain HTTP exposes credentials. Keep credentials out of plugin manifests.
 
+#### Docker Compose self-hosting
+
+This repository includes a source-build Docker image and Compose service for running the HTTP service from the checked-out source tree:
+
+```sh
+CAPLETS_SERVER_PASSWORD=change-me docker compose up --build
+```
+
+By default, Compose publishes the service on loopback only:
+
+- Base URL: `http://127.0.0.1:5387`
+- MCP endpoint: `http://127.0.0.1:5387/mcp`
+- Control endpoint: `http://127.0.0.1:5387/control`
+- Health endpoint: `http://127.0.0.1:5387/healthz`
+
+The service stores Caplets config and auth state in a Docker named volume mounted at `/data`. To use a host-visible bind mount instead, replace this Compose volume entry:
+
+```yaml
+volumes:
+  - caplets-data:/data
+```
+
+with:
+
+```yaml
+volumes:
+  - ./data:/data
+```
+
+To expose the service to a LAN interface or reverse proxy, set an explicit bind address and public base URL:
+
+```sh
+CAPLETS_BIND_ADDRESS=0.0.0.0 \
+CAPLETS_SERVER_URL=https://caplets.example.com \
+CAPLETS_SERVER_PASSWORD=change-me \
+docker compose up --build
+```
+
+Only expose Caplets beyond loopback through HTTPS/TLS and Basic Auth. `CAPLETS_SERVER_PASSWORD` protects both the MCP and control endpoints; downstream provider tokens and auth files remain server-owned inside the mounted `/data` location.
+
 Native integrations and remote-capable CLI commands read remote client settings from environment variables:
 
 ```sh
@@ -248,6 +329,12 @@ you want Caplets to expose:
   "version": 1,
   "defaultSearchLimit": 20,
   "maxSearchLimit": 50,
+  "completion": {
+    "discoveryTimeoutMs": 750,
+    "overallTimeoutMs": 1500,
+    "cacheTtlMs": 300000,
+    "negativeCacheTtlMs": 30000
+  },
   "mcpServers": {
     "filesystem": {
       "name": "Project Files",