Initial migration of BuilderLab CLI from Berd

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,31 +1,31 @@
 ---
-name: 🐛 Bug Report
-about: Thank you for taking the time, please report a reproducible bug
-title: "[Bug] <Bug Title Here>"
+name: Bug report
+about: Report a reproducible problem with BuilderLab CLI
+title: "[Bug]: "
 labels: bug
-assignees: add codeowner's @name here 
-
+assignees: []
 ---
 
-**Describe the bug**
-*A clear and concise description of what the bug is.*
+## Description
+
+<!-- What went wrong? -->
+
+## Reproduction
+
+```text
+# Command(s) to reproduce the problem
+```
+
+## Expected behavior
 
-**To Reproduce:**
-*Steps to reproduce the behavior:*
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+<!-- What did you expect to happen? -->
 
-**Expected behavior:**
-*A clear and concise description of what you expected to happen.*
+## Actual behavior
 
-**Supporting Material**
-*If applicable, add screenshots, output log and/or other documentation to help explain your problem.*
+<!-- Include relevant output. Remove credentials and other sensitive data. -->
 
-**Environment (please complete the following information):**
- - OS: [ex: iOS]
- - Version 
+## Environment
 
-**Additional context**
-Add any other context that you feel is relevant about the problem here.
+- OS:
+- CLI and version (`bl --version` or `sq agent-tools --version`):
+- Installation or build method:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,12 @@
+# The normal GitHub UI does not offer a blank issue: a well-formed issue is the
+# supported way to participate in BuilderLab CLI, so the templates ask for what
+# we need to act on it.
+blank_issues_enabled: false
+
 contact_links:
-    - name: ❓ Questions and Help 🤔
-      url: https://discord.gg/block-opensource (/add your discord channel if applicable)
-      about: This issue tracker is not for support questions. Please refer to the community for more help. 
+  - name: Questions about using BuilderLab CLI
+    url: https://github.com/block/builderlab-cli/blob/main/README.md
+    about: The README covers setup and usage. Use an issue for a reproducible bug or actionable feature request.
+  - name: Security vulnerabilities
+    url: https://github.com/block/builderlab-cli/blob/main/SECURITY.md
+    about: Please report vulnerabilities privately, never as a public issue.

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an improvement to BuilderLab CLI
+title: "[Feature]: "
+labels: enhancement
+assignees: []
+---
+
+## Problem
+
+<!-- What are you trying to accomplish, and what makes it difficult today? -->
+
+## Current workaround
+
+<!-- What do you do today? Say "none" if you have no workaround. -->
+
+## Proposed improvement
+
+<!-- Describe the behavior or outcome you would like. -->
+
+## Alternatives and non-goals
+
+<!-- What alternatives did you consider? What are you explicitly not asking for? -->

.gitignore

@@ -0,0 +1,5 @@
+target/
+sqbin/
+dist/
+.DS_Store
+.hermit

AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md / CLAUDE.md
+
+Instructions for agents working in this standalone CLI repository.
+
+## Workflow
+
+- Never use `--no-verify` unless the user explicitly asks for it.
+- Activate the Hermit environment before running repo commands that depend on managed tooling:
+
+```bash
+source ./bin/activate-hermit
+```
+
+- Install git hooks when setting up the repo locally:
+
+```bash
+lefthook install
+```
+
+## Common Commands
+
+- Build the Rust binary:
+
+```bash
+just build
+```
+
+- Run tests:
+
+```bash
+just test
+```
+
+- Run linting (rustfmt + clippy):
+
+```bash
+just lint
+```
+
+- Run the main verification suite:
+
+```bash
+just check
+```
+
+- Build the `sq` package artifact:
+
+```bash
+just build-sq
+```
+
+- Inspect the CLI surface directly:
+
+```bash
+./target/debug/agent-tools --help
+./target/debug/agent-tools utils calculate --numbers 2 3 --operation add
+```
+
+- Smoke-test the packaged `sq` module and confirm `sq` is using the local `sqbin/` output:
+
+```bash
+just package-smoke
+sq which agent-tools
+sq agent-tools linear --help
+./sqbin/agent-tools.exoskeleton linear --help
+```
+
+`sq which agent-tools` should point at the package-local `sqbin/agent-tools.exoskeleton`. If `sq agent-tools <extension> ...` prints synthesized submenu help instead of the exoskeleton output, compare against `./sqbin/agent-tools.exoskeleton <extension> ...` to distinguish outer `sq` wrapper behavior from `bl-cli` behavior.
+
+## Project Layout
+
+- `src/kgoose.rs` defines the kgoose ToolEndpoint client and re-exports the generated proto request/response types used by the CLI.
+- `src/cli.rs` bootstraps global flags and builds the dynamic clap command tree. Parsing is two-phase: a hand-rolled bootstrap parser strips infrastructure flags and extracts `command_tokens` first, then only the named extension is loaded from the API before building the clap tree. This avoids loading all extensions upfront.
+- `src/runtime.rs` loads extension/tool metadata from the live kgoose API and derives CLI parameters from tool schemas.
+- `src/catalog.rs` manages the static extensions catalog (`extensions.yaml`), embedded at compile time.
+- `src/main.rs` wires help/version output and live ToolEndpoint execution.
+- `src/proto.rs` re-exports the generated prost modules and includes the `pbjson-build` serde impls used for JSON-over-HTTP decoding of proto-backed request/metadata types.
+- `sqbin/agent-tools.exoskeleton` is the packaged executable built by `just build-sq`.
+- `docs/sq-overview.md` covers the repo and packaged CLI at a high level.
+- `docs/sq-integration.md` covers how `sq` discovers and integrates the packaged module.
+- `docs/RELEASING-sq.md` covers the Homebrew-backed `sq` command-pack release path.
+- `docs/RELEASING-bl.md` covers building the `bl` CLI binary consumed by Berd.app.
+
+External docs: https://clig.dev/llms.txt -> guide you can consult to write better command-line programs, taking traditional UNIX principles and updating them for the modern day.
+
+
+## Integration Notes
+
+- This repo is packaged as a single `sq` module named `agent-tools.exoskeleton`.
+- Homebrew packaging should install the entire `sqbin/` directory into `prefix/"etc"` so `sq` can discover the pack.
+- `sq` picks up the repo-local package when `sq which agent-tools` resolves to `sqbin/agent-tools.exoskeleton`.
+- `sq` synthesizes extension submenu help from `--describe-commands` metadata. In practice, extension-level flags such as `sq agent-tools <extension> --help` and `sq agent-tools <extension> --describe` can be intercepted by the outer `sq` wrapper instead of reaching the exoskeleton.
+- To verify exoskeleton-specific extension behavior, prefer `./sqbin/agent-tools.exoskeleton <extension> --help` and `./sqbin/agent-tools.exoskeleton <extension> --describe`, then compare with `sq agent-tools <extension> ...` to identify wrapper behavior.
+- The current CLI talks directly to the kgoose ToolEndpoint JSON-over-HTTP routes and expects `KGOOSE_BASE_URL`, `KGOOSE_PLAYPEN`, or explicit flags when needed. `GOOSEMCP_PLAYPEN` is an independent opt-in that adds an `envoy-route--goosemcp=playpen-<name>` entry to the outbound `Baggage` header for routing the downstream goosemcp Envoy; only set it when a matching playpen pod is running, otherwise extension calls fail with an opaque 5xx.
+- Prefer generated proto types over handwritten mirrors. `tonic_prost_build` generates the prost messages, `extern_path` maps the `google.protobuf` JSON value types to `pbjson_types`, and `pbjson-build` adds serde support for the JSON-over-HTTP endpoints so the Rust types stay aligned with the service protos.
+- `CallToolResponse` is now proto-backed too. `src/main.rs` pretty-prints the typed response envelope directly.
+- The CLI is dynamic at three levels: ListExtensions determines which top-level extensions exist, ListTools determines which tool subcommands exist under each extension, and each tool's schema determines its flags/options.
+- We take a hybrid static/dynamic approach:
+    - **Top-level extensions are static.** `extensions.yaml` is generated from two sources (kGoose ListExtensionsGrpcAction + G2 web app OAuth config for late-init extensions like notion, asana), then manually curated. Run `just update-extensions-catalog` to regenerate. This lets all known extensions appear in `--help` even if the user hasn't connected them yet.
+    - **Extension subcommands are fully dynamic.** ListTools and CallTool hit the live kgoose API. If the user hasn't connected an extension, `--help` for that extension will fail with a "not connected" error pointing to G2 Connections. The static catalog is used only to produce helpful error messages (distinguishing "unknown extension" from "known but not connected").
+    - **`--describe-commands` leaf node is the extension subcommand.** We don't return nested tool commands under an extension, so `sq` forwards args to the extension subcommand directly.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CODEOWNERS

