From ef51a5771bd5441ac2299a3e9bd4a8fdf7df6dbb Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Thu, 7 May 2026 20:49:30 +0800 Subject: [PATCH 1/3] docs: clarify Retinue README --- README.md | 186 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 134 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 2d2afa6..faa011e 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ scope local first

-[English](README.en.md) +[English](README.en.md) · [文档索引](docs/README.md) · [插件部署](docs/deployment/PLUGIN_DEPLOYMENT.md) · [源码开发](docs/development/SOURCE_INSTALL.md) **Retinue 让 Codex 把本地 coding agents 当作可控子代理来运行。** @@ -18,23 +18,22 @@ Codex 提交一个 coding job，Retinue 立刻返回 job handle；之后可以 ```text Codex / MCP client -> Retinue MCP 或 CLI - -> backend adapter - -> Claude Code / OpenCode - -> local job state + bounded result artifacts + -> backend-neutral lifecycle API + -> backend adapter + -> Claude Code / OpenCode + -> local job state + bounded result artifacts ``` -## 核心能力 +## 适合什么场景 -| 能力 | 说明 | -| --- | --- | -| 启动子代理 | 让 Codex 启动 Claude Code 或 OpenCode coding job，并快速拿到 `jobId` | -| 查询状态 | 用 `status` 查看 running、completed、failed、killed、orphaned、abandoned 等状态 | -| 等待和轮询 | 用 `wait` 在短时间窗口内等待终态，不阻塞主 agent 的整段任务 | -| 读取结果 | 用 `result` 获取 bounded stdout/stderr、exit metadata、外部 session id 和本地 artifact path | -| 继续会话 | 后端支持时，用 `continue` 接回已有 Claude/OpenCode session 继续工作 | -| 终止和清理 | 用 `kill` 终止指定 job，或用 `cleanup` 删除终态 job 目录，同时保留运行中或状态不确定的任务 | +Retinue 适合把一段相对独立的 coding task 委托给本机已有 agent，同时让主 Codex 线程保留控制权： -## 边界 +- 主 Codex 线程继续规划、review、验收；子代理负责局部实现、调查或验证。 +- 子代理运行时间可能较长，主线程需要先拿到 `jobId`，之后再轮询或等待结果。 +- 需要保留本地 job 状态、外部 session id、bounded stdout/stderr 和 artifact path，便于接回或排查。 +- 希望复用本机 Claude Code / OpenCode 的现有登录、模型、profile、代理、权限和配额设置，而不是在 MCP 工具里重新实现一套路由系统。 + +## 不做什么 Retinue 是本地子代理执行面，不是模型网关，也不是 provider router。 @@ -42,11 +41,25 @@ Retinue 是本地子代理执行面，不是模型网关，也不是 provider ro - 不接管 Claude Code / OpenCode 的登录、配额、代理、模型默认值或运行策略。 - 不把 prompt 放进进程 argv。 - 不在默认 `status` 响应里返回完整 prompt。 -- 不把自己扩展成通用进程管理器或云端队列。 +- 不把自己扩展成通用进程管理器、云端队列或多机调度系统。 + +更完整的边界说明见 [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md)。 + +## 核心工具流 + +普通 Codex 插件用户主要用这三个 Retinue 工具： + +| 工具 | 用途 | 典型返回 | +| --- | --- | --- | +| `retinue_spawn_agent` | 启动部署所选后端的子代理 job | `jobId`、`status`、`backend`、session id | +| `retinue_wait_agent` | 在短时间窗口内等待子代理进入终态 | running 或 terminal 状态，终态时带 result | +| `retinue_close_agent` | 关闭仍在运行的子代理，或确认已终止状态 | killed / completed / failed 等状态 | -## 快速开始 +底层仍保留 `opencode_*` 和 `claude_*` 调试工具，但它们不是默认的 Codex 委托入口。 -0.1.0 默认使用 OpenCode 后端，并让 OpenCode 使用 `plan` agent。用户不需要 clone、安装依赖或编译 Retinue。Retinue 面向 Windows、WSL/Linux 和 macOS；本轮验收路径使用 WSL。 +## 快速开始：Codex 插件市场 + +0.1.0 默认使用 OpenCode 后端，并让 OpenCode 使用 `plan` agent。普通用户不需要 clone、安装依赖或编译 Retinue。Retinue 面向 Windows、WSL/Linux 和 macOS；本轮验收路径使用 WSL。 前置条件： @@ -60,7 +73,9 @@ Retinue 是本地子代理执行面，不是模型网关，也不是 provider ro codex plugin marketplace add Disaster-Terminator/Retinue ``` -打开 Codex，运行 `/plugins`，按键盘右方向键切到 `[Retinue Local]` 插件市场，按 Enter 打开 `Retinue` 详情页，然后选择 `Install plugin`。安装后重新打开 Codex，然后让 Codex 使用 Retinue： +然后打开 Codex，运行 `/plugins`，按键盘右方向键切到 `[Retinue Local]` 插件市场，按 Enter 打开 `Retinue` 详情页，再选择 `Install plugin`。 + +安装后重新打开 Codex，然后让 Codex 使用 Retinue： ```text Use Retinue to spawn an OpenCode plan subagent. Ask it to reply exactly: RETINUE_OK. Wait for the result and close the child agent. @@ -75,33 +90,79 @@ Use Retinue to spawn an OpenCode plan subagent. Ask it to reply exactly: RETINUE 说明：Codex CLI 0.128 的 `codex plugin marketplace add/upgrade/remove` 只管理插件市场；插件安装在 Codex TUI 的 `/plugins` 里完成。`codex plugin marketplace upgrade retinue-local` 只用于更新已有市场，不是安装命令。 -## 平台说明 - -- Windows：需要本机 Node.js、Codex CLI 和 OpenCode 可用；OpenCode server 地址仍按部署环境配置。 -- WSL / Linux：本轮 0.1.0 验收路径。默认配置连接 `http://127.0.0.1:4096`。 -- macOS：按同样的 Node.js、Codex CLI、OpenCode 前置条件运行；尚未作为本轮验收主路径。 - ## 默认插件配置 插件默认 MCP 配置位于 `plugins/anchorpoint/.mcp.json`。0.1.0 固定为： ```json { - "SUPERVISOR_RETINUE_BACKEND": "opencode", - "SUPERVISOR_OPENCODE_AUTO_SERVE": "1", - "SUPERVISOR_OPENCODE_HOST": "127.0.0.1", - "SUPERVISOR_OPENCODE_AGENT": "plan" + "mcpServers": { + "retinue": { + "command": "node", + "args": ["./dist/mcp.js"], + "cwd": ".", + "startup_timeout_sec": 30, + "env": { + "SUPERVISOR_RETINUE_BACKEND": "opencode", + "SUPERVISOR_OPENCODE_AUTO_SERVE": "1", + "SUPERVISOR_OPENCODE_HOST": "127.0.0.1", + "SUPERVISOR_OPENCODE_AGENT": "plan" + } + } + } } ``` 这意味着： -- Codex 只调用 Retinue，不选择具体后端。 +- Codex 只调用 Retinue，不在每次 tool call 里选择具体后端。 - Retinue 默认管理 OpenCode server 生命周期，优先使用 `127.0.0.1:4096`，端口被外部服务占用时尝试 `4097`。 +- `cwd: "."` 让 Codex 从已安装的插件缓存目录启动 `node ./dist/mcp.js`，避免被当前对话工作目录影响。 - OpenCode 使用当前本机 profile，包括 provider、model、login、permission、plugin 和 skill。 - `plan` 是 0.1.0 的安全默认；后续会通过 Retinue 配置支持切到 `build`，不把这个选择暴露成每次 tool call 的参数。 -## Claude Code 后端 +## 安装路径怎么选 + +| 路径 | 适合谁 | 会安装什么 | +| --- | --- | --- | +| Codex 插件市场 | 普通 Codex 用户 | Retinue skill、MCP 配置、插件内置 runtime | +| npm 全局安装 | 自定义 MCP 配置或开发者环境 | `retinue`、`retinue-mcp`、`retinued` runtime | +| 源码 checkout | 贡献者、调试者 | TypeScript 源码、测试、构建和打包验证脚本 | + +普通 Codex 用户优先使用插件市场。npm 路径只安装 runtime，不安装 Retinue skill。 + +npm 安装示例： + +```bash +npm install -g @disaster-terminator/retinue@0.1.0 +codex mcp add retinue \ + --env SUPERVISOR_RETINUE_BACKEND=opencode \ + --env SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ + --env SUPERVISOR_OPENCODE_AGENT=plan \ + -- retinue-mcp +``` + +## 平台说明 + +- Windows：需要本机 Node.js、Codex CLI 和 OpenCode 可用；OpenCode server 地址仍按部署环境配置。 +- WSL / Linux：当前 0.1.0 验收主路径。默认配置连接 `http://127.0.0.1:4096`。 +- macOS：按同样的 Node.js、Codex CLI、OpenCode 前置条件运行；尚未作为本轮验收主路径。 + +## 后端状态 + +### OpenCode + +OpenCode 是 0.1.0 默认后端。Retinue 默认启用 auto-serve： + +```text +SUPERVISOR_OPENCODE_AUTO_SERVE=1 +SUPERVISOR_OPENCODE_HOST=127.0.0.1 +SUPERVISOR_OPENCODE_AGENT=plan +``` + +Retinue 只负责连接或启动本地 OpenCode server，并通过 OpenCode API 创建、等待、读取和关闭 job。模型、provider、登录、权限、插件和 skill 仍由 OpenCode 当前 profile 管理。 + +### Claude Code Claude Code 后端已经通过 fake E2E 和真实 best-effort E2E。0.1.0 默认不启用它。需要切换时，修改部署配置： @@ -111,22 +172,33 @@ SUPERVISOR_RETINUE_BACKEND=claude-code Claude Code 的模型、endpoint、权限和 profile 仍由 Claude Code 自己管理。 -## npm 安装 +## 开发和验证 -npm 包用于直接安装 Retinue runtime，适合自定义 MCP 配置或开发者环境： +贡献者从源码运行： ```bash -npm install -g @disaster-terminator/retinue@0.1.0 -codex mcp add retinue \ - --env SUPERVISOR_RETINUE_BACKEND=opencode \ - --env SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ - --env SUPERVISOR_OPENCODE_AGENT=plan \ - -- retinue-mcp +pnpm install +pnpm run build +pnpm test +``` + +发布前的确定性 gates： + +```bash +pnpm run typecheck +pnpm run check:generated +pnpm test +pnpm run verify:package ``` -普通 Codex 用户优先使用插件市场安装；npm 路径不安装 Retinue skill。 +真实 OpenCode probe： -## 验证 +```bash +SUPERVISOR_REAL_OPENCODE_PROBE=1 \ +SUPERVISOR_RETINUE_BACKEND=opencode \ +SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ +pnpm run probe:real:retinue-opencode +``` 发布前已通过： @@ -139,21 +211,31 @@ codex mcp add retinue \ - `pnpm run build` - `pnpm run verify:package` -真实 OpenCode probe： +## 常见问题 -```bash -SUPERVISOR_REAL_OPENCODE_PROBE=1 \ -SUPERVISOR_RETINUE_BACKEND=opencode \ -SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ -pnpm run probe:real:retinue-opencode -``` +### `marketplace add` 之后为什么还不能用？ + +`codex plugin marketplace add Disaster-Terminator/Retinue` 只是添加插件市场。还需要在 Codex TUI 里运行 `/plugins`，进入 `[Retinue Local]`，再选择 `Install plugin`。 + +### npm 安装后为什么没有 Retinue skill？ -## 开发者文档 +npm 包只安装 runtime，不安装 Codex 插件 skill。普通 Codex 用户应使用插件市场路径。 + +### OpenCode 端口被占用怎么办？ + +默认 auto-serve 会优先尝试 `127.0.0.1:4096`，如果该端口被外部服务占用，会尝试 `4097`。如果你明确要连接外部 OpenCode server，设置 `SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096`。 + +### 为什么不在 tool call 里传 model / provider / permission？ + +这是刻意边界。Retinue 的默认入口只负责子代理生命周期；模型、provider、权限和 profile 属于 Claude Code / OpenCode 的本地 runtime 策略。 + +## 文档导航 -- [源码安装和开发](docs/development/SOURCE_INSTALL.md) -- [0.1.0 发布计划](docs/release/0.1.0_RELEASE_PLAN.md) - [Docs Index](docs/README.md) -- [Long-Term Vision](docs/LONG_TERM_VISION.md) - [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md) -- [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md) +- [OpenCode Backend](docs/backends/OPENCODE.md) - [Plugin Deployment](docs/deployment/PLUGIN_DEPLOYMENT.md) +- [Source Install and Development](docs/development/SOURCE_INSTALL.md) +- [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md) +- [0.1.0 Release Plan](docs/release/0.1.0_RELEASE_PLAN.md) +- [Long-Term Vision](docs/LONG_TERM_VISION.md) From 1bc28c879764327991db8b489cfb1e537e4b8c64 Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Thu, 7 May 2026 20:50:07 +0800 Subject: [PATCH 2/3] docs: align English README --- README.en.md | 190 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 136 insertions(+), 54 deletions(-) diff --git a/README.en.md b/README.en.md index 0ab07eb..37fe6d0 100644 --- a/README.en.md +++ b/README.en.md @@ -9,7 +9,7 @@ scope local first

