@minasoft/mina-ai-router 0.1.5 → 0.2.1

package/docs/HTTP-UI-MCP.md

@@ -1,6 +1,8 @@
 # HTTP UI and MCP Server
 
-Mina AI Router now runs as a local HTTP server.
+Mina AI Router runs as a local HTTP server. It gives local Codex and Claude CLI agents a shared MCP router and a browser operations console.
+
+![Mina AI Router overview](./assets/mina-ai-router-overview.svg)
 
 It serves both:
 
@@ -32,21 +34,33 @@ mair server start --port 3333
 mair server status
 ```
 
+When this long-running server is active, it is the live owner for the matching router state file. Compatible CLI reads and writes proxy to the server instead of using a separate one-shot snapshot, which keeps `/api/state`, the Web UI, MCP calls, and the persisted state file consistent.
+
+`mair server start` waits for `/api/health` before reporting success. Bind failures such as `EADDRINUSE` and stale pid files that point at non-Mina servers are surfaced as operator diagnostics rather than raw parser errors.
+
 Stop:
 
 ```sh
 mair server stop
 ```
 
-## Connect Codex CLI
+## Connect Codex or Claude CLI
 
 ```sh
-codex mcp remove mina-ai-router
-codex mcp add mina-ai-router --url http://127.0.0.1:3333/mcp
-codex mcp get mina-ai-router
+# Codex users
+mair setup codex --project /path/to/project
+mair doctor --client codex --project /path/to/project
+
+# Claude users
+mair setup claude --project /path/to/project
+mair doctor --client claude --project /path/to/project
 ```
 
-Expected transport:
+Use `mair doctor --client all --project /path/to/project` only when you use both clients.
+
+The Connect Agent guide in the UI shows the same setup commands with the live MCP URL for the current server. Manual repair commands are still available in the inspector when a selected agent is stuck in `mcp-configuring`.
+
+Expected MCP URL after setup:
 
 ```text
 transport: streamable_http
@@ -63,15 +77,17 @@ http://127.0.0.1:3333/
 
 The page shows:
 
-- a router-centered agent flow diagram
-- registered agents as clickable nodes around the router
+- a router-centered live flow diagram
+- registered Codex or Claude agents as clickable nodes around the router
 - each agent's short capability notice on the node
-- agent status, project root, capability details, and tmux metadata in a modal
-- per-agent request history in a modal opened from the agent context menu
-- agent controls in the context menu: details, history, ask, attach commands, copy attach command, restart session, delete agent
+- a floating agent inspector with status, project root, tmux metadata, attach command, capabilities, and recent requests
+- an agent-filtered activity panel for routed request history
+- agent controls in the context menu: open terminal, ask, attach commands, copy attach command, restart session, delete agent
+- zoom, reset, draggable agent positions, and draggable flow canvas positioning
 - right-click flow background menu for creating a tmux-backed Codex or Claude agent from a project directory
 - a `Connect Agent` guide instead of manual UI registration
-- hidden `Developer Tools` for diagnostics such as the two-Codex demo and stale request cleanup
+
+The UI is intentionally local-operations focused: it helps you see which local agent is available, what each agent can do, and which requests are moving between them.
 
 ## Health
 
@@ -89,6 +105,15 @@ mair version
 mair verify
 ```
 
+For repository development, use `npm run verify` to run the full checkout test
+suite. A linked checkout may make `mair verify` run that same suite from the Mina
+package root. In an installed package, `mair verify` checks the packaged CLI,
+MCP server, HTTP server, Web UI assets, docs, and registration skill.
+
+Default verification does not require real Codex or Claude accounts. For local release readiness of the real CLI flow, run `MINA_REAL_CLI_SMOKE=1 npm run smoke:real-cli-contract` after `npm run verify`; it proves the installed client context can see `mina-ai-router` in the client MCP list.
+
+`mair health`, `mair agents`, and `mair agent <id>` prefer live status from a running server whose recorded state path matches the current CLI state path. This keeps health output correct when the server was started with a non-default port and when an agent is actively busy inside the server process.
+
 ## Visible Agent Commands
 
 Start a visible Codex agent in the current directory:
@@ -130,7 +155,8 @@ npm run smoke:http
 3. Click `Connect Agent` for the registration command guide.
 4. Start an agent from its project directory with `mair codex` or `mair claude`.
 5. Confirm the agent appears in the flow diagram.
-6. Click the agent node and use the context menu to inspect details, view history, or delete it.
+6. Click the agent node to open the inspector and filter the bottom activity panel to that agent.
+7. Use the agent context menu for terminal, ask, attach, restart, or delete actions.
 
 Alternative UI-created agent flow:
 

package/docs/MCP-CLIENT-SETUP.md

@@ -12,14 +12,35 @@ Start the router first:
 mair server start --port 3333
 ```
 
+## Recommended Setup
+
+Use the MAIR setup command from the project you want the agent to work in:
+
+```sh
+# Codex users
+mair setup codex --project /path/to/project
+mair doctor --client codex --project /path/to/project
+
+# Claude users
+mair setup claude --project /path/to/project
+mair doctor --client claude --project /path/to/project
+```
+
+If you use both clients, run both setup commands and then `mair doctor --client all --project /path/to/project`.
+
+`mair setup` discovers the matching running server's MCP URL, configures the selected CLI, links the `mina-ai-router-agent` registration skill, and verifies that the client reports the same MCP URL. Verification must pass both the named entry check and the visible client list check, because a real session may fail to see Mina even when `mcp get` prints an entry. `mair doctor` prints a pass/fail matrix for the server, CLI binary, MCP config, skill install, and current blocked agents.
+
+Use the manual commands below only for unusual client profiles or repair work.
+
 ## Codex
 
-Register the MAIR MCP server with Codex:
+Manual Codex MCP repair:
 
 ```sh
 codex mcp remove mina-ai-router
 codex mcp add mina-ai-router --url http://127.0.0.1:3333/mcp
 codex mcp get mina-ai-router
+codex mcp list
 ```
 
 Expected result:
@@ -36,14 +57,17 @@ cd /path/to/project
 mair codex
 ```
 
+When a Codex session is created from the Web UI or `mair codex`, Mina runs an MCP preflight for that session profile. If the profile is missing or stale, the agent enters `mcp-configuring` and the inspector shows the setup, verify, and remove commands to run before self-registration continues.
+
 ## Claude
 
-Register the MAIR MCP server with Claude Code:
+Manual Claude Code MCP repair:
 
 ```sh
 claude mcp remove mina-ai-router
 claude mcp add --transport http mina-ai-router http://127.0.0.1:3333/mcp
 claude mcp get mina-ai-router
+claude mcp list
 ```
 
 Then start Claude inside a project with MAIR:
@@ -53,6 +77,8 @@ cd /path/to/project
 mair claude
 ```
 
+Claude Code can keep MCP configuration per profile or project/session context. If a newly created Claude agent cannot see Mina MCP, keep it in `mcp-configuring`, run `mair setup claude --project /path/to/project` or the setup command shown by Mina, then verify with `mair doctor --client claude --project /path/to/project` before routing work to that session. The repaired session should show `mina-ai-router` in `claude mcp list`.
+
 ## Verify From the AI CLI
 
 In Codex or Claude, ask:
@@ -63,9 +89,36 @@ Use Mina AI Router MCP list_agents and summarize the registered agents.
 
 If the MCP setup is working, the agent should call `list_agents`.
 
+## Collaboration Prompt Example
+
+After two or more agents are registered, ask one of them:
+
+```text
+Use Mina AI Router to ask docs:
+Review the README changes and summarize what a first-time user should understand.
+```
+
+The source agent should call `list_agents` with its `callerSessionFingerprint` or `callerAgentId`, choose a target where `isSelf` is not true, send the work with `call_agent`, and check progress with `get_request_status`.
+
+For a stronger first test, ask for both the routed answer and the request id:
+
+```text
+Use Mina AI Router to ask api_server:
+Which endpoint should the frontend call for user lookup?
+Return the routed answer and the Mina request id you used.
+```
+
+Then open the browser console and inspect that request in the activity panel. The request detail should show lifecycle status, request lease state, parsed answer or error, parser diagnostics, prompt evidence, raw terminal evidence, and recovery history.
+
+If the target is stale, missing, or needs attention, ask the source agent to call `list_agents` again and select another available target or tell you which session needs repair.
+
+If the request times out but the target terminal is still running, Mina keeps the lease as `orphaned`. Use `Interrupt Terminal` only when you want to send Ctrl-C to that tmux session. Use `Mark Recovered` after you have confirmed the session is idle or repaired. These are separate from `Cancel`, which only cancels an open router request.
+
 ## Available MCP Tools
 
 - `list_agents`: list known agents and their statuses
 - `register_agent`: register or update the current visible agent