@@ -1,24 +1,9 @@
 # This CODEOWNERS file denotes the project leads
 # and encodes their responsibilities for code review.
 
-# Instructions: At a minimum, replace the '@GITHUB_USER_NAME_GOES_HERE'
-# here with at least one project lead.
-
 # Lines starting with '#' are comments.
 # Each line is a file pattern followed by one or more owners.
 # The format is described: https://github.blog/2017-07-06-introducing-code-owners/
 
 # These owners will be the default owners for everything in the repo.
-*       @jsibbison-square
-
-
-# -----------------------------------------------
-# BELOW THIS LINE ARE TEMPLATES, UNUSED
-# -----------------------------------------------
-# Order is important. The last matching pattern has the most precedence.
-# So if a pull request only touches javascript files, only these owners
-# will be requested to review.
-# *.js    @octocat @github/js
-
-# You can also use email addresses if you prefer.
-# docs/*  docs@example.com
+*       @block/builderlab-oss-team

CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to BuilderLab CLI
+
+BuilderLab CLI is developed by Block in the open. You can inspect the source,
+build it locally, and help us improve it by filing a clear issue or proposing a
+focused change.
+
+## Filing an issue
+
+Open an issue through the [issue chooser](https://github.com/block/builderlab-cli/issues/new/choose).
+Use the bug report template for behavior that does not match the documented
+CLI, and the feature request template for a capability or improvement.
+
+Blank issues are disabled so that reports contain enough information to act on.
+Issues created through the API or other tooling should meet the same standard.
+
+### Using an agent
+
+An agent can help gather version information, reduce logs, and turn notes into
+clear reproduction steps. You are still responsible for the issue: read the
+result before posting it, and never let an agent invent versions, output, or
+other details it did not observe. Write `unknown` when you do not know
+something.
+
+### Before filing
+
+Please:
+
+1. Search open and closed issues and link the closest match, or say that you
+   found none.
+2. Reproduce the problem with the current release or current `main` build.
+3. Keep one problem per issue so it can be triaged and closed cleanly.
+
+### Bug reports
+
+A useful bug report lets a maintainer reproduce the problem without a long
+back-and-forth. Include:
+
+- the exact command and relevant inputs;
+- expected and actual behavior;
+- whether it happens every time or intermittently;
+- the CLI name and exact version;
+- operating system and installation or build method; and
+- the relevant output or log excerpt.
+
+Put output in a fenced code block, include only the relevant lines, and remove
+credentials, tokens, prompts, file paths, and other sensitive information.
+
+### Feature requests
+
+Describe the problem you are trying to solve before proposing a solution.
+Include:
+
+- what you do today and any workaround;
+- why the capability belongs in BuilderLab CLI;
+- what is explicitly out of scope; and
+- alternatives you considered and why they were insufficient.
+
+## What happens next
+
+Issues are triaged on a best-effort basis. A report may be labelled and queued,
+returned for more information, closed as a duplicate, or closed as out of
+scope with an explanation. A closed issue is not a judgment on the person who
+filed it; it records a product decision.
+
+## Security issues
+
+Do not open a public issue for a security vulnerability. Follow the private
+reporting instructions in [SECURITY.md](SECURITY.md).
+
+## Building locally
+
+BuilderLab CLI uses the Hermit-managed toolchain. From the repository root:
+
+```bash
+source ./bin/activate-hermit
+just build
+just test
+just lint
+```
+
+Run the complete local verification suite before submitting a change:
+
+```bash
+just ci
+```
+
+If the repository tools have not been installed yet:
+
+```bash
+./bin/hermit install rustup just lefthook
+source ./bin/activate-hermit
+just setup
+```
+
+See the [README](README.md) for package and CLI usage, and [AGENTS.md](AGENTS.md)
+for repository layout and implementation notes.
+
+## Pull requests
+
+Keep changes focused and explain the user-visible behavior they change. Add or
+update tests and documentation when appropriate. Before requesting review:
+
+- run `just ci`;
+- confirm that generated or packaged artifacts are intentional; and
+- remove local paths, credentials, and unrelated changes from the diff.
+
+The [Block Open Source governance guide](GOVERNANCE.md) also applies to
+participation in this repository.