minixalpha · minixalpha · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026
diff --git a/README.md b/README.md
@@ -38,38 +38,12 @@ to confirm — the shape a script or a benchmark harness needs:
 
 ```bash
 nanoPyCodeAgent -p "add a --version flag and run the tests"
-nanoPyCodeAgent --prompt-file task.md
-printf "%s" "$TASK" | nanoPyCodeAgent
 ```
 
-The task is carried out in the current directory. `--max-turns N` caps how
-many model replies one run may spend (50 by default).
-
-Add `--trajectory PATH` to save that headless Agent Run as one complete
-[ATIF-v1.7](https://www.harborframework.com/docs/agents/trajectory-format)
-JSON document without changing stdout:
-
-```bash
-nanoPyCodeAgent -p "read README.md and summarize it" \
-  --trajectory ./trajectory.json
-```
-
-The option creates the requested file with owner-only permissions (`0600`)
-after the run reaches a terminal state. It refuses to overwrite an existing
-path. Trajectories may contain the task, model replies, tool arguments, and
-tool results, so treat them as sensitive data.
-
-A run like this exits `0` whenever the agent actually ran — including when it
-gave up or ran out of turns with the task unfinished, which is for whatever
-checks the result to judge. A non-zero exit means the run could not happen at
-all: `1` for missing credentials or an API that kept refusing, `2` for a
-misused command line.
-
-Every Agent Run also writes a replayable internal Event Journal under
-`~/.nanoPyCodeAgent/journals/`. These JSONL files can contain prompts, model
-replies, repository content, and tool results, so treat them as sensitive;
-the directory is user-only (`0700`) and each file is `0600`. Journals are not
-public run output or trajectories, and they are not rotated automatically yet.
+The task runs in the current directory and the command exits when the run
+ends. See the [complete CLI reference](docs/user_docs/en/cli_reference.md) for
+all task input methods, options, exit statuses, trajectory output, and Event
+Journal behavior.
 
 #### Run a branch or tagged version
 
@@ -85,31 +59,11 @@ uvx --from "git+https://github.com/minixalpha/[email protected]" nanoPyCode
 
 ### Configuration
 
-Credentials and the model come from two sources: **environment variables** and
-an optional user-level config file at `~/.nanoPyCodeAgent/settings.json`.
-Environment variables take precedence — the config file only fills in keys you
-have not set in the environment.
-
-The config file mirrors [Claude Code's settings](https://code.claude.com/docs/en/settings):
-put the values under an `env` object. Empty or whitespace-only values are ignored.
-
-```json
-{
-  "env": {
-    "ANTHROPIC_API_KEY": "",
-    "ANTHROPIC_AUTH_TOKEN": "",
-    "ANTHROPIC_BASE_URL": "",
-    "ANTHROPIC_MODEL": ""
-  }
-}
-```
-
-| Variable | Required | Default | Description |
-| --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | One credential required | — | Your Anthropic API key, or an API key accepted by a third-party service. |
-| `ANTHROPIC_AUTH_TOKEN` | One credential required | — | A bearer token used instead of `ANTHROPIC_API_KEY`; OpenRouter recommends this mode for its Anthropic-compatible endpoint. |
-| `ANTHROPIC_BASE_URL` | No | `https://api.anthropic.com` | Point the SDK at a non-official / proxy endpoint. Leave it unset to use the official API — an empty value breaks requests. |
-| `ANTHROPIC_MODEL` | No | `claude-sonnet-4-6` | Override the model. An empty or whitespace-only value falls back to the default. |
+Set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` before running the agent.
+You can also configure the endpoint and model through environment variables or
+`~/.nanoPyCodeAgent/settings.json`. See the [configuration reference](docs/user_docs/en/configuration.md)
+for supported variables, defaults, file format, precedence, and empty-value
+handling.
 
 ### How to Update
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -38,34 +38,10 @@ benchmark harness 需要的形态:
 
 ```bash
 nanoPyCodeAgent -p "add a --version flag and run the tests"
-nanoPyCodeAgent --prompt-file task.md
-printf "%s" "$TASK" | nanoPyCodeAgent
 ```
 
-任务在当前目录下执行。`--max-turns N` 限制一次运行最多花费多少轮模型回复(默认
-50 轮)。
-
-增加 `--trajectory PATH` 可以把这次 headless Agent Run 保存为一份完整的
-[ATIF-v1.7](https://www.harborframework.com/docs/agents/trajectory-format) JSON
-文档,同时不改变 stdout:
-
-```bash
-nanoPyCodeAgent -p "read README.md and summarize it" \
-  --trajectory ./trajectory.json
-```
-
-run 到达终态后,该选项才会以仅当前用户可读写的权限(`0600`)创建目标文件;如果
-目标已存在则拒绝覆盖。trajectory 可能包含任务、模型回复、工具参数和工具结果,
-应按敏感数据处理。
-
-只要 agent 真的跑起来了,退出码就是 `0`——包括它放弃了、或者轮数用尽而任务没做
-完,那该由检查结果的一方去判定。非零退出码表示这次运行根本没能进行:`1` 是缺少
-凭据或 API 持续失败,`2` 是命令行用错了。
-
-每次 Agent Run 还会在 `~/.nanoPyCodeAgent/journals/` 下写入可重放的内部 Event
-Journal。这些 JSONL 文件可能包含提示词、模型回复、仓库内容和工具结果,应按敏感
-数据处理;目录只允许当前用户访问(`0700`),每个文件的权限为 `0600`。Journal 既
-不是公开 run output,也不是 trajectory,目前还不会自动轮转。
+任务在当前目录下执行,run 结束后命令随即退出。全部任务输入方式、选项、退出状态、
+trajectory 输出和 Event Journal 行为请参阅[完整 CLI 参考](docs/user_docs/zh-CN/cli_reference.md)。
 
 #### 运行某个分支或标签版本
 
@@ -81,30 +57,9 @@ uvx --from "git+https://github.com/minixalpha/[email protected]" nanoPyCode
 
 ### 配置
 
-凭据与模型有两种配置来源:**环境变量**,以及可选的用户级配置文件
-`~/.nanoPyCodeAgent/settings.json`。环境变量优先级更高——配置文件只用于填补你
-未在环境变量中设置的键。
-
-配置文件写法与 [Claude Code settings](https://code.claude.com/docs/en/settings)
-一致:把值放在 `env` 对象下。空值或纯空白会被忽略。
-
-```json
-{
-  "env": {
-    "ANTHROPIC_API_KEY": "",
-    "ANTHROPIC_AUTH_TOKEN": "",
-    "ANTHROPIC_BASE_URL": "",
-    "ANTHROPIC_MODEL": ""
-  }
-}
-```
-
-| 变量 | 是否必填 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | 两种凭据任选其一 | 无 | 你的 Anthropic API key,或第三方服务接受的 API key。 |
-| `ANTHROPIC_AUTH_TOKEN` | 两种凭据任选其一 | 无 | 代替 `ANTHROPIC_API_KEY` 使用的 bearer token;OpenRouter 的 Anthropic-compatible endpoint 推荐这种方式。 |
-| `ANTHROPIC_BASE_URL` | 否 | `https://api.anthropic.com` | 将 SDK 指向非官方/代理 endpoint。使用官方 API 时保持不设置;留空值会导致请求失败。 |
-| `ANTHROPIC_MODEL` | 否 | `claude-sonnet-4-6` | 覆盖默认模型。空值或纯空白会回退到默认值。 |
+运行前请设置 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`。你也可以通过
+环境变量或 `~/.nanoPyCodeAgent/settings.json` 配置 endpoint 与模型。支持的变量、
+默认值、文件格式、优先级和空值处理请参阅[配置参考](docs/user_docs/zh-CN/configuration.md)。
 
 ### 如何更新
 

diff --git a/docs/changelogs/0.8.x.md b/docs/changelogs/0.8.x.md
@@ -4,6 +4,12 @@ All notable changes in the **0.8.x** release series are documented here.
 
 ## [Unreleased]
 
+### Changed
+- Moved detailed CLI and configuration guidance out of the bilingual READMEs
+  into dedicated English and Chinese user references, keeping the READMEs
+  concise while documenting task input, options, exit statuses, trajectories,
+  Event Journals, supported settings, defaults, precedence, and empty values.
+
 ## [0.8.0] - 2026-09-04
 
 ### Added

diff --git a/docs/user_docs/README.md b/docs/user_docs/README.md
@@ -0,0 +1,10 @@
+# User Documentation
+
+User-facing reference documentation for nanoPyCodeAgent is available in
+English and Simplified Chinese:
+
+- CLI reference: [English](en/cli_reference.md) | [简体中文](zh-CN/cli_reference.md)
+- Configuration: [English](en/configuration.md) | [简体中文](zh-CN/configuration.md)
+
+For installation and a concise getting-started guide, return to the main
+[English README](../../README.md) or [Chinese README](../../README.zh-CN.md).
diff --git a/docs/user_docs/en/cli_reference.md b/docs/user_docs/en/cli_reference.md
@@ -0,0 +1,154 @@
+# CLI Reference
+
+[English](cli_reference.md) | [简体中文](../zh-CN/cli_reference.md) |
+[User documentation](../README.md)
+
+`nanoPyCodeAgent` uses one command for an interactive session or a single
+headless task. Which mode starts depends on whether the command receives a
+task.
+
+## Synopsis
+
+```text
+nanoPyCodeAgent [-h] [-p TEXT | --prompt-file PATH] [--max-turns N]
+                [--trajectory PATH] [--version]
+```
+
+## Modes and task input
+
+### Interactive mode
+
+The command starts an interactive session when no task option is present and
+stdin is a terminal:
+
+```bash
+nanoPyCodeAgent
+```
+
+Enter `/exit`, press Ctrl-D, or press Ctrl-C at the `You>` prompt to end the
+session normally. `--max-turns` does not limit interactive exchanges.
+`--trajectory` is not available in interactive mode.
+
+### Headless mode
+
+Any of these input methods starts one headless run:
+
+| Input method | Example | Behavior |
+| --- | --- | --- |
+| `-p TEXT`, `--prompt TEXT` | `nanoPyCodeAgent -p "run the tests"` | Uses the argument as the task. |
+| `--prompt-file PATH` | `nanoPyCodeAgent --prompt-file task.md` | Reads the entire file as UTF-8. `~` is expanded in the path. |
+| Non-terminal stdin | `printf "%s" "$TASK" \| nanoPyCodeAgent` | Reads stdin to EOF as the task when neither task option is present. |
+
+`-p`/`--prompt` and `--prompt-file` are mutually exclusive. An explicit task
+option takes priority over stdin. Leading and trailing whitespace is removed
+from every task; an empty or whitespace-only task is a usage error. Therefore,
+running the command with empty redirected stdin, such as from `/dev/null`, does
+not start an interactive session.
+
+The headless system prompt tells the agent to work autonomously, avoid asking
+for confirmation, verify its work, and finish with a short summary.
+
+## Current working directory
+
+nanoPyCodeAgent has no working-directory option. The process's current working
+directory is the workspace for the run, including file-tool operations and
+shell commands. Start the command from the directory you want the agent to
+work in:
+
+```bash
+cd /path/to/project
+nanoPyCodeAgent -p "fix the failing tests"
+```
+
+Relative prompt-file and trajectory paths are also resolved from the current
+working directory.
+
+## Options
+
+| Option | Default | Contract |
+| --- | --- | --- |
+| `-h`, `--help` | — | Print help and exit successfully. |
+| `-p TEXT`, `--prompt TEXT` | — | Run `TEXT` as one headless task. |
+| `--prompt-file PATH` | — | Read one headless task from a UTF-8 file. The file must be readable and contain a non-empty task. |
+| `--max-turns N` | `50` | Allow at most `N` model replies in a headless run. `N` must be an integer of at least `1`. |
+| `--trajectory PATH` | disabled | Write the headless run as one ATIF-v1.7 JSON document. See [Trajectory output](#trajectory-output). |
+| `--version` | — | Print `nanoPyCodeAgent VERSION` and exit successfully. |
+
+`--max-turns` counts model replies, including replies that contain only tool
+calls. If reply `N` still requests tools, those tools are not run because no
+reply remains to consume their results. Reaching the limit prints a diagnostic
+to stderr but is still a normal headless exit.
+
+## Output channels
+
+During a headless run, stdout carries the streamed model text plus echoed tool
+calls and tool results. The startup banner, turn-limit diagnostic, and API
+errors go to stderr. This separation lets callers capture the run output while
+retaining operational diagnostics.
+
+`--trajectory` does not change stdout. There is currently no JSON or JSONL
+stdout mode.
+
+## Exit statuses
+
+| Status | Meaning |
+| --- | --- |
+| `0` | Help or version output completed; an interactive session ended normally; or a headless run started and returned control, even if the model gave up, left work incomplete, or exhausted `--max-turns`. |
+| `1` | A runtime or infrastructure failure prevented a normal run, including missing API credentials or an Anthropic/HTTP API failure. |
+| `2` | Command-line usage was invalid, including conflicting or empty task input, an invalid turn limit, an unreadable prompt file, or an invalid trajectory destination. |
+
+Exit status `0` does not certify that a headless task succeeded. A script or
+benchmark must inspect the resulting workspace or run its own verifier.
+Unexpected failures not handled by the CLI may also terminate the process with
+a non-zero status and a traceback.
+
+## Trajectory output
+
+Use `--trajectory PATH` with a headless task to write one complete
+[ATIF-v1.7](https://www.harborframework.com/docs/agents/trajectory-format)
+JSON document:
+
+```bash
+nanoPyCodeAgent -p "read README.md and summarize it" \
+  --trajectory ./trajectory.json
+```
+
+The trajectory is a separate artifact; it does not replace or redirect
+stdout. Its task, model replies, tool arguments, tool results, timing, usage,
+cost information when available, and terminal state describe a single Agent
+Run. A caught API failure after the run has started produces a partial
+trajectory with a failed terminal state.
+
+The path contract is:
+
+- `--trajectory` requires a headless task and cannot be used in interactive
+  mode.
+- `PATH` must name a file; `-` is rejected because stdout is reserved for run
+  output.
+- `~` is expanded, and relative paths use the current working directory.
+- The parent directory must already exist.
+- The destination must not already exist, including as a symbolic link. The
+  command never overwrites it.
+- The file is published after the run reaches a terminal state and is created
+  with owner-only permissions (`0600`). A failure before the Agent Run starts,
+  such as missing credentials or invalid CLI input, creates no trajectory.
+
+Trajectories can contain secrets and repository content. Store and share them
+as sensitive data.
+
+## Internal Event Journals
+
+Each Agent Run automatically creates a replayable internal JSONL Event Journal
+under `~/.nanoPyCodeAgent/journals/`. The directory is forced to owner-only
+access (`0700`), and each journal file is `0600`. A headless task that starts
+has one Agent Run; in an interactive session, each submitted user message
+starts a new Agent Run and therefore a new journal.
+
+The journal is the internal source from which an optional ATIF trajectory is
+projected. It is not public run output, not an ATIF trajectory, and has no CLI
+flag to redirect or disable it. Journal files are not rotated automatically.
+They can contain prompts, model replies, tool arguments, tool results, and
+repository content, so treat them as sensitive data.
+
+See the [configuration reference](configuration.md) for credentials, model
+selection, and endpoint settings.