docs: minor update

Signed-off-by: Chojan Shang <psiace@apache.org>

Author: PsiACE

README.md

@@ -53,10 +53,10 @@ If `AGENTS.md` exists in the workspace, it is appended to the system prompt auto
 
 Key source files:
 
-- Turn orchestrator: [`src/bub/framework.py`](src/bub/framework.py)
-- Hook contract: [`src/bub/hookspecs.py`](src/bub/hookspecs.py)
-- Builtin hooks: [`src/bub/builtin/hook_impl.py`](src/bub/builtin/hook_impl.py)
-- Skill discovery: [`src/bub/skills.py`](src/bub/skills.py)
+- Turn orchestrator: [`src/bub/framework.py`](https://github.com/bubbuild/bub/blob/main/src/bub/framework.py)
+- Hook contract: [`src/bub/hookspecs.py`](https://github.com/bubbuild/bub/blob/main/src/bub/hookspecs.py)
+- Builtin hooks: [`src/bub/builtin/hook_impl.py`](https://github.com/bubbuild/bub/blob/main/src/bub/builtin/hook_impl.py)
+- Skill discovery: [`src/bub/skills.py`](https://github.com/bubbuild/bub/blob/main/src/bub/skills.py)
 
 ## What Sets It Apart
 
@@ -109,7 +109,7 @@ Lines starting with `,` enter internal command mode (`,help`, `,skill name=my-sk
 | `BUB_API_KEY` | — | Provider key (optional with `bub login openai`) |
 | `BUB_API_BASE` | — | Custom provider endpoint |
 | `BUB_API_FORMAT` | `completion` | `completion`, `responses`, or `messages` |
-| `BUB_CLIENT_ARGS` | `{"extra_headers":{"HTTP-Referer":"https://bub.build/","X-Title":"Bub"}}` | JSON object forwarded to the underlying model client |
+| `BUB_CLIENT_ARGS` | — | JSON object forwarded to the underlying model client |
 | `BUB_MAX_STEPS` | `50` | Max tool-use loop iterations |
 | `BUB_MAX_TOKENS` | `1024` | Max tokens per model call |
 | `BUB_MODEL_TIMEOUT_SECONDS` | — | Model call timeout (seconds) |
@@ -122,13 +122,13 @@ Read more: [Context from Tape](https://tape.systems) · [Socialized Evaluation a
 
 ## Docs
 
-- [Architecture](docs/architecture.md) — lifecycle, hook precedence, error handling
-- [Features](docs/features.md) — what ships today and current boundaries
-- [Channels](docs/channels/index.md) — CLI, Telegram, and custom adapters
-- [Skills](docs/skills.md) — discovery and authoring
-- [Extension Guide](docs/extension-guide.md) — hooks, tools, plugin packaging
-- [Deployment](docs/deployment.md) — Docker, environment, upgrades
-- [Posts](docs/posts/index.md) — design notes
+- [Architecture](https://bub.build/architecture/) — lifecycle, hook precedence, error handling
+- [Features](https://bub.build/features/) — what ships today and current boundaries
+- [Channels](https://bub.build/channels/) — CLI, Telegram, and custom adapters
+- [Skills](https://bub.build/skills/) — discovery and authoring
+- [Extension Guide](https://bub.build/extension-guide/) — hooks, tools, plugin packaging
+- [Deployment](https://bub.build/deployment/) — Docker, environment, upgrades
+- [Posts](https://bub.build/posts/) — design notes
 
 ## Development
 
@@ -138,8 +138,8 @@ uv run mypy src
 uv run pytest -q
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+See [CONTRIBUTING.md](https://github.com/bubbuild/bub/blob/main/CONTRIBUTING.md).
 
 ## License
 
-[Apache-2.0](./LICENSE)
+[Apache-2.0](https://github.com/bubbuild/bub/blob/main/LICENSE)

docs/channels/cli.md

@@ -87,11 +87,11 @@ After login, you can use an OpenAI model without setting `BUB_API_KEY`:
 BUB_MODEL=openai:gpt-5-codex uv run bub chat
 ```
 
-If the upstream endpoint expects a specific OpenAI-compatible request shape, set `BUB_API_FORMAT`:
+If the upstream endpoint expects a specific request payload format, set `BUB_API_FORMAT`:
 
 - `completion`: legacy completion-style format; default
 - `responses`: OpenAI Responses API format
-- `messages`: chat-completions-style messages format
+- `messages`: Anthropic Messages API format
 
 ```bash
 BUB_MODEL=openai:gpt-5-codex BUB_API_FORMAT=responses uv run bub chat

docs/deployment.md

@@ -24,6 +24,12 @@ BUB_MODEL=openrouter:qwen/qwen3-coder-next
 OPENROUTER_API_KEY=sk-or-...
 ```
 
+Advanced model-client settings:
+
+- `BUB_API_FORMAT` selects the request payload format sent to the upstream model endpoint: `completion`, `responses`, or `messages`.
+- `BUB_CLIENT_ARGS` passes a JSON object through to the underlying model client.
+- The accepted `BUB_CLIENT_ARGS` keys depend on the selected provider and downstream SDK behavior, so treat it as an escape hatch rather than a stable cross-provider interface.
+
 ## 2) Runtime Modes
 
 Choose one command based on your operation target: