docs: recommend MCP install over long-term CLI use

.agents/skills/orchestrate/SKILL.md

@@ -4,15 +4,16 @@ description: >
   Orchestrate sub-agents for large tasks inside a single environment: plan,
   delegate coding to cheap/fast models, parallelize the critical path, keep
   reviews lean, and close every loop. Use when acting as an orchestrator or
-  writing a kickoff for one. Prefer implement when fan-out does not clearly pay.
+  writing a kickoff for one. Prefer implement when fan-out does not clearly
+  pay. For multi-environment fleets, use conduct instead.
 ---
 
 # Orchestrate
 
 This is the kody `orchestrate` skill, scoped to `@kodycodes/cli`.
 
 Fan out **sub-agents inside one environment** (shared checkout). This repo is
-one package; multi-environment fleets are out of scope here.
+one package; multi-environment fleets (`conduct`) are out of scope here.
 
 Two modes: **be** the orchestrator, or **spawn** one (smarter model) if you are
 optimized for cheap/fast execution.
@@ -46,5 +47,5 @@ optimized for cheap/fast execution.
 ## Kickoff (when spawning an orchestrator)
 
 Keep it short: goals + constraints + out-of-scope; "you orchestrate, don't bulk
-code"; preferred implementer model; single-environment; done = falsifiable.
-Point at this skill.
+code"; preferred implementer model; single-environment (not conduct); done =
+falsifiable. Point at this skill.

.agents/skills/ship-pr/SKILL.md

@@ -15,28 +15,43 @@ This is the kody `ship-pr` skill, scoped to `@kodycodes/cli`.
 
 Self-assess; user policy overrides.
 
+**Kent's standing policy (2026-08-08):** auto-ship (squash-merge + verify
+publish) once AI reviewer feedback is addressed and CI is green, unless
+**high** risk. High risk still parks ready-for-review unless merge authority
+was granted explicitly.
+
 - **Low** — green CI; nits ignorable; squash-merge when policy allows.
 - **Medium** — wait for AI reviewer(s); address **valid** feedback (ignore
   insignificant nits / already-fixed / wrong); then merge when policy allows.
 - **High** — leave ready-for-review unless the user granted merge authority.
 
+## AI reviewers
+
+Prefer **Cursor Bugbot** (`Cursor Bugbot` check / `cursor[bot]` review comments).
+Trigger with `bugbot run` or `@cursor review` on the PR if it has not started.
+
+**CodeRabbit:** if it is rate-limited, errored, or otherwise unavailable, **do
+not wait** on it for low/medium risk — proceed with Bugbot + CI. Only wait on
+CodeRabbit when the change is **high** risk (or the user explicitly asks).
+
 ## Loop
 
 1. Mark ready — `kody:@kentcdodds/github/pr/set-review-status`
    `{ prUrl, status: 'ready' }` (or owner/repo/prNumber).
 2. Wait for CI — `gh pr checks` (or compose `loop-on-ci` / `fix-ci`).
-3. Fix failures; for **medium+**, wait on AI reviewer(s) and address valid
-   feedback. Rebase only when actually unmergeable. Local gate is
-   `npm run validate`. If the change touches login / MCP protocol, also smoke
-   `whoami`, `search`, and `execute` against `https://kody.codes/mcp`.
+3. Fix failures; for **medium+**, wait on AI reviewer(s) (Bugbot first; see
+   above for CodeRabbit) and address valid feedback. Rebase only when actually
+   unmergeable. Local gate is `npm run validate`. If the change touches login /
+   MCP protocol, also smoke `whoami`, `search`, and `execute` against
+   `https://kody.codes/mcp`.
 4. Green + (medium+: valid feedback cleared) → break.
 5. Push → repeat.
 
 ## Gates ≠ CI
 
 Blocked on a release / trusted-publishing / calendar gate → **end the run**
-and schedule a wake. Don't sleep-poll or code-thrash an intentional time
-window.
+and schedule a wake (Kody `job_schedule` + `createRun`). Don't sleep-poll or
+code-thrash an intentional time window.
 
 ## Merge / publish
 

README.md

@@ -1,41 +1,27 @@
 # @kodycodes/cli
 
