Parent Issue
Part of #2 — Phase 3: Documentation Content (EN)
Objective
Create the Concepts section — deep explanations of Bub's core ideas.
Source Material
docs/architecture.md: Turn lifecycle, hook priority, error behavior, boundaries
docs/features.md: Hook-first runtime, tape context, builtin batteries
src/bub/framework.py: BubFramework class, process_inbound() flow
src/bub/hookspecs.py: All 13 hook definitions
src/bub/hook_runtime.py: HookRuntime execution logic
src/bub/builtin/context.py: Tape context building
docs/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md: Philosophy
Files to Create
1. src/content/docs/en/concepts/architecture.mdx
- Core components overview (BubFramework, HookRuntime, BubHookSpecs, Agent, ChannelManager)
- Component interaction diagram
- Boundaries and design principles
- Envelope is intentionally weakly typed
- No centralized state schema
2. src/content/docs/en/concepts/turn-lifecycle.mdx
- Step-by-step walkthrough of
process_inbound()
- Diagram: resolve_session → load_state → build_prompt → run_model → save_state → render_outbound → dispatch_outbound
- Error handling: on_error observers, exception propagation
- Fallback behaviors (no model output, no render_outbound)
- Stream events during model execution
3. src/content/docs/en/concepts/hooks.mdx
- What are hooks (pluggy foundation)
- Hook types:
call_first vs call_many
- All 13 hooks listed with signatures and semantics
- Priority: builtin first, external plugins override
- Sync vs async rules
- Signature matching (declare only needed params)
4. src/content/docs/en/concepts/tape-context.mdx
- What is tape? (Republic, append-only facts)
- Anchors and phase transitions
- Context reconstruction on demand vs session accumulation
- Handoff pattern
- Token usage awareness
- Tape forking for sub-agents
- Comparison: tape vs traditional chat history
Acceptance Criteria
- All four files created with frontmatter and sidebar ordering
- Diagrams described (can be text-based, SVG added in Phase 5)
- Hook signatures accurate against
src/bub/hookspecs.py
- Turn lifecycle matches
src/bub/framework.py implementation
- Clear, educational tone suitable for developers new to Bub
Parent Issue
Part of #2 — Phase 3: Documentation Content (EN)
Objective
Create the Concepts section — deep explanations of Bub's core ideas.
Source Material
docs/architecture.md: Turn lifecycle, hook priority, error behavior, boundariesdocs/features.md: Hook-first runtime, tape context, builtin batteriessrc/bub/framework.py: BubFramework class, process_inbound() flowsrc/bub/hookspecs.py: All 13 hook definitionssrc/bub/hook_runtime.py: HookRuntime execution logicsrc/bub/builtin/context.py: Tape context buildingdocs/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md: PhilosophyFiles to Create
1.
src/content/docs/en/concepts/architecture.mdx2.
src/content/docs/en/concepts/turn-lifecycle.mdxprocess_inbound()3.
src/content/docs/en/concepts/hooks.mdxcall_firstvscall_many4.
src/content/docs/en/concepts/tape-context.mdxAcceptance Criteria
src/bub/hookspecs.pysrc/bub/framework.pyimplementation