docs: bring the command and local API references up to date (P2.4)

commands.md lists all 23 registered slash commands with their working
aliases and drops the FTS5 and two-mind wording. api.md explains the
bearer session token and that the API is internal, fixes the session
route parameters, lists the memory routes served through the memory
contract, the current chat stream events and the permissions body, and
removes the team, import and KVARK enterprise-pack routes.
This commit is contained in:
shumeiko.it
2026-11-01 02:01:57 +01:00
parent 94d54c4188
commit dd6564451a
2 changed files with 144 additions and 128 deletions

View File

@@ -1,27 +1,41 @@
# Commands Reference
# Slash commands
Waggle provides 14 slash commands for quick actions. Type `/` in any workspace to see autocomplete suggestions.
Type `/` in a chat to see the commands with autocomplete. A command is `/name` followed by its
arguments; aliases work the same way as the name. Many commands hand a prepared request to the
agent, which then uses its normal tools and approvals.
## Command List
The commands are defined in `packages/agent/src/commands/` (`workflow-commands.ts` and
`marketplace-commands.ts`).
| Command | Aliases | Args | Description |
|---------|---------|------|-------------|
| `/catchup` | `/catch-up`, `/recap` | -- | Workspace restart summary. Shows recent activity, memories, and state so you can get up to speed instantly. |
| `/now` | `/current`, `/where` | -- | Current workspace state. What is happening right now -- active threads, recent changes, open items. |
| `/research` | `/investigate` | `<topic>` | Launch multi-agent research. Spawns the `research-team` workflow with multiple agents investigating the topic in parallel. |
| `/draft` | `/write` | `<type> [topic]` | Start a drafting workflow. Supports any document type: blog, report, email, proposal, memo. Uses the `review-pair` workflow for drafts with review. |
| `/decide` | `/decision`, `/weigh` | `<question>` | Create a structured decision matrix with options, pros/cons, risk, and effort columns. Provides an evaluation framework for systematic decision-making. |
| `/review` | `/critique`, `/check` | -- | Review the last output with a critic agent. Spawns the `review-pair` workflow to analyze the most recent response for accuracy and completeness. |
| `/spawn` | `/agent`, `/summon` | `<role> [task]` | Spawn a specialist sub-agent. Available roles: `researcher`, `writer`, `coder`, `analyst`, `reviewer`, `planner`. |
| `/skills` | `/abilities`, `/tools` | -- | Show active skills in this workspace. Lists all loaded skill files with their names. |
| `/status` | `/report`, `/progress` | -- | Project status summary. Shows workspace state including tasks, progress, blockers, and recent activity. |
| `/memory` | `/remember`, `/recall` | `[query]` | Search workspace memory. Without arguments, shows usage help. With a query, searches both personal and workspace minds. |
| `/plan` | `/decompose`, `/break-down` | `<goal>` | Break a goal into actionable tasks. Uses the `plan-execute` workflow to create a structured task list with dependencies. |
| `/focus` | `/narrow`, `/scope` | `<topic>` | Narrow agent focus to a specific topic. Subsequent responses prioritize this context. Use again to change focus. |
| `/marketplace` | `/mp`, `/market` | `<subcommand> [args]` | Marketplace operations. Sub-commands: `search`, `install`, `packs`, `installed`, `sync`. See details below. |
| `/help` | `/commands`, `/?` | -- | List all available commands with descriptions. |
## Command list
## Detailed Examples
| Command | Aliases | Arguments | What it does |
|---|---|---|---|
| `/catchup` | `/catch-up`, `/recap` | | Summary of where the workspace stands: recent activity, memories and state |
| `/now` | `/current`, `/where` | | What is happening in the workspace right now |
| `/status` | `/report`, `/progress` | | Project status: tasks, progress, blockers and recent activity |
| `/research` | `/investigate` | `<topic>` | Runs the `research-team` workflow on a topic |
| `/draft` | `/write` | `<type> [topic]` | Drafts a document (memo, report, email, proposal…) with a review cycle |
| `/decide` | `/decision`, `/weigh` | `<question>` | Builds a decision matrix with options, pros, cons, risk and effort |
| `/review` | `/critique`, `/check` | | Has a critic agent review the last answer |
| `/plan` | `/decompose`, `/break-down` | `<goal>` | Breaks a goal into a task list |
| `/spawn` | `/agent`, `/summon` | `<role> [task]` | Starts a specialist sub-agent: `researcher`, `writer`, `coder`, `analyst`, `reviewer` or `planner` |
| `/focus` | `/narrow`, `/scope` | `<topic>` | Narrows the agent's focus to a topic until you change it |
| `/memory` | `/remember`, `/recall` | `<query>` | Searches personal and workspace memory |
| `/search-all` | `/find-all` | `<query>` | Searches personal memory and all workspaces |
| `/skills` | `/abilities`, `/tools` | | Lists the active skills |
| `/plugins` | | | Lists installed plugins and capabilities |
| `/connectors` | `/integrations`, `/connections` | | Lists connected services and their status |
| `/marketplace` | `/mp`, `/market` | `<subcommand> [args]` | Marketplace: `search`, `install`, `packs`, `installed`, `sync` |
| `/workflow` | `/wf` | `<create\|list\|run> [args]` | Creates, lists or runs multi-agent workflows |
| `/export` | | `<memories\|sessions\|all\|workspace>` | Exports workspace data with the agent's help |
| `/import` | | `<source>` | Reads a file, URL or pasted text and saves what matters as workspace memories |
| `/cli` | `/cli-tools` | `[allow\|deny\|discover] [name]` | Shows or changes which command-line programs the agent may run |
| `/pr` | `/pull-request`, `/merge-request` | `<title>` | Creates a pull request from the current branch of the workspace's repository |
| `/settings` | | | Shows the current workspace and agent settings |
| `/help` | `/commands`, `/?` | | Lists all commands |
## Examples
### /catchup
@@ -29,72 +43,55 @@ Waggle provides 14 slash commands for quick actions. Type `/` in any workspace t
/catchup
```
Output: A structured briefing with what this workspace is about, recent sessions, decisions, memory count, and suggested next steps. Use this every time you return to a workspace after a break.
A briefing for when you come back to a workspace: what it is about, recent sessions, decisions
and suggested next steps.
### /research
```
/research quantum computing applications in drug discovery
/research applications of quantum computing in drug discovery
```
Spawns the `research-team` multi-agent workflow:
1. A researcher agent investigates the topic
2. Findings are synthesized and cross-referenced
3. Results are presented with citations and confidence levels
Runs the `research-team` workflow: research agents investigate the topic and their findings are
combined into one answer.
### /draft
```
/draft blog post about AI safety best practices
/draft report quarterly metrics for Q1 2026
/draft email to client about project timeline changes
/draft report quarterly metrics for Q1
/draft email to the client about the timeline change
```
The agent determines the document type from the first word and adapts its formatting accordingly. If the `review-pair` workflow is available, the draft goes through a review cycle.
The first word is the document type.
### /decide
```
/decide Should we use PostgreSQL or MongoDB for the new project?
/decide Should we use PostgreSQL or MongoDB for the new service?
```
Produces a decision matrix template:
| Option | Pros | Cons | Risk | Effort |
|--------|------|------|------|--------|
| PostgreSQL | | | | |
| MongoDB | | | | |
Ask the agent to fill it in: "Please analyze this decision for me."
Produces a matrix with a row per option and columns for pros, cons, risk and effort. Ask the
agent to fill it in.
### /spawn
```
/spawn researcher Find recent papers on transformer architectures
/spawn coder Implement a rate limiter middleware
/spawn analyst Compare our metrics against industry benchmarks
/spawn researcher Find recent papers on retrieval-augmented generation
/spawn coder Write a rate limiter middleware
```
The sub-agent runs with the specified role and task, then returns its results to the main conversation.
The sub-agent works on the task and returns its result to the conversation.
### /memory
### /memory and /search-all
```
/memory architecture decisions
/memory last meeting notes
/memory project goals
/search-all project deadlines
```
Searches both personal and workspace memory using FTS5 full-text search. Results include content, importance level, and dates.
### /plan
```
/plan Build a user dashboard with analytics
/plan Migrate the database to PostgreSQL
```
Creates a structured plan with ordered steps, dependencies, and success criteria. The agent can then execute steps sequentially.
`/memory` searches personal memory and the current workspace's memory. `/search-all` also
searches every other workspace and groups the results by workspace. See
[memory.md](../memory.md).
### /marketplace
@@ -106,33 +103,32 @@ Creates a structured plan with ordered steps, dependencies, and success criteria
/marketplace sync
```
| Sub-command | Description |
|-------------|-------------|
| `search <query>` | Search the marketplace catalog by keyword. Returns up to 10 results with name, type, category, and description. |
| `install <name>` | Install a package by name. Searches for the best match, runs SecurityGate scan, and installs. |
| `packs` | List all capability packs grouped by priority tier. |
| `installed` | Show all currently installed packages with status and install date. |
| `sync` | Trigger a manual sync from all configured marketplace sources. Reports added/updated counts. |
| Subcommand | What it does |
|---|---|
| `search <query>` | Searches the catalog, up to 10 results |
| `install <name>` | Finds the best match, runs the security scan and installs it |
| `packs` | Lists the capability packs |
| `installed` | Lists installed packages |
| `sync` | Refreshes the catalog from its sources |
## Command Parsing
### /workflow
Commands follow the format `/commandName arg1 arg2 ...`. The parser:
```
/workflow list
/workflow run research-team
/workflow create Research competitors, summarize findings and draft an executive brief
```
1. Strips the leading `/`
2. Splits on the first space to get the command name and arguments
3. Resolves aliases (e.g., `/mp` resolves to `/marketplace`)
4. Executes the handler with the argument string and workspace context
## Adding a command
Partial matching is supported for autocomplete but not for execution. You must type the full command name or alias.
Commands are `CommandDefinition` objects registered with the `CommandRegistry`
(`packages/agent/src/commands/command-registry.ts`):
## Adding Custom Commands
- `name`: the command name, lowercase, without `/`;
- `aliases`: other names, also without `/`;
- `description` and `usage`: shown in `/help`;
- `handler(args, context)`: returns the reply text. A reply that starts with
`AGENT_LOOP_REROUTE_PREFIX` is sent to the agent as a request instead of shown directly.
Commands are registered in the `CommandRegistry`. To add a custom command, create a `CommandDefinition` with:
- `name` -- the primary command name (lowercase)
- `aliases` -- alternative names
- `description` -- shown in `/help` output
- `usage` -- usage string with argument placeholders
- `handler` -- async function receiving `(args: string, context: CommandContext)`
See `packages/agent/src/commands/` for implementation examples.
Register a new command in `registerWorkflowCommands` or in a registration function of your
own, called from the sidecar (`packages/server/src/local/index.ts`).