bubbuild · frostming · Mar 6, 2026 · Feb 13, 2026 · Feb 14, 2026 · Feb 22, 2026
diff --git a/.gitignore b/.gitignore
@@ -142,3 +142,6 @@ cython_debug/
 
 # Reference directory - ignore all reference projects
 reference/
+
+# Local legacy backups created during framework migrations
+backup/
diff --git a/README.md b/README.md
@@ -1,103 +1,97 @@
 # Bub
 
-[![Release](https://img.shields.io/github/v/release/bubbuild/bub)](https://github.com/bubbuild/bub/releases)
-[![Build status](https://img.shields.io/github/actions/workflow/status/bubbuild/bub/main.yml?branch=main)](https://github.com/bubbuild/bub/actions/workflows/main.yml?query=branch%3Amain)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/bubbuild/bub)](https://github.com/bubbuild/bub/graphs/commit-activity)
-[![License](https://img.shields.io/github/license/bubbuild/bub)](LICENSE)
+Bub is a hook-first AI framework built on `pluggy`: the core stays small and orchestrates turns, while builtins and plugins provide behavior.
 
-> Bub it. Build it.
+## Current Implementation
 
-Bub is a collaborative agent for shared delivery workflows, evolving into a framework that helps other agents operate with the same collaboration model.
-It is not a personal-assistant shell: it is designed for shared environments where work must be inspectable, handoff-friendly, and operationally reliable.
-
-> Documentation: <https://bub.build>
-
-Built on [Republic](https://github.com/bubbuild/republic), Bub treats context as explicit assembly from verifiable interaction history, rather than opaque inherited state.
-This aligns with [Socialized Evaluation](https://psiace.me/posts/im-and-socialized-evaluation/): systems are judged by how well teams can inspect, review, and continue work together.
-
-## What Bub Provides
-
-- Multi-operator collaboration in shared delivery environments.
-- Explicit command boundaries for predictable execution.
-- Verifiable history (`tape`, `anchor`, `handoff`) for audit and continuity.
-- Channel-neutral behavior across CLI and message channels.
-- Extensible tools and skills with a unified operator-facing workflow.
+- CLI bootstrap: `src/bub/__main__.py` (Typer app)
+- Turn orchestrator: `src/bub/framework.py`
+- Hook contract: `src/bub/hookspecs.py`
+- Builtin hooks/runtime: `src/bub/builtin/hook_impl.py` + `src/bub/builtin/engine.py`
+- Skill discovery and validation: `src/bub/skills.py`
 
 ## Quick Start
 
 ```bash
 git clone https://github.com/bubbuild/bub.git
 cd bub
 uv sync
-cp env.example .env
+uv run bub --help
 ```
 
-Minimal `.env`:
-
 ```bash
-BUB_MODEL=openrouter:qwen/qwen3-coder-next
-LLM_API_KEY=your_key_here
+# Runtime off: falls back to model_output=prompt
+BUB_RUNTIME_ENABLED=0 uv run bub run "hello"
 ```
 
-Start interactive CLI:
-
 ```bash
-uv run bub
+# Internal command mode (line starts with ',')
+BUB_RUNTIME_ENABLED=0 uv run bub run ",help"
 ```
 
-## Interaction Model
-
-- `hello`: natural language routed to model.
-- `,help`: internal command.
-- `,git status`: shell command.
-- `, ls -la`: shell command (space after comma is optional).
-
-Common commands:
-
-```text
-,help
-,tools
-,tool.describe name=fs.read
-,skills.list
-,skills.describe name=friendly-python
-,handoff name=phase-1 summary="bootstrap done"
-,anchors
-,tape.info
-,tape.search query=error
-,tape.reset archive=true
-,quit
+```bash
+# Model runtime (hosted providers usually require a key)
+BUB_API_KEY=your_key uv run bub run "Summarize this repository"
 ```
 
-## Channel Runtime (Optional)
+## CLI Commands
 
-Telegram:
+- `bub run MESSAGE`: execute one inbound turn and print outbound messages
+- `bub hooks`: print hook-to-plugin bindings
+- `bub install PLUGIN_SPEC`: install plugin from PyPI or `owner/repo` (GitHub shorthand)
 
-```bash
-BUB_TELEGRAM_ENABLED=true
-BUB_TELEGRAM_TOKEN=123456:token
-BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]'
-uv run bub message
-```
+## Runtime Behavior
 
-Discord:
+- Regular text input: uses `run_model`; if runtime is unavailable, output falls back to the prompt text
+- Comma commands: `,help`, `,tools`, `,fs.read ...`, etc.
+- Unknown comma commands: executed as `bash -lc` in workspace
+- Session event log: `.bub/runtime/<session-hash>.jsonl`
+- `AGENTS.md`: if present in workspace, appended to runtime system prompt
 
-```bash
-BUB_DISCORD_ENABLED=true
-BUB_DISCORD_TOKEN=discord_bot_token
-BUB_DISCORD_ALLOW_FROM='["123456789012345678","your_discord_name"]'
-BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]'
-uv run bub message
+## Skills
+
+- Discovery roots with deterministic override:
+  1. `<workspace>/.agent/skills`
+  2. `~/.agent/skills`
+  3. `src/bub_skills`
+- Each skill directory must include `SKILL.md`
+- Supported frontmatter fields:
+  - required: `name`, `description`
+  - optional: `license`, `compatibility`, `metadata`, `allowed-tools`
+
+## Plugin Development
+
+Plugins are loaded from Python entry points in `group="bub"`:
+
+```toml
+[project.entry-points."bub"]
+my_plugin = "my_package.my_plugin"
 ```
 
-## Development
+Implement hooks with `@hookimpl` following `BubHookSpecs`.
+
+## Runtime Environment Variables
+
+- `BUB_RUNTIME_ENABLED`: `auto` (default), `1`, `0`
+- `BUB_MODEL`: default `openrouter:qwen/qwen3-coder-next`
+- `BUB_API_KEY`: runtime provider key
+- `BUB_API_BASE`: optional provider base URL
+- `BUB_RUNTIME_MAX_STEPS`: default `8`
+- `BUB_RUNTIME_MAX_TOKENS`: default `1024`
+- `BUB_RUNTIME_MODEL_TIMEOUT_SECONDS`: default `90`
+
+## Documentation
+
+- `docs/index.md`: overview
+- `docs/architecture.md`: lifecycle, precedence, and failure isolation
+- `docs/skills.md`: skill discovery and frontmatter constraints
+- `docs/cli.md`: CLI usage and comma command mode
+- `docs/features.md`: implemented capabilities and limits
+
+## Development Checks
 
 ```bash
 uv run ruff check .
-uv run mypy
+uv run mypy src
 uv run pytest -q
-just docs-test
 ```
-
-## License
-
-[Apache 2.0](./LICENSE)
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -9,7 +9,7 @@ services:
     volumes:
       - ${BUB_WORKSPACE_PATH:-.}:/workspace
       - ${BUB_HOME:-${HOME}/.bub}:/data
-      - ${BUB_AGENT_HOME:-${HOME}/.agent}:/root/.agent
+      - ${BUB_AGENT_HOME:-${HOME}/.agents}:/root/.agents
     stdin_open: true
     tty: true
     restart: unless-stopped
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,49 +1,60 @@
 # Architecture
 
-This page is for developers and advanced users who need to understand why Bub behavior is deterministic and how to extend it safely.
-
-## Core Principles
-
-1. One session, one append-only tape.
-2. Same routing rules for user input and assistant output.
-3. Command execution and model reasoning are explicit layers.
-4. Phase transitions are represented by `anchor/handoff`, not hidden state jumps.
-5. Human and agent operators follow the same collaboration boundaries.
-
-## Runtime Topology
-
-```text
-input -> InputRouter -> AgentLoop -> ModelRunner -> InputRouter(assistant output) -> ...
-                \-> direct command response
-```
-
-Key modules:
-
-- `src/bub/core/router.py`: command detection, execution, and failure context wrapping.
-- `src/bub/core/agent_loop.py`: turn orchestration and stop conditions.
-- `src/bub/core/model_runner.py`: bounded model loop and user-driven skill-hint activation.
-- `src/bub/tape/service.py`: tape read/write, anchor/handoff, reset, and search.
-- `src/bub/tools/*`: unified registry and progressive tool view.
-
-## Single Turn Flow
-
-1. `InputRouter.route_user` checks whether input starts with `,`.
-2. If command succeeds, return output directly.
-3. If command fails, generate a `<command ...>` block for model context.
-4. `ModelRunner` gets assistant output.
-5. `route_assistant` applies the same command parsing/execution rules.
-6. Loop ends on plain final text, explicit quit, or `max_steps`.
-
-## Tape, Anchor, Handoff
-
-- Tape is workspace-level JSONL for replay and audit.
-- `handoff` writes an anchor with optional `summary` and `next_steps`.
-- `anchors` lists phase boundaries.
-- `tape.reset` clears active context (optionally archiving first).
-
-## Tools and Skills
-
-- Built-in tools and skills live in one registry.
-- System prompt starts with compact tool descriptions.
-- Full tool schema is expanded on demand (`tool.describe` or explicit selection).
-- `$name` hints progressively expand tool/skill details from either user input or model output.
+## Core Components
+
+- `BubFramework`: creates the plugin manager, loads plugins, and runs `process_inbound()`.
+- `BubHookSpecs`: defines all hook contracts (`src/bub/hookspecs.py`).
+- `HookRuntime`: executes hooks with sync/async compatibility helpers (`src/bub/hook_runtime.py`).
+- `Agent`: builtin model-and-tools runtime (`src/bub/builtin/agent.py`).
+- `ChannelManager`: starts channels, buffers inbound messages, and routes outbound messages (`src/bub/channels/manager.py`).
+
+## Turn Lifecycle
+
+`BubFramework.process_inbound()` currently executes in this order:
+
+1. Resolve session via `resolve_session(message)` (fallback to `channel:chat_id` if empty).
+2. Initialize state with `_runtime_workspace` from `BubFramework.workspace`.
+3. Merge all `load_state(message, session_id)` dicts.
+4. Build prompt via `build_prompt(message, session_id, state)` (fallback to inbound `content` if empty).
+5. Execute `run_model(prompt, session_id, state)`.
+6. Always execute `save_state(...)` in a `finally` block.
+7. Render outbound batches via `render_outbound(...)`, then flatten them.
+8. If no outbound exists, emit one fallback outbound.
+9. Dispatch each outbound via `dispatch_outbound(message)`.
+
+## Hook Priority Semantics
+
+- Registration order:
+1. Builtin plugin `builtin`
+2. External entry points (`group="bub"`)
+- Execution order:
+1. `HookRuntime` reverses pluggy implementation order, so later-registered plugins run first.
+2. `call_first` returns the first non-`None` value.
+3. `call_many` collects every implementation return value (including `None`).
+- Merge/override details:
+1. `load_state` is reversed again before merge so high-priority plugins win on key collisions.
+2. `provide_channels` is collected by `BubFramework.get_channels()`, and the first channel name wins, so high-priority plugins can override builtin channel names.
+
+## Error Behavior
+
+- For normal hooks, `HookRuntime` does not swallow implementation errors.
+- `process_inbound()` catches top-level exceptions, notifies `on_error(stage="turn", ...)`, then re-raises.
+- `on_error` itself is observer-safe: one failing observer does not block the others.
+- In sync calls (`call_first_sync`/`call_many_sync`), awaitable return values are skipped with a warning.
+
+## Builtin Runtime Notes
+
+Builtin `BuiltinImpl` behavior includes:
+
+- `build_prompt`: supports comma command mode; non-command text may include `context_str`.
+- `run_model`: delegates to `Agent.run()`.
+- `system_prompt`: combines a default prompt with workspace `AGENTS.md`.
+- `register_cli_commands`: installs `run`, `gateway`, `chat`, plus hidden compatibility/diagnostic commands.
+- `provide_channels`: returns `telegram` and `cli` channel adapters.
+- `provide_tape_store`: returns a file-backed tape store under `~/.bub/tapes`.
+
+## Boundaries
+
+- `Envelope` stays intentionally weakly typed (`Any` + accessor helpers).
+- There is no globally enforced schema for cross-plugin `state`.
+- Runtime behavior in this document is aligned with current source code.
diff --git a/docs/assets/images/baby-bub.png b/docs/assets/images/baby-bub.png
diff --git a/docs/channels.md b/docs/channels.md
diff --git a/docs/channels/index.md b/docs/channels/index.md
@@ -0,0 +1,47 @@
+# Channels
+
+Bub uses channel adapters to run the same agent pipeline across different I/O endpoints.
+
+## Builtin Channels
+
+- `cli`: local interactive terminal channel (`uv run bub chat`)
+- `telegram`: Telegram bot channel (`uv run bub gateway`)
+
+See [Telegram](telegram.md) for channel-specific configuration and runtime behavior.
+
+## Run Modes
+
+Local interactive mode:
+
+```bash
+uv run bub chat
+```
+
+Channel listener mode (all non-`cli` channels by default):
+
+```bash
+uv run bub gateway
+```
+
+Enable only Telegram:
+
+```bash
+uv run bub gateway --enable-channel telegram
+```
+
+## Session Semantics
+
+- `run` command default session id: `<channel>:<chat_id>`
+- Telegram channel session id: `telegram:<chat_id>`
+- `chat` command default session id: `cli_session` (override with `--session-id`)
+
+## Debounce Behavior
+
+- `cli` does not debounce; each input is processed immediately.
+- Other channels can debounce and batch inbound messages per session.
+- Comma commands (`,` prefix) always bypass debounce and execute immediately.
+
+## About Discord
+
+Core Bub does not currently include a builtin Discord adapter.
+If you need Discord, implement it in an external plugin via `provide_channels`.