docs: align Bub positioning and clarify collaboration model

CONTRIBUTING.md

@@ -9,7 +9,7 @@ You can contribute in many ways:
 
 ## Report Bugs
 
-Report bugs at https://github.com/psiace/bub/issues
+Report bugs at https://github.com/bubbuild/bub/issues
 
 If you are reporting a bug, please include:
 
@@ -33,7 +33,7 @@ bub could always use more documentation, whether as part of the official docs, i
 
 ## Submit Feedback
 
-The best way to send feedback is to file an issue at https://github.com/psiace/bub/issues.
+The best way to send feedback is to file an issue at https://github.com/bubbuild/bub/issues.
 
 If you are proposing a new feature:
 

README.md

@@ -1,26 +1,32 @@
 # Bub
 
-[![Release](https://img.shields.io/github/v/release/psiace/bub)](https://github.com/psiace/bub/releases)
-[![Build status](https://img.shields.io/github/actions/workflow/status/psiace/bub/main.yml?branch=main)](https://github.com/psiace/bub/actions/workflows/main.yml?query=branch%3Amain)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/psiace/bub)](https://github.com/psiace/bub/graphs/commit-activity)
-[![License](https://img.shields.io/github/license/psiace/bub)](LICENSE)
+[![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 it. Build it.
 
-Bub is a coding agent CLI built on `republic`.
-It is designed for real engineering workflows where execution must be predictable, inspectable, and recoverable.
+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.
 
-## Four Things To Know
+> Documentation: <https://bub.build>
 
-1. Command boundary is strict: only lines starting with `,` are treated as commands.
-2. The same routing model is applied to both user input and assistant output.
-3. Successful commands return directly; failed commands fall back to the model with structured context.
-4. Session context is append-only tape with explicit `anchor/handoff` transitions.
+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.
 
 ## Quick Start
 
 ```bash
-git clone https://github.com/psiace/bub.git
+git clone https://github.com/bubbuild/bub.git
 cd bub
 uv sync
 cp env.example .env
@@ -39,7 +45,7 @@ Start interactive CLI:
 uv run bub
 ```
 
-## Interaction Rules
+## Interaction Model
 
 - `hello`: natural language routed to model.
 - `,help`: internal command.
@@ -62,7 +68,9 @@ Common commands:
 ,quit
 ```
 
-## Telegram (Optional)
+## Channel Runtime (Optional)
+
+Telegram:
 
 ```bash
 BUB_TELEGRAM_ENABLED=true
@@ -71,7 +79,7 @@ BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]'
 uv run bub message
 ```
 
-## Discord (Optional)
+Discord:
 
 ```bash
 BUB_DISCORD_ENABLED=true
@@ -81,16 +89,6 @@ BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]'
 uv run bub message
 ```
 
-## Documentation
-
-- `docs/index.md`: getting started and usage overview
-- `docs/deployment.md`: local + Docker deployment playbook
-- `docs/features.md`: key capabilities and why they matter
-- `docs/cli.md`: interactive CLI workflow and troubleshooting
-- `docs/architecture.md`: agent loop, tape, anchor, and tool/skill design
-- `docs/telegram.md`: Telegram integration and operations
-- `docs/discord.md`: Discord integration and operations
-
 ## Development
 
 ```bash

docs/architecture.md

@@ -8,6 +8,7 @@ This page is for developers and advanced users who need to understand why Bub be
 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
 

docs/channels.md

@@ -0,0 +1,26 @@
+# Channels
+
+Bub supports running the same agent loop through message channels.
+Use channels when you want remote operation from mobile or shared team environments.
+
+## Supported Channels
+
+- [Telegram](telegram.md): direct messages and group chats.
+- [Discord](discord.md): servers, channels, and threads.
+
+## Run Entry
+
+Start channel mode with:
+
+```bash
+uv run bub message
+```
+
+If the process exits immediately, check that at least one channel is enabled in `.env`.
+
+## Session Isolation
+
+- Telegram session key: `telegram:<chat_id>`
+- Discord session key: `discord:<channel_id>`
+
+This keeps message history isolated per conversation endpoint.

docs/cli.md

@@ -1,6 +1,6 @@
 # Interactive CLI
 
-## Runtime Commands
+## Run Commands
 
 ```bash
 uv run bub chat
@@ -16,7 +16,7 @@ uv run bub chat \
   --session-id cli-main
 ```
 
-Other runtime modes:
+Other run modes:
 
 - `uv run bub run "summarize current repo status"`: one-shot message and exit.
 - `uv run bub message`: run enabled message channels (Telegram/Discord).

docs/deployment.md

@@ -11,7 +11,7 @@ This page covers production-oriented setups for Bub, including local process man
 Quick bootstrap:
 
 ```bash
-git clone https://github.com/psiace/bub.git
+git clone https://github.com/bubbuild/bub.git
 cd bub
 uv sync
 cp env.example .env
@@ -32,7 +32,7 @@ Choose one mode based on your operation target:
    `uv run bub chat`
 2. Channel service (Telegram/Discord):
    `uv run bub message`
-3. Scheduler-only autonomous runtime:
+3. Scheduler-only autonomous mode:
    `uv run bub idle`
 
 One-shot operation:
@@ -115,4 +115,4 @@ uv run mypy
 uv run pytest -q
 ```
 
-Then restart your runtime (`chat`, `message`, or container service).
+Then restart your service mode (`chat`, `message`, or container service).

docs/discord.md

@@ -1,6 +1,6 @@
 # Discord Integration
 
-Discord allows Bub to run as a remote coding assistant for team channels, threads, and DMs.
+Discord allows Bub to run as a remote collaboration endpoint for team channels, threads, and DMs.
 
 ## Configure
 
@@ -30,9 +30,9 @@ Notes:
 uv run bub message
 ```
 
-## Runtime Behavior
+## Run Behavior
 
-- Uses `discord.py` bot runtime.
+- Uses `discord.py` bot service loop.
 - Each Discord channel maps to `discord:<channel_id>` session key.
 - Inbound text enters the same `AgentLoop` used by CLI.
 - Outbound immediate output is sent back in-channel (split into chunks when too long).
@@ -49,4 +49,4 @@ uv run bub message
 1. Keep bot token only in `.env` or a secret manager.
 2. Restrict `BUB_DISCORD_ALLOW_CHANNELS` and `BUB_DISCORD_ALLOW_FROM`.
 3. Confirm the bot has message-content intent enabled in Discord Developer Portal.
-4. If no response is observed, verify token, allowlists, intents, and runtime logs.
+4. If no response is observed, verify token, allowlists, intents, and service logs.

docs/features.md

@@ -1,6 +1,6 @@
 # Key Features
 
-This page summarizes the capabilities users rely on most when working with Bub.
+This page summarizes the capabilities operators rely on most when working with Bub.
 
 ## 1. Deterministic Command Routing
 
@@ -17,9 +17,9 @@ Why it matters: fewer accidental tool calls and more predictable behavior.
 
 Why it matters: the assistant can debug based on real command output instead of generic guesses.
 
-## 3. Tape-First Session Memory
+## 3. Verifiable Session History and Context Assembly
 
-- Bub writes session activity to append-only tape.
+- Bub records session activity as append-only, verifiable history.
 - `,anchors` and `,handoff` mark phase transitions.
 - `,tape.search` and `,tape.info` help inspect context quickly.
 
@@ -39,7 +39,7 @@ Why it matters: prompt stays focused while advanced capabilities remain availabl
 
 - Rich interactive shell with history and completions.
 - `Ctrl-X` toggles shell mode for faster command execution.
-- Same runtime behavior as channel integrations.
+- Same behavior model as channel integrations.
 
 Why it matters: local debugging and implementation loops are fast and consistent.
 

docs/index.md

@@ -1,45 +1,39 @@
 # Bub Docs
 
-Bub is built for day-to-day coding tasks: run commands, edit files, debug failures, and keep progress visible across long sessions.
+Bub is a collaborative agent for shared delivery workflows, evolving into a framework that helps other agents operate with the same collaboration model.
+If you only remember one thing from this page, remember this: Bub is built for shared delivery workflows where execution must be inspectable, handoff-friendly, and repeatable.
 
-## What You Can Expect
+Under the hood, Bub uses [Republic](https://github.com/bubbuild/republic) to assemble context from traceable history instead of inheriting opaque state.
+Its operating philosophy follows [Socialized Evaluation](https://psiace.me/posts/im-and-socialized-evaluation/): quality is judged by whether teams can inspect decisions and continue work safely.
 
-- Clear command behavior: only lines that start with `,` are commands.
-- One execution path: the same rules apply to both your input and assistant-generated commands.
-- Graceful recovery: failed commands are fed back to the model with structured context.
-- Trackable sessions: tape, anchors, and handoff help you resume work cleanly.
+## What Bub Is (and Is Not)
 
-## How Bub Behaves In Practice
+- Bub is a collaboration agent for human and agent operators.
+- Bub is not a personal-assistant-only chat shell.
+- Bub keeps command execution explicit, reviewable, and recoverable.
 
-1. Type normal text to ask the assistant.
-2. Start a line with `,` to run a command.
-3. Known names such as `,help` are internal commands.
-4. Other comma-prefixed lines are treated as shell commands.
-5. If a command fails, Bub keeps going and uses the error context in the next model step.
+## How Bub Works
 
-## Start Here
+1. Input boundary: only lines starting with `,` are treated as commands.
+2. Unified routing: the same routing rules apply to user input and assistant output.
+3. Structured fallback: failed commands are returned to the model with execution evidence.
+4. Persistent evidence: interaction history is append-only (`tape`) and can be searched.
+5. Explicit transitions: `anchor` and `handoff` represent phase changes and responsibility transfer.
 
-- [Key Features](features.md)
-- [Interactive CLI](cli.md)
-- [Deployment Guide](deployment.md)
-- [Architecture](architecture.md)
-- [Telegram Integration](telegram.md)
-- [Discord Integration](discord.md)
+## Checklist
 
-## Common Commands
+1. Start with model + API key in `.env`.
+2. Run `uv run bub` and ask a normal question.
+3. Run `,help` and `,tools` to inspect available capabilities.
+4. Execute one shell command like `,git status`.
+5. Create one handoff: `,handoff name=phase-1 summary="..."`.
+6. Verify history using `,tape.info` or `,tape.search query=...`.
 
-```text
-,help
-,tools
-,tool.describe name=fs.read
-,tape.info
-,tape.search query=timeout
-,handoff name=phase-2 summary="router fixed" next_steps="run pytest"
-,anchors
-,tape.reset archive=true
-```
+## Where To Read Next
 
-## Configuration
-
-Start from `env.example` in the repository root.
-Use model + API key first, then add Telegram and advanced settings when needed.
+- [Key Features](features.md): capability-level overview.
+- [Interactive CLI](cli.md): interactive workflow and troubleshooting.
+- [Architecture](architecture.md): runtime boundaries and internals.
+- [Deployment Guide](deployment.md): local and Docker operations.
+- [Channels](channels.md): Telegram and Discord runtime model.
+- [Post: Socialized Evaluation and Agent Partnership](posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md): project position and principles.

docs/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership.md

@@ -0,0 +1,68 @@
+---
+title: "Bub: Socialized Evaluation and Agent Partnership"
+date: 2026-03-01
+description: "Why Bub is designed as an agent partner system where humans and agents share the same operator model."
+---
+
+# Bub: Socialized Evaluation and Agent Partnership
+
+I care less about whether an agent can complete a demo task, and more about whether a real team can trust it under pressure.
+That is where most systems fail: not at capability, but at collaboration.
+
+Bub is not designed as a personal-only assistant.
+It is designed for shared environments where humans and agents are treated as equivalent operators.
+Current deployments may use one primary agent, but the collaboration model itself is symmetric: the same boundaries, evidence model, and handoff semantics apply to both humans and agents.
+
+The practical goal is simple: when work gets messy, Bub should still feel like a dependable teammate.
+It should make execution visible, handoff safe, and continuation predictable.
+
+## From Tool Execution to Human Partnership
+
+Many agent systems focus on whether a model can execute commands.
+For real teams, that is not enough.
+What matters is whether outcomes remain understandable, reviewable, and improvable over long time horizons.
+
+Bub treats this as a first-class design target:
+
+- Agents should assist human workflows, not replace human judgment.
+- Operator decisions, agent actions, and execution evidence should stay visible.
+- Collaboration should remain stable when more operators and automation layers join.
+
+## Socialized Evaluation as a System Principle
+
+In Bub, evaluation is not only model-centric.
+It is social by design:
+
+- Can teammates inspect what happened and why?
+- Can reviewers audit decisions without hidden state?
+- Can future operators continue work from recorded evidence?
+- Can all operators (human or agent) coordinate without opaque side effects?
+
+If the answer is no, the system is not reliable enough for production collaboration.
+The term "Socialized Evaluation" follows the framing in [Instant Messaging and Socialized Evaluation](https://psiace.me/posts/im-and-socialized-evaluation/).
+
+## Why Operator Equivalence by Default
+
+Single-user flows can hide many structural problems.
+Multi-operator settings expose them quickly: state conflicts, unclear responsibility, and fragile context boundaries.
+
+Bub is built with these constraints from day one:
+
+- Explicit command boundaries.
+- Verifiable execution history with explicit anchor and handoff points.
+- Handoff and anchors for continuity across people and phases.
+- Channel/runtime neutrality for different operation surfaces.
+
+This is how Bub moves from "assistant behavior" to "collaboration infrastructure."
+
+## Relationship to Republic
+
+Bub uses [Republic](https://github.com/bubbuild/republic) as its context runtime.
+Republic's key value is not "a better memory trick." It reframes the problem: keep interaction history as verifiable facts, then assemble minimally sufficient context for each task.
+Bub builds on that model to support practical collaboration workflows where humans and agents participate as equivalent operators.
+
+## Closing
+
+Our direction is simple:
+
+Build agents that are useful in real social systems, not only impressive in isolated demos.