docs: align deployment and command docs with runtime behavior

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
 

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"
 ```
 

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:

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.

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=<name>` returns `(no such skill)`.
 
 ## Authoring Guidance