# berd — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT # berd Knowledge Base An LLM-maintained knowledge base on **berd** (github.com/block/berd) — Block's open-source desktop app for getting work done with any model: a model-agnostic chat/work client with composable capabilities, a CLI (bb / berdctl), auth flows, and an 'sq' integration. Pinned to v0.6.2. ## Concepts - [[concepts/berd-overview|Berd Overview]] - [[concepts/product-and-design|Product and Design]] - [[concepts/composable-capabilities|Composable Capabilities]] - [[concepts/operating-laws|Operating Laws]] - [[concepts/architecture|berdctl Architecture]] - [[concepts/bb-cli-and-berdctl|bb-cli and the bb / berdctl Command Surfaces]] - [[concepts/sq-integration|sq Integration]] - [[concepts/release-and-updates|Release and Auto-Update, and Windows Onboarding]] - [[concepts/security-and-telemetry|Security Posture and Telemetry]] - [[concepts/governance|Governance]] ## Summaries - [[summaries/release-digest|Release Digest: v0.6.0-rc.1 through v0.6.2]] --- title: "berdctl Architecture" type: concept tags: [architecture, cli, developer] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-docs-berdctl-architecture-md.md", "raw/github_doc-readme-md.md", "raw/github_doc-product-md.md", "raw/github_doc-bb-cli-readme-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: high berd_version: "v0.6.2" --- ## Definition At the top level, Berd is a Tauri 2 + React 19 desktop shell that talks to the upstream Goose agent backend over an ACP WebSocket served by a `goose serve` sidecar (see [[concepts/berd-overview]]). `berdctl` is the app-bundled CLI that lets agents (and scripts) *control that running desktop app* — creating projects, listing sessions, sending prompts — as opposed to `bb-cli`'s `bb`/`agent-tools`, which talk to Block's separate kgoose backend (see [[concepts/bb-cli-and-berdctl]]). ```sh berdctl session list --json berdctl project create --name demo ``` ## How It Works berdctl is implemented in three layers, each with a distinct trust and policy role: 1. **CLI** — `src-tauri/crates/berdctl/`. Parses flags with clap, prints help, reads the app's discovery file, and sends JSON calls. CLI-side validation is convenience only, not a security boundary. 2. **Broker** — `src-tauri/plugins/berdctl/`. Runs a localhost server inside the app itself. It rejects browser-origin requests, enforces in-flight and timeout limits, and forwards calls to the renderer with no command-specific logic of its own. 3. **Renderer registry** — `src/features/berdctl/commands/`. Strict-parses arguments with zod, runs guards, executes through app state, and returns JSON results. **This is the real trust boundary** — any same-user process can bypass the CLI entirely and POST directly to the broker. ### Layer rules - The broker stays transport-only: host/origin checks, discovery/version handshake, in-flight cap, timeouts, request correlation. No command nouns, verbs, action names, or command-specific policy live here. - The registry owns policy: zod strict parsing, bounds, command safety metadata, running-session guards, and app mutations. - The CLI owns agent UX: stable flag names, local parse errors, exit codes, and hand-authored help. Agents are expected to be able to rely on `--help`. ### Command source of truth Each command module owns a zod schema with `.strict()` and `.describe()` on every field, an inferred TypeScript input type, guardrail bounds, `summary`/`description`/`helpFooter` text, safety metadata (`effect`, `visibility`, `destructive`), and `precheck`/`execute` functions. Descriptors must be import-pure — static imports are limited to zod, berdctl command types, and pure helpers; stores, Tauri APIs, providers, navigation, and caches load dynamically from `execute`/`precheck` via domain runtime modules. ### Contract generation `pnpm generate:berdctl-contract` reads the command descriptors and writes two embedded artifacts consumed by the Rust CLI: - `api-surface.json` — client-neutral protocol version, groups/actions, field model, bounds, descriptions, and JSON Schema for args. - `cli-surface.json` — the noun/verb tree, CLI summaries, noun prose, and help footers. The berdctl crate embeds these with `include_str!` and builds its clap tree from them at startup. `wire.rs` maps flags back to wire args from the same specs; `validate.rs` and crate tests catch stale artifacts, missing prose, unbuildable flag shapes, and contract/CLI mismatches. ### CLI shape The CLI is generated from the wire field model and stays deliberately simple: `lower_snake_case` fields become `--kebab-case` flags, required wire fields become required flags, optional fields may be omitted, and numeric bounds come from zod. Shapes the generic CLI can't express safely (e.g. explicit null) are modeled as separate explicit actions rather than Rust-side exceptions — for example, `session move --project-id ` moves a session into a project, while `session clear-project` is the distinct action for moving it out of any project. ### Help Help is treated as product surface, authored in the command module rather than generated prose: `registry.ts`'s `cli.about` for noun lines, each command's `summary`/`description`/`helpFooter`, `.describe()` on every field, and top-level help/exit-code text in `tree.rs`. Tests fail on empty/TODO prose and on stale rendered-help pins; error remediation belongs in error messages, not generic help text. ### Safety model v1 has **no auth tokens and no confirmation dialogs**. This is only acceptable while mutations remain visible in the UI and are either reversible or are direct, explicitly-requested product actions (e.g. creating a session, sending a prompt). Required command properties: - Destructive work requires an explicit caller opt-in and must remain visible in the app. - No invisible non-read mutations. - Mutations are visible immediately or discoverable in normal app UI. - One-way verbs are limited to visible product actions the caller explicitly asked for. - The broker protects app availability with in-flight caps and timeouts. Delete, bulk, silent, invisible, or broadly destructive verbs require reopening the auth/confirmation design before implementation — a visible command may expose narrowly scoped destructive behavior only through an explicit flag that names the loss and defaults to refusal; interactive prompts or piecemeal auth are not acceptable substitutes added in a command PR. ### Versioning The broker writes a discovery file containing `protocolVersion`, generation, and port; the CLI verifies it via `/v1/ping` before making calls. Breaking wire reshapes must bump all three of: `src-tauri/plugins/berdctl/src/discovery.rs`, `src-tauri/crates/berdctl/src/discovery.rs`, and `src/features/berdctl/commands/contract.ts`. Tests only assert the three constants are equal to each other — they do **not** automatically detect breaking surface changes; reviewers must identify reshapes and require the bump. Adding a command or an optional field is not considered a wire reshape. ## Key Parameters | Property | Enforced by | |---|---| | Contract artifacts fresh | `pnpm generate:berdctl-contract --check`, `just check` | | Descriptor import purity | `contractImport.test.ts` (node) | | Every action strict-parses and has fixtures | `commands.test.ts` | | Bounds live in schemas | `bounds.test.ts` plus generated contract diff | | Help fields complete | generator + `validate.rs` | | clap tree matches CLI surface | berdctl crate tests | | wire mapping matches CLI surface | berdctl crate tests | | protocol constants equal | berdctl crate + plugin crate tests | | rendered help reviewed | inline `EXPECTED_*_HELP` pins | | broker command-agnostic | `broker_source_stays_free_of_command_literals` | | safety metadata complete | berdctl command tests | Review-only (not automatically enforced): single renderer dispatch point, detecting breaking wire reshapes, and product judgment for no-auth command eligibility. ## When To Use Use this page to understand how the Berd desktop app, its bundled control CLI, and the app's product surfaces relate at a systems level — especially before adding or changing a `berdctl` command, or when deciding whether a new mutation needs the "destructive opt-in" treatment. For the higher-level product shape and design-system rules that the renderer's UI (and therefore berdctl's visibility guarantees) must honor, see `PRODUCT.md`'s design principles ("show operational truth plainly") referenced in [[concepts/berd-overview]]. ## Risks & Pitfalls - The CLI's own flag validation is "convenience only" — it is not the security boundary. Any same-user process can bypass the CLI and POST straight to the broker, so real policy must live in the renderer registry, not the CLI. - The no-auth, no-confirmation-dialog safety model is conditional, not permanent: it only holds while every mutation stays visible-and-reversible or is a direct explicit user action. Adding a delete/bulk/silent verb without reopening the auth design is explicitly disallowed. - Wire-reshape detection is not fully automated — the three-constant-equality tests only catch drift between the constants, not whether a given change actually constitutes a breaking reshape. This is called out as a review-only responsibility. - Broker code must stay free of command-specific literals; adding "just one" command noun or verb into the broker violates the transport-only layering rule. ## Related Concepts - [[concepts/berd-overview]] — the overall Tauri/React + Goose ACP shape that berdctl sits inside - [[concepts/bb-cli-and-berdctl]] — the separate `bb`/`agent-tools` CLI surface, for contrast - [[concepts/composable-capabilities]] — how the renderer's own product surfaces are composed, which berdctl commands ultimately mutate ## Sources - raw/github_doc-docs-berdctl-architecture-md.md - raw/github_doc-readme-md.md - raw/github_doc-product-md.md - raw/github_doc-bb-cli-readme-md.md - raw/github_release-berd-v0-6-2.md --- title: "bb-cli and the bb / berdctl Command Surfaces" type: concept tags: [cli, auth, developer] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-bb-cli-readme-md.md", "raw/github_doc-bb-cli-docs-bb-auth-flow-md.md", "raw/github_doc-bb-cli-docs-bb-auth-local-testing-md.md", "raw/github_doc-docs-berdctl-architecture-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: high berd_version: "v0.6.2" --- ## Definition `bb-cli` is a Rust package inside the `berd` repo that builds two distinct CLI binaries for BuilderBot/kgoose workflows: `agent-tools` (exposed as the `sq agent-tools` command, described in [[concepts/sq-integration]]) and `bb`, the BuilderBot CLI used for skills-marketplace operations and `bb tools`. `bb` is not the same thing as `berdctl` — `berdctl` is the app-bundled CLI that agents use to control the running Berd desktop app itself (see [[concepts/architecture]]), while `bb` is BuilderBot's own CLI for talking to the kgoose backend (skills, auth, org config). ## How It Works ### Building and running From the `berd` repo root, the Hermit-managed toolchain is activated first: ```bash source ./bin/activate-hermit just bb-cli-build just bb-cli-test just bb-cli-lint ``` From `berd/bb-cli` directly, package-local recipes are also available (`./bin/hermit install rustup just lefthook`, `source ./bin/activate-hermit`, `just setup`), plus the packaged-executable build: ```bash just build-sq just update-extensions-catalog ./sqbin/agent-tools.exoskeleton --describe-commands ``` The `bb` binary is built and run directly with Cargo: ```bash cargo build --locked --bin bb ./target/debug/bb --help ./target/debug/bb skills --help ``` Against a local sibling `../cash-server/kgoose` service, `KGOOSE_BASE_URL` points the CLI at `localhost:8080` using the `--local-dev` flag: ```bash KGOOSE_BASE_URL=http://localhost:8080 ./target/debug/bb --local-dev skills doctor KGOOSE_BASE_URL=http://localhost:8080 ./target/debug/bb --local-dev skills list ``` Non-`--local-dev` `bb` commands that contact kgoose require an org, set via `bb config set org ` or collected interactively by `bb auth login`. This org-routing requirement does **not** apply to `sq agent-tools`. ### Runtime behavior (agent-tools) `agent-tools` sends JSON requests to three Misk gRPC-over-HTTP paths under `squareup.cash.kgoose.api.v3.ToolEndpointService`: `ListExtensions`, `ListTools`, and `CallTool`. When flags are not supplied, the CLI falls back to environment variables: `KGOOSE_BASE_URL`, `KGOOSE_PLAYPEN`, `GOOSEMCP_PLAYPEN`, `KGOOSE_TIMEOUT`, and `STS_ACCESS_TOKEN`. If `STS_ACCESS_TOKEN` is set, it is forwarded as the `x-forwarded-identity-token` header on outbound requests. The installed `sq agent-tools` command targets production (`https://kgoose.sqprod.co`); local/staging/playpen testing uses the direct `./target/debug/agent-tools` binary with `KGOOSE_BASE_URL` and `KGOOSE_PLAYPEN` overrides. ### The `bb auth` flow `bb auth login` is a browser-mediated CLI login. Web and CLI share the same Auth0 login path, but the resulting credentials are typed and delivered differently: 1. The CLI starts a localhost callback server and opens the browser to `/v1/auth/login?type=cli&returnTo=http://127.0.0.1:/callback`. 2. The backend stores an `AuthTransaction` (type=cli, loopback `returnTo`), sets an oauth state cookie, and redirects the browser to Auth0. 3. Auth0 completes login and redirects back to the backend's `/v1/auth/callback` with a code and state. 4. The backend exchanges the code for tokens using the stored PKCE verifier, creates a short-lived one-time exchange code, and redirects the browser to the CLI's localhost callback with that code. 5. The CLI POSTs the code to `/v1/auth/login/exchange`; the backend verifies it is valid, unused, unexpired, and `type=cli`, then creates and returns a CLI session credential. 6. The CLI attaches that credential to subsequent API calls via the `X-BB-Session-Credential` header. Security constraints on this flow, stated directly in the source: - Web sessions are returned as secure cookies and accepted only as cookies. - CLI sessions are returned by the exchange endpoint and accepted only via the `X-BB-Session-Credential` header. - Durable session credentials are never placed in redirect URLs. - The localhost redirect carries only a short-lived, single-use exchange code. - CLI `returnTo` targets must be loopback URLs. ### Local auth testing The critical invariant for local testing is that the browser must hit `/v1/auth/login` and `/v1/auth/callback` on the *same host* that Auth0 redirects to, because kgoose relies on an HttpOnly state cookie between those two requests. Testing against a Kubernetes port-forward uses `localhost:5173` (not `127.0.0.1:5173`, which would not match the registered Auth0 callback URI) forwarded to the pod's dynamic Java app port (not the `8080` health/admin listener): ```bash BB_AUTH_STORAGE=file \ BB_AUTH_STORAGE_FILE="$(pwd)/target/bb-auth-sessions.json" \ KGOOSE_BASE_URL="http://localhost:5173" \ KGOOSE_SERVICE_PATH="/cash-app/goose" \ ./target/debug/bb auth login ``` By default the CLI stores browser auth sessions in the OS keyring; `BB_AUTH_STORAGE=file` (with `BB_AUTH_STORAGE_FILE`) redirects storage to a file for local debugging without touching keyring state. Against staging, `KGOOSE_BASE_URL="https://blockstaging.build"` is used with the public `/api/goose` BFF prefix by default; `KGOOSE_SERVICE_PATH=/cash-app/goose` is only needed when calling kgoose directly (e.g. through the port-forward). Against a playpen, `BB_KGOOSE_PLAYPEN=` routes backend auth requests with a `Baggage: kgoose-builderbot-playpen=` header, and the Chrome extension must be enabled for playpen login so browser requests route through the playpen too. ## Key Parameters - **Env vars (agent-tools):** `KGOOSE_BASE_URL`, `KGOOSE_PLAYPEN`, `GOOSEMCP_PLAYPEN`, `KGOOSE_TIMEOUT`, `STS_ACCESS_TOKEN`. - **Env vars (bb auth testing):** `BB_AUTH_STORAGE`, `BB_AUTH_STORAGE_FILE`, `KGOOSE_SERVICE_PATH`, `BB_KGOOSE_PLAYPEN`. - **Org requirement:** non-local-dev `bb` commands need `bb config set org ` (or interactive `bb auth login`); `sq agent-tools` is exempt. - **BLOX auto-routing:** when `KGOOSE_BASE_URL` is unset in `blox`, `IS_BLOX=true` with `BLOX_ENVIRONMENT=production`/`staging` routes automatically to `http://kgoose.cashappservices.com` or the staging equivalent. - **Project layout:** `src/kgoose.rs` (ToolEndpoint client/HTTP models), `extensions.yaml` (checked-in root catalog), `src/catalog.rs`, `src/cli.rs`, `src/runtime.rs`, `src/proto.rs`. ## When To Use Reach for this page when working on `bb`/`agent-tools` builds, wiring up `bb auth login` in a new environment (local port-forward, staging, or playpen), or debugging why the browser-mediated login isn't completing. For questions about the *desktop app's own* control-plane CLI, see [[concepts/architecture]] instead. ## Risks & Pitfalls - Host mismatch breaks local auth testing: the browser must hit the exact host Auth0 is configured to redirect to (`localhost:5173`, not `127.0.0.1:5173`). - Forwarding the wrong port breaks the flow: forward to the pod's dynamic Java app port, not the `8080` health/admin listener. - Never log callback query strings, cookies, or returned session credentials — this is called out explicitly as a rule, not a suggestion. - The `extensions.yaml` root catalog is checked in and cached; it does not update itself when kgoose's live `ListExtensions` response changes — it must be refreshed with `just update-extensions-catalog` or `cargo run -- --write-extensions extensions.yaml`, with generated summaries manually cleaned up before shipping. - Org routing rules differ between `bb` and `sq agent-tools` — assuming they're symmetric (e.g. expecting `bb config set org` to matter for `agent-tools`) will lead to confusion. ## Related Concepts - [[concepts/architecture]] — how `berdctl` (the desktop-app control CLI) differs from `bb-cli`, and how the two fit into the wider app - [[concepts/sq-integration]] — how `agent-tools` is exposed as `sq agent-tools` - [[concepts/security-and-telemetry]] — the project's broader security-reporting posture ## Sources - raw/github_doc-bb-cli-readme-md.md - raw/github_doc-bb-cli-docs-bb-auth-flow-md.md - raw/github_doc-bb-cli-docs-bb-auth-local-testing-md.md - raw/github_doc-docs-berdctl-architecture-md.md - raw/github_release-berd-v0-6-2.md --- title: "Berd Overview" type: concept tags: [overview, product] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-readme-md.md", "raw/github_doc-product-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: high berd_version: "v0.6.2" --- ## Definition Berd is an open-source desktop app, built by a small team at Block, for working with AI agents. It packages a persistent "agent workspace" as a standalone application: users start chats, attach files or folders, choose agents and models, work inside projects, manage skills and extensions, review session history, configure providers, and build automations, all without losing the thread of the workspace. The product's job, as stated in `PRODUCT.md`, is "to make agent work feel grounded, inspectable, and continuous." ## How It Works Technically, Berd is built with Tauri 2 and React 19, and it talks to the upstream Goose backend over the ACP WebSocket protocol served by a `goose serve` sidecar. This split — a Tauri/React desktop shell in front of a separately-versioned Goose agent backend — is what makes Berd model-agnostic in practice: the desktop app is a work surface, and the Goose backend underneath handles agent execution against whatever provider and model the user has configured. The public repository builds a general-purpose distribution that is fully self-contained (no private package registries or enterprise credentials required). Organizations can also produce **enterprise distributions** by supplying their own managed provider settings, private resources, and release infrastructure through the repository's distribution seams, without adding private material to the public source tree. Two related extension points support this: - An **optional companion CLI** distribution seam — the public app does not require a private CLI package, but enterprise distributors can package their own implementation while keeping the normal Berd build and validation flow. - Vendored dependencies such as `@aaif/goose-sdk` and a pinned Goose backend, tracked via `goose-backend.lock.json`, so `just setup` / `just dev` reproduce a known-good backend build (or allow an explicit local override via `GOOSE_BIN`). Berd also publishes portable **Agent Skills** under `skills/` that can be installed independently of the Berd app itself (for example, `buzz-handoff`, which brings Buzz channel/thread context into a private agent conversation). ## Key Parameters - **Backend coupling**: pinned via `goose-backend.lock.json`; `GOOSE_BIN` env var allows a local override for testing an upstream Goose binary. - **Users/audience**: engineers, product designers, and other builders doing real work with AI agents inside a desktop workspace — people who move between broad product thinking and concrete implementation (per `PRODUCT.md`). - **Brand personality**: "Focused, capable, companionable" — a calm, practical daily-use tool that respects expert users without being cold, and makes low-configuration states feel approachable rather than broken. - **Distribution model**: single public source tree; enterprise variants are overlays (managed providers, private resources, release/signing infrastructure), not forks with private code mixed in. - **Build commands**: `just setup`, `just dev`, `just bundle`, `just check`, `just test`, `just tauri-check`, `just clippy`. ## When To Use Berd is the right frame of reference whenever the work is about the desktop chat/work client itself — its packaging, its relationship to the Goose backend, its distribution model, or its target users — rather than about a specific subsystem. For subsystem-level detail, see the sibling concept pages: [[concepts/composable-capabilities]] for how product surfaces are built, [[concepts/operating-laws]] for the behavioral invariants that govern chat and agents, and [[concepts/product-and-design]] for the design system and assistive-UX layer. ## Risks & Pitfalls - Anti-references called out explicitly in `PRODUCT.md`: Berd should not feel like "a generic chatbot wrapper, a dark terminal skin, a dashboard stuffed with metrics, or a marketing site wearing product chrome," and should avoid "novelty-first AI visuals, vague 'assistant magic' copy," or becoming "a pile of disconnected settings pages." - Contribution model is restrictive: Berd is open in the sense that anyone can read the source, build it, and fork it — but the project does **not** accept pull requests from outside authorized repository collaborators, and outside PRs are closed automatically. The intended path to participate is filing a well-formed issue per `CONTRIBUTING.md`. - Because the Goose backend is version-pinned, mismatches between an ad hoc `GOOSE_BIN` override and the app's expectations are an explicit, named failure mode: `just dev` "fails if the lockfile commit no longer matches the cached build" unless the override is used deliberately. ## Related Concepts - [[concepts/composable-capabilities]] - [[concepts/operating-laws]] - [[concepts/product-and-design]] - [[concepts/governance]] ## Sources - raw/github_doc-readme-md.md - raw/github_doc-product-md.md - raw/github_release-berd-v0-6-2.md --- title: "Composable Capabilities" type: concept tags: [capabilities, architecture, product] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-docs-composable-capabilities-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: medium berd_version: "v0.6.2" --- ## Definition Composable capabilities is Berd's architecture direction for building product surfaces that serve both beginners and pro engineers without forking a separate hard-coded screen for every workflow. Instead of each screen reimplementing its own version of shared product behavior, a **capability** is a reusable product unit — a bundle of data needs, states, actions, and render modes — that any number of composed **views** can assemble. As the docs put it: "Views compose capabilities. Capabilities own product behavior. Shared UI owns visual primitives. APIs own side effects. The registry describes what exists; it does not own runtime state." ## How It Works The architecture is a layered stack: ```text design-system primitives down to feature-owned capabilities down to composed product views and surfaces ``` Vocabulary that disambiguates the model: | Term | Meaning | Example | | --- | --- | --- | | Component | Mostly visual UI; does not own workflow logic | Button, dialog, tabs, empty state | | Capability | A reusable product unit bundling data needs, actions, states, render modes | Terminal, conversation composer, pull request summary | | Capability registry | A thin app-level catalog of capability contracts/entry points (not a state store) | `terminal` descriptor | | View | A composed screen/panel/workflow made from capabilities | Chat view, home, PR inbox | | Surface | A place or density where a capability can appear | Bottom dock, right rail, floating panel, home pill | | Render mode | A capability-owned way to render for a given surface/density | `bottomDock`, `floating`, `rightRail` | | Control policy | Explicit availability for optional controls in a render mode | Model picker visible/hidden | | API | The boundary to Tauri, ACP, GitHub, local storage, external services | Start a terminal, submit a message | | Model | Product rules/state definitions not tied to a visual layout | Terminal tab rules, composer disabled states | `Feature` and `capability` answer different questions: **feature = who owns the code**, **capability = what reusable product behavior that code offers**. A product area (e.g. "the terminal") can be both — the terminal capability's code still lives in `src/features/terminal/`. Recommended feature folder shape for new/actively-touched areas: ```text src/features// api/ side effects and service boundaries model/ domain types, state rules, filters, derived status hooks/ data loading, mutations, controller hooks ui/ reusable feature UI pieces capabilities/ behavior bundles and render-mode entry points views/ team-authored composed screens and panels ``` Ownership boundaries are strict: shared UI (`src/shared/ui`) must not know about product domains (no `PullRequestReviewButton` there); feature folders own the source of truth for their domain and expose capabilities/UI to others; capabilities own data needs, states, actions, and render modes but not the entire app layout or unrelated neighboring panels; views are opinionated about arrangement but must not duplicate capability behavior. A capability can be reused **across** feature boundaries too — e.g. a pull-request review workspace composing a chat capability inside its view via chat's public exports, without the PR feature reaching into private chat hooks or copying chat session logic. Before registering or reusing a capability, the **Capability Contract** should be answered: what product concept it models, what data/context it needs, what actions it performs, what states it handles (loading, empty, error, disabled, permission, etc.), what render modes it supports, which controls are optional, what owns side effects, and what should stay view-specific. ## Key Parameters - **Registry**: a thin, static TypeScript metadata catalog (`src/app/capabilities/{types.ts,registry.ts}`) that lists what capabilities exist, who owns them, required context, supported render modes, and exposed states/actions — explicitly **not** a runtime state store and not a plugin framework. - **Render modes**: named layout/density variants of the same capability (e.g. `TerminalBottomDock`, `TerminalFloatingPanel`, `TerminalRightRailTile`; or `home`, `chatFooter`, `agentBuilder` for the conversation composer). - **Control policy**: named, explicit visibility/enablement of optional controls per render mode (e.g. `modelPicker: hidden`), preferred over long lists of unstructured booleans like `showModelPicker`, `showVoice`, etc. - **Naming**: capability names use the simplest durable product noun a designer/user would say (`Terminal`, `Conversation Composer`, `Session List`), not implementation-shaped names (`Chat Footer Composer Module`); registry ids are short product nouns (`terminal`) or dotted only when a feature exposes multiple distinct capabilities (`terminal.runningIndicator`). - **Current pilot**: the Terminal capability, chosen because its own feature request is about flexible placement (bottom dock first, then floating panel, then right rail/bento). ## When To Use Apply the capability decision test before coding a new or touched product area. Strong candidates: the same behavior is needed in more than one view or likely surface; a screen is becoming a bundle of unrelated responsibilities; the feature needs multiple render densities or placements; logic is being copied between pages/panels/chat/home/agent-builder; the behavior has meaningful product states beyond simple display; a future user-composed workspace would reasonably want this unit; the request is about moving, docking, reusing, or reconfiguring a tool; the concept can be named without referencing its current screen location. Probably not yet a capability: used only once and still changing quickly; the only reuse is visual styling (belongs in shared UI); the contract is speculative; the extracted unit can't be named as a durable product concept. Migration is meant to be incremental — "when a feature request touches a product area, ask whether that product area should be shaped as a composable capability as part of the work" — not a rewrite. ## Risks & Pitfalls - Letting the registry become a second app state system: it "should not own open terminal tabs... composer drafts... current session runtime," and should not become a plugin framework "before the product needs one." - Extracting a capability from speculative requirements rather than real, grounded surface needs — the docs explicitly flag "the contract is speculative and not grounded in a real surface need" as a sign something is not ready to become a capability. - Letting render-mode adapters invent separate workflows instead of sharing the same capability contract ("The adapter decides visual density and chrome; it should not invent a separate workflow"). - Cross-feature composition done wrong: reaching into another feature's private hooks, copying its session logic, or mutating its state through undocumented helpers, instead of using its public capability entry point. - Over-migrating: pausing feature work to migrate the whole app into capabilities, or doing "large rewrites whose only goal is matching this folder shape," both explicitly discouraged. ## Related Concepts - [[concepts/berd-overview]] - [[concepts/product-and-design]] - [[concepts/operating-laws]] ## Sources - raw/github_doc-docs-composable-capabilities-md.md - raw/github_release-berd-v0-6-2.md --- title: "Governance" type: concept tags: [governance, product] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-governance-md.md", "raw/github_doc-readme-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: low berd_version: "v0.6.2" --- ## Definition Berd does not define its own project governance model in-repo. `GOVERNANCE.md` in the Berd repository is a single pointer: "[Click here for Block Open Source Project governance information](https://github.com/block/.github/blob/main/GOVERNANCE.md)." Berd's governance is therefore inherited from Block's org-wide open-source governance policy rather than specified per-project. ## How It Works The mirrored raw source (`raw/github_doc-governance-md.md`) contains only this redirect link and no inline governance content, so the specific rules of that org-wide policy (maintainer structure, decision-making process, escalation paths, etc.) are **not** captured in this knowledge base's raw sources and cannot be stated here with confidence. What the raw sources do establish, from `README.md`, is the practical, observable shape of how outside participation is handled day to day, which functions as Berd's de facto contribution governance even though it is not itself labeled "governance": - Berd is built by a small team at Block, in the open: anyone can read the source, build it, and fork it freely. - The project explicitly does **not** accept pull requests from outside authorized repository collaborators; outside PRs are closed automatically. - The sanctioned path for outside participation is filing a well-formed issue. A reproducible bug report is treated as worth more than a patch, "because it's the part we can't do ourselves." `CONTRIBUTING.md` and the repository's issue forms specify what each kind of issue needs. - Contributors/users are pointed to a `CODE_OF_CONDUCT.md` and a `SECURITY.md`, with an explicit instruction never to report a security vulnerability as a public issue. ## Key Parameters - **Governance source of truth**: external, at `github.com/block/.github/blob/main/GOVERNANCE.md` (Block org-wide policy) — not mirrored into this KB's raw/ sources. - **Contribution model**: issues yes, external PRs no (auto-closed). - **Adjacent policy documents referenced but not mirrored in raw/**: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md` (note: `raw/github_doc-security-md.md` exists in this KB's raw set but was out of scope for this page and not read for it). ## When To Use Use this page only to record that Berd's authoritative governance policy lives outside the repository, and to describe the observable contribution mechanics (issues over PRs). Do not use this page as a substitute for reading Block's actual org-wide `GOVERNANCE.md` if a question requires specifics like maintainer roles, voting, or escalation — those are not sourced here. ## Risks & Pitfalls - **Unsourced claim / gap**: the actual content of Block's org-wide governance policy (maintainer roles, decision rights, escalation, project lifecycle rules) is not available in this KB's raw/ mirrors — only the redirect link is. Any statement about the specifics of that policy would be speculation and is deliberately omitted here. - Mistaking "open source, readable and forkable" for "open contribution": Berd is source-available and forkable but structurally closed to outside PRs, which is a governance-relevant distinction worth not conflating. - Reporting a security vulnerability as a public GitHub issue — the README explicitly warns against this, though the security-specific process itself is documented in `SECURITY.md`, which was not read for this page. ## Related Concepts - [[concepts/berd-overview]] ## Sources - raw/github_doc-governance-md.md - raw/github_doc-readme-md.md - raw/github_release-berd-v0-6-2.md --- title: "Operating Laws" type: concept tags: [laws, architecture, product] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-laws-readme-md.md", "raw/github_doc-laws-agents-md.md", "raw/github_doc-laws-chat-md.md", "raw/github_doc-product-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: high berd_version: "v0.6.2" --- ## Definition Berd's "LAWS" are a directory (`LAWS/`) of **architectural laws**: written statements of required product and user-experience behavior that are the source of truth for what the product does, independent of how the current implementation happens to be structured. They exist so that durable product invariants — the boundaries that should remain authoritative as feature designs change — are written down and normatively enforceable, rather than left implicit in code that could drift. ## How It Works Laws use RFC 2119 / BCP 14 normative language: the words **MUST** and **MUST NOT**, when written in all capitals, carry their formal meaning. `LAWS/README.md` sets out the rules for what may be written as a law: - Laws MUST describe behavior that is observable in the product. - Laws MUST specify product or UX behavior, not implementation details. - Laws MUST express deliberately established, durable product invariants or boundaries meant to remain authoritative as feature designs change. - Feature requirements, workflows, fields, formats, and other changeable feature policy MUST NOT be written as laws merely because they are observable or settled. - A law candidate MUST NOT be added unless the product explicitly chooses to canonize it as an enduring constraint. - Each law MUST state one requirement, using MUST/MUST NOT, and MUST be concise and independently understandable. - Code and tests MUST conform to the laws. - Product decisions that are not settled MUST NOT be written as laws. Process requirement: agents and contributors MUST read the relevant law files before planning, implementing, or reviewing behavior changes. Pull requests that change observable behavior MUST identify the affected laws and MUST update code, tests, or laws so they agree — i.e., laws and implementation are kept in sync deliberately, not left to diverge. Two law files currently populate concrete rules: **`LAWS/AGENTS.md` — Invoking agents** contains one law: an agent MUST have a configured provider and model before it can be invoked. This is a minimal but load-bearing invariant given Berd's model-agnostic design (see [[concepts/berd-overview]]): the app supports many providers/models, but an agent can never run in an unconfigured, ambiguous state. **`LAWS/CHAT.md` — Composer queues and session dispatch** is much larger and governs how the chat composer queues and dispatches messages to a session. Its rules cluster into: - *Queue acceptance and dispatch*: every accepted composer message MUST be queued into the selected chat's queue, in acceptance order, even before that chat's session is ready; the queue retains the most recently accepted message/persona intent; a queue MUST NOT dispatch a message before every message ahead of it, and a session must be "ready" (able to begin processing the queue's first message) before dispatch; when a session becomes ready, its queue MUST resume dispatching. - *Dispatch outcomes*: a queue MUST NOT dequeue a message before the session begins processing it; user removal affects only the selected message; dispatch MUST NOT create more than one user turn (including after a failed dispatch); a failed dispatch MUST leave the message first in the queue; no second copy may be dispatched while the first is unresolved; a dispatch outcome MUST NOT change any other queued message. - *Queue editing and removal*: editing a queued message MUST NOT change its position; removal MUST NOT reorder remaining messages; cancelling an edit MUST leave the message unchanged; dispatching a message MUST NOT alter text entered later in the composer. - *Queue steering* (jumping a message from queue to session early): a message not first in the queue MUST NOT be steered; a steering outcome MUST NOT change any other queued message; while a session is running, an empty-composer shortcut MUST steer the first queued message when steering is available; a composer shortcut MUST NOT steer while the composer has draft text or a queued message is being edited. - *Session activity presentation*: subagent activity MUST appear in the chat transcript with the subagent identity and delegated task when known. ## Key Parameters - **Directory**: `LAWS/` at the repo root; `LAWS/README.md` (meta-rules for laws), `LAWS/AGENTS.md` (agent invocation), `LAWS/CHAT.md` (composer/queue/dispatch). - **Normative keywords**: MUST / MUST NOT (RFC 2119 / BCP 14), binding only when fully capitalized. - **Granularity**: one requirement per law statement — laws are deliberately atomic and independently understandable rather than bundled into paragraphs of policy. - **Enforcement coupling**: PRs that change observable behavior must identify affected laws and reconcile code, tests, and law text. ## When To Use Read the relevant `LAWS/` files before planning, implementing, or reviewing any change to agent invocation or chat composer/queue/session-dispatch behavior — this is a stated requirement, not just good practice. Treat a law as the tie-breaker when an implementation detail and a law text disagree: code MUST conform to the law, so either the code is wrong or the law needs to be deliberately amended (not silently outrun by new feature work). Use the laws to distinguish durable invariants (e.g., "one queued message dispatches at a time") from ordinary, changeable feature policy (e.g., specific queue UI copy or field names), which should NOT be promoted to law status. ## Risks & Pitfalls - Writing feature policy as if it were law: the rules explicitly forbid this ("MUST NOT be written as laws merely because they are observable or settled"), since it would freeze normal product iteration. - Letting code drift from a law without updating either — the README's requirement that PRs "identify the affected laws and MUST update the code, tests, or laws so they agree" implies this is a real failure mode the process is designed to catch. - Treating lowercase "must"/"shall" language as normative — only all-caps MUST/MUST NOT carry RFC 2119 force per the stated convention. - Missing the queue-integrity invariants in `LAWS/CHAT.md` when touching composer or dispatch code — e.g., accidentally allowing more than one user turn from a single dispatch, or allowing steering of a non-first queued message, both explicitly prohibited. ## Related Concepts - [[concepts/berd-overview]] - [[concepts/composable-capabilities]] - [[concepts/product-and-design]] ## Sources - raw/github_doc-laws-readme-md.md - raw/github_doc-laws-agents-md.md - raw/github_doc-laws-chat-md.md - raw/github_doc-product-md.md - raw/github_release-berd-v0-6-2.md --- title: "Product and Design" type: concept tags: [design, product, capabilities] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-design-md.md", "raw/github_doc-docs-assistive-ux-md.md", "raw/github_doc-product-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: high berd_version: "v0.6.2" --- ## Definition Berd's product design combines a documented visual design system (creative north star: "The Grounded Workbench") with an "Assistive UX" pattern for adaptive, in-product guidance. Together they operationalize the product principles set out in `PRODUCT.md`: making context legible, keeping the work surface quiet, treating configuration as part of the workflow, showing operational truth plainly, and designing for continuity across sessions and projects. ## How It Works **Design system.** `DESIGN.md` documents Berd's actual design-system tokens (backed by `src/shared/styles/globals.css` and `src/shared/ui/`), not an aspirational spec. It defines a semantic token system (`--primary`, `--card`, `--muted`, `--destructive`, `--success`, `--info`, `--warning`, `--border`, `--ring`, etc.) consumed through Tailwind-facing utility classes (`text-foreground`, `bg-card`, `border-border`). Named rules govern how tokens are used: the **Token Contract Rule** (use existing variables/aliases, don't invent friendly alias tokens like "ink" or "paper"), the **Theme Provider Rule** (light/dark, density, and primary-color override only — not a full runtime token generator), the **Raw-CSS Token Rule** (pseudo-elements and filters consume tokens directly via `var()` rather than through `@theme inline`), the **State Color Rule** (red/green/blue/yellow communicate status only, never decoration), and the **Neutral Migration Rule** (no new raw `#ffffff`/`#000000` outside the token layer). Typography uses self-hosted Inter (`font-sans`/`font-display`) and Geist Mono (`font-mono`) — Cash Sans is explicitly excluded because it is proprietary and this is an externally distributed product. A five-step corner-radius scale (`rounded-xs` 6px through `rounded-lg` 24px, plus `rounded-full`) nests concentrically, with one deliberate exception: `rounded-composer` (40px) is reserved for the chat composer, the app's "signature component," and must not be reused elsewhere. Elevation follows a **Flat First Rule** (most surfaces are flat at rest; shadows appear on hover/popovers/dialogs) and a **No Glass Rule** (translucent glass is reserved for floating chrome — top bar, nav panes, right rail, global composer pill — not for contained panels/cards). Component guidance treats the chat composer as the surface earning the most craft: max width `max-w-3xl`, centered, with attachments, persona/skills selection, text entry, toolbar, voice, send/stop, and context usage all visible without becoming "a control panel." The Automations feature UI is explicitly excluded as design precedent because it "did not receive the same craft pass." **Assistive UX.** This is the architecture pattern for moments where Berd adapts to the user: teaching that a control exists, suggesting a better default, or changing a setting once there's strong evidence the user wants that behavior. It defines three escalating types: - **Discover** — teaches that a control/setting/capability exists; small, temporary, easy to ignore; never changes settings itself; retires when clicked, when the related setting changes, or after enough exposures. - **Suggest** — notices a repeated behavior and asks before changing a setting; applies only after explicit acceptance; avoids repeated prompting after dismissal. - **Auto Apply** — changes a setting after strong behavioral evidence, then explains what changed and offers undo; requires a stronger signal threshold than suggest, touches only reversible/local preferences, and must never touch secrets, credentials, permissions, destructive actions, provider setup, or billing-like behavior. Every assistive rule has an explicit lifecycle: Eligible → Shown → Accepted / Dismissed → Retired, with a separate Applied → Undone path for auto-apply. Architecturally, assistive state lives under one shared umbrella (recommended shape: `src/shared/assistive-ux/{registry.ts, state.ts, runtime.ts, signals.ts}`, with renderer-local storage namespaced `goose:assistive-ux`), kept strictly separate from the actual user settings it may read or set: "A setting answers, 'what does the user want the product to do?' Assistive state answers, 'what has the app already taught, suggested, observed, accepted, retired, or applied?'" Assistive UX may read a setting or call its public setter after acceptance, but must never store its own state inside the setting object, hide settings behind guidance-only logic, or become a source of truth for product behavior. A manual settings change by the user should usually retire or reset related assistive UX, since it's strong evidence the user already understands the control. ## Key Parameters - **Design tokens**: semantic color tokens (primary/card/muted/destructive/success/info/warning/border/ring), a 5-step radius scale, a small shadow vocabulary (`--shadow-mini` through `--shadow-modal`), and typography roles (display/headline/title/body/label/mono). - **Assistive UX types**: `discover`, `suggest`, `autoApply` — ordered by increasing evidence threshold and increasing risk of the change being surprising. - **Assistive UX state shape**: `version`, `moments` (by id: type, shownCount, acceptedAt, retiredAt, retiredReason, lastShownAt), `signals` (by id: counters, lastObservedAt), `applied` (by id: appliedAt, undoAvailable, reason) — explicitly coarse behavior counts, never chat text, file paths, or provider secrets. - **Product principles** (`PRODUCT.md`): context legibility, quiet work surface, configuration-as-workflow, honest operational state, continuity across sessions/projects. - **Brand personality**: "Focused, capable, companionable." ## When To Use Reach for the design-system rules whenever adding or changing any visual surface — pick the Tailwind-facing token/class, radius step, or shadow token from the documented vocabulary before inventing a new one, and change the design system itself (`globals.css`, `src/shared/ui/`) first if something is genuinely missing. Reach for Assistive UX specifically when a feature wants to teach a user something, recommend a setting change based on observed behavior, or auto-adjust a low-risk local preference — and pick the type (`discover`/`suggest`/`autoApply`) based on how strong the behavioral evidence is and how reversible/low-risk the change is. ## Risks & Pitfalls - Design anti-patterns explicitly named in both `PRODUCT.md` and `DESIGN.md`: generic chatbot wrapper, dark terminal skin, metrics-stuffed dashboard, marketing site wearing product chrome, novelty-first AI visuals, oversized decorative cards, vague "assistant magic" copy, side-stripe borders, gradient text, decorative glassmorphism, hero-metric templates, identical card grids, modal-first UX, and a settings area that becomes "a pile of disconnected pages." - Reusing the composer's exclusive `rounded-composer` (40px) radius elsewhere, or nesting cards (`DESIGN.md` says "never nest cards"). - Using the Automations UI as a source for new visual decisions — explicitly disallowed ("The No Automations Precedent Rule"). - Assistive UX becoming "nagging UX": failing to define retirement conditions, over-triggering `discover` moments, or applying `suggest`/`autoApply` changes without enough evidence. - Auto Apply overreaching into secrets, credentials, permissions, destructive actions, provider setup, or billing-like behavior — explicitly prohibited regardless of signal strength. - Blurring the assistive-state/settings boundary: storing assistive bookkeeping inside the setting object itself, or letting assistive state become a source of truth for product behavior instead of a record of what guidance has already happened. ## Related Concepts - [[concepts/berd-overview]] - [[concepts/composable-capabilities]] - [[concepts/operating-laws]] ## Sources - raw/github_doc-design-md.md - raw/github_doc-docs-assistive-ux-md.md - raw/github_doc-product-md.md - raw/github_release-berd-v0-6-2.md --- title: "Release and Auto-Update, and Windows Onboarding" type: concept tags: [ops, architecture, developer] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-docs-release-and-updates-md.md", "raw/github_doc-docs-windows-onboarding-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: high berd_version: "v0.6.2" --- ## Definition Berd ships releases and delivers updates through [Tauri's updater plugin](https://v2.tauri.app/plugin/updater/). Today only the public macOS build is fully live: it uses a GitHub release feed and an Ed25519 verification key. Windows and Linux release artifacts are built and staged at every release, but their updater is intentionally **disabled** until those platforms are approved for automatic distribution; local, custom, and other distributor builds also disable updates unless the distributor supplies a complete, trusted updater profile of their own. Separately, `docs/windows-onboarding.md` documents a **native Windows dev-app verification lane** — not the installer/update path above, but the flow for building and running Berd natively on Windows for development. ## How It Works ### The trust contract The updater endpoint and its verification key form one trust contract. `scripts/release/build-tauri-release-config.mjs` requires an explicit `BERD_RELEASE_CHANNEL`; any *enabled* profile requires both `BERD_UPDATER_ENDPOINT` and `BERD_UPDATER_PUBLIC_KEY`, enforces credential-free HTTPS, and never falls back to another channel. Disabled builds carry no updater endpoint, key, or plugin registration at all. ### Feed and assets Tag-bound release defaults live in `scripts/release/release-channel.json`; the release workflow narrows its promotion copy to only the platforms currently approved for automatic distribution. The rolling updater endpoint is `https://github.com/block/berd/releases/download/berd-desktop-latest/latest.json`, and the always-current macOS installer is `https://github.com/block/berd/releases/download/berd-desktop-latest/Berd-latest-darwin-aarch64.dmg`. Public releases must be at least `0.6.0-rc.1`; the app, bundled `berdctl`, internal `tauri-plugin-berdctl`, their Cargo lock entries, and the changelog are all validated at the immutable tag before GitHub creates the release. A version `X.Y.Z` publishes architecture-qualified assets across all three platforms — macOS (`.app.zip`, `.dmg`, `.app.tar.gz` + `.sig` + `.sha256`), Windows (`-setup.exe`, `-setup.nsis.zip` + `.sig` + `.sha256`), and Linux (`.AppImage`, `.deb`, `.AppImage.tar.gz` + `.sig` + `.sha256`) — but the **updater manifest currently contains only `darwin-aarch64`**. Windows and Linux artifacts are attached to the versioned release for manual testing only; they are not copied into the rolling updater release and do not gate promotion. ### Release flow 1. `just release-prepare X.Y.Z` generates and prints release notes, requires explicit approval, creates `release/vX.Y.Z`, synchronizes every release version and Cargo lock entry, updates `CHANGELOG.md`, validates, commits, pushes, and opens a PR. Prerelease notes start from the latest release tag; stable notes start from the latest *stable* tag so they cover the full release cycle. 2. The release PR is reviewed and squash-merged. 3. `just release-publish X.Y.Z` resolves the PR's squash-merge commit, verifies the committed release state, creates an annotated tag on that exact commit, and pushes only `refs/tags/vX.Y.Z`. 4. The workflow verifies the checkout and the canonical remote tag resolve to the same main-reachable commit, and that the tag is annotated. 5. It creates (or safely resumes) an immutable versioned GitHub release using the matching `CHANGELOG.md` section. 6. Independent platform jobs build the macOS app/DMG, the Windows NSIS installer, and Linux AppImage/deb packages. Windows and Linux compile with `BERD_RELEASE_CHANNEL=disabled` so manual test installs never query a feed that omits their platform. 7. The macOS signing action signs, notarizes, and staples its artifacts. The Windows NSIS installer and Linux packages are published **without** platform-native code signatures. 8. Each platform produces a minisign-signed updater archive, a SHA-256 digest, and an attested source-bound provenance receipt — minisign authenticates the Windows and Linux updater archives even though their enclosed payloads have no platform-native signature. 9. Promotion waits for macOS staging and approval in the GitHub `release` environment, then re-downloads and re-verifies the immutable macOS payload. Windows and Linux continue independently and may finish before or after promotion. Promotion rejects version downgrades and changed same-version manifests, and rechecks the rolling manifest immediately before publishing. 10. The unchanged tag-bound promotion script is given a temporary macOS-only channel configuration; it uploads the macOS payload, then uploads `latest.json` **last**. Uploading the manifest last is deliberate: it keeps installed clients on the previous release if staging or verification fails anywhere upstream. Rollback is handled as a new, higher-patch release containing reverted code — never a lower manifest version. ### Re-enabling Windows or Linux auto-update A platform must not be added to the manifest until its installer behavior and release posture are approved. Re-enabling requires updating `.github/workflows/release.yml` and its contract test together: flip that platform's `BERD_RELEASE_CHANNEL` to `public`, restore `BERD_UPDATER_ENDPOINT`, move `BERD_UPDATER_PUBLIC_KEY` from the packaging step back into the job environment, restore the public-key preflight step (and, for Linux, set `VITE_UPDATER_ENABLED=true` — the Windows bundle script derives its renderer gate from `BERD_RELEASE_CHANNEL` instead); add the platform job to `promote.needs`/`promote.if`; verify with `verify-versioned-release.sh` before promotion; add the platform ID to the temporary `.platforms` array passed to `promote-updater.sh` (removed once every platform in `release-channel.json` is approved); and exercise an install/update from a prior build before confirming the rolling archive and manifest entry are anonymously downloadable. The rolling feed must be anonymously downloadable *before* the first promotion — not possible while the release repository is private. ### Manual recovery Recovery is limited to the same immutable tag and source: ```bash gh workflow run release.yml \ --repo block/berd \ --ref v1.2.3 \ -f tag=v1.2.3 ``` A complete platform payload is reused as-is; an incomplete one is deleted as a unit and rebuilt. Promotion reverifies every platform selected for the rolling feed. ### Downstream distributions Berd keeps build/bundle mechanics CI-neutral: a downstream distribution checks out a reviewed Berd revision, supplies its own updater and runtime configuration, invokes the normal builders, and then owns its own signing and publication. Custom macOS builds use `BUILD_KIND=custom` with `BERD_RELEASE_CHANNEL=disabled`; `scripts/release/build-macos.sh` validates their configuration, stamps the suffixed version, stages resources, and builds the unsigned app — distribution-specific orchestration and artifact destinations live outside this repository. ### GitHub repository setup `block/berd` requires a `release` environment that mandates maintainer review, prevents self-approval, and allows deployments only from `v*` tags, configured with the `BERD_UPDATER_PUBLIC_KEY`, `TAURI_SIGNING_PRIVATE_KEY`, `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`, `OSX_CODESIGN_ROLE`, and `CODESIGN_S3_BUCKET` secrets. `v*` is protected by paired rulesets: one restricts tag *creation* to release maintainers; the other, with no bypass, blocks tag updates, deletion, and force changes. ### Windows onboarding (native dev-app lane) This lane is for **native Windows dev-app verification only** — it does not replace the Mac/Hermit flow and does not build a Windows installer. Its first milestone is: install/diagnose native Windows prerequisites, verify npm/pnpm access, build the pinned Goose backend natively, and launch the real Tauri dev app with `just dev-windows`. **Native Berd provider sign-in is intentionally deferred on Windows** — both the app and `doctor-windows` report this as a known gap. A fresh machine needs two seed installs before the repeatable `just` entrypoint works: `winget install --id Casey.Just -e` and, if needed, `winget install --id Git.Git -e` (a fresh PowerShell may be required afterward for `PATH` to pick them up). From the repo root: ```powershell just bootstrap-windows # check-only, prints exact remediation just bootstrap-windows install # installs missing prereqs via WinGet, may prompt once for admin (VS Build Tools) just doctor-windows # verify readiness just setup-windows # install deps, build vendored SDK, install hooks, build pinned Goose backend just dev-windows # launch native Tauri dev app ``` Bootstrap installs/validates: Git and Git Bash, Visual Studio Build Tools with MSVC C++ tools, Microsoft Edge WebView2 Runtime, the Rust MSVC toolchain pinned by `rust-toolchain.toml`, `fnm`/Node/Corepack/`pnpm@10.33.0`, CMake, LLVM/libclang, jq, Python, Lefthook, and `just` itself. It does **not** create or mutate npm registry/TLS configuration — registry mirrors, proxies, or custom CAs must be configured through normal Node/npm tooling first, and TLS verification must never be bypassed with `strict-ssl=false`. `just setup-windows` clones and builds the Goose backend pinned by `goose-backend.lock.json`; managed state lands in `%LOCALAPPDATA%\berd-dev\goose`, `%LOCALAPPDATA%\berd-dev\cargo-target`, and `%LOCALAPPDATA%\berd-dev\stamp.json` (the stamp records repo, ref, commit, Cargo package, binary name, and resolved `goose.exe` path — re-running setup reuses the build when those still match). `just dev-windows` launches native Tauri dev mode using Windows-native paths for the managed `goose.exe` and the built `berdctl.exe`; **the `bb` CLI resource is not staged on Windows**, because the app currently only maps and resolves `bb` on macOS. Additional validation commands: `just tauri-check-windows` (Windows-native Rust/Tauri checks with external sidecars disabled) and `just test-windows-dev` (focused Windows script/stamp/cleanup tests). Cleanup is dry-run by default (`just cleanup-windows`); actual removal requires `remove -Yes` for Berd-local caches/artifacts (root `node_modules`, `.pnpm-store`, `dist`, `sdk\node_modules`, `sdk\dist`, Lefthook hooks), a second acknowledgment `-YesShared` for anything touching machine-shared tooling, `-IncludeNodeState` for Corepack/fnm/npm-global-pnpm state, `-IncludeSharedTools` for rustup/fnm/CMake/LLVM/jq/Python/just/Lefthook (Git is deliberately retained), and a separate explicit `-IncludeWebView2` because the WebView2 Runtime is shared OS-level infrastructure used by Teams, Outlook, and other apps. ## Key Parameters | File | Role | |---|---| | `scripts/release/release-channel.json` | Repository, rolling tag, and tag-bound platform defaults | | `scripts/release/build-tauri-release-config.mjs` | Fail-closed updater profile overlay | | `scripts/release/package-signed-updater{,-windows,-linux}.sh` | Per-platform updater archive, signature, digest | | `scripts/release/verify-updater-signature.sh` | Verifies updater signatures against the embedded key | | `scripts/release/generate-latest-json.sh` | Validates and creates the updater manifest | | `scripts/release/validate-manifest-promotion.mjs` | Enforces monotonic, idempotent rolling-manifest publication | | `.github/workflows/release.yml` | Tag/recovery staging and approval-gated promotion | | `src/features/updates/hooks/UpdaterProvider.tsx` | Update check/download/install/restart state | | `src-tauri/src/lib.rs` | Registers the updater only when configured | - **Windows prerequisite versions:** `pnpm@10.33.0`; Rust MSVC toolchain per `rust-toolchain.toml`. - **Managed Goose state (Windows):** `%LOCALAPPDATA%\berd-dev\{goose,cargo-target,stamp.json}`. ## When To Use Use this page when preparing or reviewing a release, deciding whether Windows/Linux auto-update can be turned on, debugging why an update did or didn't land, or bringing up a native Windows dev environment for the first time. ## Risks & Pitfalls - The Windows NSIS installer and Linux packages ship without platform-native code signatures — only minisign authenticates their updater archives; an "unsigned publisher" warning on Windows install is expected, not a bug. - Do not add a platform to the updater manifest before its installer behavior and release posture are formally approved — this is a repeated, explicit instruction, not a soft preference. - The rolling feed must be anonymously downloadable before the *first* promotion, which is impossible while the release repository stays private — a real current blocker on turning on Windows/Linux auto-update. - **External contributors cannot currently complete `doctor-windows` or `setup-windows` on a fresh machine**: the checked-in Windows scripts still validate a legacy organization-specific npm mirror, and this guide intentionally does not publish that private configuration. The documented workaround is to track the GitHub issue or use the supported macOS/Hermit flow instead. - Native Berd provider sign-in is deferred on Windows — a single warning from `doctor-windows` about this is expected and does not indicate a broken setup. - The `bb` CLI resource is not staged in the Windows dev app build at all (macOS-only today) — code or tests that assume `bb` is available on Windows dev builds will fail. ## Related Concepts - [[concepts/security-and-telemetry]] — the Ed25519/minisign signing model that underpins updater trust - [[concepts/architecture]] — `berdctl.exe` is one of the two Windows-native binaries `just dev-windows` launches - [[concepts/bb-cli-and-berdctl]] — the `bb` CLI surface not yet staged on Windows ## Sources - raw/github_doc-docs-release-and-updates-md.md - raw/github_doc-docs-windows-onboarding-md.md - raw/github_release-berd-v0-6-2.md --- title: "Security Posture and Telemetry" type: concept tags: [ops, product, user] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-security-md.md", "raw/github_doc-telemetry-md.md", "raw/github_doc-readme-md.md", "raw/github_doc-docs-release-and-updates-md.md", "raw/github_doc-bb-cli-docs-bb-auth-flow-md.md", "raw/github_doc-bb-cli-docs-bb-auth-local-testing-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: medium berd_version: "v0.6.2" --- ## Definition Berd's security and telemetry posture is documented across two very short root-level files, `SECURITY.md` and `TELEMETRY.md`. `SECURITY.md` is not a berd-specific policy at all — it is a single-line pointer to [Block's org-wide open source security policy](https://github.com/block/.github/blob/main/SECURITY.md). `TELEMETRY.md` defines an explicit, opt-in telemetry model: telemetry is disabled by default in official Berd distributions, and what it collects (and excludes) when a user turns it on is spelled out precisely. ## How It Works ### Vulnerability reporting `SECURITY.md`'s entire content is a link to Block's shared, organization-wide security policy — berd inherits Block's general vulnerability-handling process rather than defining its own. Separately, the README is explicit that **a security vulnerability should never be reported as a public GitHub issue**; ordinary bug reports go through the normal issue-filing workflow described in `CONTRIBUTING.md`, but security issues are carved out from that path entirely. ### Telemetry Telemetry is **disabled by default** in official Berd distributions. If a user enables it, Block collects: - a random installation identifier, and - a limited set of predefined usage events, used "to operate and improve Berd." Telemetry explicitly **excludes** prompts, messages, files, source code, credentials, names, emails, and IP addresses as *collected telemetry fields* — with one carve-out: Block and its service providers do process IP addresses for transmission, security, and rate-limiting purposes, which is a normal side effect of running any networked service rather than part of the telemetry payload itself. Users can disable telemetry at any time in Berd's settings. Block's privacy practices and user rights are documented separately in the [Berd Privacy Notice](https://berd.xyz/sites/berd/privacy.html). Third-party distributions or forks may modify, remove, or redirect the telemetry feature entirely and may follow different data practices — the guarantees in `TELEMETRY.md` apply only to official Berd distributions, and anyone running a fork or third-party build needs to check that distributor's own documentation and source. ## Key Parameters - **Default state:** telemetry off in official builds (opt-in, not opt-out). - **Collected (if enabled):** random install ID, limited predefined usage events. - **Excluded from telemetry:** prompts, messages, files, source code, credentials, names, emails, IP addresses (with the IP-processing carve-out noted above for transmission/security/rate-limiting). - **User control:** toggle in Berd's settings, at any time. - **Scope of the policy:** official Berd distributions only — forks/third-party distributions are explicitly out of scope. - **Security reports:** never a public GitHub issue; follow Block's linked org-wide security policy instead. ## When To Use Reach for this page when answering a user's question about what Berd collects, when deciding how a fork's telemetry behavior should be documented, or when someone needs to know where to report a security vulnerability (as opposed to a normal bug). ## Risks & Pitfalls - `SECURITY.md` gives no berd-specific detail — anyone expecting a berd-specific CVE process, disclosure timeline, or contact address inside the `berd` repo itself will not find one; it is entirely inherited from Block's org-wide default. - The "excludes IP addresses" claim in `TELEMETRY.md` is not absolute: Block and its service providers still process IP addresses for transmission, security, and rate-limiting. Treating this as "Berd never sees your IP" would overstate the policy. - Because forks/third-party distributions can freely modify or redirect telemetry, the guarantees in this page do not automatically carry over to a downstream or enterprise distribution — that distributor's own docs and source are the source of truth for such a build, per [[concepts/berd-overview]]'s enterprise-distribution model. - The release pipeline's signing/notarization/minisign infrastructure (see [[concepts/release-and-updates]]) is a meaningfully large part of Berd's actual security posture in practice, even though it is documented separately from `SECURITY.md` — a reader looking only at `SECURITY.md` would miss it entirely. ## Related Concepts - [[concepts/release-and-updates]] — the Ed25519/minisign signing and notarization pipeline that is a de facto part of Berd's security model - [[concepts/bb-cli-and-berdctl]] — the `bb auth` flow's own explicit security constraints (session-credential handling, no logging of secrets) - [[concepts/berd-overview]] — the enterprise-distribution model that telemetry/security guarantees do not automatically extend to ## Sources - raw/github_doc-security-md.md - raw/github_doc-telemetry-md.md - raw/github_doc-readme-md.md - raw/github_doc-docs-release-and-updates-md.md - raw/github_doc-bb-cli-docs-bb-auth-flow-md.md - raw/github_doc-bb-cli-docs-bb-auth-local-testing-md.md - raw/github_release-berd-v0-6-2.md --- title: "sq Integration" type: concept tags: [cli, architecture, developer] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_doc-bb-cli-docs-sq-overview-md.md", "raw/github_doc-bb-cli-docs-sq-integration-md.md", "raw/github_doc-bb-cli-readme-md.md", "raw/github_release-berd-v0-6-2.md"] confidence: high berd_version: "v0.6.2" --- ## Definition `sq` is Block's Common Toolchain: a CLI framework, in the spirit of [oclif](https://oclif.io/) or [Cobra](https://github.com/spf13/cobra), built on [exoskeleton](https://github.com/square/exoskeleton). It provides a single, consistent entrypoint — menus, help pages, tab-completion, suggestions, on-demand install/auto-update, and usage/reliability/performance instrumentation — for a long tail of otherwise-independent CLIs at Block. `sq` is preinstalled on Block laptops; elsewhere it installs via `brew install square/formula/sq`. Within `berd`, `bb-cli`'s `agent-tools` binary is packaged and shipped specifically as the `sq agent-tools` subcommand (see [[concepts/bb-cli-and-berdctl]]). ## How It Works ### What makes sq different Unlike other CLI frameworks, `sq`'s subcommands are not objects inside a single TypeScript or Go program — each subcommand is a standalone, separate executable living in a predictable location. That lets each subcommand be implemented in a different language and released on its own schedule. ### Discovery `sq` finds a subcommand executable (e.g. `cowsay`) by searching, in order: 1. `./sqbin` in the current working directory or any ancestor directory 2. `/opt/homebrew/etc/sqbin` 3. `/usr/local/etc/sqbin` For `sq mysql pull`-style nested commands, subdirectories plus a `.sq-module` magic-comment file define a menu of nested commands. ### Two ways to integrate a command - **Simple commands** (including shell scripts): respond to `--summary` and `--help` flags, or — for shell scripts — include `# SUMMARY:` and `# HELP:` magic comments right after the shebang. - **Subcommand trees**: name the executable with a `.exoskeleton` extension and make it respond to `--describe-commands` by printing JSON describing the tool's command structure to stdout. `sq util` is the framework's own example of this pattern. `agent-tools` uses the second pattern: the packaged `sq` binary is `sqbin/agent-tools.exoskeleton`, and `agent-tools --describe-commands` describes its extension/tool tree. `bb-cli`'s README documents a **static extension catalog** for root discovery (checked-in `extensions.yaml`), with live tool metadata loaded only once a specific extension is selected — `sq agent-tools --help` lists extensions, `sq agent-tools --help` lists that extension's tools, and `sq agent-tools --help` lists that tool's arguments. The catalog is refreshed with `just update-extensions-catalog` or `cargo run -- --write-extensions extensions.yaml`; when a sibling `../g2` checkout is present, the `just` recipe also merges G2 connection config/descriptions so extensions such as `block-uid`, `asana`, and `todoist` still appear in the static catalog even if missing from the live response. ### Metadata `sq` tracks five pieces of metadata per command/module: **name** (required), **summary** (required, ≤80 chars), **help** (required), **version** (optional, X.Y.Z), and **formula** (optional, the Homebrew formula used for update checks and metrics). Commands installed via Homebrew have version/formula extracted from their keg automatically. ### Conventions - **SUMMARY**: under 80 characters, a single sentence, no trailing period, starting with an imperative verb (`ssh Connect to services...`, not `ssh Connects to...` or `ssh This lets you connect to...`). - **HELP**: each section gets its own all-caps heading (rendered bold white by `sq`) and 3-space-multiple indentation; `USAGE` is always first, `OPTIONS` documents flags if applicable, `EXAMPLES` is included, and `SUPPORT` — naming a Slack channel and optionally a PR-welcoming repo — is always last. ### Completions `sq` supports tab-completion on command names natively. For argument/flag completion, `sq` invokes the target command with `--complete -- `; the command writes newline-separated suggestions to stdout followed by a `:`-prefixed [shellcomp directive](https://github.com/square/exoskeleton/tree/main/pkg/shellcomp). A nonzero exit or unparsable output tells the shell to skip completion entirely. Go projects can import `github.com/square/exoskeleton/pkg/shellcomp` directly. ### Metrics `sq` automatically collects usage metrics (failure rate/exit-code breakdown, daily active users/stickiness, CSAT via `@csat-bot`) per command, viewable in a Looker dashboard filtered by command name. A CLI can add custom labels by writing `LABELS \n` to the named pipe identified by the `SQ_METRICS_PIPE` environment variable that `sq` sets when invoking the subcommand. ### Distributing a pack The recommended project layout puts executables under `./sqbin` (shell scripts or compiled binaries), which gives a better local-dev loop (since `sq` discovers `./sqbin` first) and lets the Homebrew formula be minimal — just `(prefix/"etc").install "sqbin"`. Multiple executables are grouped into a subdirectory with a `.sq-module` file to form a named menu (e.g. `sq sentry search`, `sq sentry events`, with `sq sentry` as the menu). ### Best practices: exit codes `sq`'s dashboards get more value out of [semantic exit codes](https://github.com/square/exit/#the-codes) than the default crash=1/success=0 pattern — e.g. exit `80` (Usage Error) for invalid user input, or exit `101` (Unavailable) when an upstream API returns `503`/`504`. ## Key Parameters - **Discovery path order:** `./sqbin` (cwd or ancestors) → `/opt/homebrew/etc/sqbin` → `/usr/local/etc/sqbin`. - **`agent-tools` production target:** `https://kgoose.sqprod.co`. - **`agent-tools` env overrides for local/staging/playpen:** `KGOOSE_BASE_URL`, `KGOOSE_PLAYPEN` (see [[concepts/bb-cli-and-berdctl]]). - **Catalog refresh commands:** `just update-extensions-catalog`, `cargo run -- --write-extensions extensions.yaml`. - **Metrics pipe:** `SQ_METRICS_PIPE` env var, `LABELS`-prefixed messages. ## When To Use Reach for this page when working out why an `agent-tools` extension or tool isn't showing up under `sq agent-tools`, when writing SUMMARY/HELP text for a new sq-integrated command, or when explaining to someone unfamiliar with Block's tooling why `berd`'s `agent-tools` binary is invoked as `sq agent-tools ...` rather than run directly. ## Risks & Pitfalls - `sq` caches the root `--describe-commands` output, so `extensions.yaml` must be refreshed manually with `just update-extensions-catalog` (or `cargo run -- --write-extensions extensions.yaml`) whenever the live extension set changes — generated summaries then need manual cleanup before shipping, per the `bb-cli` README. - An extension present only in `../g2` (not in the live `ListExtensions` response) will silently disappear from the static root catalog unless the G2 checkout is present when the catalog is regenerated. - SUMMARY text that ends in a period, isn't imperative, or exceeds ~80 characters violates the documented `sq` convention and will look inconsistent in `sq`'s command menu. - A `--complete` implementation that exits nonzero or emits unparsable output silently disables completion for that command rather than erroring loudly. ## Related Concepts - [[concepts/bb-cli-and-berdctl]] — how `agent-tools` is built and packaged as `sqbin/agent-tools.exoskeleton` - [[concepts/architecture]] — the separate, unrelated `berdctl` CLI that controls the Berd desktop app directly (not sq-integrated) ## Sources - raw/github_doc-bb-cli-docs-sq-overview-md.md - raw/github_doc-bb-cli-docs-sq-integration-md.md - raw/github_doc-bb-cli-readme-md.md - raw/github_release-berd-v0-6-2.md # Change Log ## 2026-08-24 — Initial build Built from the block/berd repo docs + 7 release mirrors. berd is Block's open-source desktop app for getting work done with any model (model-agnostic client + bb/berdctl CLI), built on Tauri + React + Goose. **Pages (11):** 10 concepts + 1 summary (release digest). **Sourcing notes:** - `governance` is **confidence: low** — the repo's GOVERNANCE.md is only a redirect to Block's org-wide governance doc (not mirrored); the page states this gap and covers the observable contribution mechanics from the README instead. `security-and-telemetry` similarly notes SECURITY.md is a one-line pointer to Block's org policy. - Preserved an upstream inconsistency: the v0.6.2 release note's body prose opens "Berd 0.6.1 expands..." (an apparent copy-paste slip in Block's own note); flagged in the release digest rather than silently corrected. - Newest stable release v0.6.2; v0.6.0 was the first open-source release. - No XL tier (small/early project). --- title: "Release Digest: v0.6.0-rc.1 through v0.6.2" type: summary tags: [ops, product] created: 2026-08-24 updated: 2026-08-24 sources: ["raw/github_release-berd-v0-6-0-rc-1.md", "raw/github_release-berd-v0-6-0-rc-2.md", "raw/github_release-berd-v0-6-0-rc-3.md", "raw/github_release-berd-v0-6-0.md", "raw/github_release-berd-v0-6-1.md", "raw/github_release-berd-v0-6-2.md", "raw/github_release-berd-desktop-auto-update.md", "raw/github_doc-docs-release-and-updates-md.md"] confidence: medium berd_version: "v0.6.2" --- ## Key Points - **v0.6.0 (published 2026-08-14) is Berd's first open-source release.** The GitHub release note for it states plainly: "Berd v0.6.0 is out—our first open-source release," describing Berd as bringing "projects, chats, agents, skills, and provider setup into one place, with tools for following and steering agent work." Per `docs/release-and-updates.md` (`raw/github_doc-docs-release-and-updates-md.md`), public releases must be at least `0.6.0-rc.1` — consistent with this being the earliest public release line. - **Release cadence was rapid at first, then landed in short, uneven intervals — not "roughly weekly."** All three release candidates (`rc.1`, `rc.2`, `rc.3`) and the `v0.6.0` stable tag were published within two days of each other (2026-08-13 to 2026-08-14). After that, stable releases came out `v0.6.0` (2026-08-14) → `v0.6.1` (2026-08-17, a 3-day gap) → `v0.6.2` (2026-08-18, a ~1-day gap). Those are the actual intervals; they are shorter and more irregular than "weekly." **Interpretation, not a release-note fact:** combined with the still-0.x version numbers, this pattern is consistent with a project in an active, pre-1.0 stabilization phase, but that reading is this wiki's analysis of the cadence, not something the release notes themselves state. - **rc.1** (2026-08-13): introduced multi-folder project chats (per-Git-folder worktree behavior, with clearer setup prompts/progress/error handling), grouped queued-message improvements (dismissing one no longer unexpectedly sends the next), and an experimental five-step Berdy onboarding tour covering providers, agents, and skills. - **rc.2** (2026-08-13): focused on platform reliability — improved Windows packaging and signed update delivery across Windows and Linux, plus an updated bundled Goose runtime that maintains compatibility with existing ACP extensions. - **rc.3** (2026-08-13): added automatic chat archiving (with a confirmation step, protecting active/running/pinned/draft-bearing chats), clearer subagent activity labeling (delegation, messages, waiting, interruptions, cancellations), and experimental guided starter tasks that jump directly into the relevant workflow. - **v0.6.0 stable** (2026-08-14) rolled the rc changes into GA and added: agent sharing available to everyone (share cards directly from the agent gallery/detail page, no experiment flag needed) and a streamlined sidebar that starts directly with navigation and chats. - **v0.6.1** (2026-08-17): reliable queued messaging (follow-ups auto-send when the agent is ready, even after navigating away; messages wait for new chats to finish starting); cleaner chat controls (no more brief queued-indicator flash on normal sends; empty-composer `Enter` steers the first queued message); safer transcript refreshes (long tool-heavy chats keep accurate scroll/history, and an incomplete reload/compaction preserves the existing transcript with a recoverable error instead of corrupting it); improved agent cards (consistent collectible-card design, avatar-aware colors, motion, editable descriptions, more dependable PNG export); a polished Home canvas; a refined chat context rail; Windows links now open directly in Chrome when available with a reliable default-browser fallback; a refreshed macOS installer with a permanent download link; and a release-metadata compatibility fix so older Berd versions can install future updates without false verification failures. - **v0.6.2** (2026-08-18): expanded the starter-agent collection to seven bundled agents (Agt Builder, Choosey, Copycat, Pushback, Tinker, Wildcard, plus one more), with new Home canvases featuring Tinker and Wildcard while existing layouts stay unchanged; added Slack-friendly agent sharing via downloadable ZIP (preserving instructions and settings, alongside the existing PNG/Markdown export options); reorganized connections into company-managed services vs. local MCPs (for Goose, Claude Code, or Codex) with a shared search and agent-guided setup flow; and made Agent Work details more stable (expanding a previous step no longer jumps the conversation unexpectedly, and long tool details stay compact in a scrollable, keyboard-accessible area). - **Labeling inconsistency in the raw v0.6.2 release note, flagged rather than silently corrected:** the mirror at `raw/github_release-berd-v0-6-2.md` is tagged and titled `v0.6.2` (published 2026-08-18) but its body text opens with "Berd 0.6.1 expands the starter agent collection..." — i.e. the prose references version 0.6.1 even though the tag/title/date metadata is 0.6.2. This looks like a copy-paste artifact in Block's own release notes rather than a mirroring error; the feature list summarized above is attributed to the v0.6.2 tag on the strength of the mirror's tag/title/date frontmatter, not its prose version number. - **`berd-desktop-latest` is not a version, it's the rolling auto-update channel.** Its release note reads only: "Rolling release for the Tauri auto-updater. Use versioned releases for manual downloads." This is the GitHub release tag that `latest.json` (the updater manifest, per `raw/github_doc-docs-release-and-updates-md.md` and referenced in [[concepts/release-and-updates]]) is published against — not a release with its own feature list. - **Every versioned release mirror repeats the same platform-signing caveat**, worded identically across all six versioned releases (`rc.1` through `v0.6.2`): "The Windows NSIS installer and Linux packages lack platform-native code signatures; their updater archives remain minisign-authenticated," consistent with the signing/promotion model documented in `raw/github_doc-docs-release-and-updates-md.md` and [[concepts/release-and-updates]]. - Each versioned release note also carries a `Full Changelog` compare link and a `Source commit` hash tying the note to an exact git commit, matching the immutable-tag release flow described in `raw/github_doc-docs-release-and-updates-md.md` and [[concepts/release-and-updates]]. ## Relevant Concepts - [[concepts/release-and-updates]] — the release/promotion pipeline, signing model, and platform-enablement rules these releases were produced under - [[concepts/security-and-telemetry]] — the minisign/Ed25519 trust model referenced by the repeated signing caveat - [[concepts/berd-overview]] — the product surfaces (projects, chats, agents, skills, providers) these releases iterate on ## Source Metadata | Tag | Published | Source | |---|---|---| | v0.6.0-rc.1 | 2026-08-13T02:00:21Z | raw/github_release-berd-v0-6-0-rc-1.md | | v0.6.0-rc.2 | 2026-08-13T15:39:56Z | raw/github_release-berd-v0-6-0-rc-2.md | | v0.6.0-rc.3 | 2026-08-13T18:49:23Z | raw/github_release-berd-v0-6-0-rc-3.md | | v0.6.0 | 2026-08-14T17:43:12Z | raw/github_release-berd-v0-6-0.md | | v0.6.1 | 2026-08-17T21:54:58Z | raw/github_release-berd-v0-6-1.md | | v0.6.2 | 2026-08-18T15:45:33Z | raw/github_release-berd-v0-6-2.md | | berd-desktop-latest | 2026-08-14T20:01:40Z | raw/github_release-berd-desktop-auto-update.md | All rows are `source_type: github_release` mirrors of `https://github.com/block/berd/releases/tag/`, fetched 2026-08-24. Every versioned row (all but `berd-desktop-latest`) additionally carries a `Source commit` SHA in the raw file body. ## Sources - raw/github_release-berd-v0-6-0-rc-1.md - raw/github_release-berd-v0-6-0-rc-2.md - raw/github_release-berd-v0-6-0-rc-3.md - raw/github_release-berd-v0-6-0.md - raw/github_release-berd-v0-6-1.md - raw/github_release-berd-v0-6-2.md - raw/github_release-berd-desktop-auto-update.md - raw/github_doc-docs-release-and-updates-md.md