-- `call_agent`: send a task to another registered agent
+- `call_agent`: send a task to another registered agent. Provide `callerAgentId` or `callerSessionFingerprint` so Mina can reject accidental self-calls. Use `allowSelfCall: true` only for diagnostics.
 - `get_request_status`: check a routed request
+
+`list_agents` returns `isSelf` for the caller when identity is supplied. A source agent should avoid targets where `isSelf` is true unless the user explicitly asked for a self-diagnostic.

package/docs/SKILL-INSTALL-GUIDE.md

@@ -8,9 +8,27 @@ skills/mina-ai-router-agent/SKILL.md
 
 The skill lets Codex or Claude register the current visible tmux-backed CLI session with MAIR without requiring the user to write a full registration payload.
 
+## Recommended
+
+Use first-run setup instead of linking the skill by hand:
+
+```sh
+# Codex users
+mair setup codex --project /path/to/project
+mair doctor --client codex --project /path/to/project
+
+# Claude users
+mair setup claude --project /path/to/project
+mair doctor --client claude --project /path/to/project
+```
+
+If you use both clients, run both setup commands and then `mair doctor --client all --project /path/to/project`.
+
+`mair setup` links this skill into the right client location and verifies MCP config for the running router URL. Use the manual steps below only for custom profiles or repair.
+
 ## Codex
 
