# Bucky Docs
> Documentation for the Bucky platform, API, and MCP tools.
---
# Introduction
Source: https://docs.buckybuild.com/docs
Bucky is the **pre-development platform** that turns an address into sourced
site intelligence, project analysis, and decision-ready deliverables.
Developers, design-builders, architects, and planning consultants use it to
screen sites, read zoning and feasibility with citations, and carry a project
from first look through entitlement. Homeowners and marketplace professionals
work in the same product on a smaller scale.
These docs are organized around what you do, not who you are:
- **Start a project** — an address, the map, and Project Scout.
- **Read the site** — parcels, zoning, feasibility, and what's cited vs. unverified.
- **Work with the team** — who to add on a project, and when.
- **Connect agents** — the MCP server, the CLI, and the public [OpenAPI document](/docs/api).
## Where to start
Browse by section in the sidebar, or use search (top right) to jump straight to
a page.
## For agents and integrators
Four machine-readable surfaces, each at a stable URL:
- **Bucky MCP server** — Streamable HTTP at `https://buckybuild.com/api/mcp`. Tools for
feasibility, projects, geography, and the marketplace. See [MCP](/docs/mcp), or read the
[server card](https://buckybuild.com/.well-known/mcp/server-card.json) before connecting.
- **Bucky OpenAPI spec** — [`/openapi.json`](https://buckybuild.com/openapi.json), an
OpenAPI 3.1 description of the curated public REST surface under `/api/v1` and
`/api/marketplace/v2`. Every operation carries an `operationId` and a typed error schema,
so it converts directly to LLM function-calling definitions.
- **Bucky CLI** — scripted access to the same product state, with an agent-safe profile. See
[CLI](/docs/cli).
- **Discovery** — [`/.well-known/api-catalog`](https://buckybuild.com/.well-known/api-catalog)
(RFC 9727) indexes all of the above;
[`/AGENTS.md`](https://buckybuild.com/AGENTS.md) and
[`/llms.txt`](https://buckybuild.com/llms.txt) are the prose entry points, and
[`/auth.md`](https://buckybuild.com/auth.md) walks through obtaining credentials.
## When to use these docs
Reach for this site when you are building *against* Bucky: integrating the API or MCP server,
scripting the CLI, or working out how authentication and scopes fit together.
For what Bucky is and who it is for, start at
[buckybuild.com/llms.txt](https://buckybuild.com/llms.txt). For whether a particular city is
covered — coverage is onboarded jurisdiction by jurisdiction, and these docs do not enumerate
it — see [coverage](https://buckybuild.com/en/coverage). For a zoning or feasibility answer
about a real address, call the API: the docs describe the interface, not the data.
---
# API
Source: https://docs.buckybuild.com/docs/api
The public REST contract is a **prepaid site check** plus the two free reads a
developer needs around it. There is no monthly API plan.
Start with the [developer quickstart](/docs/getting-started/developer-quickstart):
load credit, mint a `bk_live_` key at `/settings/developer`, call
`/api/v1/sites/check`, and read the `usage` receipt.
## Priced unit
`POST|GET /api/v1/sites/check` is the **only** metered route. The billable unit
is a sourced result, not a transport call. Uncovered sites return **HTTP 202**
with `answered: false` and a receipt proving `charged: false, reason:
'not_covered'`.
Price: **$0.10 USD** per sourced check. Minimum load: **$10 USD**. A free
account includes 10 site lookups a month, including headless use, so a $10 load
is **110 checks in month one**.
The envelope is `{ schemaVersion, checkId, answered, normalizedAddress,
coverage, parcel, zoning, facts, usage, generatedAt }`. Every priced response
also stamps `X-Bucky-Receipt-*` headers, including 304 and 402.
## Free reads
| Route | Auth | Notes |
| --------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `GET /api/v1/coverage/divisions/{slug}` | Anonymous | Count-only coverage card. Not a coordinate lookup — `/api/geo/coverage-status` already does that. |
| `GET /api/v1/usage/balance` | Session, user JWT, or `usage:read` key | Remaining prepaid balance. A missing account is a zero balance, not a 404. |
| `POST /api/v1/addresses/suggest` | Optional key (`site:read`) | Free. |
| `POST /api/v1/addresses/retrieve` | Optional key (`site:read`) | Free. |
## What a key cannot do
- **`sites/context`** stays session/JWT in M1 — not key-eligible, so callers
cannot arbitrage a free context against a priced check.
- **`sites/resolve`** is first-party only. It persists a `feasibility_sites`
row. A key receives `403 FORBIDDEN`.
- **`feasibility/analyses*`** is first-party only. A key receives `402
SCOPE_UNAVAILABLE` naming the unsold `analysis:write` scope.
- **`research/*`** is denylisted from the public OpenAPI artifact. Those
handlers are admin-only.
## Redaction
`ownershipHint` and `rawCityData` are **never** returned to a key, regardless of
scope. If ownership is ever sold it is a separately-priced `parcel:owner` scope
with its own consent review. See
[`docs/api/public-api-boundary.md`](https://github.com/markbucky/bucky/blob/main/docs/api/public-api-boundary.md).
## Authentication
`Authorization: Bearer bk_live_…` (or `bk_test_…`). Scopes: `site:read`,
`usage:read`. CORS stays off — a key is a server-side credential and must not
ship to a browser. Session cookies and Supabase user JWTs still work on v1;
programmatic JWTs need Professional. Keys skip that subscription gate and debit
prepaid credit.
Match auth errors on `code`: `AUTH_REQUIRED` and `INVALID_API_KEY` are 401;
`INSUFFICIENT_SCOPE` is 403. Details live in
[`docs/api/v1-auth.md`](https://github.com/markbucky/bucky/blob/main/docs/api/v1-auth.md).
## OpenAPI
The machine-readable description is an OpenAPI 3.1 document:
```
https://buckybuild.com/openapi.json
```
The same document is served at `/api/openapi`, and both are advertised as
`service-desc` in [`/.well-known/api-catalog`](https://buckybuild.com/.well-known/api-catalog).
It is a **curated subset** of the internal surface — default-deny — covering
`/api/v1` (site check, coverage, usage, addresses) and `/api/marketplace/v2`.
Every operation carries a unique `operationId`, typed parameters, and a
documented error schema.
## Versioning, errors, and rate limits
- **Versioning** is in the URL path (`/api/v1`, `/api/marketplace/v2`). There is
no unversioned public surface. Within a version, changes are additive only.
Retirement is signalled with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594)
response headers.
- **Errors** return a consistent JSON envelope: `error`, `code`, `category`,
`status`, `retryable`, `supportId`, `requestId`. Match on `code`, never on the
message text.
- **Rate limits** are reported as `RateLimit` and `RateLimit-Policy` alongside
`RateLimit-Limit` / `-Remaining` / `-Reset`. A 429 carries `Retry-After`. The
ledger is the spend bound — do not treat the per-lambda bucket as abuse
control.
## Use this today
- **HTTP** — this page and the [developer quickstart](/docs/getting-started/developer-quickstart).
- **MCP** — tools for agents. See [MCP](/docs/mcp).
- **CLI** — product and scripting workflows. See [CLI](/docs/cli).
Building an integration now? Start with the [developer
quickstart](/docs/getting-started/developer-quickstart). Use [MCP](/docs/mcp) if you are wiring an
AI agent, or the [CLI](/docs/cli) for scripting.
---
# CLI
Source: https://docs.buckybuild.com/docs/cli
Install the latest promoted Bucky CLI release on macOS or Linux:
```bash
curl -fsSL https://raw.githubusercontent.com/markbucky/bucky/main/apps/bucky-cli/install.sh | sh
```
The installer requires Node.js 24 or newer, verifies the release archive's
SHA-256 checksum, and installs without `sudo` under `~/.local/bin`. To inspect
the installer before running it:
```bash
curl -fsSLo install-bucky.sh \
https://raw.githubusercontent.com/markbucky/bucky/main/apps/bucky-cli/install.sh
less install-bucky.sh
sh install-bucky.sh
```
Set `BUCKY_VERSION=` to install a specific promoted version. Running
the installer again updates the CLI. It prints the exact user-local paths to
remove when uninstalling.
The TypeScript `bucky` CLI provides two deliberately separate command groups:
- **Product commands** act as a Bucky user through the existing application APIs.
- **City commands** wrap the reviewed municipality-onboarding scripts for operators.
From a repository checkout:
```bash
pnpm install
pnpm bucky -- --help
pnpm bucky -- doctor
```
`nx build bucky-cli` produces `apps/bucky-cli/dist/bin.js`. The package exposes
that file as the `bucky` binary.
## Agent-friendly output
Pass the global `--json` option before the command for one deterministic
envelope:
```bash
pnpm --silent bucky -- --json capabilities
pnpm --silent bucky -- --json projects list --limit 5
pnpm --silent bucky -- --json city status --city us-il-chicago
```
Successes use `{ "ok": true, "data": ... }`; failures include an error code and
an executable hint. Exit code `0` means success, `1` means a domain violation or
rejected operation, and `2` means invalid input or an infrastructure problem.
The CLI also respects `NO_COLOR` and `BUCKY_NO_TUI`. Human output uses one of
three terminal modes: `machine` (`--json` or piped stdout), `human-interactive`
(both stdin and stdout are TTYs), or `human-static` (CI, `BUCKY_NO_TUI`,
`TERM=dumb`, or non-interactive stdin). JSON and piped stdout never include
prompts, spinners, cursor controls, or ANSI progress frames.
Use pnpm's `--silent` option when consuming JSON from the repository script so
its script banner does not precede the envelope. The installed `bucky` binary
does not need this wrapper option.
Mutating commands support `--dry-run`. A dry run prints the intended HTTP
request or delegated command, a field-level preview, and whether the action is
undoable. It does not execute the mutation.
Non-interactive execution (`--json`, piped stdout, or CI) requires explicit
`--yes` after reviewing the same command with `--dry-run`. Interactive terminals
prompt with `[y/N/edit]` before executing.
Executed mutations write a pending secret-free receipt **before** the first
remote write, then update the same receipt id terminally
(`completed` / `failed` / `cancelled` / `unknown`). Inspect them with
`bucky operations list` and `bucky operations show `. After an
ambiguous project create, resume with
`bucky projects create --retry-operation --yes` (same intent
flags) so the original `Idempotency-Key` is reused. `projects duplicate` and
`programs create` use the same flag. Identical payloads alone never
deduplicate. `bucky undo ` or `bucky undo --last --yes` replays
only inverses recorded on the receipt. `agent-context` reports per-command
`mutation.idempotent` and `mutation.reversible` as machine-readable fields. Chat
turns are not cross-invocation retry-safe.
Human output (without `--json`) is summary-first: one-line outcomes, then
decision-relevant key/value rows or width-aware tables. Pass `--full` before the
command to expand domain payloads, and `--verbose` to include redacted diagnostic
details on errors. Tables adapt to terminal width and fall back to pipe-safe
`column | column` lines on narrow screens. Semantic color is used for success,
warning, and failure states; set `NO_COLOR` or `--no-color` to disable it.
Errors print what happened, a likely cause when known, and an exact safe next
step. Suggested commands from fuzzy discovery may appear for unknown subcommands,
but are never executed automatically.
Output is compact by default to protect agent context windows. Knowledge search
omits large section bodies, project detail omits associations, and reference
lists default to 20 rows. Pass the global `--full` option before the command
when the complete payload is necessary:
```bash
pnpm --silent bucky -- --json --full projects get
pnpm --silent bucky -- --json --full knowledge search --q "front setback"
```
List responses retain pagination metadata. `projects list` and `references list`
accept `--offset` as well as `--limit`. Continue `references list` with the next
`--offset` while `pagination.hasMore` is true.
Network reads and safe idempotent writes retry twice by default (**transport**
retries inside one process). The global `--timeout ` defaults to 120
seconds and covers response headers plus complete JSON bodies. During
`chat turn`, the same value is a stream-idle timeout and resets whenever an
event arrives; `--timeout 0` disables it. Do not wrap the CLI in another retry
loop: writes retry only when they carry an idempotency key. Cross-process
recovery uses `--retry-operation `, not payload similarity.
## Product authentication
Product commands require a real Supabase user JWT. They never open a browser.
The token is read from `BUCKY_ACCESS_TOKEN` first, then from the XDG config file
at `${XDG_CONFIG_HOME:-~/.config}/bucky/config.json`.
The CLI currently signs in existing accounts only. New account registration,
email confirmation, waitlist policy, and signup profile side effects remain in
the Bucky web signup flow.
```bash
bucky --profile agent auth login
bucky --profile agent agent check \
--require projects:read,projects:create,chat:write,knowledge:read
```
Interactive login prompts for the deployment, email, and a hidden password. It
defaults to `https://buckybuild.com`, discovers the deployment's browser-public
Supabase URL and anonymous key, and saves that public configuration in the
selected profile only after authentication succeeds. Remote origins require
HTTPS; loopback HTTP is supported for local development.
### Dedicated agent profile
Named profiles isolate a coding agent's session from a developer's default
login. The `agent` profile is stored at
`${XDG_CONFIG_HOME:-~/.config}/bucky/profiles/agent.json` with user-only file
permissions.
Bootstrap it once without putting the password in shell history:
```bash
bucky --profile agent auth login
pnpm --silent bucky -- --profile agent --json auth status
pnpm --silent bucky -- --profile agent --json agent check \
--require projects:read,projects:create,chat:write,knowledge:read
```
Use a dedicated product user with project-scoped membership. Do not provide the
CLI with a Supabase service-role key or assume platform-admin access.
### Automation and headless login
`--json`, CI, and non-TTY execution never prompt. Set `BUCKY_EMAIL` and
`BUCKY_PASSWORD` for a headless password exchange, or pipe existing access and
refresh tokens to
`--access-token-stdin` or `--refresh-token-stdin`. Secret-valued argv flags remain
available for compatibility but emit a deprecation warning; do not put secrets
in argv.
```bash
BUCKY_EMAIL=user@example.com BUCKY_PASSWORD=... bucky --json auth login
printf %s "$BUCKY_ACCESS_TOKEN" | bucky --json auth login --access-token-stdin
```
When a required value is missing, headless mode returns one
`AUTH_INPUT_MISSING` JSON envelope instead of pausing.
Saved sessions automatically exchange their refresh token when the access token
is about to expire. Tokens supplied through `BUCKY_ACCESS_TOKEN` remain
caller-owned and are never refreshed or persisted.
## Readiness and capability discovery
Prefer `agent-context` for the rich, versioned command introspection document
(arguments, enums, bounds, mutation/confirmation, execution modes). `capabilities`
remains a compatibility projection of the same `CommandSpec` source for one release.
`agent check` verifies the active profile with bounded reads:
```bash
pnpm --silent bucky -- --profile agent --json agent-context
pnpm --silent bucky -- --profile agent --json capabilities
pnpm --silent bucky -- --profile agent --json agent check
pnpm --silent bucky -- --profile agent --json agent check \
--require projects:read,projects:create,chat:write,knowledge:read
```
The accepted `agent check --require` tokens are `projects:read`,
`projects:create`, `chat:write`, and `knowledge:read`. A required write
capability succeeds only when the command is present in the local CLI and the
versioned server readiness endpoint confirms authorization. Each write probe
reports `commandAvailable`, `authenticated`, `reachable`, and `authorized`.
Missing or incompatible server support is `unavailable` and fails closed.
Readiness never creates a project, sends a chat message, initialises credits, or
otherwise mutates product state.
## Discovery and shell completion
Interactive terminals can open a searchable command palette with `bucky` (no
arguments). The palette returns canonical argv for copy/run; it does not execute
mutations. Non-interactive stdout prints five starter examples.
`bucky help` shows bounded contextual suggestions based on your
profile, authentication, readiness, recent projects, and recent conversations.
Each probe is read-only, timed out, and labeled when unavailable. Suggestions
show canonical argv only — they are never executed automatically.
On first interactive run, Bucky walks through profile setup and `auth login`,
then probes readiness. That flow writes only local auth/profile configuration.
```bash
bucky
bucky help
bucky palette
bucky '?' # legacy alias; quote it because ? is a shell glob
bucky chat resume
bucky chat resume
bucky completion zsh > ~/.zsh/completions/_bucky
bucky completion bash >> ~/.bashrc
bucky completion fish > ~/.config/fish/completions/bucky.fish
```
Shell completion uses bounded read-only resolvers for projects, conversations,
reviewed city slugs, and `agent check --require` tokens. JSON and piped stdout
never open the palette.
## Batch writes
Most write commands accept a top-level JSON **array** on `--input`, not just a
single object. One process shares auth and one HTTP client, and writes one
receipt per item plus a run-level summary. Importing 27 sites is five
invocations rather than roughly a hundred.
```bash
bucky --json notes add --input ./notes.json --dry-run
bucky --json notes add --input ./notes.json --yes
bucky --json notes add --input ./notes.json --continue-on-error --yes
```
The bound is **25 items per invocation**, uniform across every batch command and
enforced before any network call. `agent-context` publishes the authoritative
list, each command's `maxItems`, and the `itemKeys` an item may set:
```bash
bucky --json agent-context | jq '.data.commands | with_entries(select(.value.batch)) | keys'
```
### The project positional is optional
Passing `` applies it to every item. Omitting it lets each item
carry its own `projectId`, so **one invocation can span projects**:
```json
[
{ "projectId": "…", "body": "Need a geotech report" },
{ "projectId": "…", "body": "Call the surveyor", "title": "Follow-up" }
]
```
Supplying both a positional and a differing per-item `projectId` is an error
rather than a silent override.
### Failure semantics
Every item is validated before any item is written, so a malformed row at
position 5 fails the run with nothing written. Execution is then sequential and
stops at the first failure unless `--continue-on-error` is passed. A run with
any failure exits `1` with `error.code = BATCH_PARTIAL_FAILURE` and a per-item
breakdown in `error.details.items`, each carrying its own `receiptId`:
```json
{
"batch": true,
"total": 3,
"succeeded": 1,
"failed": 1,
"skipped": 1,
"items": [
{ "index": 0, "status": "succeeded", "receiptId": "…", "resourceId": "…" },
{ "index": 1, "status": "failed", "receiptId": "…", "error": { "code": "HTTP_400" } },
{ "index": 2, "status": "skipped", "reason": "stopped-after-failure" }
]
}
```
### Idempotency on batched creates
`projects create` is auto-keyed. In the array form it refuses
`--retry-operation` and `--idempotency-key`, since each addresses a single
write. Every item instead gets its own key and receipt, and an item may supply
its own `idempotencyKey` — which is what makes re-running an import file safe:
```json
[
{ "name": "North East False Creek", "lat": 49.27, "lng": -123.11, "idempotencyKey": "notion-3715f18b" },
{ "name": "King Street", "idempotencyKey": "notion-0777802a" }
]
```
Commands where a resend would duplicate or has no coherent meaning deliberately
do not batch — `projects create-assembly`, `projects invite`,
`designs set-primary`, `chat turn`, `documents upload`, and the ops-local
`city` / `research` groups.
## Public command reference
Agent-safe inventory (generated from `CommandSpec`; do not edit by hand):
{/* BEGIN GENERATED CLI COMMAND INVENTORY */}
| Command | Kind | Auth | Summary |
| --- | --- | --- | --- |
| `agent check` | read | product | Probe bounded product readiness for agent workflows |
| `agent-context` | read-local | none | Emit the versioned agent-safe command introspection document |
| `amenities list` | read | product | List active amenity ids on a project |
| `amenities set` | write | product | Replace the active amenity set (supports --dry-run) |
| `analysis run` | write | product | Enqueue a fresh project analysis run (supports --dry-run) |
| `analysis show` | read | product | Show current project analysis and agentStatus |
| `analysis wait` | read | product | Poll agentStatus until analysis is current, failed, or none |
| `auth login` | write-local | none | Sign in and persist a profile session |
| `auth logout` | write-local | none | Remove stored credentials for the active profile |
| `auth status` | read-local | none | Show profile, token source, and expiry without a network call |
| `auth whoami` | read | product | Show the authenticated user subject and email |
| `capabilities` | read-local | none | Show this CLI build command and transport contract |
| `chat resume` | read | product | Select a recent conversation and show the canonical continuation argv |
| `chat turn` | write | product | Send one project-scoped chat turn (supports --dry-run) |
| `city ingest` | write | ops-local | Run reviewed city knowledge ingest (supports --dry-run) |
| `city next` | read | ops-local | Show the next onboarding action for a municipality |
| `city status` | read | ops-local | Show municipality onboarding status from geo scripts |
| `completion bash` | read-local | none | Emit a bash completion script |
| `completion fish` | read-local | none | Emit a fish completion script |
| `completion zsh` | read-local | none | Emit a zsh completion script |
| `conversations get` | read | product | Load one conversation with messages |
| `conversations list` | read | product | List conversations for a project |
| `costs add` | write | product | Add or update cost ledger rows (supports --dry-run) |
| `costs review` | write | product | Confirm or reject a proposed cost ledger row (supports --dry-run) |
| `costs show` | read | product | Show the project cost ledger split by review status |
| `coverage get` | read | product | Get one count-only division coverage card |
| `designs add` | write | product | Attach a marketplace design and make it primary (supports --dry-run) |
| `designs clear` | write | product | Soft-delete every attached design (supports --dry-run) |
| `designs list` | read | product | List designs attached to a project |
| `designs remove` | write | product | Soft-delete one attached design (supports --dry-run) |
| `designs set-primary` | write | product | Make an attached design the primary (supports --dry-run) |
| `doctor` | read | none | Check local CLI configuration and connectivity |
| `documents delete` | write | product | Delete a project document and its stored file (supports --dry-run) |
| `documents download` | read | product | Download a project document to a local file |
| `documents intelligence` | read | product | Show stored document intelligence (brief, facts, questions) |
| `documents list` | read | product | List project documents (metadata only) |
| `documents search` | read | product | Answer a question from the project documents with cited excerpts |
| `documents update` | write | product | Update project document metadata (supports --dry-run) |
| `documents upload` | write | product | Upload a local file into a project (supports --dry-run) |
| `evidence datasets` | read | product | List evidence dataset summaries for a project |
| `evidence interpret` | write | product | Interpret one evidence record (bounded; supports --dry-run) |
| `evidence interpret-batch` | write | product | Interpret up to 10 evidence records in one call (bounded; supports --dry-run) |
| `evidence list` | read | product | List project evidence substrate records |
| `evidence refresh` | write | product | Refresh one evidence dataset or family (bounded; supports --dry-run) |
| `evidence save` | write | product | Promote an evidence record from candidate to saved (supports --dry-run) |
| `evidence unsave` | write | product | Demote a saved evidence record back to candidate (supports --dry-run) |
| `financing add` | write | product | Add a financing source (supports --dry-run) |
| `financing list` | read | product | List project financing sources |
| `financing options` | read | product | List funding-program evaluations for a project |
| `financing package` | read | product | Download a funding-program package as HTML |
| `financing remove` | write | product | Remove a financing source (supports --dry-run) |
| `financing update` | write | product | Update a financing source (supports --dry-run) |
| `geo resolve` | read | product | Resolve an address to coordinates, its geo division and that division's coverage |
| `help` | read-local | none | Show bounded contextual suggestions for your profile and state |
| `knowledge search` | read | product | Search zoning and product knowledge |
| `notes add` | write | product | Create a project note (supports --dry-run) |
| `notes apply-suggestion` | write | product | Apply or dismiss a stored note suggestion (bounded; supports --dry-run) |
| `notes delete` | write | product | Delete a project note (supports --dry-run) |
| `notes list` | read | product | List project notes |
| `notes regenerate-title` | write | product | Regenerate a note title from its body (bounded; supports --dry-run) |
| `notes update` | write | product | Update a project note (supports --dry-run) |
| `operations list` | read-local | none | List secret-free mutation receipts for the active profile |
| `operations show` | read-local | none | Show one mutation receipt by id |
| `opportunities compare` | read | product | Compare 2–4 assessments from one run on normalized features |
| `opportunities inspect` | read | product | Show one assessment with its evidence references and recorded outcomes |
| `opportunities list` | read | product | List recent opportunity runs |
| `opportunities review` | write | product | Record an observed pursue/pass decision on one assessment (supports --dry-run) |
| `opportunities screen` | write | product | Run one bounded live opportunity discovery and persist the run (supports --dry-run) |
| `opportunities show` | read | product | Show one opportunity run with its brief and ranked assessments |
| `parcels deal` | write | product | Set deal tracking — status, notes and money — on one attached parcel (supports --dry-run) |
| `parcels detach` | write | product | Remove a parcel from a project assemblage (supports --dry-run) |
| `parcels list` | read | product | List a project's attached parcels with their deal tracking |
| `parcels search` | read | product | List parcels near a point for land assembly |
| `parcels set-role` | write | product | Change an attached parcel between build and context (supports --dry-run) |
| `programs calculate` | write | product | Run the development-program engine, optionally persisting a snapshot |
| `programs create` | write | product | Create a development program on a project (supports --dry-run) |
| `programs list` | read | product | List development programs for a project |
| `programs select` | write | product | Make one development program the selected scenario (supports --dry-run) |
| `programs sync-costs` | write | product | Push the selected program's latest snapshot into the cost ledger (supports --dry-run) |
| `programs update` | write | product | Update an existing development program (supports --dry-run) |
| `programs zoning-context` | read | product | Show the zoning facts a program for one explicit use would be built against |
| `projects archive` | write | product | Soft-cancel a project (supports --dry-run) |
| `projects attach-parcels` | write | product | Attach additional parcels to an existing project (supports --dry-run) |
| `projects clear-location` | write | product | Clear a project's location (supports --dry-run) |
| `projects create` | write | product | Create a project (supports --dry-run) |
| `projects create-assembly` | write | product | Create a multi-parcel land assembly project (supports --dry-run) |
| `projects duplicate` | write | product | Duplicate a project with its location and parcels (supports --dry-run) |
| `projects get` | read | product | Get one project by id |
| `projects invite` | write | product | Invite a person to a project by email (supports --dry-run) |
| `projects list` | read | product | List accessible projects with bounded pagination |
| `projects location` | read | product | Show the project location and geo FK tree |
| `projects set-location` | write | product | Set or repair a project location and resolve geo FKs (supports --dry-run) |
| `projects update` | write | product | Update project fields (supports --dry-run) |
| `references add` | write | product | Attach a knowledge section to a project (supports --dry-run) |
| `references clear-note` | write | product | Delete the calling user’s note on a knowledge link (supports --dry-run) |
| `references exclude` | write | product | Exclude a knowledge link for the calling user (supports --dry-run) |
| `references include` | write | product | Undo the calling user’s exclude on a knowledge link (supports --dry-run) |
| `references list` | read | product | List knowledge references attached to a project |
| `references pin` | write | product | Pin a knowledge link for the calling user (supports --dry-run) |
| `references quote` | write | product | Attach a quote to a knowledge link (supports --dry-run) |
| `references remove` | write | product | Detach a user-added knowledge section from a project (supports --dry-run) |
| `references set-note` | write | product | Create or replace the calling user’s note on a knowledge link (supports --dry-run) |
| `references unpin` | write | product | Remove the calling user’s pin on a knowledge link (supports --dry-run) |
| `reports compose` | read | product | Compose a grounded report plan from project analysis |
| `reports export` | write | product | Export a report PDF to a local file (spends records.exports) |
| `research datasets list` | read | product | List bounded proprietary inventory for one division |
| `research datasets update` | write | product | Append an operator correction as a revision |
| `research runs cancel` | write | product | Cancel a run while retaining written inventory |
| `research runs get` | read | product | Get research run status, usage, and outcomes |
| `research runs post-result` | write | product | Post one ordered research stage result |
| `research runs start` | write | product | Start a bounded geo source-research run |
| `undo` | write | product | Undo a reversible mutation from its receipt |
| `zoning show` | read | product | Show per-parcel zoning, built-form overlay and site envelope |
{/* END GENERATED CLI COMMAND INVENTORY */}
Example invocations:
```bash
pnpm bucky -- agent-context
pnpm bucky -- capabilities
pnpm bucky -- help
pnpm bucky -- doctor
pnpm bucky -- completion zsh
pnpm bucky -- completion bash
pnpm bucky -- completion fish
pnpm bucky -- auth login
pnpm bucky -- auth status
pnpm bucky -- auth whoami
pnpm bucky -- auth logout
pnpm bucky -- agent check
```
Projects:
```bash
pnpm bucky -- projects list --limit 20
pnpm bucky -- projects get
pnpm bucky -- projects create --name "Main Street" --address "12 Main St" --dry-run
pnpm bucky -- projects update --name "Main Street Infill" --dry-run
pnpm bucky -- projects archive --dry-run
```
`projects archive` is a soft cancel: it retains the project row.
## Land assembly (multi-parcel projects)
`projects create` makes a single-location project: it writes the project and its location,
but attaches no parcels. For a site made of several parcels — a campus, a block assembly,
a building plus its parking lot — use `projects create-assembly`.
```bash
pnpm bucky -- parcels search --lat 45.004744 --lng -93.261962 --radius 120
pnpm bucky -- projects create-assembly --name "Holy Cross Campus" \
--lat 45.004744 --lng -93.261962 --radius 120 \
--parcel 1402924210178 --parcel 1402924210122 --dry-run
pnpm bucky -- projects attach-parcels \
--lat 45.004744 --lng -93.261962 --parcel 1402924220152 --role context --dry-run
```
The usual flow is `parcels search` to find external ids near a point, then `create-assembly`
with the ids you want. Every parcel is attached with role `build`; use
`attach-parcels --role context` afterwards for surrounding parcels you want as context
rather than as part of the site.
**Two modes.** With `--lat/--lng`, the CLI looks the parcels up and derives the commit
polygon from their own geometry — so even `--dry-run` performs that lookup and needs auth.
With `--input`, you supply `geoDivisionId`, `polygon` and `parcelExternalIds` yourself;
that mode is fully offline and is the only way to commit a non-rectangular polygon.
**Parcel order matters.** The first `--parcel` becomes the seed lot: it anchors the
project's location and parcel ordering. Repeat the flag or pass a comma-separated list;
duplicates are dropped without reordering.
**`create-assembly` is not server-idempotent.** Unlike `projects create`, the assembly
endpoint inserts unconditionally — a resend creates a second project. The CLI disables
transport retries for this command and offers no `--retry-operation`. If a run ends with
an unknown outcome, run `projects list` and archive any duplicate rather than retrying.
`bucky undo ` reverses a completed assembly.
**`parcels search` returns no owner names** — the API strips ownership from area
candidates. Pass `--full` to include each parcel's boundary geometry.
Conversations and chat:
```bash
pnpm bucky -- conversations list --project --limit 20
pnpm bucky -- conversations get --project
pnpm bucky -- chat resume
pnpm bucky -- chat resume
pnpm bucky -- chat turn --project --message "Summarize this site" --dry-run
pnpm bucky -- chat turn --project --conversation \
--message "Continue with the permit risks"
```
Pass the opaque `nextCursor` returned by `conversations list` back through
`--cursor`. `chat resume` selects a recent conversation and prints the canonical
`chat turn --conversation ` argv. Sending still requires an explicit
`--message` and mutation review.
Knowledge and references:
```bash
pnpm bucky -- knowledge search --q "front setback" --limit 10
pnpm bucky -- references list --limit 20 --offset 0
pnpm bucky -- references add --section --dry-run
```
## City operations
City commands run only inside a Bucky checkout. They reuse the existing
`pnpm geo:*` entrypoints and read ops credentials from
`apps/bucky-ui/.env.local` or the repository `.env.local`; the service-role key
is never copied into XDG configuration.
```bash
pnpm bucky -- city status --city us-il-chicago
pnpm bucky -- city next --city us-il-chicago
pnpm bucky -- city ingest --city us-il-chicago --dry-run
```
The existing `pnpm geo:*` commands remain supported for detailed operator
workflows and troubleshooting.
---
# Getting Started
Source: https://docs.buckybuild.com/docs/getting-started
New to Bucky? This section gives you a working mental model of the platform
before you reach the reference material. Read it top to bottom, or jump to what
you need.
## Pick your path
- **Development, design, and planning teams** — work in the product on one
known address first. Continue to the [Platform](/docs/platform) section.
- **Developers and agents** — connect over the [HTTP API](/docs/api), the
[MCP](/docs/mcp) server, or the [CLI](/docs/cli). Start with the
[developer quickstart](/docs/getting-started/developer-quickstart).
Pages are tagged by audience and lifecycle in their metadata, and the search dialog (top right)
covers every page and heading. Code blocks and headings are copy-link friendly.
---
# Core concepts
Source: https://docs.buckybuild.com/docs/getting-started/core-concepts
A few concepts appear across every part of Bucky. Learn these once and the
rest of the docs — the platform, MCP, and the CLI — will read naturally.
## Pre-development
**Pre-development** is the work before construction starts: site exploration,
zoning, feasibility, design intent, budgeting, approvals, and team formation.
Bucky is built for this stage, not for running the job site once you break
ground.
## Site intelligence
**Site intelligence** is the parcel, ownership, zoning, entitlement, and
context data connected to a property. Bucky assembles this from local sources
and attaches a citation to what it can, so you can tell what's sourced from
what still needs verification.
## BuckyAssist and Project Scout
**BuckyAssist** is Bucky's AI planning assistant — ask in plain language in
chat. On the Projects map, the same assistant appears as **Project Scout** in
the map dock, focused on exploring blocks, comparing site options, and
assessing development potential. See
[Site exploration](/docs/platform/site-exploration) and
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist).
## Project
A **project** is the container for a piece of planning work. It ties together
the parcel you're studying, the analysis you run against it, and the services
you engage. Most workflows start by creating or opening a project.
## Parcel
A **parcel** is a specific piece of land. It carries the geographic and
physical facts Bucky reasons about — boundaries, lot dimensions, and the
identifiers a jurisdiction uses to refer to it. A parcel is the anchor for
zoning and feasibility: almost every question ("what can I build?", "does it
pencil?") resolves against a parcel.
## Zoning
**Zoning** is the set of rules a jurisdiction places on a parcel — what uses
are allowed and the limits that shape what can be built. Bucky interprets the
applicable zoning for a parcel and cites the bylaw behind each answer, instead
of asking you to read it cover to cover.
## Feasibility
**Feasibility** is the analysis of whether a project is viable on a given
parcel under its zoning. It's where the physical facts and the rules meet the
numbers, helping you decide whether an idea is worth pursuing before you
commit time and money.
## Entitlement pathway
The **entitlement pathway** is the permits, variances, rezonings, reviews, and
decision bodies a proposal has to move through to advance. Bucky tracks the
open questions on that path inside the project, rather than as a separate
research exercise.
## Site option
A **site option** is a named candidate site on a project — often created after
map exploration with Project Scout. Before you save a project, exploration
candidates appear as **unsaved** site options on the map; **Review & create**
or **Save option** makes them durable inside the project.
## People on a project
A project can name **team members** (login access), **partner companies** (no
login), **stakeholders** (tracked contacts, no login), and **viewers** or
share recipients who only need to see the workspace. Company-account seats
are separate from project access. See
[people on a project](/docs/platform/people).
## Services
**Services** are the people and providers who do the work — builders,
designers, and architects — discoverable through Bucky's marketplace. Once a
project has a direction, services are how you connect it to the right team.
## Deliverable
A **deliverable** is a reusable output built from a project's cited analysis —
a feasibility report, investment memo, RFP package, or permit package — for
the next decision maker: a client, lender, council, or partner.
## How they fit together
Use **Project Scout** on the map to explore land and compare **site options**. A **project**
studies a **parcel**. The parcel's **zoning** defines what's allowed, **feasibility** tests
whether it works, **people** decide who sees the work, **services** connect the project to the
people who build it, and a **deliverable** carries the record to the next decision.
Each concept has a deeper home in the [Platform](/docs/platform) section. For
map and chat prompts, see
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist). When you're ready
to do something concrete, head to the
[quickstart](/docs/getting-started/quickstart).
---
# Developer quickstart
Source: https://docs.buckybuild.com/docs/getting-started/developer-quickstart
Load at least $10 of prepaid credit, mint a key, run one priced site check, and
read the receipt. A key is a server-side credential. CORS stays off — do not
ship it to a browser.
A free account includes **10 site lookups / month**, including headless use. A
$10 load is **110 checks in month one**, then 100 per $10 after that. Each
sourced check is **$0.10 USD**. Uncovered sites return HTTP 202 with
`charged: false` and are not billed.
## 1. Load credit and mint a key
1. Sign in and open [Settings → Developer](https://buckybuild.com/en/settings/developer).
2. Load at least **$10 USD**.
3. Create a key. Copy the secret once. Prefixes are `bk_live_` in production and
`bk_test_` locally.
```bash
export BUCKY_API_KEY='bk_live_…'
```
## 2. Four curls
Anonymous coverage is free. The site check is the only priced route.
```bash
curl -sS https://buckybuild.com/api/v1/coverage/divisions/toronto-on
```
```bash
curl -sS -i \
-H "Authorization: Bearer $BUCKY_API_KEY" \
'https://buckybuild.com/api/v1/sites/check?address=100%20Queen%20St%20W,%20Toronto'
```
Read `usage` in the JSON body and the receipt headers:
`X-Bucky-Receipt-Id`, `X-Bucky-Price-Usd`, `X-Bucky-Debit-Usd`,
`X-Bucky-Balance-Usd`, `X-Bucky-Billing-Reason`. A 304 still carries those
headers. A 402 reports the shortfall without a second round trip.
```bash
curl -sS -H "Authorization: Bearer $BUCKY_API_KEY" \
https://buckybuild.com/api/v1/usage/balance
```
```bash
curl -sS https://buckybuild.com/openapi.json | head
```
Coverage and OpenAPI are free. Address suggest is also free but needs a UUID
`sessionToken` — skip it here. `sites/check` is the meter.
## 3. CLI
The CLI is not on npm. Install the promoted binary, then hit the same coverage
route:
```bash
curl -fsSL https://raw.githubusercontent.com/markbucky/bucky/main/apps/bucky-cli/install.sh | sh
bucky coverage get toronto-on
```
Balance is the same `GET /api/v1/usage/balance` call as the third curl. Auth
for product commands is `bucky auth login`. See [CLI](/docs/cli).
## Next
- [API](/docs/api) — priced check, free reads, redaction, CORS, and the 401 taxonomy.
- [MCP](/docs/mcp) — agents.
- [CLI](/docs/cli) — install and product commands.
---
# Quickstart
Source: https://docs.buckybuild.com/docs/getting-started/quickstart
This is the shortest path to a useful first result. Most teams start with one
known address; developers and agents integrate over MCP or the CLI.
## Start with one address
1. Open the **Projects map** and frame a site — search an address, drop a pin, or
draw an area.
2. Use **Project Scout** to explore the block, compare options, or assess
development potential. See [site exploration](/docs/platform/site-exploration).
3. Use **Review & create** to save a project from your selection, or continue
scouting and save a **site option** later.
4. Review [zoning](/docs/platform/zoning) and [feasibility](/docs/platform/feasibility)
on the framed site — both carry a citation back to the source.
5. Explore [services](/docs/platform/services) once the site looks viable and
you're ready to find people to build.
Example prompts for Scout and chat: [Prompting BuckyAssist](/docs/guides/prompting-buckyassist).
New to the terms? Skim [core concepts](/docs/getting-started/core-concepts) first.
## Decide who sees it (a firm)
One champion, one known address, then decide who sees the project. Do not
provision the whole office first.
1. Follow the steps above on a site you already know.
2. Read [people on a project](/docs/platform/people) before you invite anyone.
3. Walk [First week with your team](/docs/guides/first-week-with-your-team) if
you need the full rollout sequence.
## For developers and agents
The same entities — projects, parcels, zoning, feasibility — can be accessed
programmatically:
- **MCP** — read, write, and export tools. An agent can create a project from an
address, run feasibility on it, and export a report. See the
[MCP tool reference](/docs/mcp/reference).
- **CLI** — product and city-operator commands. See [CLI](/docs/cli).
- **API** — prepaid `POST|GET /api/v1/sites/check` is the priced unit. See the
[developer quickstart](/docs/getting-started/developer-quickstart) and
[API](/docs/api).
Map exploration and Project Scout are product UI workflows; they are not
exposed as MCP tools.
## Choose how you work
## Where to go next
- Teams → [Site exploration](/docs/platform/site-exploration) and the
[Platform](/docs/platform) section. Firms:
[First week with your team](/docs/guides/first-week-with-your-team).
- Agents → [MCP](/docs/mcp) and the [tool reference](/docs/mcp/reference).
- Scripting → [CLI](/docs/cli).
---
# What is Bucky?
Source: https://docs.buckybuild.com/docs/getting-started/what-is-bucky
Bucky is the **pre-development platform** that turns an address into sourced
site intelligence, project analysis, and decision-ready deliverables. It
brings parcel and ownership data, zoning and entitlement rules, and
feasibility math into one workspace — so you can reach a defensible go/no-go
before you commit significant time, consultant fees, option money, or capital.
## The problem it solves
Pre-development decisions depend on facts scattered across parcel records,
zoning maps, ordinance text, and institutional memory. Answering _"what can I
build here, and does it pencil out?"_ can take weeks of manual assembly. Bucky
connects the parcel, the applicable zoning, and the feasibility math into one
sourced read, with a citation attached to what it can verify.
## What you can do
- **Screen a site on the map** — use [Project Scout](/docs/guides/prompting-buckyassist)
to explore blocks, compare options, and kill weak sites before you commit to
a project.
- **Read a parcel** — lot dimensions, boundaries, and the zoning that applies
to it.
- **Understand the rules** — see what a parcel's zoning constrains, in plain
terms, with a citation back to the bylaw.
- **Check feasibility** — a defensible read on whether a project is viable
before you commit further.
- **Carry the record forward** — decide who sees the project, then produce a
cited deliverable for the next decision maker.
## Who it's for
Homeowners evaluating a residential build, and professionals discoverable
through the marketplace, work in the same product on a smaller scale.
## How you use it
Bucky meets you where you work:
- A **web application** for hands-on planning — including **BuckyAssist** and
**Project Scout** on the map. See
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist).
- An **MCP server** for agents, covering reads, project writes, and report
export — see [MCP](/docs/mcp) and the [tool reference](/docs/mcp/reference).
- A **command-line interface** for scripting and local workflows — see
[CLI](/docs/cli).
- A **REST API** for programmatic access — the narrative docs and generated
reference are not shipped yet; MCP and the CLI are the supported
integration paths today. See [API](/docs/api).
Bucky is decision support, not a permit, appraisal, or professional certification. Coverage
expands jurisdiction by jurisdiction — check what's cited vs. unverified for your address.
Read the [core concepts](/docs/getting-started/core-concepts) that show up across every part of
the product, or jump to [Prompting BuckyAssist](/docs/guides/prompting-buckyassist) for example
prompts on the map and in chat.
---
# Guides
Source: https://docs.buckybuild.com/docs/guides
Guides are end-to-end, task-oriented walkthroughs that cut across the platform,
MCP, and the CLI rather than documenting a single surface.
## Published
- [Prompting BuckyAssist](/docs/guides/prompting-buckyassist) — example prompts for
Project Scout on the map and BuckyAssist in chat (zoning, designs, project
workspace, Skills).
- [End-to-end parcel analysis](/docs/guides/parcel-analysis) — one address through
screening, zoning, feasibility, and a go/no-go decision.
- [First week with your team](/docs/guides/first-week-with-your-team) — one
champion, one known address, then decide who sees the project.
- [How to read and export a feasibility report](/docs/guides/feasibility-report) —
turn a project's cited analysis into an audience-ready deliverable.
Platform concepts for map exploration live in
[Site exploration](/docs/platform/site-exploration) — use that page for how Scout,
site options, and **Review & create** work; use the prompting guide for what to say.
Who belongs on a project is in [People on a project](/docs/platform/people).
## Coming later
- Shortlisting builders from the marketplace.
---
# How to read and export a feasibility report
Source: https://docs.buckybuild.com/docs/guides/feasibility-report
A feasibility report is Bucky's
[deliverable](/docs/getting-started/core-concepts#deliverable): a reusable
artifact built from a project's cited parcel, zoning, and feasibility read,
for the next decision maker — a client, lender, board, or resident committee.
## Lead with the decision it supports
Before you generate one, know who reads it and what they decide:
- **Investor / lender** — is this worth funding?
- **Owner** — should I move forward on my own site?
- **Board** — should the organization commit resources?
- **Resident** — what does this mean for the neighborhood?
Bucky asks for that audience up front, because a report for a lender and a
report for a resident committee lead with different facts even when the
underlying analysis is the same.
## What's inside
A report is built from the same cited analysis you already read on the
project:
- The **parcel** — geometry, dimensions, identifiers.
- The **zoning** — permitted uses and envelope limits, each with a
[source status](/docs/platform/zoning#what-you-see).
- The **feasibility** read — whether the project pencils under that zoning.
Anything that isn't `cited` or `cited_conditional` in the underlying analysis
stays flagged in the report, too. A deliverable does not upgrade an
`unverified_default` value into a fact.
## How to produce one
Ask BuckyAssist from an open project, for example:
- "Draft an investor report from this project"
- "Draft a brief report for the board"
Pick:
- **Audience** — investor, owner, board, or resident.
- **Detail** — brief or detailed.
BuckyAssist composes a plan first. Preview it before you spend an export — the
plan is free to review and revise; exporting the PDF is not.
Confirm the plan before exporting. Composing and previewing a report plan does not spend your
export allowance; confirming and exporting the PDF does.
## Other deliverable types
A feasibility report is the most common deliverable, but the same cited
project record can back other artifacts as the project moves further along —
an investment memo, an RFP package for a design-build search, or a permit
package once you reach entitlement. See
[core concepts](/docs/getting-started/core-concepts#deliverable) for how these
relate.
## Before you send it
A Bucky report is decision support built from cited and, where noted, unverified data — not a
permit, appraisal, or legal opinion. Review it, and flag anything that still needs verification,
before it goes to a lender, board, or municipality.
## Where to go next
- [Feasibility](/docs/platform/feasibility) — what the analysis behind the report considers.
- [People on a project](/docs/platform/people) — decide who on the project sees the report before you share it externally.
- [Prompting BuckyAssist](/docs/guides/prompting-buckyassist) — more example prompts for project workspace tasks.
---
# First week with your team
Source: https://docs.buckybuild.com/docs/guides/first-week-with-your-team
This is how to start Bucky with a team without deploying it to the whole firm,
and how that same project then runs the development. Do **not** provision every
seat first. Do **not** treat MCP or the API as the rollout — those surfaces are
for developers and agents, documented under [API](/docs/api) and [MCP](/docs/mcp).
## What “done” looks like this week
One live [project](/docs/platform/projects) on an address you already know,
with a cited zoning and [feasibility](/docs/platform/feasibility) read, and a
clear choice of who (if anyone) sees it.
## Day one — champion and address
1. Sign in as the person who will run the first site.
2. Open the **Projects map**. Search the address, drop a pin, or draw the site.
3. Use **Project Scout** to explore, then **Review & create** to save a project.
See [site exploration](/docs/platform/site-exploration).
4. Read [zoning](/docs/platform/zoning) and [feasibility](/docs/platform/feasibility)
on that site before you invite anyone.
If the site does not work, you found out on day one. That is a successful first
use.
## Then decide who sees it
Use [people on a project](/docs/platform/people). The short version:
- A colleague who will run analysis → add them to the **team**.
- A client or principal who needs to see the live workspace → **viewer** invite
or share link (Professional).
- A planner, lender, or neighbour you are tracking → **stakeholder** (no login).
- An architect or builder you may hire → **partner** company (no login).
- The whole office → do not add them this week.
If nobody else needs to see the project yet, stop. The champion can keep working
alone.
## Week two — one invite, then seats
If someone else will actually work in Bucky, invite that one person. Add company
seats when sharing is habitual, not because a roster exists on paper.
## After week one — the same project
Bucky stays on that project through screening, feasibility, entitlement, and
team formation. Parties join when the stage needs them. The stage table is on
[people on a project](/docs/platform/people#across-the-development).
Construction execution is not Bucky. The file remains the sourced record you
hand to the people who build.
## Prompts on the map and in chat
Example prompts for Scout and BuckyAssist:
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist).
---
# End-to-end parcel analysis
Source: https://docs.buckybuild.com/docs/guides/parcel-analysis
This walks one address through Bucky's full chain — parcel facts, local
rules, feasibility, and a decision — in one workflow. The goal of this walk
isn't to find a good site; it's to make screening cheap enough that killing a
weak one costs you an afternoon, not six weeks.
## 1. Screen on the map
Open the **Projects map** and search the address, drop a pin, or draw an
area. Use **Project Scout** to explore the block and get an early **Site
summary** before you commit to anything. See
[site exploration](/docs/platform/site-exploration) and
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist) for example
prompts.
If the site summary already looks wrong for what you need — zone doesn't
allow the use, lot too small, obvious constraint — stop here and screen the
next address. Nothing is saved yet, so there's nothing to clean up.
## 2. Read the parcel
If the site clears the first look, open the [parcel](/docs/platform/parcels)
read: geometry, dimensions, and the jurisdiction's identifier for the lot.
These are the physical facts everything downstream depends on — check the
[source status](/docs/resources/citations) if a dimension looks off.
## 3. Read zoning with citations
Ask Project Scout **"What can I build here?"** or **"Review zoning"**. Read
the permitted uses and the envelope limits (height, setbacks, site coverage,
FSR), and check the **status** behind each one — see
[Zoning](/docs/platform/zoning#what-you-see). A `cited` limit is traceable to
the bylaw; treat anything `unverified_default` or `not_extracted` as a
question, not an answer.
## 4. Assess feasibility
Ask Scout to **assess development potential**, or open the full
[feasibility](/docs/platform/feasibility) panel on your framed site. This is
where the parcel's physical facts and the zoning's rules meet the numbers —
the step that tells you whether the idea is actually workable, not just
allowed.
## 5. Decide: go, no-go, or not yet
Three outcomes, all legitimate:
- **No-go** — the read disqualifies the site. You've spent an afternoon, not
a retainer. Screen the next address.
- **Not yet** — the read depends on values that are `unverified_default`,
`not_extracted`, or `conditional_unresolved`. Note what needs verification
before you commit further — see
[Citations and confidence](/docs/resources/citations).
- **Go** — use **Review & create** to save the project (if you haven't
already), and move to who sees it next.
## 6. If it's a go: bring in the team, then services
Decide who needs a seat before you invite anyone — see
[people on a project](/docs/platform/people). Once the project has direction,
[services](/docs/platform/services) is how you connect it to builders,
designers, and architects. If you need to hand the read to a client, lender,
or committee, turn it into a deliverable — see
[how to read and export a feasibility report](/docs/guides/feasibility-report).
Every step above produces decision support, not a permit, appraisal, or legal opinion. The
citation status behind each value tells you what still needs human verification.
## Where to go next
- [Core concepts](/docs/getting-started/core-concepts) — the vocabulary behind each step.
- [First week with your team](/docs/guides/first-week-with-your-team) — the same
chain, run by a firm instead of one person.
- [Coverage](/docs/resources/coverage) — check before you run this on an
address outside a market you already know.
---
# Prompting BuckyAssist
Source: https://docs.buckybuild.com/docs/guides/prompting-buckyassist
**BuckyAssist** is Bucky's AI assistant. Ask in plain language — you do not need special commands or syntax. On the map, **Project Scout** helps you explore blocks, highlight lots, and compare site options. See [Site exploration](/docs/platform/site-exploration) for how the map workflow fits together. Elsewhere, BuckyAssist can research parcels and [zoning](/docs/platform/zoning), find designs and professionals, and help you manage [project](/docs/platform/projects) work.
This guide shows what to say and how to get better answers.
## How to get better answers
A few habits make a big difference:
- **Start from the map** when you are scouting — pan to the area, drop a pin, or draw a site boundary, then ask BuckyAssist to explore or assess it.
- **Lead with an address** when you ask what can be built on a site — a street address or postal code works best.
- **Be specific about the outcome** you want: a block preview, setbacks and height, townhouse designs under a budget, or a comparison between two streets.
- **Use @ mentions** to reference a specific design, completed build, or seller when you want to compare or ask follow-up questions.
- **Open or save a project** when you need live city data, site options, or work that should stay attached to a project.
- **Ask one clear thing per message**, then follow up after results appear — BuckyAssist works best as a conversation, not a single mega-prompt.
## Project Scout (map exploration)
**Project Scout** is the assistant in the map dock. Start here when you are studying land — previewing blocks, highlighting lots, comparing corridors, and saving site options — rather than browsing the full design catalog.
**Example prompts:**
- Explore a block-sized site at the center of my current map view
- Explore the block around this location on the map and highlight its lots
- Explore development sites near Vancouver
- Help me draw an area on the map and highlight the lots inside it
- Show the zoning layer in my current map view
- Assess development potential
- Review zoning for the lots in this selected area
- Summarize the lots, total area, and known site constraints in this selection
- Compare these two streets for development potential
- Save Option A as a site option on my project
Live municipal open data (permits, hydrants, parcel records, and similar) often requires a saved
project. If BuckyAssist prompts you to save or open a project first, that is expected.
For where Project Scout lives, how the panel switches between Explore / Assess /
Refine, what a map exploration produces, and how to save your work, see
[site exploration](/docs/platform/site-exploration).
## Zoning and building rules
Use this when you want to know what a parcel allows — setbacks, height, density, permitted uses, or building-code topics like fire separation.
**Example prompts:**
- Check zoning rules for 123 Main St, Vancouver
- What can I build here?
- What are the setbacks and height limits for this address?
- What are the building codes for this location?
- Check setbacks and what I can build here
Zoning and feasibility answers help you decide whether an idea is worth pursuing. They do not
replace a planner, lawyer, or engineer. Municipal bylaws are the source of truth.
## Designs and completed builds
Use this to browse the marketplace — prefab and modular designs, or real completed homes you can use as comparables.
**Example prompts:**
- Find completed builds near an address
- Show me townhouse designs I can browse now
- Show townhouse design options in the catalog
- Show comparable completed builds near this project
- Generate a clay model render from a design
Clay renders ask for your approval before they run.
## Professionals and builders
Use this to find people who can help — architects, contractors, and other professionals — or builders who carry specific design catalogs.
**Example prompts:**
- Find professionals near my project area
- Find experts near Vancouver
- Show me designs for a laneway house
- Find a builder that makes modular townhouses
To book time with a professional, use the booking flow in the marketplace — BuckyAssist helps you discover and compare, not schedule appointments directly in chat.
## Cost and grants
Use this when you want a rough construction estimate from comparable builds, or to check grant eligibility.
**Example prompts:**
- Estimate construction cost from comparables
- Estimate construction cost for this scope
- Am I eligible for grants or incentives for this project?
Grant checks are available for individual accounts.
## Project workspace
Use this when you have a project open — tasks, reports, documents, and project details.
**Example prompts:**
- List my projects
- Add a task to follow up with the planner
- Draft an investor report from this project
- What do my documents say about setbacks on this site?
- Search my project documents for title issues
## Memory
BuckyAssist can remember durable facts about your preferences so you do not have to repeat them every session.
**Example prompts:**
- Remember my budget is $800K
- Remember I prefer modular construction
- Remember my target move-in date is fall 2027
If a new fact conflicts with something BuckyAssist already knows, you may see an approval card to confirm the update.
## Skills
**Skills** are focused workflows you can pick from the Skills selector. Each skill starts with a template you can finish in your own words.
| Skill | Starter prompt |
| -------------------- | ------------------------------------------------ |
| Courtyards | Audit my project for courtyard feasibility: |
| Document Intake | Run document intake on my project documents: |
| Legal & Title Review | Review legal and title documents for my project: |
| Report draft | Improve this report draft: |
## Where you chat matters
BuckyAssist behaves slightly differently depending on where you open it:
- **Project Scout (map dock)** — site exploration first; start with the prompts above. Marketplace browsing is secondary.
- **Main chat** — full marketplace discovery, zoning research, and project help.
- **Skills selector** — a narrow workflow with a starter template and focused follow-ups.
You can also pick a **tool mode** (Building Codes & Rules, Designs, Experts, Locations) to pre-fill the start of your message — for example, “What are the building codes for …” or “Find experts near …”.
## What to expect in the conversation
BuckyAssist may not answer only in text. You might see:
- **Clarifying questions** — multiple-choice or short-answer cards when your request needs one more detail.
- **Visual results** — design lists, maps, exploration plans, and comparison tables instead of long plain-text lists.
- **Approval cards** — before saving memory, editing project fields, or generating a clay render.
Follow the cards on screen; they are part of how BuckyAssist completes the task.
## Limits and good judgment
- **Coverage varies by city.** BuckyAssist will tell you when it cannot ground an answer in data for your jurisdiction.
- **Do not treat estimates as quotes.** Construction cost ranges come from comparables and scope — they are a starting point, not a bid.
- **Exploration drafts are not legal boundaries.** Block previews and drawn areas are planning aids; confirm dimensions and ownership with official records.
- **Booking happens in the product.** Use marketplace booking flows to schedule with sellers — not chat commands.
## Quick reference
| You want to… | Try saying… |
| ------------------------- | -------------------------------------------------------------- |
| Explore a site on the map | “Explore the block around [address]” |
| Assess a selected area | “Assess development potential” |
| Compare two corridors | “Compare these two streets for development potential” |
| Save a site choice | “Save Option A as a site option” |
| Learn what a site allows | “Check zoning rules for [address]” or “What can I build here?” |
| Browse designs | “Show me designs for [project type]” |
| See real completed homes | “Find completed builds near [address]” |
| Find people to hire | “Find professionals near my project area” |
| Rough cost sense | “Estimate construction cost from comparables” |
| Track project work | “Add a task to follow up with the planner” |
| Remember a preference | “Remember my budget is $800K” |
| Run a focused workflow | Pick a **Skill** and complete its starter prompt |
For the concepts behind these workflows, see [Core concepts](/docs/getting-started/core-concepts). When you are ready to run an analysis end to end, start from the [quickstart](/docs/getting-started/quickstart).
---
# MCP
Source: https://docs.buckybuild.com/docs/mcp
The MCP section is for AI agents and the developers wiring them up. Bucky exposes
a deliberately narrow subset of its tool registry over MCP, spanning three
scopes: `mcp:read` for site and project reads, `mcp:write` for creating and
updating projects and running feasibility, and `mcp:export` for report PDFs.
Feedback is a separate, unscoped write that always requires human review and
acceptance. The tools share core registries with BuckyAssist but omit map
exploration and marketplace render tools. MCP does not mirror the CLI mutation
set; parcel attach is the one extra write so a created project can hold lots.
## What is available today
The generated [MCP tool reference](/docs/mcp/reference) is the source-derived
inventory of everything the server exposes. The [tools overview](/docs/mcp/tools)
groups that inventory into builder workflows.
The allowlist includes project and project-memory reads, address and geographic
context, nearby records, seller search, and knowledge search. Authenticated
clients also receive `submitBuckyFeedback`, which opens a client-native form and
persists only after the human accepts it. Project Scout map flows and
marketplace rendering remain product-only. Project writes on this surface are
the four tools in the generated reference; they preview and emit receipts (see
the mutation-safety and write-scope decisions in `docs/mcp/mcp-protocol-maturity.md`).
`saveToProject` can create a project and attach parcels. Archive, programs, costs,
and location repair stay on the CLI.
Follow the verified [HTTP integration workflow](/docs/mcp/integrations) to exercise the current
transport. Regenerate the [tool reference](/docs/mcp/reference) with `pnpm generate-mcp-reference`
when the registry changes.
---
# Connect Bucky to your AI
Source: https://docs.buckybuild.com/docs/mcp/connect
Bucky runs an MCP server, so an AI assistant can look up zoning, parcels, and
feasibility for a street address without you leaving the conversation.
You need one thing:
```
https://buckybuild.com/api/mcp
```
Everything below is a different way of handing that URL to a client. Pick yours.
## Claude
Claude web and Claude Desktop both support remote MCP servers as **custom
connectors**. There is no install link — Anthropic does not offer one — so this
is a paste.
1. Open **Settings → Connectors**.
2. Choose **Add custom connector**.
3. Paste `https://buckybuild.com/api/mcp` and save.
4. Ask Claude something that needs Bucky — "what can I build at 412 Main St?" —
and approve the sign-in page it opens.
Custom connectors need a paid Claude plan (Pro, Max, or Team). If you are on the free plan, use
Cursor or the CLI below instead.
## Cursor
Cursor supports one-click install:
Add Bucky to Cursor
Or add it by hand in **Settings → MCP → Add new MCP server**, with
`https://buckybuild.com/api/mcp` as the URL. Cursor registers itself
automatically; you do not need to create anything on the Bucky side first.
## VS Code
Add Bucky to VS Code
## Claude Code
```bash
claude mcp add --transport http bucky https://buckybuild.com/api/mcp
```
Claude Code opens the sign-in page the first time a tool needs your account.
## Codex
Codex reads `~/.codex/config.toml`. A `url` key rather than a `command` is what
selects the Streamable HTTP transport:
```toml
[mcp_servers.bucky]
url = "https://buckybuild.com/api/mcp"
```
Then run the OAuth leg once:
```bash
codex mcp login bucky
```
## ChatGPT
ChatGPT reaches custom MCP servers through **Settings → Connectors** in
developer mode. Add `https://buckybuild.com/api/mcp` and approve the sign-in
page. This needs a paid ChatGPT plan.
## Grok
Open [grok.com/connectors](https://grok.com/connectors), choose **New
Connector**, then **Custom**, and paste `https://buckybuild.com/api/mcp`. Grok
reads the tool list from the server. Custom connectors are on Grok's paid tiers.
Grok Build, the terminal CLI, reads MCP configuration you already have — nothing
extra to do there.
## Windsurf, Zed, Cline, and everything else
Any client that speaks Streamable HTTP takes the same object in its own MCP
config file:
```json
{ "type": "http", "url": "https://buckybuild.com/api/mcp" }
```
## Bucky CLI
```bash
bucky auth login
```
This opens a browser, signs you in, and stores the token locally. No connector
configuration needed.
## Signing in
The first time your assistant calls a tool that needs your account, it opens a
Bucky sign-in page. You will see:
1. **Which app is connecting** — named at the top of the sign-in form.
2. **What it will be able to do** — the exact permissions, listed before you
approve. Reading your projects, creating and updating them, and exporting
report PDFs are separate permissions, because exporting spends your export
credits.
Approve once and the connection persists. You never paste a token, and the
assistant never sees your password.
Two tools work with no account at all, so you can check the connection is live
before signing in: `getBuckyMcpGuide` and `explainFeasibilityStatus`.
## Managing and disconnecting
Connected apps are listed at **Settings → Connected apps** in Bucky, with what
each one can do and when it was last used. Disconnecting takes effect
immediately — the next request that app makes is refused, rather than working
until its token happens to expire.
## If it does not connect
- **"Invalid client"** — your client registered but could not be resolved. This
was a bug fixed on 2026-08-17; make sure the client is not caching an old
registration, and try removing and re-adding the connector.
- **Signed in but nothing happened** — the connector flow needs to return you to
Bucky's authorization page after login. If you land on the Bucky dashboard
instead, the flow was interrupted; start it again from your assistant.
- **"New Bucky accounts are paused"** — self-serve signup is currently closed.
Join the waitlist, and connect once your account exists.
## For developers
Protocol details — transport, discovery documents, verifying the endpoint with
`curl` — are in [MCP integrations](/docs/mcp/integrations). The tool catalog is
in [MCP tools](/docs/mcp/tools).
---
# MCP Integrations
Source: https://docs.buckybuild.com/docs/mcp/integrations
Bucky's MCP surface is a route inside the web app, not a separate service: it is
`POST /api/mcp`, served by the same deployment as everything else. The transport
is Streamable HTTP, stateless — no session id. It serves MCP `2026-07-28` and
keeps a stateless compatibility leg for 2025-era clients. `GET` and `DELETE` on
the endpoint answer `405`.
Named desktop and editor client configurations are still pending transport
compatibility testing; do not translate this endpoint into a stdio or SSE
configuration.
Agents can discover the server before connecting through the public
`/.well-known/mcp/server-card.json` document. It advertises the same server
name and version as the runtime, MCP `2026-07-28`, the `/api/mcp` Streamable
HTTP endpoint, and dynamic tools. The card marks tools as dynamic because
`tools/list` is the runtime authority; the catalog itself is the same for
anonymous and authenticated callers.
## Requirements
Use Node 24 or newer and pnpm 11.8.0 from a Bucky checkout. The route needs the
app's usual environment, so run the app itself:
```bash
pnpm nx dev bucky-ui
```
The examples below assume `http://127.0.0.1:3000`; substitute the port the dev
server prints if it differs.
## Verify the current protocol
MCP `2026-07-28` uses a per-request `_meta` envelope and `server/discover`; it
does not require an initialization handshake:
```bash
curl --fail --silent http://127.0.0.1:3000/api/mcp \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--header 'Mcp-Method: server/discover' \
--data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"}}}}'
```
The result lists `2026-07-28` in `supportedVersions`, includes the tools
capability, and carries `resultType: "complete"`.
The endpoint also supports 2025-era `initialize`, `ping`, and `tools/list`. For
that compatibility leg the spec requires clients to accept **both**
`application/json` and `text/event-stream`. Omitting either gets a `406`, not a
protocol answer:
```bash
curl --fail --silent http://127.0.0.1:3000/api/mcp \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'
```
The response may be an SSE `data:` frame, which is valid Streamable HTTP.
## List tools
```bash
curl --fail --silent http://127.0.0.1:3000/api/mcp \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```
The result's `tools` array is the runtime authority. Regenerate the
[generated tool reference](/docs/mcp/reference) with `pnpm generate-mcp-reference`
when bundle tools change.
**`tools/list` always returns the full catalog.** Execution stays gated: calling
an authenticated tool without a Bucky access token returns HTTP 401 and
`WWW-Authenticate`, which is what starts browser OAuth. An expired or invalid
bearer also 401s — including on `tools/list` — so the client refreshes instead
of silently falling back to the two anonymous tools. Claude.ai ToolSearch only
indexes names from `tools/list`; hiding gated tools until a token is already
on the wire means they are never called and OAuth never starts.
## Origin
Requests carrying an `Origin` header are validated against an allowlist and
rejected with `403` if it does not match — required by the transport spec to
prevent DNS rebinding. Requests with **no** `Origin` are allowed, which is the
normal case: non-browser MCP clients do not send one. Add browser origins via
the `MCP_ALLOWED_ORIGINS` environment variable (comma-separated).
## Call the public zero-cost tools
Anonymous callers can still invoke two static tools without a token:
- `getBuckyMcpGuide` describes the surface, how to start OAuth by calling a gated tool, and safety rules.
- `explainFeasibilityStatus` explains one Bucky coverage or fact status and its safe next action.
`tools/list` also advertises the authenticated tools. Call one of those to start
sign-in; do not disconnect the connector first.
Neither public tool queries a database, geocoder, AI model, or third-party API, so this
MVP does not require Redis or another shared spend limiter.
```bash
curl --fail --silent http://127.0.0.1:3000/api/mcp \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getBuckyMcpGuide","arguments":{}}}'
```
```bash
curl --fail --silent http://127.0.0.1:3000/api/mcp \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"explainFeasibilityStatus","arguments":{"status":"not_extracted"}}}'
```
## Call address feasibility with authentication
`getFeasibilitySnapshot` requires a valid bearer token because resolving an
address may use cost-bearing infrastructure. It returns the lot, its zone and
permitted uses, and the building envelope in one call.
Every envelope value arrives with its own `status`, and **a null value means
nothing without it**:
| `status` | Meaning |
| ------------------------ | ---------------------------------------------------------------------------- |
| `cited` | Extracted from the bylaw. |
| `cited_conditional` | Resolved from a conditional rule that applies to this site. |
| `conditional_unresolved` | Conditional tiers exist; none resolve for this site. Unknown, not unlimited. |
| `no_limit_in_bylaw` | The bylaw sets no zone-level limit. A real answer. |
| `unverified_default` | A cached zoning value with no citation behind it. Indicative only. |
| `not_extracted` | Never extracted for this zone. Unknown. |
`no_limit_in_bylaw` and `not_extracted` both carry `value: null` and mean
opposite things. Reporting the second as "no limit" is the failure mode this
shape exists to prevent.
When an address falls outside coverage the call still succeeds, with
`answered: false` and a `coverage` block saying why — `planned_not_live`,
`unseeded_place`, `geocode_failed`, and so on. `coverage.eligibilityKnown` is
false when we could not determine eligibility at all, which is distinct from
determining that a place is not covered.
## Call the authenticated tier
Workflow bundles require a real Bucky account. **OAuth browser sign-in is the happy path**
for Claude Desktop, ChatGPT, and Cursor. Bearer JWT paste is a **Cursor/scripting fallback**
(tokens expire in about one hour).
### OAuth (Claude Desktop, ChatGPT, Cursor)
1. Add remote MCP server URL: `https://buckybuild.com/api/mcp`
2. Call an authenticated tool (for example `getFeasibilitySnapshot`). Complete the browser Bucky sign-in your client presents. Do not disconnect the connector first.
3. Protected resource metadata:
`https://buckybuild.com/.well-known/oauth-protected-resource/api/mcp`
4. Authorization server metadata:
`https://buckybuild.com/.well-known/oauth-authorization-server`
Call `getBuckyMcpGuide` over MCP for the in-band setup summary and first-project checklist.
### CLI (agents use `--profile agent`; humans run login once)
```bash
bucky --profile agent auth login
bucky --profile agent agent check
bucky --profile agent projects create --name "Demo" --address "4170 Sophia St, Vancouver BC"
bucky --profile agent analysis run
bucky --profile agent analysis wait
bucky --profile agent reports export --out report.pdf
```
Interactive `auth login` opens the same browser identity as the web app. Password, stdin
tokens, and environment variables remain supported for automation.
### Bearer fallback (Cursor scripting only)
Keep tokens out of command history by reading without echo:
```bash
read -r -s 'BUCKY_MCP_TOKEN?Supabase user access token: '
export BUCKY_MCP_TOKEN
curl --fail --silent http://127.0.0.1:3000/api/mcp \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--header "Authorization: Bearer ${BUCKY_MCP_TOKEN}" \
--data '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"getFeasibilitySnapshot","arguments":{"address":"4170 Sophia St, Vancouver BC","source":"zoning_lookup"}}}'
unset BUCKY_MCP_TOKEN
```
Missing, malformed, expired, or invalid bearer tokens are rejected with
`-32010`. A tool that fails on its own terms returns a normal result with
`isError: true`; an unexpected server-side failure returns `-32603` with no
detail, and the real error is written to stderr.
Bearer tokens expire in about an hour. OAuth refresh is the documented client path.
## Submit human-reviewed feedback
Authenticated callers also receive `submitBuckyFeedback`. Call it only when the
user explicitly asks to send feedback, report a problem, suggest an
improvement, or praise something. The first call returns
`resultType: "input_required"` with a form elicitation request. A compatible MCP
client presents that form to the human and retries the same tool call with the
accepted response.
Nothing is persisted when the form is declined or cancelled. Accepted feedback
is validated and scrubbed for common personal-data and credential shapes before
it is stored in Supabase. Generate a UUID for `submissionId` and reuse that UUID
when retrying the same report; duplicate submissions are treated as a successful
idempotent retry.
This tool is not an agent telemetry channel. Agents must not invoke it silently
or infer feedback from a failed tool call. Agent-observed operational friction
continues to use the internal papercut signal.
Before deploying the tool, apply
`supabase/migrations/20260729223000_generalize_feedback_for_mcp.sql`. The
migration adds the narrowly scoped RLS policy for explicit MCP feedback and
extends the admin feedback view. If the write fails, the tool returns
`success: false` and tells the caller to retry with the same `submissionId`; it
does not silently acknowledge a dropped report.
## Test seam
Vitest resolves the include globs relative to its working directory, so run this
from the app, not the repo root:
```bash
cd apps/bucky-ui
pnpm exec vitest run --config vitest.config.ts app/api/mcp server/mcp
```
The route suite drives the official v2 SDK through `POST` with a stubbed tool
registry, covering both protocol eras, header/body validation, the body cap,
`tools/list`, `tools/call`, per-tool auth, and error sanitisation. The registry
suite loads the canonical tool graph unmocked and asserts every annotation and
auth boundary. Feedback tests cover elicitation, decline/cancel, validated
acceptance, idempotency, provenance, and failed-write behavior. The bundle suite
covers coverage honesty, redaction, raw-address non-retention, attribution, and
the cache.
---
# MCP Tool Reference
Source: https://docs.buckybuild.com/docs/mcp/reference
{/* GENERATED FILE — do not edit by hand.
Source: scripts/generate-mcp-reference.mts from apps/bucky-ui/server/mcp/tool-registry.ts.
Run `pnpm generate-mcp-reference` to update. */}
These tools are exposed over Bucky's MCP server at `POST /api/mcp`. Each entry is
generated from the runtime registry. `tools/list` advertises the full catalog to every
caller; authenticated tools still require a Bucky account at call time.
## Guidance
### Get the Bucky MCP guide
`getBuckyMcpGuide`
Return a static guide to the Bucky MCP surface: what works without sign-in, how to start OAuth by calling a gated tool, how to connect Cursor or the CLI with a real account, and feasibility safety rules. Makes no database, geocoding, AI, or third-party API call.
**Read-only:** yes
**Parameters:**
_No parameters._
### Explain a Bucky feasibility status
`explainFeasibilityStatus`
Explain one Bucky coverage or per-fact provenance status and the safe next action. This is a pure static lookup: it does not inspect an address, retrieve property data, or call a database, geocoder, AI model, or third-party API. Accepts exactly one of: live, live_unavailable, planned_not_live, geo_division_uncatalogued, unseeded_place, geocode_failed, cited, cited_conditional, conditional_unresolved, no_limit_in_bylaw, not_extracted, site_specific_schedule, unverified_default.
**Read-only:** yes
**Parameters:**
- `status` (enum: "live" | "live_unavailable" | "planned_not_live" | "geo_division_uncatalogued" | "unseeded_place" | "geocode_failed" | "cited" | "cited_conditional" | "conditional_unresolved" | "no_limit_in_bylaw" | "not_extracted" | "site_specific_schedule" | "unverified_default" | "derived_from_cited" | "defaulted" | "missing", required) — A Bucky coverage resolution status or per-fact provenance status returned by a feasibility result. Must be copied verbatim from a feasibility result — one of: live, live_unavailable, planned_not_live, geo_division_uncatalogued, unseeded_place, geocode_failed, cited, cited_conditional, conditional_unresolved, no_limit_in_bylaw, not_extracted, site_specific_schedule, unverified_default, derived_from_cited, defaulted, missing. Do not paraphrase or invent a status.
## Feasibility
### Get feasibility snapshot for an address
`getFeasibilitySnapshot`
Look up what can be built at a specific street address in Canada or the US. Returns the lot (area, width, depth), its zone and permitted uses, and the building envelope (height, storeys, site coverage, FSR, and front/rear/side/flanking setbacks) in one call. Use when someone asks what they can build, how tall, how close to the property line, how big their lot is, or what their property is zoned for. Do not use for questions that are not about a specific address — it resolves one address at a time and cannot search or compare. Every envelope value carries a `status`. A null value with status `no_limit_in_bylaw` means the bylaw sets no limit; a null value with status `not_extracted` means the value is unknown to Bucky; a null value with status `site_specific_schedule` means the zone is governed by a per-site schedule, not a zone table. Never report `not_extracted` or `site_specific_schedule` as "no limit" or as zero.
**Read-only:** yes
**Parameters:**
- `address` (string, required) — Street address to analyse, e.g. "4170 Sophia St, Vancouver BC".
- `source` (enum: "zoning_lookup" | "lot_dimensions" | "setback_lookup" | "height_limit_lookup" | "full", required) — Which question the caller is answering. Used for attribution and to pick the link back; the payload is the same either way.
## Projects
### Run project feasibility analysis
`runFeasibilityAnalysis`
Enqueue a fresh deterministic analysis run for a saved project. Pass `projectId`, or `project` with the name the user said; with neither, the result lists their projects and nothing is queued. Returns immediately with `agentStatus` (`queued`, `running`, `current`, `failed`, or `none`) and a receipt id; does not block on completion. Irreversible: a queued run cannot be un-queued from MCP. Re-check with `getProjectContext`, but no more than once every 15 seconds — it is a multi-query bundle, not a status endpoint.
**Read-only:** no
**Parameters:**
- `projectId` (string, optional) — Project UUID. Omit if you pass `project`.
- `project` (string, optional) — Project name to match, when you do not have the UUID. Case-insensitive; an exact name wins over a partial one. Matching more than one lists the candidates instead of guessing.
### Get project context bundle
`getProjectContext`
Load one project with analysis envelope, compact agentStatus, document summaries, evidence summaries, the project memory digest, and external_ref when the project was imported from another system. You do not need a UUID: pass `project` with the name the user said, or call with neither and the result lists their projects to choose from. Use before composing reports or after scheduling analysis.
**Read-only:** yes
**Parameters:**
- `projectId` (string, optional) — Project UUID. Omit if you pass `project`.
- `project` (string, optional) — Project name to match, when you do not have the UUID. Case-insensitive; an exact name wins over a partial one. Matching more than one lists the candidates instead of guessing.
- `documentsLimit` (integer, required)
- `evidenceLimit` (integer, required)
### Create or attach to a project
`saveToProject`
Create a new project from a site (`create`), attach lots (`attach_parcels`, using lot.parcelExternalId from getFeasibilitySnapshot), or attach a knowledge reference (`attach_reference`). On `create`, pass `address`, or `lat` and `lng` from getFeasibilitySnapshot when you already have them: coordinates resolve the project to a city, and an address alone is geocoded server-side. Check `geography` on the result — `resolved: false` means the project has no city context and feasibility analysis will have nothing to resolve against, and `coordinateSource: "geocoded"` means the server picked the point, so confirm it is the right site. preview=true returns the field-level diff and writes nothing. A write returns a receipt. Not reversible on this surface: MCP cannot archive a project, detach a parcel, or detach a reference. attach_parcels and attach_reference take `projectId`, or `project` with the name the user said; with neither, the result lists their projects and nothing is attached. Create accepts idempotencyKey and externalRef (`\:\`, e.g. `notion:\`) so an imported project can be looked up later.
**Read-only:** no
**Parameters:**
- `action` (enum: "create" | "attach_reference" | "attach_parcels", required) — create: new project from a site. attach_parcels: attach lots to an existing project (use lot.parcelExternalId from getFeasibilitySnapshot). attach_reference: link a knowledge section to an existing project.
- `name` (string, optional)
- `address` (string, optional) — Street address of the site. On `create` this is geocoded server-side when lat/lng are not supplied, and is what gets recorded as the project address.
- `lat` (number, optional) — Latitude from getFeasibilitySnapshot. Supplied coordinates are never re-geocoded.
- `lng` (number, optional) — Longitude from getFeasibilitySnapshot.
- `projectId` (string, optional) — Existing project UUID. Required by attach_parcels and attach_reference unless you pass `project`; ignored by create.
- `project` (string, optional) — Project name to match instead of a UUID, for attach_parcels and attach_reference. Matching more than one lists the candidates instead of guessing. Ignored by create.
- `sectionUuid` (string, optional)
- `parcelExternalIds` (string[], optional) — Source parcel ids to attach. Copy lot.parcelExternalId from getFeasibilitySnapshot, or from bucky parcels search.
- `role` (enum: "build" | "context", optional) — build is the lot being developed; context is surrounding land. Default build.
- `radiusM` (integer, optional) — Search half-width in metres when resolving parcel ids. Default 150.
- `idempotencyKey` (string, optional)
- `externalRef` (string, optional) — Provenance of an imported project. Canonical form is `\:\` (e.g. `notion:\`). Unique per creator when set. Returned on getProjectContext. Distinct from idempotencyKey.
- `preview` (boolean, required) — When true, return the field-level diff and write nothing.
### Update project fields
`updateProject`
Patch project metadata (name, lifecycle status, externalRef). Pass `projectId`, or `project` with the name the user said; with neither, the result lists their projects and nothing is written. preview=true returns the field-level diff and writes nothing. A write returns a receipt; undoOperationId restores the captured prior fields. Does not archive or delete.
**Read-only:** no
**Parameters:**
- `projectId` (string, optional) — Project UUID. Omit if you pass `project`.
- `project` (string, optional) — Project name to match, when you do not have the UUID. Case-insensitive; an exact name wins over a partial one. Matching more than one lists the candidates instead of guessing.
- `name` (string, optional)
- `lifecycleStatus` (string, optional)
- `externalRef` (one of, optional) — Provenance of an imported project. Canonical form is `\:\` (e.g. `notion:\`). Unique per creator when set. Pass null to clear.
- `preview` (boolean, required) — When true, return the field-level diff and write nothing. Combined with undoOperationId, returns the stored receipt.
- `undoOperationId` (string, optional) — Receipt id from a prior updateProject write. Restores the captured prior fields. With preview=true, inspects the receipt instead.
### List or unlist a project on the public map
`setProjectMapListing`
Put a project on the public Bucky map, or take it off. Pass `projectId`, or `project` with the name the user said; with neither, the result lists their projects and nothing is published. Listing publishes the build-lot centroid, the project name, its zone category, typology and lifecycle status to anyone — signed in or not. Nothing else about the project is published. The project must have a build lot with a centroid; a project that has only an address and no attached build parcel cannot be pinned. Ask the human before listing a site that is not already public knowledge. A client, a friend, or a private residence is theirs to publish, not yours. preview=true returns the current state, the exact pin that would be published, and any privacy warning, and writes nothing. Unlisting removes the pin but does not un-share anything already collected while it was public.
**Read-only:** no
**Parameters:**
- `projectId` (string, optional) — Project UUID. Omit if you pass `project`.
- `project` (string, optional) — Project name to match, when you do not have the UUID. Case-insensitive; an exact name wins over a partial one. Matching more than one lists the candidates instead of guessing.
- `listed` (boolean, required) — true lists the project on the public map; false removes it. Listing publishes the build-lot centroid and the project name to anyone, signed in or not.
- `preview` (boolean, required) — When true, return the current listing state, the pin that would be published, and any privacy warning, and write nothing.
### Compose and export a project report PDF
`produceProjectReport`
Pass `projectId`, or `project` with the name the user said; with neither, the result lists their projects and no meter is spent. Compose a grounded report plan, optionally preview without spending export meter (`preview=true`), or confirm export (`confirm=true`) to save the plan and return a short-lived signed download URL plus a receipt — never PDF bytes in the tool result. Confirm spends `records.exports` and is irreversible.
**Read-only:** no
**Parameters:**
- `projectId` (string, optional) — Project UUID. Omit if you pass `project`.
- `project` (string, optional) — Project name to match, when you do not have the UUID. Case-insensitive; an exact name wins over a partial one. Matching more than one lists the candidates instead of guessing.
- `audience` (enum: "investor" | "owner" | "board" | "resident", required)
- `detail` (enum: "brief" | "detailed", required)
- `request` (string, optional)
- `preview` (boolean, required) — When true, compose only — no export meter spend and no download URL.
- `confirm` (boolean, required) — When true, compose (if needed), save, export PDF, and return a download URL. Required when preview is false. Spends records.exports and cannot be undone.
- `planName` (string, optional)
## Feedback
### Submit feedback to Bucky
`submitBuckyFeedback`
Open a human-reviewed feedback form and submit it to the Bucky product team. Call only when the user explicitly asks to send feedback, report a problem, suggest an improvement, or praise something. The server asks the MCP client to show the form; nothing is saved unless the human accepts it. Do not use for silent agent self-reporting.
**Read-only:** no
**Parameters:**
- `submissionId` (string, optional) — Optional. A UUID for this submission; generated server-side when omitted. Pass the same UUID when retrying this exact feedback so it is not recorded twice.
- `affectedToolName` (string, optional) — Tool the user is commenting on, when already known
---
# MCP Tools
Source: https://docs.buckybuild.com/docs/mcp/tools
Bucky's MCP server exposes a deliberately narrow subset of the canonical Bucky
tool registry. Two tools are anonymous and cost nothing; the rest require
authentication and a scope.
| Tool | Scope | Effect |
| -------------------------- | ------------ | ----------------------------------------------- |
| `getBuckyMcpGuide` | none | Static guide to this surface |
| `explainFeasibilityStatus` | none | Static status lookup |
| `getFeasibilitySnapshot` | `mcp:read` | Site facts for an address |
| `getProjectContext` | `mcp:read` | Read a project and its analysis |
| `saveToProject` | `mcp:write` | Create a project; attach parcels or a reference |
| `updateProject` | `mcp:write` | Update project fields |
| `runFeasibilityAnalysis` | `mcp:write` | Start an analysis run on a project |
| `setProjectMapListing` | `mcp:write` | List or unlist a project on the public map |
| `produceProjectReport` | `mcp:export` | Render a report PDF; spends `records.exports` |
| `submitBuckyFeedback` | none | Human-reviewed product feedback |
A client that requests no scopes is granted `mcp`, which covers all three. Export
is separate because it is the only tool that spends a metered resource.
## Choose a workflow
- **Projects:** find a user's projects, load aggregate details, or retrieve the
compact memory digest used to resume project context.
- **Location:** resolve an address, find its geographic division, and inspect
nearby builds or sellers.
- **Marketplace:** search professional and service-provider records.
- **Knowledge:** use structured regulatory lookup when you have jurisdiction or
citation context, and semantic search for broader construction knowledge.
- **Feedback:** call `submitBuckyFeedback` only when the user explicitly asks to
report a problem, suggest an improvement, or send praise. Never use it for
silent agent self-reporting.
Tool names, parameters, return contracts, and the complete current inventory
are generated in the [MCP tool reference](/docs/mcp/reference).
## Product-only alternatives
Some canonical descriptions mention richer BuckyAssist tools. The generated
reference marks each such name as **BuckyAssist only; unavailable over MCP**.
An MCP client must not attempt to call those alternatives. Live map control
(`requestMapInteraction`, including `set-basemap` for streets vs satellite) is
Assist-only: this product MCP surface has no map chrome, and neither does the
Bucky CLI. Use `tools/list` as the runtime authority whenever client state and
documentation disagree.
## Boundary
Authenticated MCP writes are `saveToProject`, `updateProject`, `runFeasibilityAnalysis`,
and `produceProjectReport`. They preview with `preview=true` (report uses `preview` /
`confirm`). A write returns a receipt. `updateProject` can reverse from that receipt;
create, parcel attach, knowledge attach, analysis enqueue, and report export cannot
be undone on this surface. Archive, detach, delete, development programs, cost
ledger, location repair, and chat stay on the Bucky CLI — `getBuckyMcpGuide`
lists each unreachable workflow with its command.
---
# Platform
Source: https://docs.buckybuild.com/docs/platform
The Platform section explains the core entities that make up Bucky and how they
work together. If you've read [core concepts](/docs/getting-started/core-concepts),
this is the deeper dive.
For **Project Scout** and map exploration prompts, see
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist).
## A typical workflow
The entities are designed around one through-line — analyzing a piece of land and
deciding what to do with it:
1. **Scout on the map** — see [site exploration](/docs/platform/site-exploration) and
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist) to explore blocks, compare site
options, and read an early site summary.
2. **Create a project** — use **Review & create** to save your selection, or open an existing
project.
3. **Review zoning** to understand what's allowed on the parcel or assembly.
4. **Run feasibility** to see whether the project pencils out.
5. **Decide who sees it** — [people on a project](/docs/platform/people) before
you invite the firm.
6. **Engage services** to take a viable project forward.
Task-specific walkthroughs live in [Guides](/docs/guides) — start with [First week with your
team](/docs/guides/first-week-with-your-team) for a firm rollout, or [Prompting
BuckyAssist](/docs/guides/prompting-buckyassist) for map and chat prompts.
Developers and agents can reach the same entities over [MCP](/docs/mcp) or the
[CLI](/docs/cli) today; the HTTP [API](/docs/api) reference is not shipped yet.
---
# Feasibility
Source: https://docs.buckybuild.com/docs/platform/feasibility
**Feasibility** is the analysis of whether a project is viable on a given
[parcel](/docs/platform/parcels) under its [zoning](/docs/platform/zoning).
It's the step where the physical facts of the land and the rules that govern
it meet the numbers.
## What you do
On the Projects map, ask Project Scout to **assess development potential**,
or open the feasibility body after you frame a site. See
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist) for example
prompts.
## Site summary vs. full feasibility
**Project Scout** can produce a **Site summary** right after exploration — a
short brief with parcels, area, zone, and build-envelope hints. That's an
early read to decide whether a site is worth studying further. See
[site exploration](/docs/platform/site-exploration) for the full map
workflow.
The full **feasibility** panel on a framed site goes deeper: the structured
analysis you run once you're ready to judge viability on a specific
selection.
## What it considers
Feasibility brings together what Bucky already knows about a project:
- What the **parcel** physically allows — its size and shape.
- What its **zoning** permits, and the source status behind each limit — see
[Zoning](/docs/platform/zoning#what-you-see) for the full status table.
- How those combine into whether a given idea is workable.
Read the citation status behind each figure before you treat it as final. A
`cited` limit came from the bylaw; an `unverified_default` is indicative
only; some figures are a stated assumption rather than either. See
[Citations and confidence](/docs/resources/citations) for the difference and
what to verify.
## What it's not
Feasibility is decision support, not a permit, appraisal, or guarantee. It tells you whether an
idea is worth pursuing further, under human review — it does not replace detailed design,
engineering, or professional advice, and it is not a substitute for a jurisdiction's own approval
process.
## After feasibility
A project that looks viable is ready to move forward — which is where
[services](/docs/platform/services) come in: the people who can design and
build it. To hand the read to someone else, see
[how to read a feasibility report](/docs/guides/feasibility-report).
---
# Parcels
Source: https://docs.buckybuild.com/docs/platform/parcels
A **parcel** is the piece of land Bucky reasons about. It's the anchor for
almost everything else: zoning applies to a parcel, and feasibility is judged
on a parcel. When you ask "what can I build here?", _here_ is a parcel.
## What you do
Frame a parcel by searching an address, dropping a pin, or drawing an area on
the Projects map — including an **assembly** of multiple adjacent lots. See
[site exploration](/docs/platform/site-exploration).
## What you see
- **Geometry** — the parcel's boundary, which defines its shape and extent.
- **Dimensions** — measurements derived from that boundary, such as lot width
and depth, that matter for what can fit on the land.
- **Identifiers** — the reference a jurisdiction uses for the parcel. These
vary by region: much of the US uses a parcel identification number (PIN);
other jurisdictions use their own scheme.
## Source status
Parcel geometry and dimensions come from municipal or county land records
where Bucky has ingested them for that jurisdiction. Where a boundary or
dimension has no source on file, Bucky says so rather than estimating
silently — treat an unsourced figure as a starting point to verify, not a
survey. See [Citations and confidence](/docs/resources/citations) for how
Bucky distinguishes a sourced fact from an assumption.
Because every jurisdiction names land differently, Bucky surfaces the identifier that's meaningful
for a parcel's location rather than forcing a single global scheme.
## Why the parcel matters
The physical facts of a parcel — how big it is, what shape, where its
boundaries sit — combine with its [zoning](/docs/platform/zoning) to determine
what's buildable. That combination is exactly what
[feasibility](/docs/platform/feasibility) evaluates.
## Limits
- What's known about a parcel depends on the data available for its
jurisdiction. Coverage expands jurisdiction by jurisdiction — see
[Coverage](/docs/resources/coverage).
- Parcel geometry is a planning aid, not a survey. Confirm boundaries and
ownership with official records before you rely on them for a legal
purpose.
---
# People on a project
Source: https://docs.buckybuild.com/docs/platform/people
A [project](/docs/platform/projects) can name many people. Only some of them
get a Bucky login. Mixing those types is the usual source of “who do we add?”
confusion.
Use this page to choose the right type. For the first-week sequence, see
[First week with your team](/docs/guides/first-week-with-your-team).
## The four types
| Type | What they are | Login? | When to use |
| ------------------ | ---------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------- |
| **Team** | Collaborators on this project | Yes | They will work in Bucky — run analysis, edit, or administer the project. |
| **Partners** | Companies aligned to the project | No | An architect, builder, or other firm you may hire. Linking them does not grant access. |
| **Stakeholders** | People or organizations you are tracking | No | A planner, lender, neighbour, or other contact you need on the record. |
| **Share / viewer** | Someone who should _see_ the workspace | Viewer login, or a share link | A client or principal who needs the live project, not a seat to run it. |
Organization members are a fifth concept, and they are **not** a project type.
A company-account seat does not by itself put someone on a project.
Marketplace [services](/docs/platform/services) are how you later find people
to build. That is not “adding a party” on day one.
## Team (login access)
Team members appear on the project **Team** tab. Roles:
| Role in Bucky | What it means |
| ------------------------------------ | ----------------------------------------------------------------------- |
| **Owner** | Full control of the project, including who else is on it. |
| **Admin** | Can manage the project and its people. |
| **Service Provider** (`contributor`) | Can work on the project — analysis, notes, files — but is not an owner. |
| **Viewer** | Can see the project workspace. Cannot edit. |
Add a colleague to the team only if they will work in Bucky. If they only need
to read the site, invite them as a **viewer** or send a share link.
## Partners (companies, no login)
**Partner companies** are external firms on the project. Linking a company does
**not** grant login access. Use this when you want the relationship on the
project — an architect or builder you may hire — without giving them a
workspace yet.
Give that firm a seat later only if they need to work in the project.
## Stakeholders (tracked contacts, no login)
**Stakeholders** are people or organizations you track for due diligence. They
do not get a login. Parcel owners can appear here when Bucky already knows
them.
Use stakeholders for a planner, lender, neighbour, or anyone you need on the
record without inviting them into Bucky.
## Share links and viewer invites
Two ways to let someone _see_ the work without making them an operator:
- **Viewer invite** — they sign in and open the project as a viewer.
- **Share link** — they open a view of the project from a link.
Inviting a viewer or creating a share link is included with **Professional**.
You can still create and analyze the first project on a Personal plan; add
sharing when a client or colleague needs to see the live workspace.
## Organization members vs project members
| | Organization member | Project member |
| ----------- | -------------------------------- | ----------------------------- |
| Scope | The company account | One project |
| Grants | A seat in the firm | Access to that project |
| Typical use | Admins and staff of your company | The people on a specific site |
Adding someone to the company does not put them on every project. Adding
someone to a project does not make them an organization admin.
## What not to do on day one
- Do not invite the whole office.
- Do not give a login to every name on the deal.
- Do not treat marketplace discovery as a required first step.
Start with one champion and one project. Then decide who needs a seat. The
[first-week guide](/docs/guides/first-week-with-your-team) walks that path.
## Across the development
Parties are not a day-one roster. They attach to the **same project** as the
work moves:
| Stage | What you do in Bucky | Who you add |
| ----------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Screen** | Scout addresses, compare options, kill weak sites. | Champion only. |
| **Go / no-go** | Save the project. Read zoning and feasibility with citations. | Viewer or share link for a client or principal who needs the live read. |
| **Definition** | Scenarios, envelope, program, assumptions. | Team members who will work in Bucky. Owner as a stakeholder. |
| **Entitlement** | Approval path, cited memos, open questions for the next hearing. | Planner, neighbours, council contacts as **stakeholders**. Do not give the city a login. |
| **Team formation** | Link firms you may hire. Find [services](/docs/platform/services) when you are ready to build. | **Partner** companies (no login). A workspace only if they will work in the file. |
| **Toward shovel-ready** | The project stays the record of facts, assumptions, and decisions. | No new roster. Construction execution is not Bucky. |
Bucky is the pre-development record. It does not replace a construction PM
system once you are on site.
---
# Projects
Source: https://docs.buckybuild.com/docs/platform/projects
A **project** is the unit of work in Bucky. It's the container that holds
everything about a single planning effort — the parcel you're studying, the
zoning and feasibility analysis you run against it, the **site options** you
compare, and the services you engage to move it forward.
## Why projects exist
Planning a build involves many moving parts that only make sense together. A
project keeps them in one place so you can pick up where you left off, compare
options, and share a coherent picture rather than a pile of disconnected lookups.
## What a project holds
- **A parcel** — the property the project is about. See [parcels](/docs/platform/parcels).
- **Site options** — named candidate sites, often created from map exploration with
[Project Scout](/docs/guides/prompting-buckyassist). Before a project exists,
options on the map are **unsaved**; **Review & create** or **Save option** makes
them durable on the project.
- **Analysis** — the zoning interpretation and [feasibility](/docs/platform/feasibility)
work run against that parcel or option.
- **People** — the team with login access, partner companies, tracked
stakeholders, and anyone who only needs to see the workspace. See
[people on a project](/docs/platform/people).
- **Services** — the builders, designers, or architects engaged to take it
forward. See [services](/docs/platform/services).
## Working with projects
You can start from the **Projects map** — scout a block with Project Scout, compare
site options, then use **Review & create** to save a project from your selection.
See [site exploration](/docs/platform/site-exploration). Or open an existing
project and continue zoning and feasibility work in context.
From there the rest of the platform — [zoning](/docs/platform/zoning) and
[feasibility](/docs/platform/feasibility) — operates within the project's scope.
When you are ready to involve other people, start from
[people on a project](/docs/platform/people) rather than inviting the whole
firm.
For prompts on the map and in chat, see [Prompting
BuckyAssist](/docs/guides/prompting-buckyassist). Agents can read project context programmatically
over [MCP](/docs/mcp) today; the HTTP [API](/docs/api) reference is not shipped yet.
---
# Services
Source: https://docs.buckybuild.com/docs/platform/services
**Services** are the builders, designers, and architects discoverable through
Bucky's marketplace. Once a [project](/docs/platform/projects) has a
direction and looks [feasible](/docs/platform/feasibility), services are how
you connect it to the right team.
## Where this fits
Services are a **team-formation** step, not the reason a project starts. Most
projects move through screen → go/no-go → definition → entitlement before
team formation matters — see the stage table in
[people on a project](/docs/platform/people#across-the-development). Do not
treat marketplace discovery as a day-one requirement.
## What you do
From a project with a viable feasibility read, browse the marketplace for:
- **Builders** — the trades and contractors who do the construction.
- **Designers** — the people who shape how a project looks and functions.
- **Architects** — the specialists who handle architectural design.
Linking a firm as a [partner company](/docs/platform/people#partners-companies-no-login)
on the project does not by itself grant them a login — give them a workspace
seat only once they need to work in the file.
## Limits
What's available depends on the providers active in a given market. Coverage
and depth vary by market — this is a later-stage convenience, not a
guaranteed staffing outcome for every address.
---
# Site exploration
Source: https://docs.buckybuild.com/docs/platform/site-exploration
**Site exploration** is how you study land on the map before you commit to a
[project](/docs/platform/projects). **Project Scout** — BuckyAssist in the map
dock — runs guided explorations, compares options, and surfaces an early **Site
summary** so you can decide what is worth saving.
For copy-paste prompts, see [Prompting BuckyAssist](/docs/guides/prompting-buckyassist).
## Where it lives
Site exploration is available on the **Projects map** — the map inside your
projects workspace when you are studying land. It is not on the general
marketplace browse view.
Open the map, frame a site (search an address, drop a pin, or draw an area), then
use the **Project Scout** dock at the bottom of the feasibility panel. You can
also use **Ask Scout about …** from address search when you have a query typed
in.
## Frame a site on the map
Before Scout can assess a site, you usually frame it on the map:
- **Search** an address or place name.
- **Drop a pin** anywhere on the map.
- **Draw a polygon** to select parcels inside an area you define.
- Accept an **AI draft area** Scout suggests — it is marked **Not saved** until
you confirm it.
An **assembly** is multiple parcels combined for development (for example
adjacent lots). Scout and the map tools can work on single lots or assemblies.
## Explore, assess, and refine
The right-hand panel switches modes as you work:
| Mode | When | What you see |
| ----------- | ---------------------------- | ---------------------------------------------------------------------------------- |
| **Explore** | No site framed yet | Project Scout expanded — scout the map view or a block around an address |
| **Assess** | Site framed, Scout collapsed | Full [feasibility](/docs/platform/feasibility) body for the selection |
| **Refine** | Site framed, Scout open | Site summary strip plus Scout — dig deeper without losing an in-flight exploration |
## What Scout produces
When you ask Scout to explore or compare sites, you may see:
- **Map Exploration Plan** — a guided flow (focus map, preview a block, highlight
lots). Nothing is saved unless you choose **Review & create** or save a site
option on a project.
- **Site comparison** — when comparing two or more corridors or options, a table
with parcels, area, zones, and a verdict (Good / Review / Limited).
- **Site options** strip — session candidates labeled **Unsaved** (up to eight).
Flip between them on the map.
- **Site summary** — a short brief after exploration (parcels, area, zone, build
envelope hints). This is an early read, not the full feasibility report.
Exploration drafts and AI-suggested polygons are planning aids, not legal boundaries. Confirm
dimensions and ownership with official records.
## Unsaved vs saved site options
| State | Where | How it becomes durable |
| ----------- | ------------------------------------------- | -------------------------------------------------------------- |
| **Unsaved** | Site options strip on the map | Use **Review & create** to create a project and attach options |
| **Saved** | Inside a [project](/docs/platform/projects) | **Save option** from the site summary or Scout approval card |
**Saved site options** are named candidates you can reopen, rename, or archive
on a project. They often carry a linked feasibility analysis.
## Review & create
**Review & create** on the map toolbar is the main path to turn map work into a
project. It creates a project from your current selection and can carry unsaved
site options into that project.
Live municipal open data (permits, hydrants, parcel records, and similar) often
requires a saved project. If Scout shows **Save this site to unlock live city
data**, use **Review & create** first.
## How exploration connects to zoning and feasibility
1. **Explore** — Scout highlights lots and may show zoning layers on the map.
2. **Site summary** — early read of zone and build envelope for the selection.
3. **Assess** — full feasibility panel when you are ready to judge viability.
4. **Zoning detail** — ask Scout “What can I build here?” or “Review zoning” for
rule-level answers grounded in your jurisdiction. See [zoning](/docs/platform/zoning).
Scout on the map does not replace reading bylaws or hiring professionals — it
helps you decide which sites are worth studying further.
## What Scout does not do on the map
- **Browse the design catalog** — use main BuckyAssist chat for marketplace
designs and completed builds.
- **Book professionals** — discovery in chat; booking in the marketplace UI.
- **Corridor parcel discovery** — multi-street **comparison** is supported;
automated corridor-wide parcel discovery is not available yet.
---
# Zoning
Source: https://docs.buckybuild.com/docs/platform/zoning
**Zoning** is the set of rules a jurisdiction places on a parcel — what uses
are permitted and the limits that shape what can be built. It's usually the
first hard constraint on any project.
## What you do
On the Projects map, ask Project Scout **"What can I build here?"** or
**"Review zoning"** for a framed site. See
[site exploration](/docs/platform/site-exploration) and
[Prompting BuckyAssist](/docs/guides/prompting-buckyassist).
## What you see
Bucky returns the zone and its permitted uses, plus the limits that shape a
building envelope — height, storeys, site coverage, floor space ratio, and
front / rear / side / flanking setbacks. Every value carries a **status**:
| `status` | Meaning |
| ------------------------ | ---------------------------------------------------------------------------- |
| `cited` | Extracted from the bylaw. |
| `cited_conditional` | Resolved from a conditional rule that applies to this site. |
| `conditional_unresolved` | Conditional tiers exist; none resolve for this site. Unknown, not unlimited. |
| `no_limit_in_bylaw` | The bylaw sets no zone-level limit. A real answer. |
| `unverified_default` | A cached zoning value with no citation behind it. Indicative only. |
| `not_extracted` | Never extracted for this zone. Unknown. |
`no_limit_in_bylaw` and `not_extracted` can both show as an empty limit and
mean opposite things — one is a real answer, the other means Bucky does not
know yet. Read the status, not just the number. See
[Citations and confidence](/docs/resources/citations) for what each status
means for assumptions and what to verify before you rely on one.
## How to verify a value
Every `cited` and `cited_conditional` value links back to the bylaw section it
came from. Open that citation before you treat a setback or height limit as
final — Bucky interprets the bylaw, but the bylaw stays the source of truth.
Bucky's interpretation is anchored to the underlying bylaw text for a jurisdiction. As coverage
expands, more jurisdictions and rule types move from cached defaults to cited values.
## What it's not
A cited zoning answer is decision support, not a variance, permit, or legal
opinion. Confirm anything load-bearing to your decision with the jurisdiction
or a planner before you commit.
## How it fits
Zoning sits between a parcel and a decision: the parcel says what the land
_is_, zoning says what you're _allowed_ to do with it, and
[feasibility](/docs/platform/feasibility) says whether doing it actually
works.
---
# Resources
Source: https://docs.buckybuild.com/docs/resources
The Resources section holds the supporting pages that build trust and keep the
docs useful over time — the things that aren't tied to a single feature.
## Planned pages
- `architecture` — a high-level view of how Bucky fits together.
- `security` — data handling, auth model, and security posture.
- `changelog` — notable platform and docs changes.
---
# Citations and confidence
Source: https://docs.buckybuild.com/docs/resources/citations
"Cited" is doing a lot of work in these docs, so this page defines it once.
Bucky is not the only tool now claiming citation-backed answers — the honest
version of that claim is proving depth on a specific fact, not asserting it
for the product as a whole.
## Every fact carries a status, not just a value
A number without provenance is an opinion. Bucky attaches a status to zoning
and feasibility values so you can tell a sourced fact from a cached guess:
| Status | Meaning |
| ------------------------ | ---------------------------------------------------------------------------- |
| `cited` | Extracted from the bylaw. |
| `cited_conditional` | Resolved from a conditional rule that applies to this site. |
| `conditional_unresolved` | Conditional tiers exist; none resolve for this site. Unknown, not unlimited. |
| `no_limit_in_bylaw` | The bylaw sets no zone-level limit. A real answer. |
| `unverified_default` | A cached value with no citation behind it. Indicative only. |
| `not_extracted` | Never extracted for this zone. Unknown. |
You'll see this table applied on [Zoning](/docs/platform/zoning#what-you-see);
this page is the canonical definition and covers what the table doesn't:
assumptions, what to verify, and what "verified" would even mean.
## Assumptions are not citations
Some feasibility figures are not extracted from a bylaw at all — they're a
declared assumption Bucky used to produce a number where no cited value
exists (for example, a typical setback pattern for a zone with
`not_extracted` values). An assumption is not a hidden default: it should be
visible on the result, not baked silently into the math.
Read the difference before you act on a figure:
- **Cited** — traceable to a specific bylaw section.
- **Assumption** — Bucky's stated placeholder, used because nothing is cited yet.
- **Unverified default** — a cached figure carried from another source, no
citation attached.
Only the first is a fact you can defend without further work.
## How to inspect a citation
Every `cited` and `cited_conditional` value links back to the bylaw section
it came from. Open it. The citation is what makes the value checkable — that
is the entire point of citing it, not a formality to skip.
## What to verify next
Before a `cited_conditional`, `conditional_unresolved`, or `unverified_default`
value goes into a decision, a deliverable, or a hearing:
- **`conditional_unresolved`** — confirm with the jurisdiction which
conditional tier actually applies to your site; Bucky flags the ambiguity,
it does not resolve it for you.
- **`unverified_default`** — treat it as a planning estimate and check it
against the current bylaw or a local professional before relying on it.
- **`not_extracted`** — Bucky does not know yet. That is not the same as "no
limit" — see [Zoning](/docs/platform/zoning#what-you-see).
## What "verified" would mean
Bucky does not currently mark any fact `verified`, and does not use the word
for a person, fact, or output without stating the standard behind it. If that
changes, this page will say what verification means and who performed it —
not just apply the label.
## Where this shows up
- [Parcels](/docs/platform/parcels) — geometry and dimensions carry the same
sourced-vs-unsourced distinction.
- [Zoning](/docs/platform/zoning) — the primary home of the status table above.
- [Feasibility](/docs/platform/feasibility) — combines cited and assumed
values; read the status behind each input before trusting the output.
- [Coverage](/docs/resources/coverage) — the jurisdiction-level status that
determines whether any of this applies to an address at all.
- [How to read and export a feasibility report](/docs/guides/feasibility-report) —
a deliverable carries these statuses forward; it does not upgrade them.
---
# Coverage
Source: https://docs.buckybuild.com/docs/resources/coverage
"Your data will not be right in my market" is the objection Bucky hears most
from teams that work in one place and know it well. This page explains what
coverage means for an address, so you can check it instead of guessing.
## Coverage is explicit, not assumed
Bucky does not claim universal coverage, and it does not silently guess when
it doesn't have a jurisdiction. Every address resolves to a coverage status
you can see:
| Status | Meaning |
| --------------------------- | -------------------------------------------------------------------- |
| `live` | The address's jurisdiction is seeded and answering from source data. |
| `live_unavailable` | The jurisdiction is live, but this specific answer isn't available. |
| `planned_not_live` | The jurisdiction is on the roadmap; not seeded yet. |
| `geo_division_uncatalogued` | Bucky can't yet place the address in a known jurisdiction. |
| `unseeded_place` | The place itself has not been seeded. |
| `geocode_failed` | The address couldn't be resolved to a location at all. |
When an address falls outside coverage, Bucky still tells you why — it does
not return an empty or misleading result.
## Why this matters more than a city count
Coverage breadth is easy to claim and hard to verify — competitors publish
tens of thousands of cities without a public list or a way to check one. Bucky
takes the opposite approach: an explicit status per address, and a citation
per fact once a jurisdiction is live. See
[Zoning](/docs/platform/zoning#what-you-see) for how that shows up at the rule
level.
Depth in a jurisdiction also varies. A `live` jurisdiction can still have
individual zones or rule types that are `unverified_default` or
`not_extracted` rather than `cited` — check the status on the specific answer
you need, not just whether the city is "in."
## How to check coverage for your market
1. Run a project on one address you already know in your market.
2. Read the coverage status and the per-fact status on the zoning and
feasibility results.
3. Treat `cited` and `cited_conditional` values as sourced; treat
`unverified_default` and anything outside coverage as a starting point to
verify, not a final answer.
## What Bucky will not claim
Bucky does not publish a target city count or promise coverage in a market
it hasn't seeded. New jurisdictions are added over time; if your market isn't
live yet, the honest answer is `planned_not_live` or `unseeded_place`, not a
guess dressed up as a result.
---
# FAQ
Source: https://docs.buckybuild.com/docs/resources/faq
These answers use the language people bring to a first conversation. Deeper
how-to lives in [People on a project](/docs/platform/people) and
[First week with your team](/docs/guides/first-week-with-your-team).
## How do we actually use this?
The same [project](/docs/platform/projects) carries the site from first look
through entitlement and team formation.
**Week one:** one address you already know. Bucky pulls the parcel, zoning, and
overlays. You read [feasibility](/docs/platform/feasibility) and share the read
if someone else needs to see it.
**After that:** screening, go/no-go, definition, entitlement, and who you hire
all stay on that file. Parties join when the stage needs them — not as a
day-one roster. See [people on a project](/docs/platform/people#across-the-development).
Bucky is the pre-development record, not the construction job site. The
[quickstart](/docs/getting-started/quickstart) is the firm starting path.
## Who gets added to a project?
You first. Then only the people who need a seat or a view:
- **Team** — colleagues who will work in Bucky.
- **Viewer or share link** — a client or principal who should see the workspace.
- **Stakeholder** — a planner, lender, or neighbour you track (no login).
- **Partner company** — a firm you may hire (no login until they need a workspace).
Do not add the whole office on day one. They join by stage — a viewer at
go/no-go, a stakeholder at entitlement, a partner when you hire. See
[people on a project](/docs/platform/people).
## Don't I already have an analyst, broker, planner, or consultant who does this?
Yes, and Bucky doesn't replace their judgment. It gives that expert a
reusable, sourced starting point instead of a blank spreadsheet — so their
time goes to the calls that need a human, not to re-deriving parcel and
zoning facts on every site. See [feasibility](/docs/platform/feasibility).
## Will your data be right for my market? We work in one city and we know it.
Coverage expands jurisdiction by jurisdiction, and Bucky shows what's
[cited, cached, or missing](/docs/platform/zoning#what-you-see) for an address
rather than promising universal coverage. Check a site you already know
before trusting one you don't. See [Coverage](/docs/resources/coverage).
## Who is liable if the data is wrong?
Bucky is decision support, not a permit, appraisal, or legal opinion. Every
zoning and feasibility value carries a status so you can see what's sourced
from the bylaw and what still needs verification before you rely on it. See
[Citations and confidence](/docs/resources/citations).
## We already use GIS, spreadsheets, or a data provider — why add this?
Those tools stay useful. Bucky connects the work that starts at the address
and carries it through zoning and feasibility to a
[deliverable](/docs/guides/feasibility-report), instead of living as one more
disconnected lookup.
## Won't this cut into billable hours or proprietary process?
Bucky doesn't charge per report, so screening more sites doesn't cost more
than screening one. Killing a weak site in week one is cheaper than
discovering it is weak in week six — the hours that frees up go to judgment,
design, and client service, not to re-running diligence you've already paid
for once.
## Is the subscription worth it for my volume?
Run it on one address you already know before judging it against your
volume — the [quickstart](/docs/getting-started/quickstart) is built for
exactly that, not a feature tour.
## What's the best way to roll this out?
One champion, one live project, then one invite. Week two is when you decide
whether anyone else needs a seat. After that, deploy means **the same project
through the development** — not a firm-wide IT rollout, and not MCP or the
API.
Walk the first week in
[First week with your team](/docs/guides/first-week-with-your-team). The stage
map is on [people on a project](/docs/platform/people#across-the-development).