@openscout/scout 0.2.94 → 0.2.95

package/NOTICE

@@ -0,0 +1,14 @@
+OpenScout
+Copyright 2026 Arach Tchoupani
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,423 +1,245 @@
-# scout
+<p align="center">
+  <a href="https://openscout.app">
+    <img src="https://openscout.app/og.png" alt="Scout — one place for all your agents, local-first and neutral by design" width="100%" />
+  </a>
+</p>
 
-> **Requires [Bun](https://bun.sh).** Scout uses Bun as its runtime. If you don't have it: `brew install bun`
+<p align="center">
+  <strong>The coordination layer for the coding agents you already run.</strong><br />
+  Discover agents, dispatch work, send messages, and follow progress across the tools you already use.
+</p>
 
-Install:
+<p align="center">
+  <a href="https://www.npmjs.com/package/@openscout/scout"><img alt="npm version" src="https://img.shields.io/npm/v/@openscout/scout?style=flat-square&amp;label=npm&amp;color=94d59a&amp;labelColor=171a16" /></a>
+  <a href="https://bun.sh"><img alt="Bun 1.3 or newer" src="https://img.shields.io/badge/runtime-Bun_%E2%89%A5_1.3-f7f4ea?style=flat-square&amp;labelColor=171a16&amp;logo=bun" /></a>
+  <a href="https://github.com/oscout/scout/blob/main/LICENSE"><img alt="Apache 2.0 license" src="https://img.shields.io/badge/license-Apache--2.0-f7f4ea?style=flat-square&amp;labelColor=171a16" /></a>
+  <a href="https://openscout.app"><img alt="OpenScout project homepage" src="https://img.shields.io/badge/project-openscout.app-dde6d8?style=flat-square&amp;labelColor=171a16" /></a>
+</p>
 
-```bash
-bun add -g @openscout/scout
-scout --help
-```
-
-`@openscout/scout` is the public package name. It installs the `scout` command and carries the bundled broker/runtime and web UI. Installing it does not start services; commands such as `scout setup`, `scout up`, and `scout server start` activate them explicitly.
-
-## Canonical Flow
-
-```bash
-scout setup
-scout doctor
-scout whoami
-scout who
-scout latest
-scout runtimes
-scout providers usage
-scout ask --project ../talkie --harness claude "can you review our docs?"
-```
-
-`scout setup` is the canonical onboarding entry point. It creates or updates:
-
-- `~/Library/Application Support/OpenScout/settings.json`
-- `~/Library/Application Support/OpenScout/relay-agents.json` for compatibility with the existing machine-local agent registry
-- `.openscout/project.json` for the current repo when needed
-
-It also discovers local and project-backed agents from your configured workspace roots, installs the base Scout service, attempts to start it, and ensures Caddy is available for the local `scout.local` edge. On macOS, setup installs missing Caddy with `brew install caddy`; otherwise install Caddy yourself or set `OPENSCOUT_CADDY_BIN`.
-
-`scout doctor --fix` asks the native `scoutd` daemon to run conservative repairs
-when that daemon version exposes them. Use `scout doctor --fix --yes` for
-non-interactive install scripts; older or missing `scoutd` binaries simply leave
-the normal doctor report intact.
-
-For a CLI-only onboarding pass, save the same identity, workspace roots, and
-runtime choice used by the app flows:
-
-```bash
-scout config set name "Ada"
-scout setup --source-root ~/dev --default-harness codex
-scout runtimes
-```
-
-`scout setup` creates `~/.openscout/config.json` when it is missing. Use
-`scout init` when you only want to rewrite the local host/port config, for
-example `scout init --force --broker-port 43110 --web-port 43120
---pairing-port 43130`.
+---
 
-When the input is not a known subcommand and includes exactly one `@agent` mention, Scout treats it as an implicit `ask`: it records durable work with the broker, waits for the target to acknowledge or complete immediately, and leaves later completion visible through the conversation or flight follow-up. For example:
+Scout is a local-first control plane for AI agents. It sits underneath Claude
+Code, Codex, Cursor, Pi, and other harnesses, giving them one durable broker for
+discovery, messages, work, and routing without moving agents out of the tools
+where they already run.
 
-```bash
-scout @dewey can you review our docs?
-scout hey @hudson please inspect the failing test
-scout --as vox --timeout 900 @talkie take another pass on the keyboard port
-```
+## What Scout gives you
 
-Reserved leading profile names are deterministic fresh-session routes for the
-current project, not shorthand agent names:
+| Capability | What it means |
+| --- | --- |
+| **Discover** | See agents, projects, sessions, and available runtimes from one place. |
+| **Coordinate** | Send an update, dispatch owned work, or route by project and harness explicitly. |
+| **Follow** | Keep requests, replies, progress, and durable follow-up handles visible across surfaces. |
+| **Reach** | Coordinate through the local broker first, with optional mesh reachability across trusted machines. |
 
-```bash
-scout ask Fable to review the parser
-scout ask Opus high to fix the tests
-scout ask --profile kimi "review the parser"
-```
+Agents keep owning their processes and transcripts. Scout owns the coordination
+records it creates and exposes the same broker-backed state through the CLI,
+TUI, web UI, and optional native apps.
 
-The broker owns each profile's harness/model/default mapping. `--effort` is an
-optional Fable/Opus override; Kimi and Grok reject it until their ACP transports
-expose reasoning-effort control. Direct `scout ask --to fable ...` always means
-an existing target named `fable`; it is never silently converted to a profile.
+## Start here
 
-For a natural-language existing target, use an explicit `agent` prefix and
-`to` delimiter:
+Scout requires [Bun 1.3 or newer](https://bun.sh). The full broker and service
+package currently targets Apple Silicon macOS.
 
 ```bash
-scout ask agent Composer Review to fix the tests
+bun add -g @openscout/scout
+scout setup
+scout doctor
 ```
 
-Scout normalizes that name to exact handle `@composer-review`. Zero or multiple
-agent/session matches fail with disambiguation instead of choosing by locality
-or similarity.
-
-## One Routing Model
+Prefer npm for global packages? `npm install -g @openscout/scout` installs the
+same package; Bun is still required at runtime.
 
-The routing rules do not change by harness, UI, or host:
+Installing the package does not silently start services. `scout setup`
+configures the local broker and attempts to start it explicitly; `scout doctor`
+then verifies that the broker and project inventory are healthy.
 
-- one target -> DM
-- group coordination -> explicit channel
-- everyone -> `scout broadcast`
-- tell / update -> `scout send`
-- owned work / requested reply -> `scout ask`
-- follow-up stays in the same DM or explicit channel
+## Make your first handoff
 
-Short mutable callback names are broker-owned route aliases:
-
-```bash
-scout alias set review --to scope.main.arts-mac-mini-local
-scout alias set patch --to session:019eff52-9347-7470-ba5c-6bfe99d8dd83
-scout alias resolve patch
-scout alias repoint patch --to session:<new-id> --if-revision 1
-scout alias unset patch --if-revision 2
-scout ask --to alias:review "take a fresh pass"
-```
-
-Aliases are scoped to the current project/local host unless `--project` or
-`--host` is supplied. They point at existing targets and never create or rename
-cards. Native bare agent names win; `alias:<name>` is the explicit form.
-
-The lowest-churn fresh start is **capability first**: pass the project path and
-optional harness, then let the broker choose or create the concrete worker.
-Do not guess generic names like `claude.main` just because you want Claude. Use
-the returned `ref`, flight, conversation, work, or session handle for follow-up.
-If the worker proves useful, promote it to a named/pinned sibling after the fact
-using the broker-suggested handle when one is returned.
-
-When sender, target, or recent activity is unclear, the shortest orientation loop is:
+Route work by project and harness instead of guessing an agent name:
 
 ```bash
 scout whoami
-scout inbox --latest 10 --json
-scout who
-scout channel triage --latest 10 --json
-scout latest
-scout latest --channel triage --messages --limit 3
+scout runtimes
+scout ask --project . --harness codex \
+  "Review this repository and return the three highest-leverage improvements."
 ```
 
-Use `channel <name> --latest <count> --json` for the cheapest agent-facing
-channel catch-up. It reads broker messages for that channel and exits. Use
-`latest --channel <name>` when you want the compact activity projection instead.
-Use `inbox --latest <count> --json` for direct messages addressed to the
-current inferred agent identity.
-
-CLI agents should use these commands rather than curling broker HTTP endpoints
-or reading relay files directly.
-
-### Sender identity
-
-`scout send`, `scout ask`, and `scout broadcast` all use the
-same default sender identity. Most of the time you should let Scout infer it
-from your current context. For agent-to-agent delegation, check `scout whoami`
-first and use `--as` whenever the acting project agent must be preserved
-explicitly across shells, hosts, or bridges.
-
-`scout watch` follows a conversation or channel; it does not choose a sender.
-
-Inspect the current default once:
+Scout resolves or starts a suitable worker, records the request, and returns a
+durable handle. Continue the same work with the returned ref:
 
 ```bash
-scout whoami
+scout ask --ref <ref> "Now check the tests."
 ```
 
-Default sender resolution is:
-
-1. `--as <agent>` for that command
-2. `OPENSCOUT_AGENT` when the current session already has a bound agent
-3. the current project-scoped sender inferred from your working directory
-4. your operator name when you're outside a project context
-
-Coding-agent hosts use the project-scoped sender for `scout ask` automatically when
-the CLI detects a host harness signal:
+## One routing model
 
-- **Scout-managed:** `OPENSCOUT_AGENT`, `OPENSCOUT_MANAGED_AGENT`
-- **Cursor:** `CURSOR_AGENT=1`
-- **Claude Code:** `CLAUDECODE=1`, `CLAUDE_CODE_CHILD_SESSION`, `CLAUDE_CODE_REMOTE`, session ids
-- **Codex:** `CODEX_THREAD_ID`, `CODEX_CI=1`, `CODEX_SANDBOX`, proposed `AGENT=codex`
+| You mean… | Use… |
+| --- | --- |
+| “Heads up.” | `scout send --to <target> "message"` |
+| “Do this and get back to me.” | `scout ask --to <target> "request"` |
+| “Start fresh in this project.” | `scout ask --project . --harness <harness> "request"` |
+| “Continue that exact work.” | `scout ask --ref <ref> "follow-up"` |
+| “Coordinate a group.” | `scout send --channel <name> "message"` |
 
-Run `scout whoami --json` to see which signal matched. Human terminal shells still
-default to `operator` unless `--as` or a host signal is present.
+One explicit target is a direct message. Group coordination uses an explicit
+channel. Shared broadcast is opt-in, and routing lives in structured metadata
+rather than accidental mentions in message text.
 
-That keeps ordinary collaboration simple:
-
-```bash
-scout send --to vox "heads up: I’m on the runtime side"
-scout ask --to vox "can you confirm the broker fix?"
-scout ask --project ../talkie --harness claude "review the build spec"
-scout ask --harness codex "review this in a fresh Codex worker"
-```
+## What ships in this package
 
-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
-belong in shell argv.
-
-Nomenclature:
-
-- **Prompt file**: the primary work prompt for `scout ask`; pass it with `--prompt-file <path>`.
-- **Message file**: the message body for `scout send`, `scout broadcast`, or `scout speak`; pass it with `--message-file <path>`.
-- **Body file**: shared alias for either command family; `--body-file <path>` reads the same UTF-8 text into the broker `body` field.
-
-Examples:
-
-```bash
-scout ask --to hudson --prompt-file ./handoff.md
-scout @hudson --prompt-file ./review-request.md
-scout send --channel triage --message-file ./status-update.md
-scout broadcast --message-file ./maintenance-window.md
+```text
+Claude Code  ─┐
+Codex        ─┼── local Scout broker ── CLI · Monitor · Web
+Other agents ─┘   messages · work · routing
+                         │
+                         └── optional surfaces: Rust TUI · macOS · iOS
 ```
 
-The file is read locally before dispatch. The local broker still receives one
-structured request containing the target, body, sender, routing fields, and
-metadata, so the rest of the broker and mesh path can choose the right transport
-without depending on shell argument size.
-
-### One-to-one delegation
-
-When one project agent is delegating concrete work to one other agent, treat it
-as a private handoff:
-
-- keep it in a DM, not `channel.shared`
-- preserve the acting project agent as the sender
-- keep progress and completion in that same DM
-
-Today the best CLI surface for that handoff is `scout ask`, because it opens a
-DM by default when no explicit channel is pinned:
+`@openscout/scout` installs:
 
-```bash
-scout whoami
-scout ask --to hudson "Build the editable CodeViewer and report back with the integration-ready surface."
-```
+- the `scout` command;
+- the bundled local broker and runtime;
+- the local web control surface opened by `scout server open`;
+- the bundled terminal console launched by `scout monitor`.
 
-If the invoking shell or host path might not already be bound to the acting
-project agent, make it explicit:
+The Rust TUI launched by `scout tui` and the macOS and iOS apps are optional
+OpenScout surfaces; they are not installed by the npm package. They read and
+write the same coordination state when present.
 
-```bash
-scout ask --as premotion.master.mini --to hudson "Build the editable CodeViewer and report back with the integration-ready surface."
-```
-
-Use `channel.shared` only when the work is genuinely for a group, not for a
-single owner.
+## CLI at a glance
 
-### Label-scoped catch-up
+| Goal | Commands |
+| --- | --- |
+| Bootstrap and verify | `scout setup`, `scout doctor`, `scout config` |
+| Find your bearings | `scout whoami`, `scout who`, `scout runtimes`, `scout inbox` |
+| Coordinate | `scout send`, `scout ask`, `scout broadcast`, `scout watch` |
+| Follow activity | `scout latest`, `scout flight`, `scout label`, `scout tail` |
+| Operate local agents | `scout up`, `scout down`, `scout ps`, `scout restart` |
+| Open a bundled surface | `scout monitor`, `scout server open` |
+| Open an optional surface | `scout tui`, `scout menu` |
+| Connect tools | `scout mcp`, `scout pair`, `scout mesh` |
 
-Use labels to tie related asks together without creating a new workflow object:
+Run `scout --help` for the complete command list and
+`scout <command> --help` for current flags and examples.
 
-```bash
-scout ask --to hudson --label release:0.2.66 "Review the package bump."
-scout ask --to lattices --label release:0.2.66 "Check the install path."
-scout label feed release:0.2.66 --since 10m
-scout label watch release:0.2.66 --interval 2
-scout label brief release:0.2.66
-```
+## Works with the tools you already use
 
-Labels are plain metadata. They can mean a goal, release, milestone, incident,
-or any local convention. `scout label watch` streams a normalized firehose of
-matching Scout-owned activity; `scout label brief` gives a compact digest. Scout
-does not assign a lifecycle to the label.
+Scout has host integrations for Claude Code, Codex, Cursor, Pi, and Hermes, plus
+MCP, ACP, Slack, Telegram, voice, and webhook paths where those transports are
+configured. The broker provides the shared coordination model; each harness
+keeps its native runtime and workflow.
 
-### Addressing specific agents
+See the [integration guide](https://github.com/oscout/scout/blob/main/docs/integrations.md)
+for the current package and setup map.
 
-Agent identity has six dimensions: `definitionId`, workspace qualifier, `profile`, `harness`, `model`, `node`. Canonical form:
+## Advanced CLI reference
 
-```
-@<definitionId>[.<workspaceQualifier>][.profile:<profile>][.harness:<harness>][.model:<model>][.node:<node>]
-```
+<details>
+<summary><strong>Setup and local configuration</strong></summary>
 
-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:
+`scout setup` is the canonical onboarding command. It saves the local identity
+and workspace roots, discovers project-backed agents, installs the base service,
+and attempts to start the broker. A CLI-only setup can make its inputs explicit:
 
 ```bash
-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 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"
+scout config set name "Ada"
+scout setup --source-root ~/dev --default-harness codex
+scout doctor
 ```
 
-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.
+Use `scout doctor --fix` for conservative native-daemon repairs when the
+installed daemon supports them. Use `scout init` only when you need to rewrite
+the low-level local host and port configuration.
 
-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.
+See the [install guide](https://github.com/oscout/scout/blob/main/install.md)
+and [quickstart](https://openscout.app/docs/quickstart) for prerequisites,
+filesystem footprint, and first-run success criteria.
 
-For current-project work where the harness is the only important choice, omit
-`--to` and `--project`; Scout infers the current project and creates or chooses
-a compatible worker:
+</details>
 
-```bash
-scout ask --harness codex "take a fresh pass on this repo"
-```
+<details>
+<summary><strong>Routing, profiles, sessions, and follow-up</strong></summary>
 
-That routes by the current project path and asks the broker to create or choose
-a compatible worker. For another repo, pass the repo path explicitly:
+Capability-first routing is the lowest-churn way to start fresh work. Give Scout
+the project and, when it matters, the harness; use a concrete target only when
+you mean one known agent or session.
 
 ```bash
-scout ask --project ../talkie --harness claude "review the modular build spec"
-```
+# Fresh worker for the current project
+scout ask --harness codex "Review the parser."
 
-Use an exact `--ref` or `session:<id>` only when the intent is to continue prior
-context. If the broker returns a friendly worker handle, treat it as the human
-mnemonic; promote/pin it only after the routed worker proves useful.
+# Fresh worker through a broker-owned runtime profile
+scout ask --profile kimi "Review the parser."
 
-Local product handoffs use the public Scout address:
+# One known target
+scout ask --to hudson "Check the release package."
 
-```bash
-scout send --to scout "message for the local Scout inbox"
+# Continue from a returned handle or exact session
+scout ask --ref <ref> "Take another pass."
+scout ask --to session:<id> "Continue this exact runtime context."
 ```
 
-Broker names and concrete node or agent ids are diagnostic details. Normal send
-output should say whether the message was sent, not which broker or internal
-session handled it. Reusing an existing session is an explicit continuity
-choice, not the default.
+One target means a direct message. Groups use explicit channels. `scout send`
+is for durable updates where no response is expected; `scout ask` creates owned
+work with a reply path. Runtime profiles such as Fable, Opus, Kimi, and Grok are
+broker-owned fresh-session routes, not guessed agent names.
 
-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.
+See [runtime sessions](https://github.com/oscout/scout/blob/main/docs/runtime-sessions.md)
+and [Scout comms](https://github.com/oscout/scout/blob/main/docs/scout-comms.md)
+for identity dimensions, session continuation, aliases, delivery state, and
+advanced routing grammar.
 
-```bash
-scout ask --ref 7f3a9c21 "continue from that handoff"
-scout send --ref 7f3a9c21 "status for that same session"
-```
-
-Diagnostic views may show both layers, for example:
+</details>
 
-```text
-sent to Scout via DM (ref:7f3a9c21)
-```
+<details>
+<summary><strong>Operator views, files, and local surfaces</strong></summary>
 
-## Current Commands
+The shortest orientation loop is:
 
 ```bash
-scout --help
-scout version
-scout doctor
-scout setup
-scout runtimes
-scout providers usage
 scout whoami
-scout send
-scout speak
-scout ask
-scout watch
+scout inbox --latest 10 --json
 scout who
 scout latest
-scout broadcast
-scout up
-scout down
-scout ps
-scout restart
-scout menu
-scout pair
-scout server start
-scout server open
-scout tui
-scout tui --take mesh
-```
-
-### Provider Usage and Orchestration Map
-
-Read every quota window from the live `/providers` feed without opening the
-web UI, or combine those windows with Scout's role/model/provider policy:
-
-```bash
 scout providers usage
-scout providers usage --json
-scout providers usage --cached
-scout providers map
-scout providers map --role implementation
-scout providers map --json
 ```
 
-`usage` refreshes the shared service-budget pipeline and prints every available
-quota window with percent used and remaining, the local reset time, source, and
-observation freshness. `map` derives each window's burn pace, telemetry
-confidence, and binding remaining quota, then recommends a model/provider for
-product judgment, synthesis, critique, inventory, implementation, and review.
-These dispatch roles are recommendations; they do not create durable
-`scout role` assignments. `--cached` skips live provider probes when a recent
-server snapshot is available; a cold or expired cache still reads providers.
-
-### Menu Bar App (`scout menu`)
-
-On macOS, `scout menu` is the quick launcher for the native menu bar app.
+Use file-backed input when a request is too large or structured for shell argv:
 
 ```bash
-scout menu
-scout menu status
-scout menu restart
-scout menu quit
+scout ask --to hudson --prompt-file ./review-request.md
+scout send --channel triage --message-file ./status-update.md
 ```
 
-If you run it from an OpenScout repo checkout, Scout prefers the repo helper at
-`apps/macos/bin/openscout-menu.ts`, so it can auto-build and launch the app bundle for you.
-Outside the repo, it opens an installed `OpenScout Menu` app when available.
+`scout monitor` opens the bundled terminal console. `scout server open` reuses
+or starts the bundled local web UI. `scout tui` launches the separately built
+Rust TUI when `scout-tui` is installed or available from a source checkout, and
+`scout menu` opens an installed macOS app when available.
 
-### Web UI (`scout server start`, `scout server open`)
+Run `scout --help` for the current command inventory and
+`scout <command> --help` for all flags.
 
-Runs the current OpenScout web UI used by the repo’s `bun run dev` entry. **Bun must be on your PATH.** Published CLI builds ship `dist/scout-control-plane-web.mjs` and `dist/client/` (Vite build); when `dist/client/index.html` is present, **`scout server start` defaults to static assets** unless you pass `--vite-url` to proxy a dev server.
-
-```bash
-scout whoami
-scout who
-scout latest
-scout server open
-scout server start
-scout server start --port 43120
-scout server open --path /agents/arc-codex-2.master.mini
-scout server start --public-origin http://scout.local
-scout server edge --local-name m1
-scout server start --vite-url http://127.0.0.1:43173   # SPA dev server
-scout server start --static --static-root /custom/client
-```
+</details>
 
-`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.
+## Current posture
 
-The application server binds to `0.0.0.0` by default, treats `scout.local` as the local portal name, and derives the node URL as `<machine>.scout.local` unless the user configures a short alias such as `m1`. `scout server edge` publishes `scout.local` plus the node host with Bonjour/mDNS and runs Caddy against the active web port. The managed edge defaults to HTTP on port `80` for zero-cert local browsing. HTTPS remains an explicit opt-in via `--edge-scheme https` or `--edge-scheme both` plus `scout server trust`.
+> Scout is in active v0.x development for high-trust local developer pilots.
+> It is not yet an enterprise-ready, compliance-ready, or hardened multi-tenant
+> runtime. Optional mesh features provide reachability and coordination, not
+> global consensus or exactly-once delivery.
 
-`scout setup` verifies Caddy for this path. The setup command installs it with Homebrew on macOS when `caddy` is not already available, but Scout still runs Caddy directly with the generated `~/.scout/local-edge/Caddyfile` instead of registering a separate Homebrew service. The base LaunchAgent is labelled `app.openscout` and supervises the broker, local edge, web startup, and menu bar app; `scout doctor` prints the exact `launchctl bootout ...` command for the current mode.
+## Go deeper
 
-When the edge is up but the web app is down, Caddy serves a same-origin "Start Scout" page. The button calls Caddy's internal `/__openscout/web/start` path, which proxies to the always-on broker and starts the web server while keeping the user-facing URL at `scout.local` or `<name>.scout.local`.
+- [OpenScout project homepage](https://openscout.app)
+- [Quickstart](https://openscout.app/docs/quickstart)
+- [Documentation](https://openscout.app/docs)
+- [Architecture](https://openscout.app/docs/architecture)
+- [Current status and scope](https://openscout.app/docs/current-posture)
+- [Public source](https://github.com/oscout/scout)
+- [Issues](https://github.com/oscout/scout/issues)
 
-`packages/web` remains the internal web workspace. Published installs get that same server and client through `@openscout/scout`.
+## License
 
-For source development, `bun run dev:edge -- --local-name m1` starts the web dev stack and the local edge together. It generates Caddy config against the actual selected dev port, so worktree-specific ports and busy-port fallback still route through `scout.local`.
+Apache-2.0. See the [license](https://github.com/oscout/scout/blob/main/LICENSE)
+and [notice](https://github.com/oscout/scout/blob/main/packages/cli/NOTICE).

package/dist/build-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "packageName": "@openscout/scout",
-  "version": "0.2.94",
-  "commit": "23bcb0d2821b93066f0eb79f88d622777d8170e0",
+  "version": "0.2.95",
+  "commit": "edcbc2933b914dee199c741ffa986d8c4127a318",
   "branch": "HEAD",
   "sourceDirty": false,
-  "builtAt": "2026-08-29T17:32:28.098Z"
+  "builtAt": "2026-08-31T02:14:41.975Z"
 }

package/dist/main.mjs

@@ -100958,7 +100958,7 @@ var init_stdio2 = __esm(() => {
 // ../../apps/desktop/src/shared/product.ts
 var SCOUT_APP_VERSION;
 var init_product = __esm(() => {
-  SCOUT_APP_VERSION = process.env.SCOUT_APP_VERSION?.trim() || "0.2.94";
+  SCOUT_APP_VERSION = process.env.SCOUT_APP_VERSION?.trim() || "0.2.95";
 });
 
 // ../../apps/desktop/src/core/mcp/stdio-server-lifecycle.ts
@@ -105022,7 +105022,9 @@ __export(exports_install, {
   runInstallCommand: () => runInstallCommand,
   renderInstallCommandHelp: () => renderInstallCommandHelp,
   parseInstallArgs: () => parseInstallArgs,
-  findAppDmgAsset: () => findAppDmgAsset
+  findAppDmgAsset: () => findAppDmgAsset,
+  OPENSCOUT_RELEASE_REPOSITORY: () => OPENSCOUT_RELEASE_REPOSITORY,
+  OPENSCOUT_RELEASE_OWNER: () => OPENSCOUT_RELEASE_OWNER
 });
 import { spawnSync as spawnSync8 } from "child_process";
 import { existsSync as existsSync39, mkdtempSync, rmSync as rmSync5, writeFileSync as writeFileSync9 } from "fs";
@@ -105115,7 +105117,7 @@ function getInstalledVersion() {
   return version3 || null;
 }
 async function fetchRelease(version3) {
-  const base = `https://api.github.com/repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases`;
+  const base = `https://api.github.com/repos/${OPENSCOUT_RELEASE_OWNER}/${OPENSCOUT_RELEASE_REPOSITORY}/releases`;
   const apiUrl = version3 ? `${base}/tags/${version3}` : `${base}/latest`;
   try {
     const response = await fetch(apiUrl, {
@@ -105125,12 +105127,12 @@ async function fetchRelease(version3) {
       return await response.json();
     }
   } catch {}
-  const apiPath = version3 ? `repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases/tags/${version3}` : `repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases/latest`;
+  const apiPath = version3 ? `repos/${OPENSCOUT_RELEASE_OWNER}/${OPENSCOUT_RELEASE_REPOSITORY}/releases/tags/${version3}` : `repos/${OPENSCOUT_RELEASE_OWNER}/${OPENSCOUT_RELEASE_REPOSITORY}/releases/latest`;
   const gh = spawnSync8("gh", ["api", apiPath], { encoding: "utf8" });
   if ((gh.status ?? 1) === 0 && gh.stdout.trim()) {
     return JSON.parse(gh.stdout);
   }
-  throw new ScoutCliError(version3 ? `release "${version3}" not found on GitHub (${GITHUB_OWNER}/${GITHUB_REPO})` : `could not fetch the latest OpenScout release from GitHub (${GITHUB_OWNER}/${GITHUB_REPO})`);
+  throw new ScoutCliError(version3 ? `release "${version3}" not found on GitHub (${OPENSCOUT_RELEASE_OWNER}/${OPENSCOUT_RELEASE_REPOSITORY})` : `could not fetch the latest OpenScout release from GitHub (${OPENSCOUT_RELEASE_OWNER}/${OPENSCOUT_RELEASE_REPOSITORY})`);
 }
 function findAppDmgAsset(release) {
   const assets = release.assets ?? [];
@@ -105304,7 +105306,7 @@ async function runInstallCommand(context, args) {
     message: `${verb} OpenScout ${installedAfter} \u2192 ${APP_PATH}${relaunchNote}`
   }, renderInstallResult);
 }
-var GITHUB_OWNER = "arach", GITHUB_REPO = "openscout", APP_NAME = "OpenScout.app", APP_PATH, INFO_PLIST_PATH, APP_BUNDLE_ID = "app.openscout.scout", APP_PROCESS_NAME = "Scout", USER_AGENT = "scout-cli", HELP_FLAGS9;
+var OPENSCOUT_RELEASE_OWNER = "oscout", OPENSCOUT_RELEASE_REPOSITORY = "scout", APP_NAME = "OpenScout.app", APP_PATH, INFO_PLIST_PATH, APP_BUNDLE_ID = "app.openscout.scout", APP_PROCESS_NAME = "Scout", USER_AGENT = "scout-cli", HELP_FLAGS9;
 var init_install = __esm(() => {
   init_errors();
   APP_PATH = `/Applications/${APP_NAME}`;

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@openscout/scout",
-  "version": "0.2.94",
-  "description": "Public Scout package that installs the `scout` command and bundled local runtime",
+  "version": "0.2.95",
+  "description": "Local-first control plane for discovering, messaging, and coordinating AI agents across Claude Code, Codex, and more",
+  "keywords": [
+    "openscout",
+    "ai-agents",
+    "coding-agents",
+    "agent-coordination",
+    "multi-agent",
+    "local-first",
+    "control-plane",
+    "agent-broker",
+    "developer-tools",
+    "cli",
+    "mcp",
+    "acp",
+    "claude-code",
+    "codex",
+    "cursor",
+    "bun"
+  ],
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -12,18 +30,19 @@
   "bugs": {
     "url": "https://github.com/oscout/scout/issues"
   },
-  "homepage": "https://github.com/oscout/scout#readme",
+  "homepage": "https://openscout.app",
   "bin": {
     "scout": "./bin/scout",
     "openscout-runtime": "./bin/openscout-runtime.mjs"
   },
   "engines": {
-    "bun": ">=1.2"
+    "bun": ">=1.3"
   },
   "files": [
     "bin",
     "dist",
-    "README.md"
+    "README.md",
+    "NOTICE"
   ],
   "dependencies": {
     "@lydell/node-pty": "1.2.0-beta.12",
@@ -46,5 +65,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "23bcb0d2821b93066f0eb79f88d622777d8170e0"
+  "gitHead": "edcbc2933b914dee199c741ffa986d8c4127a318"
 }