-Install the skill into your Codex skills directory:
+Manual Codex skill install:
 
 ```sh
 mkdir -p ~/.codex/skills
@@ -45,7 +63,7 @@ Expected behavior:
 
 Claude Code project skills live under `.claude/skills/*/SKILL.md`.
 
-For a single project, copy or link the MAIR skill into that project:
+Manual Claude project skill install:
 
 ```sh
 cd /path/to/project
@@ -91,6 +109,6 @@ Open the MAIR UI:
 http://127.0.0.1:3333/
 ```
 
-Click the agent node and choose `Status & Details`.
+Click the agent node and open `Edit Capabilities` from the inspector.
 
 The capability summary should describe the target project, and the capability sources should mention files such as `CLAUDE.md`, `AGENTS.md`, `README.md`, or package metadata.

package/docs/TROUBLESHOOTING.md

@@ -11,7 +11,9 @@ export MINA_TMUX_BIN=/opt/homebrew/bin/tmux
 
 ## MCP and CLI See Different Agents
 
-They are probably using different state files.
+By default, Mina uses `~/.mair/router-state.json` and `~/.mair/mair-server.json` so commands run from different directories share one local server.
+
+If MCP and CLI still see different agents, they are probably using explicit custom state files.
 
 Set the same `MINA_ROUTER_STATE` for both processes:
 
@@ -19,6 +21,53 @@ Set the same `MINA_ROUTER_STATE` for both processes:
 export MINA_ROUTER_STATE=/absolute/path/to/router-state.json
 ```
 
+## Agent Created But Not Ready
+
+Visible Codex or Claude sessions can be reachable in tmux while still blocked by first-run prompts. Mina reports those sessions as `needs-attention` instead of `available`.
+
+Common blockers:
+
+- `permission-required`: approve the trust or permission prompt with the guided Mina action when available, or attach to the terminal and approve it directly.
+- `client-update-required`: Codex is stopped at an update prompt. Use the Web UI's `Skip Codex Update` guided action for the known skip choice, or attach to tmux and choose an update option manually, then retry registration.
+- `mcp-configuring`: run the setup command shown in the inspector, then confirm `codex mcp list` or `claude mcp list` contains `mina-ai-router`.
+- `registration-pending`: the prompt was sent and Mina is waiting for the CLI agent to call the registration skill.
+
+## `mair server start` Fails on an Occupied Port
+
+`mair server start` waits for the Mina `/api/health` endpoint before it reports success. If the port is already occupied, the command should fail with a bind diagnostic such as `EADDRINUSE` and point at the server log.
+
+Useful checks:
+
+```sh
+mair server status
+lsof -nP -iTCP:3333 -sTCP:LISTEN
+cat ~/.mair/mair-server.log
+```
+
+Stop the process that owns the port, or start Mina on another port:
+
+```sh
+mair server start --port 34333
+```
+
+## Stale or Non-Mina Pid File
+
+If `MINA_SERVER_PID` points at a live process that is not Mina, CLI live reads and writes stop with a stale/non-Mina pid-file diagnostic. This prevents split-brain writes against the local state file.
+
+Safe recovery:
+
+```sh
+mair server status
+rm ~/.mair/mair-server.json
+mair server start --port 3333
+```
+
+Use the custom pid path if you set one:
+
+```sh
+rm "$MINA_SERVER_PID"
+```
+
 ## `call_agent` Times Out
 
 Common causes:
@@ -69,7 +118,7 @@ mair register payment --agent gemini --transport tmux --session payment --target
 Runtime JSON state is ignored by git.
 
 ```sh
-rm data/router-state.json
+rm ~/.mair/router-state.json
 ```
 
 Use this carefully; it deletes local registrations and request history.

package/docs/USER-START-GUIDE.md

@@ -2,26 +2,34 @@
 
 This guide is for someone who wants to use Mina AI Router, not develop it.
 
+Mina AI Router is for running several local Codex or Claude CLI agents and letting them collaborate through one local MCP router.
+
+![Mina AI Router overview](./assets/mina-ai-router-overview.svg)
+
 ## What You Will Set Up
 
 You will:
 
 1. Install the `mair` command.
 2. Start the local router and Web UI.
-3. Connect Codex or Claude to the local MCP server.
-4. Install the agent registration skill.
+3. Run first-run setup for Codex or Claude.
+4. Check readiness with `mair doctor`.
 5. Create visible tmux-backed agents.
-6. Inspect and control agents from the browser.
+6. Route tasks between agents and watch the activity from the browser.
 
 ## 1. Install the `mair` Command
 
-Install the published package:
+Use the GitHub checkout:
 
 ```sh
-npm install -g @minasoft/mina-ai-router
+git clone https://github.com/stevennana/mina-ai-router.git
+cd mina-ai-router
+npm install
+npm run build
+npm link
 ```
 
-Verify:
+Verify the linked command:
 
 ```sh
 mair version
@@ -32,10 +40,29 @@ Expected output:
 ```json
 {
   "name": "@minasoft/mina-ai-router",
-  "version": "0.1.0"
+  "version": "0.1.5"
 }
 ```
 
+For a GitHub checkout, the full test suite is:
+
+```sh
+npm run verify
+```
+
+Before claiming a real Codex or Claude out-of-box flow is ready on your machine, also run:
+
+```sh
+MINA_REAL_CLI_SMOKE=1 npm run smoke:real-cli-contract
+```
+
+Default `npm run verify` is account-free and deterministic. The opt-in real CLI contract smoke checks the installed client context and can fail when a local Codex or Claude profile cannot see Mina MCP.
+
+When Mina is installed as a packaged CLI instead of linked from this checkout,
+`mair verify` runs an installed-package self-check. It validates Mina's packaged
+CLI, MCP server, HTTP server, Web UI assets, docs, and registration skill without
+running any npm script from your current project.
+
 ## 2. Start the Router
 
 ```sh
@@ -49,16 +76,31 @@ Open:
 http://127.0.0.1:3333/
 ```
 
-The center node is the local MCP router. The surrounding nodes are registered agents.
+The center node is the local MCP router. The surrounding nodes are visible Codex or Claude agents running in local tmux sessions.
 
 ![Live agent flow](./assets/mair-live-flow.jpg)
 
+While the router server is running, it owns the live state for that `MINA_ROUTER_STATE` file. Normal CLI reads and writes talk to the matching server when possible, so `mair health`, `mair agents`, `mair agent <id>`, the Web UI, and MCP calls stay aligned during active routes.
+
+By default, those runtime files live in `~/.mair`. You can run `mair server status` from your home directory or any project directory and it will check the same local server. Use `MINA_RUNTIME_DIR`, `MINA_ROUTER_STATE`, or `MINA_SERVER_PID` only when you intentionally want an isolated test/runtime.
+
 ## 3. Connect Your AI CLI to MCP
 
-Pick the guide for the CLI you use:
+Run setup from the project directory you want the agent to work in:
 
-- Codex: [Codex MCP Setup](./MCP-CLIENT-SETUP.md#codex)
-- Claude: [Claude MCP Setup](./MCP-CLIENT-SETUP.md#claude)
+```sh
+# Codex users
+mair setup codex --project /path/to/project
+mair doctor --client codex --project /path/to/project
+
+# Claude users
+mair setup claude --project /path/to/project
+mair doctor --client claude --project /path/to/project
+```
+
+If you use both clients, run both setup commands and then `mair doctor --client all --project /path/to/project`.
+
+`mair setup` discovers the matching running server's MCP URL, registers that URL with the chosen CLI, installs the registration skill, and verifies the client config. If your CLI uses a special profile, use the manual commands in [MCP Client Setup](./MCP-CLIENT-SETUP.md).
 
 This gives the AI CLI access to these MAIR MCP tools:
 
@@ -67,16 +109,9 @@ This gives the AI CLI access to these MAIR MCP tools:
 - `call_agent`
 - `get_request_status`
 
-## 4. Install the Registration Skill
-
-Pick the guide for the CLI you use:
-
-- Codex: [Codex Skill Install](./SKILL-INSTALL-GUIDE.md#codex)
-- Claude: [Claude Skill Install](./SKILL-INSTALL-GUIDE.md#claude)
+## 4. Registration Skill
 
-The skill lets the agent register itself without asking you to type a long JSON payload.
-
-It automatically infers:
+`mair setup` installs the registration skill automatically. The skill lets the agent register itself without asking you to type a long JSON payload. It automatically infers:
 
 - project root
 - tmux session id
@@ -85,6 +120,10 @@ It automatically infers:
 - capability summary
 - capability sources
 
+Registration is idempotent. If the Web UI already created the agent placeholder, the skill should confirm and enrich that same agent instead of registering a second copy for the same tmux session.
+
+For manual skill installation or unusual profiles, see [Skill Install Guide](./SKILL-INSTALL-GUIDE.md).
+
 ## 5. Create an Agent From the Web UI
 
 This is the easiest path for most users.
@@ -95,9 +134,19 @@ This is the easiest path for most users.
 4. Select a project directory.
 5. Click `Create Agent`.
 
-Mina creates or reuses a tmux session and registers the agent in the router.
+Mina creates or reuses a tmux session and registers the agent in the router. If the same tmux session later self-registers from the agent CLI, Mina updates the existing agent record instead of creating a duplicate.
+
+Watch the readiness state after creation:
 
-If Codex or Claude needs trust approval, the Web UI shows the terminal so you can respond.
+- `created`: Mina created or reused the tmux session.
+- `permission-required`: Codex or Claude is waiting for trust or permission approval. Use the guided action in Mina when one is available, or open the terminal and approve the prompt directly.
+- `client-update-required`: Codex is waiting at an update prompt. Skip or resolve the prompt in the terminal, then retry registration.
+- `mcp-configuring`: the session does not yet have the Mina MCP server configured. Run the setup command shown in the inspector.
+- `registration-pending`: Mina is waiting for the agent to confirm self-registration.
+- `ready`: the session is reachable, registered, and safe to route work to.
+- `failed`: creation or preflight hit a blocker that needs operator repair.
+
+If Codex or Claude needs trust approval, the Web UI shows the terminal so you can respond. If MCP setup is missing, the inspector shows the exact setup, verify, and remove commands for the CLI profile. A newly created blocked agent may show `needs-attention` until you complete the inspector's permission, MCP setup, or registration action; this is expected and prevents accidental routing.
 
 ## 6. Alternative: Create an Agent From a Terminal
 
@@ -132,12 +181,17 @@ If you created the agent from the Web UI, this step is still useful but not alwa
 
 ## 8. Inspect or Edit Capabilities
 
-Click an agent node and choose `Status & Details`.
+Click an agent node. The floating inspector opens on the right, and the bottom activity panel filters to that agent.
+
+Use `Edit Capabilities` when you want to update what the agent is good at.
 
 You can view and edit:
 
 - capability summary
 - capability sources
+- structured capability quality
+- answerable domains
+- evidence sources
 - project root
 - tmux session
 - attach commands
@@ -146,7 +200,7 @@ You can view and edit:
 
 ## 9. Open the Agent Terminal
 
-Click an agent node and choose `Open Terminal`.
+Click an agent node and choose `Open Terminal` from the context menu or the inspector.
 
 The browser shows the current tmux screen. Type into the input field and press `Enter`, or click `Send`.
 
@@ -174,13 +228,90 @@ Summarize method, endpoint, parameters, and source files.
 Expected flow:
 
 1. The source agent calls `list_agents`.
-2. It chooses the target agent.
+2. It chooses a target agent where `isSelf` is not true.
 3. It calls `call_agent`.
 4. MAIR sends the task into the target tmux session.
 5. The target agent answers with Mina response markers.
 6. MAIR returns the parsed answer to the source agent.
 
-## 11. Stop the Router
+You can watch the routed request in the bottom activity panel. Selecting the target agent filters that panel to only that agent's work.
+
+## 11. Inspect the Routed Request
+
+After the request appears in the activity panel, click the row to open the request detail view.
+
+Use this view to check:
+
+- source and target agent
+- current lifecycle status
+- request lease state
+- parsed answer or error
+- parser diagnostics for missing or malformed response markers
+- prompt evidence sent to the target
+- raw terminal evidence captured from the target agent
+- recovery history for operator actions
+- retry lineage when a request was retried
+
+The detail view is the fastest way to understand whether a collaboration failed because the target timed out, the terminal transport failed, or the answer did not include Mina response markers.
+
+## 12. Recover From a Bad Request
+
+Use the activity panel actions when a collaboration needs operator help:
+
+- `Retry` sends the same task again and links the new request back to the original.
+- `Cancel` stops an open created, sent, or waiting request from being updated by a late terminal response.
+- `Interrupt Terminal` sends Ctrl-C to the target tmux session for an orphaned timed-out request.
+- `Mark Recovered` releases an orphaned request lease after you confirm the target session is idle or repaired.
+- `Archive` hides old terminal noise without deleting the request history.
+- `Unarchive` restores a request when you need to inspect it again.
+
+These controls are intentionally local and explicit. Cancel request, interrupt terminal, and mark recovered are separate actions. They do not hide the original request; they preserve enough lineage and recovery history to explain what happened.
+
+## 13. Refresh Capabilities
+
+Each agent has a capability card that helps you decide where to route work.
+
+Capability states mean:
+
+- `Missing`: the agent has not registered a useful capability summary.
+- `Fresh`: generated capability metadata was refreshed recently.
+- `Stale`: generated capability metadata is old or missing a refresh timestamp.
+- `Manual`: you edited the capability card yourself.
+- `Strong`: the profile explains what the project does, what the agent can answer, and what evidence supports that claim.
+- `Thin`: the profile exists but is too generic to trust for routing decisions.
+
+From the inspector, use `Edit Capabilities` for manual corrections or `Copy Refresh Command` to copy:
+
+```sh
+mair agent refresh-capabilities <agent-id>
+```
+
+Run the command when an agent's project changed and you want it to inspect local docs again.
+
+## 14. Read Health States
+
+The UI and CLI use the same health states:
+
+- `available`: the session is reachable and can receive routed work.
+- `busy`: Mina is already routing a request to that agent.
+- `stale`: Mina has not recently confirmed reachability.
+- `missing`: the tmux session or transport target is gone.
+- `needs-attention`: the agent needs an operator action before normal routing. This can mean the last routed request failed or timed out, or the agent is blocked on first-run readiness such as trust approval, MCP setup, or pending self-registration.
+- `unknown`: this transport does not expose a live health check.
+
+Useful CLI checks:
+
+```sh
+mair health
+mair agents
+mair agent <agent-id>
+```
+
+Use these before routing important work, especially after restarting terminals or deleting tmux sessions.
+
+If you started the server on a non-default port, `mair health` uses the matching running server record and reports that MCP URL instead of the default `3333` URL. During a server-routed request, the same command should show the target agent as `busy`, matching the browser.
+
+## 15. Stop the Router
 
 ```sh
 mair server stop