-Turn one-off agent work into something you can rerun: a local MCP client for
-[Kody](https://kody.codes) with login, OS keychain token storage, `search`, and
-`execute`. Talks MCP `2026-07-28` (Kody's stateless `/mcp` lane) and logs in
-with Client ID Metadata Documents (SEP-991).
+Install [Kody](https://kody.codes) as a remote MCP server in local agents.
+Talks MCP `2026-07-28` (Kody's stateless `/mcp` lane) and logs in with Client
+ID Metadata Documents (SEP-991).
+
+**Long term, use Kody through the host MCP connection** — `search` and
+`execute` in Cursor, Claude Code, or another client. This CLI writes that
+config. Keep `kody login` / `kody search` / `kody execute` for bootstrap,
+scripts, or hosts that cannot run MCP.
 
 ```bash
 npx @kodycodes/cli install
-npx @kodycodes/cli login
-npx @kodycodes/cli search "what can you do"
 npx @kodycodes/cli skill install
 ```
 
 Copyright © 2026 [Kent C. Dodds](https://kentcdodds.com). MIT licensed.
 
-## Install
+## Install the MCP server
 
 ```bash
-npm install -g @kodycodes/cli
-kody login
+npx @kodycodes/cli install
 ```
 
-Or run via `npx @kodycodes/cli` without a global install.
-
-## Commands
-
-| Command | Purpose |
-| --- | --- |
-| `kody install` | Detect running local MCP clients, write their config, and start host OAuth. |
-| `kody login` | Browser OAuth (CIMD + PKCE). Stores access and refresh tokens. |
-| `kody logout` | Deletes stored credentials. |
-| `kody status` | Shows login state without printing secrets. |
-| `kody whoami` | Confirms the MCP connection and lists tools. |
-| `kody search [query]` | Calls Kody `search`. |
-| `kody execute` | Calls Kody `execute` (`--code`, `--file`, or stdin via `--file -`). |
-| `kody skill install` | Copies the getting-started skill into Claude Code / Cursor / Agents. |
-
 `kody install` lists **running local** agents (Cursor, Claude Desktop, VS Code,
 Goose, Claude Code, Codex, Windsurf, Zed, and similar) and writes each host's
 remote MCP entry for `https://kody.codes/mcp`. Common host formats go through
@@ -46,12 +32,45 @@ After install, the CLI prints a prompt you can paste into the configured agent
 to continue onboarding. Host OAuth stays in that client — `kody login` is only
 for the CLI itself.
 
+```bash
+npx @kodycodes/cli skill install
+```
+
+copies the getting-started skill into Claude Code / Cursor / Agents. That skill
+also tells the agent to prefer the MCP server over the CLI.
+
 `--mcp-url` or `KODY_MCP_URL` overrides the default `https://kody.codes/mcp`.
+
+## CLI as a local client
+
+Optional. Use when you need a scripted or headless client instead of a host
+MCP connection.
+
+```bash
+npm install -g @kodycodes/cli
+kody login
+```
+
+Or run via `npx @kodycodes/cli` without a global install.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `kody install` | Detect running local MCP clients, write their config, and start host OAuth. **Recommended long-term path.** |
+| `kody skill install` | Copies the getting-started skill into Claude Code / Cursor / Agents. |
+| `kody login` | Browser OAuth (CIMD + PKCE) for the CLI itself. Stores access and refresh tokens. |
+| `kody logout` | Deletes stored CLI credentials. |
+| `kody status` | Shows CLI login state without printing secrets. |
+| `kody whoami` | Confirms the CLI MCP connection and lists tools. |
+| `kody search [query]` | Calls Kody `search` from the CLI (prefer the host MCP tool). |
+| `kody execute` | Calls Kody `execute` from the CLI (`--code`, `--file`, or stdin via `--file -`). |
+
 `--json` prints structured MCP results.
 
 ## Token storage
 
-Credentials are stored in the OS secret store:
+CLI credentials are stored in the OS secret store:
 
 - macOS: Keychain
 - Windows: Credential Manager

skills/kody/SKILL.md

@@ -1,69 +1,69 @@
 ---
 name: kody
 description: >
-  Use the Kody CLI to log in, search Kody capabilities, and execute
-  sandboxed modules against kody.codes. Use when the user mentions Kody,
-  kody.codes, durable agent tasks, or wants to search/execute via `kody`.
+  Install Kody as a remote MCP server, then use `search` and `execute`
+  from the host agent. Use when the user mentions Kody, kody.codes,
+  durable agent tasks, or wants to search/execute via Kody.
 ---
 
-# Kody CLI
+# Kody
 
-Kody is a remote MCP personal assistant. This skill uses the `@kodycodes/cli`
-package — a local MCP client — instead of configuring an MCP server by hand.
+Kody is a remote MCP personal assistant. **Long term, install it as an MCP
+server in this agent** and call `search` / `execute` directly. Do not keep
+using the CLI as the everyday interface once the server is connected.
 
-## Install
+`@kodycodes/cli` is a bootstrapper: it writes host MCP config and can act as
+a local client when MCP is not available.
+
+## Install the MCP server (recommended)
 
 ```bash
-npm install -g @kodycodes/cli
-# or
-npx @kodycodes/cli --help
+npx @kodycodes/cli install
 ```
 
-Then install this skill into the current host if it is not already present:
+That command lists **running local** agents and writes each host's remote
+MCP entry for `https://kody.codes/mcp`. Host OAuth stays in that client —
+do not run `kody login` for the host connection.
 
-```bash
-npx @kodycodes/cli skill install
-```
+After install, prefer the Kody MCP tools in this agent:
 
-To add Kody as a remote MCP server in running local agents:
+- `search` — discover capabilities, packages, and entity detail
+- `execute` — run one-off modules against those capabilities
 
-```bash
-npx @kodycodes/cli install
-```
+Prefer `search` before `execute`. If Kody is already connected here, skip
+the CLI and use those tools.
 
-That command only lists local clients that are currently running. For web-based
-clients (ChatGPT, Claude.ai, Grok), point the user at
+For web-based clients (ChatGPT, Claude.ai, Grok), point the user at
 https://kody.codes/onboarding.
 
-## Login
+To copy this skill into Claude Code / Cursor / Agents:
 
 ```bash
-kody login
+npx @kodycodes/cli skill install
 ```
 
-The CLI opens a browser for Kody OAuth (PKCE + Client ID Metadata Documents).
-If a browser cannot open, it prints the URL. Tokens (access + refresh) are
-stored in the OS keychain on macOS, Windows, and Linux. Linux without Secret
-Service falls back to a `0600` file under `$XDG_CONFIG_HOME/kody`.
-
-Never ask the user to paste tokens into chat.
+## CLI fallback
 
-## Use Kody
+Use the CLI only for bootstrap, scripting, or when this agent cannot reach
+Kody over MCP.
 
 ```bash
+npm install -g @kodycodes/cli
+kody login
 kody search "what can you do"
 kody search --domain email
 kody execute --code "import { kody } from 'kody:runtime'\nexport default async function main() { return await kody.search({ query: 'what can you do' }) }"
-```
-
-`search` and `execute` are Kody's only MCP tools. Prefer `kody search` before
-`kody execute`. Add `--json` when you need structured output.
-
-```bash
 kody status
 kody whoami
 kody logout
 ```
 
+The CLI opens a browser for Kody OAuth (PKCE + Client ID Metadata Documents).
+If a browser cannot open, it prints the URL. Tokens (access + refresh) are
+stored in the OS keychain on macOS, Windows, and Linux. Linux without Secret
+Service falls back to a `0600` file under `$XDG_CONFIG_HOME/kody`.
+
+Never ask the user to paste tokens into chat.
+
 Override the MCP URL with `--mcp-url` or `KODY_MCP_URL` for preview or local
 servers. Default: `https://kody.codes/mcp`.

src/help.ts

@@ -4,7 +4,7 @@ import { readPackageVersion } from './package-info.js'
 
 export const usage = `Kody CLI ${readPackageVersion()}
 
-A local MCP client for https://kody.codes — login once, then search and execute.
+Install Kody as a remote MCP server in local agents, or use this CLI as a local client.
 
 Usage:
   kody login [--mcp-url <url>] [--no-browser]

test/skill.test.ts

@@ -15,7 +15,10 @@ test('installSkill writes the bundled skill to user host directories', async ()
 	const targets = await installSkill({ home, sourcePath })
 	assert.equal(targets.length, userSkillTargets(home).length)
 	for (const target of targets) {
-		assert.match(readFileSync(target.path, 'utf8'), /kody login/)
+		const body = readFileSync(target.path, 'utf8')
+		assert.match(body, /Install the MCP server \(recommended\)/)
+		assert.match(body, /npx @kodycodes\/cli install/)
+		assert.match(body, /kody login/)
 	}
 })