Skip to content

docs: Write Concepts documentation (EN) #8

@100gle

Description

@100gle

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions