@openscout/scout 0.2.62 → 0.2.63

package/README.md

@@ -20,7 +20,7 @@ scout whoami
 scout who
 scout latest
 scout runtimes
-scout @dewey can you review our docs?
+scout ask --to dewey "can you review our docs?"
 ```
 
 `scout setup` is the canonical onboarding entry point. It creates or updates:
@@ -52,7 +52,7 @@ The routing rules do not change by harness, UI, or host:
 - owned work / requested reply -> `scout ask`
 - follow-up stays in the same DM or explicit channel
 
-The shortest healthy operator loop is:
+When sender, target, or recent activity is unclear, the shortest orientation loop is:
 
 ```bash
 scout whoami
@@ -86,13 +86,17 @@ Default sender resolution is:
 That keeps ordinary collaboration simple:
 
 ```bash
-scout whoami
-scout send "@vox heads up: I’m on the runtime side"
+scout send --to vox "heads up: I’m on the runtime side"
 scout ask --to vox "can you confirm the broker fix?"
 ```
 
 Known on-demand or offline agents are supposed to wake on first delivery. `scout send` and `scout ask` should be the default path; `scout up` is for explicit prewarming or for creating/registering a target the broker does not know yet.
 
+Prefer `scout send --to <agent> "message"` for tells. Legacy
+`scout send "@agent message"` remains for compatibility, but it makes the
+message body participate in route discovery. With `--to`, quoted handles inside
+the text stay text.
+
 ### File-backed input
 
 Use a file when the primary prompt or message is too large or too structured to
@@ -147,22 +151,24 @@ single owner.
 
 ### Addressing specific agents
 
-Agent identity has five dimensions: `definitionId`, workspace qualifier, `profile`, `harness`, `node`. Canonical form:
+Agent identity has six dimensions: `definitionId`, workspace qualifier, `profile`, `harness`, `model`, `node`. Canonical form:
 
 ```
-@<definitionId>[.<workspaceQualifier>][.profile:<profile>][.harness:<harness>][.node:<node>]
+@<definitionId>[.<workspaceQualifier>][.profile:<profile>][.harness:<harness>][.model:<model>][.node:<node>]
 ```
 
 Short `@name` only resolves when exactly one matching agent is available from the current context. If multiple agents share a name (e.g. one Codex-backed, one Claude-backed), pin the dimension you care about with a typed qualifier:
 
 ```bash
-scout @vox.harness:codex message from hudson: please retry the build
+scout send --to vox.harness:codex "message from hudson: please retry the build"
 scout ask --to vox.harness:claude "what did the reviewer flag?"
-scout @arc.profile:reviewer take another pass
-scout @vox.harness:codex.node:mini run locally on mini
+scout ask --to arc.profile:reviewer "take another pass"
+scout ask --to vox.harness:codex.node:mini "run locally on mini"
+scout ask --to lattices#codex?5.5 "take task A"
+scout ask --to lattices#claude?sonnet "take task B"
 ```
 
-Aliases: `runtime:` = `harness:`, `persona:` = `profile:`, `branch:` / `worktree:` = workspace qualifier. Dimensions combine in any order.
+Aliases: `runtime:` = `harness:`, `persona:` = `profile:`, `branch:` / `worktree:` = workspace qualifier. Shorthand `#codex` maps to `harness:codex`; `?sonnet` or `?5.5` maps to `model:<model>`. Dimensions combine in any order.
 
 If direct send/ask still comes back unresolved, treat that as a routing problem, not a mere "target is offline" problem. The right follow-up is to disambiguate the target, inspect broker context with `scout who` / `scout latest`, or create/register the missing identity. Do not default to pushing the bring-up step back onto the operator for a known target.