-[中文](README.md) +[中文](README.md) · [Docs Index](docs/README.md) · [Plugin Deployment](docs/deployment/PLUGIN_DEPLOYMENT.md) · [Source Development](docs/development/SOURCE_INSTALL.md) **Retinue lets Codex run local coding agents as controllable subagents.** @@ -18,23 +18,22 @@ Codex submits a coding job, Retinue returns a job handle immediately, and the ca ```text Codex / MCP client -> Retinue MCP or CLI - -> backend adapter - -> Claude Code / OpenCode - -> local job state + bounded result artifacts + -> backend-neutral lifecycle API + -> backend adapter + -> Claude Code / OpenCode + -> local job state + bounded result artifacts ``` -## Core capabilities +## When to use it -| Capability | Description | -| --- | --- | -| Start subagents | Start Claude Code or OpenCode coding jobs from Codex and return a `jobId` quickly | -| Inspect status | Read running, completed, failed, stopped, orphaned, abandoned, and related states | -| Wait or poll | Wait within a short timeout window without blocking the main agent's whole task | -| Read results | Return bounded stdout/stderr, exit metadata, external session ids, and local artifact paths | -| Continue sessions | Continue an existing Claude/OpenCode session when the backend supports it | -| Kill and clean up | Kill selected jobs and remove terminal job directories while preserving running or ambiguous jobs | +Retinue is useful when a Codex thread needs to delegate a bounded coding task to an existing local agent while keeping lifecycle control in the main thread: -## Boundary +- The main Codex thread can continue planning, reviewing, and validating while the child agent investigates or implements a focused task. +- The child agent may take long enough that the main thread should receive a `jobId` first and poll or wait later. +- The caller needs local job state, external session ids, bounded stdout/stderr, and artifact paths for recovery or debugging. +- The deployment should reuse an existing local Claude Code or OpenCode profile instead of reimplementing provider routing inside an MCP tool. + +## What it is not Retinue is a local subagent execution surface. It is not a model gateway or provider router. @@ -42,11 +41,25 @@ Retinue is a local subagent execution surface. It is not a model gateway or prov - It does not own Claude Code or OpenCode login, quota, proxy, model defaults, or runtime policy. - It does not put prompts into process argv. - It does not return full prompts from default `status` responses. -- It does not try to become a general process manager or cloud queue. +- It does not try to become a general process manager, cloud queue, or multi-machine scheduler. + +See [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md) for the full boundary. + +## Core tool flow + +Normal Codex plugin usage focuses on three Retinue tools: + +| Tool | Purpose | Typical return | +| --- | --- | --- | +| `retinue_spawn_agent` | Start a child-agent job through the deployment-selected backend | `jobId`, `status`, `backend`, session ids | +| `retinue_wait_agent` | Wait within a short timeout window for the child agent to reach a terminal state | running or terminal status; terminal responses include result | +| `retinue_close_agent` | Stop a running child agent or confirm an already terminal state | killed / completed / failed and related states | -## Quick Start +Lower-level `opencode_*` and `claude_*` tools remain available for adapter debugging, but they are not the default Codex delegation surface. -Retinue 0.1.0 defaults to OpenCode and asks OpenCode to use its `plan` agent. Users do not need to clone, install dependencies, or compile Retinue. Retinue targets Windows, WSL/Linux, and macOS; this round's acceptance path uses WSL. +## Quick Start: Codex plugin marketplace + +Retinue 0.1.0 defaults to OpenCode and asks OpenCode to use its `plan` agent. Normal users do not need to clone, install dependencies, or compile Retinue. Retinue targets Windows, WSL/Linux, and macOS; this round's acceptance path uses WSL. Requirements: @@ -60,7 +73,9 @@ Add the Retinue plugin marketplace to Codex: codex plugin marketplace add Disaster-Terminator/Retinue ``` -Open Codex, run `/plugins`, press the keyboard Right Arrow key until `[Retinue Local]` is selected, press Enter to open the `Retinue` details page, then choose `Install plugin`. After installation, restart Codex, then ask: +Then open Codex, run `/plugins`, press the keyboard Right Arrow key until `[Retinue Local]` is selected, press Enter to open the `Retinue` details page, then choose `Install plugin`. + +After installation, restart Codex, then ask: ```text Use Retinue to spawn an OpenCode plan subagent. Ask it to reply exactly: RETINUE_OK. Wait for the result and close the child agent. @@ -75,33 +90,79 @@ Expected result: Note: Codex CLI 0.128 `codex plugin marketplace add/upgrade/remove` manages marketplaces only. Plugin installation happens in the Codex TUI `/plugins` screen. `codex plugin marketplace upgrade retinue-local` updates an existing marketplace; it is not an install command. -## Platform Notes - -- Windows: requires local Node.js, Codex CLI, and OpenCode; configure the OpenCode server URL for the deployment. -- WSL / Linux: current 0.1.0 acceptance path. The default config connects to `http://127.0.0.1:4096`. -- macOS: uses the same Node.js, Codex CLI, and OpenCode prerequisites; it is not the primary validation path for this round. - -## Default Plugin Config +## Default plugin config The plugin MCP config lives at `plugins/anchorpoint/.mcp.json`. Retinue 0.1.0 defaults to: ```json { - "SUPERVISOR_RETINUE_BACKEND": "opencode", - "SUPERVISOR_OPENCODE_AUTO_SERVE": "1", - "SUPERVISOR_OPENCODE_HOST": "127.0.0.1", - "SUPERVISOR_OPENCODE_AGENT": "plan" + "mcpServers": { + "retinue": { + "command": "node", + "args": ["./dist/mcp.js"], + "cwd": ".", + "startup_timeout_sec": 30, + "env": { + "SUPERVISOR_RETINUE_BACKEND": "opencode", + "SUPERVISOR_OPENCODE_AUTO_SERVE": "1", + "SUPERVISOR_OPENCODE_HOST": "127.0.0.1", + "SUPERVISOR_OPENCODE_AGENT": "plan" + } + } + } } ``` This means: -- Codex calls Retinue and does not choose the concrete backend. +- Codex calls Retinue and does not choose the concrete backend on every tool call. - Retinue manages the OpenCode server lifecycle by default. It prefers `127.0.0.1:4096` and tries `4097` when that port is occupied by an external service. +- `cwd: "."` makes Codex start `node ./dist/mcp.js` from the installed plugin cache instead of the current conversation working directory. - OpenCode uses the active local profile for provider, model, login, permissions, plugins, and skills. - `plan` is the 0.1.0 safety default. A future Retinue config file will allow deployments to choose `build` without exposing that choice as a per-call tool argument. -## Claude Code Backend +## Choosing an install path + +| Path | Best for | What it installs | +| --- | --- | --- | +| Codex plugin marketplace | Normal Codex users | Retinue skill, MCP config, plugin-local runtime | +| Global npm install | Custom MCP configuration or development setups | `retinue`, `retinue-mcp`, `retinued` runtime | +| Source checkout | Contributors and debugging | TypeScript source, tests, build, and package verification scripts | + +Normal Codex users should prefer the plugin marketplace path. The npm path installs runtime only; it does not install the Retinue skill. + +npm install example: + +```bash +npm install -g @disaster-terminator/retinue@0.1.0 +codex mcp add retinue \ + --env SUPERVISOR_RETINUE_BACKEND=opencode \ + --env SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ + --env SUPERVISOR_OPENCODE_AGENT=plan \ + -- retinue-mcp +``` + +## Platform notes + +- Windows: requires local Node.js, Codex CLI, and OpenCode; configure the OpenCode server URL for the deployment. +- WSL / Linux: current 0.1.0 acceptance path. The default config connects to `http://127.0.0.1:4096`. +- macOS: uses the same Node.js, Codex CLI, and OpenCode prerequisites; it is not the primary validation path for this round. + +## Backend status + +### OpenCode + +OpenCode is the default 0.1.0 backend. Retinue enables auto-serve by default: + +```text +SUPERVISOR_OPENCODE_AUTO_SERVE=1 +SUPERVISOR_OPENCODE_HOST=127.0.0.1 +SUPERVISOR_OPENCODE_AGENT=plan +``` + +Retinue only connects to or starts the local OpenCode server and uses the OpenCode API to create, wait for, read, and close jobs. Model, provider, login, permission, plugin, and skill behavior remains owned by the active OpenCode profile. + +### Claude Code The Claude Code backend has fake E2E and best-effort real E2E coverage. It is not enabled by default in 0.1.0. To switch a deployment: @@ -111,22 +172,33 @@ SUPERVISOR_RETINUE_BACKEND=claude-code Claude Code still owns its model, endpoint, permission, and profile behavior. -## npm Install +## Development and verification -The npm package installs the Retinue runtime directly. Use it for custom MCP configuration or development setups: +Run from source: ```bash -npm install -g @disaster-terminator/retinue@0.1.0 -codex mcp add retinue \ - --env SUPERVISOR_RETINUE_BACKEND=opencode \ - --env SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ - --env SUPERVISOR_OPENCODE_AGENT=plan \ - -- retinue-mcp +pnpm install +pnpm run build +pnpm test +``` + +Deterministic release gates: + +```bash +pnpm run typecheck +pnpm run check:generated +pnpm test +pnpm run verify:package ``` -Normal Codex users should prefer the plugin marketplace path. The npm path does not install the Retinue skill. +Real OpenCode probe: -## Verification +```bash +SUPERVISOR_REAL_OPENCODE_PROBE=1 \ +SUPERVISOR_RETINUE_BACKEND=opencode \ +SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ +pnpm run probe:real:retinue-opencode +``` Before the 0.1.0 release, Retinue passed: @@ -139,21 +211,31 @@ Before the 0.1.0 release, Retinue passed: - `pnpm run build` - `pnpm run verify:package` -Real OpenCode probe: +## FAQ -```bash -SUPERVISOR_REAL_OPENCODE_PROBE=1 \ -SUPERVISOR_RETINUE_BACKEND=opencode \ -SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096 \ -pnpm run probe:real:retinue-opencode -``` +### Why is Retinue unavailable after `marketplace add`? -## Developer Docs +`codex plugin marketplace add Disaster-Terminator/Retinue` only adds the marketplace. You still need to open Codex, run `/plugins`, enter `[Retinue Local]`, and choose `Install plugin`. -- [Source install and development](docs/development/SOURCE_INSTALL.md) -- [0.1.0 release plan](docs/release/0.1.0_RELEASE_PLAN.md) -- [Docs index](docs/README.md) -- [Long-Term Vision](docs/LONG_TERM_VISION.md) +### Why is there no Retinue skill after npm install? + +The npm package installs runtime only. It does not install the Codex plugin skill. Normal Codex users should use the plugin marketplace path. + +### What if the OpenCode port is already occupied? + +Default auto-serve prefers `127.0.0.1:4096` and tries `4097` when that port is occupied by an external service. If you intentionally want to attach to an external OpenCode server, set `SUPERVISOR_OPENCODE_BASE_URL=http://127.0.0.1:4096`. + +### Why not pass model / provider / permission in the tool call? + +That is an intentional product boundary. Retinue's default entry point handles child-agent lifecycle. Model, provider, permission, and profile behavior belong to the local Claude Code or OpenCode runtime. + +## Documentation + +- [Docs Index](docs/README.md) - [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md) -- [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md) +- [OpenCode Backend](docs/backends/OPENCODE.md) - [Plugin Deployment](docs/deployment/PLUGIN_DEPLOYMENT.md) +- [Source Install and Development](docs/development/SOURCE_INSTALL.md) +- [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md) +- [0.1.0 Release Plan](docs/release/0.1.0_RELEASE_PLAN.md) +- [Long-Term Vision](docs/LONG_TERM_VISION.md) From 79cea4d6b5da6c32248f793b58b2bbd1ff40e09e Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Thu, 7 May 2026 20:50:37 +0800 Subject: [PATCH 3/3] docs: add task-oriented docs index --- docs/README.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index d8341a7..fa01488 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,22 @@ # Retinue Docs -Start here. Current product guidance is separated from historical notes so the root `docs/` -directory stays readable. +Start here when the root README is not enough. The current product docs are separated from historical notes so `docs/` stays readable. -## Current Product +## Read by task + +| I want to... | Read | +| --- | --- | +| Understand what Retinue is allowed to do | [Project Boundary](architecture/PROJECT_BOUNDARY.md) | +| Install the Codex plugin or inspect packaged plugin shape | [Plugin Deployment](deployment/PLUGIN_DEPLOYMENT.md) | +| Develop from source or run deterministic checks | [Source Install and Development](development/SOURCE_INSTALL.md) | +| Understand the default OpenCode backend | [OpenCode Backend](backends/OPENCODE.md) | +| Check service / daemon lifecycle behavior | [Service Lifecycle](deployment/SERVICE_LIFECYCLE.md) | +| Run the short verification gates | [Verification](VERIFICATION.md) | +| Track 0.1.0 release readiness | [0.1.0 Release Plan](release/0.1.0_RELEASE_PLAN.md) | +| Review active hardening issues | [0.1.0 Hardening Issues](release/0.1.0_HARDENING_ISSUES.md) | +| Understand the longer-term product direction | [Long-Term Vision](LONG_TERM_VISION.md) | + +## Current product - [0.1.0 Release Plan](release/0.1.0_RELEASE_PLAN.md) - release gate, completed work, and deferred issues. - [0.1.0 Hardening Issues](release/0.1.0_HARDENING_ISSUES.md) - active smoke/E2E issues and acceptance boundaries. @@ -11,14 +24,14 @@ directory stays readable. - [Project Boundary](architecture/PROJECT_BOUNDARY.md) - what Retinue is and is not. - [OpenCode Backend](backends/OPENCODE.md) - OpenCode adapter behavior and constraints. -## Deployment +## Deployment and development -- [Plugin Deployment](deployment/PLUGIN_DEPLOYMENT.md) - Codex plugin packaging and install shape. -- [Source Install And Development](development/SOURCE_INSTALL.md) - contributor setup and source-tree verification. +- [Plugin Deployment](deployment/PLUGIN_DEPLOYMENT.md) - Codex plugin packaging, marketplace install shape, and plugin cache behavior. +- [Source Install and Development](development/SOURCE_INSTALL.md) - contributor setup and source-tree verification. - [Service Lifecycle](deployment/SERVICE_LIFECYCLE.md) - daemon start, inspect, and stop workflow. - [Verification](VERIFICATION.md) - short test and packaging gates. -## Real Runtime Runbooks +## Real runtime runbooks - [Production OpenCode E2E](runbooks/PRODUCTION_OPENCODE_E2E.md) - [Real Claude Code Probes](runbooks/REAL_CLAUDE_PROBES.md)