From 745e13e35f01cb7207057f583ce38e282c7dd385 Mon Sep 17 00:00:00 2001 From: eeee0717 Date: Thu, 19 Mar 2026 10:45:00 +0800 Subject: [PATCH] docs: align deployment and command docs with runtime behavior --- README.md | 22 +++++++++++----------- docs/channels/cli.md | 2 +- docs/deployment.md | 11 +++++++++-- docs/features.md | 2 +- docs/skills.md | 9 ++++++--- 5 files changed, 28 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index deb64806..02f8107f 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ See the [Extension Guide](https://bub.build/extension-guide/) for hook semantics | `bub login openai` | OpenAI Codex OAuth | | `bub hooks` | Print hook-to-plugin bindings | -Lines starting with `,` enter internal command mode (`,help`, `,tools`, `,fs.read path=README.md`). +Lines starting with `,` enter internal command mode (`,help`, `,skill name=my-skill`, `,fs.read path=README.md`). ## Configuration @@ -100,9 +100,9 @@ Lines starting with `,` enter internal command mode (`,help`, `,tools`, `,fs.rea | `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_RUNTIME_MAX_STEPS` | `50` | Max tool-use loop iterations | -| `BUB_RUNTIME_MAX_TOKENS` | `1024` | Max tokens per model call | -| `BUB_RUNTIME_MODEL_TIMEOUT_SECONDS` | — | Model call timeout (seconds) | +| `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) | ## Background @@ -112,13 +112,13 @@ Read more: [Context from Tape](https://tape.systems) · [Socialized Evaluation a ## Docs -- [Architecture](architecture.md) — lifecycle, hook precedence, error handling -- [Features](features.md) — what ships today and current boundaries -- [Channels](channels/index.md) — CLI, Telegram, and custom adapters -- [Skills](skills.md) — discovery and authoring -- [Extension Guide](extension-guide.md) — hooks, tools, plugin packaging -- [Deployment](deployment.md) — Docker, environment, upgrades -- [Posts](posts/index.md) — design notes +- [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 ## Development diff --git a/docs/channels/cli.md b/docs/channels/cli.md index 5d98c3ec..48a1d379 100644 --- a/docs/channels/cli.md +++ b/docs/channels/cli.md @@ -22,7 +22,7 @@ Comma-prefixed input enters internal command mode: ```bash uv run bub run ",help" -uv run bub run ",tools" +uv run bub run ",skill name=my-skill" uv run bub run ",fs.read path=README.md" ``` diff --git a/docs/deployment.md b/docs/deployment.md index 75543756..9e900515 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -68,14 +68,21 @@ Default mounts in `docker-compose.yml`: - `${BUB_WORKSPACE_PATH:-.}:/workspace` - `${BUB_HOME:-${HOME}/.bub}:/data` -- `${BUB_AGENT_HOME:-${HOME}/.agent}:/root/.agent` +- `${BUB_AGENT_HOME:-${HOME}/.agents}:/root/.agents` + +Notes: + +- Bub runtime data is written under `BUB_HOME` (container default: `/root/.bub`). +- In this compose file, `BUB_HOME` is used as the host bind source for `/data`. +- Do not set `BUB_HOME=/data` directly in `.env` with this compose file, or the host bind source will also become `/data`. +- If you want Bub runtime home to be `/data` in container, split variables first (for example `BUB_HOME_HOST` for host path) and then set `BUB_HOME=/data`. ## 5) Operational Checks 1. Verify process: `ps aux | rg "bub (chat|gateway|run)"` 2. Verify model config: - `rg -n "BUB_MODEL|OPENROUTER_API_KEY|LLM_API_KEY" .env` + `rg -n "BUB_MODEL|BUB_API_KEY|BUB_API_BASE|BUB_.*_API_KEY|BUB_.*_API_BASE|OPENROUTER_API_KEY" .env` 3. Verify Telegram settings: `rg -n "BUB_TELEGRAM_TOKEN|BUB_TELEGRAM_ALLOW_USERS|BUB_TELEGRAM_ALLOW_CHATS" .env` 4. Verify startup logs: diff --git a/docs/features.md b/docs/features.md index 1b60df75..e5e7b067 100644 --- a/docs/features.md +++ b/docs/features.md @@ -17,7 +17,7 @@ Context is reconstructed from tape records, not accumulated in session state. - **CLI**: `run`, `chat`, `gateway`, `login`, `hooks` via Typer. - **Model runtime**: agent loop with tool use, backed by [Republic](https://github.com/bubbuild/republic). -- **Comma commands**: `,help`, `,tools`, `,fs.read`, etc. Unknown commands fall back to shell. +- **Comma commands**: `,help`, `,skill`, `,fs.read`, etc. Unknown commands fall back to shell. - **Channels**: `cli` and `telegram` ship as defaults. All of these are hook implementations. Replace what you need. diff --git a/docs/skills.md b/docs/skills.md index 1737f048..752b631e 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -17,6 +17,8 @@ Validation rules from `src/bub/skills.py`: - frontmatter must include non-empty `name` and `description` - directory name must exactly match frontmatter `name` - `name` must match regex `^[a-z0-9]+(?:-[a-z0-9]+)*$` +- `name` length must be `<= 64` +- `description` length must be `<= 1024` - if provided, `metadata` must be a map of `string -> string` ## Frontmatter Fields @@ -38,16 +40,17 @@ Skills are discovered from three roots in this precedence order: If names collide, earlier roots in this list win. +Legacy path note: `.agent/skills` is still scanned for compatibility, but Bub emits a deprecation warning and prefers `.agents/skills`. + ## Runtime Access Builtin command mode can inspect discovered skills: ```bash -uv run bub run ",skills.list" -uv run bub run ",skills.describe name=my-skill" +uv run bub run ",skill name=my-skill" ``` -If no valid skills are discovered, `,skills.list` returns `(no skills)`. +If a skill is not found, `,skill name=` returns `(no such skill)`. ## Authoring Guidance