@openscout/scout 0.2.62 → 0.2.64

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,25 +151,49 @@ 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.
 
+By default, a label handoff such as `@openscout.harness:claude` should mean
+"use the OpenScout identity on the Claude harness in a fresh session/context."
+Reusing an existing session is an explicit continuity choice, not the default.
+The broker should keep the stable agent name as the address and record the
+concrete session binding in the delivery receipt/history.
+
+Session refs are separate route targets for continuing a concrete bound
+session. Use the bare `ref:<suffix>` form in receipts/history, and pass the
+suffix with `--ref`; do not encode refs into `@agent#harness?model` identity
+syntax.
+
+```bash
+scout ask --ref 7f3a9c21 "continue from that handoff"
+scout send --ref 7f3a9c21 "status for that same session"
+```
+
+Receipts should name both layers, for example:
+
+```text
+sent to @openscout#claude via DM (ref:7f3a9c21)
+```
+
 ## Current Commands
 
 ```bash
@@ -221,10 +249,13 @@ scout server open
 scout server start
 scout server start --port 3200
 scout server open --path /agents/arc-codex-2.master.mini
+scout server start --public-origin https://scout.my-mac.local
 scout server start --vite-url http://127.0.0.1:43173   # SPA dev server
 scout server start --static --static-root /custom/client
 ```
 
 `scout server open` reuses an already-running matching Scout server on that port, or starts one in the background and opens the browser for you. Use `scout server` or `scout server help` for full flags.
 
+The application server derives the LAN hostname `scout.<machine>.local` by default. For a Caddy or other edge proxy, set `--public-origin https://scout.<machine>.local` (or `OPENSCOUT_WEB_PUBLIC_ORIGIN`) so browser origins match the app server's trusted host model.
+
 For the same web UI without the full `scout` CLI package, use **`@openscout/web`** (`openscout-web`): it ships its own `dist/client`, bundled Bun server, and pairing supervisor.