# The day-one stack plan

`npx create-bucker --stack` reads your repository and produces one plan for the whole app instead of
one SDK: the SDK and what it needs, a monitor for every scheduled job it can read without guessing,
an HTTPS check on your production URL, a **draft** status page, and a starter alert to the two
people you name. It tells you what the plan will cost a month before anything is applied, and it ends
in a signed receipt with one line per signal.

```bash
# What a coding agent runs: prints the plan and stops. No DSN, no token, no network.
npx create-bucker --stack --json --dry-run \
  --url https://app.example.com --notify you@example.com --notify them@example.com

# What you run, after reading it:
npx create-bucker --stack --token "$BUCKER_TOKEN" --org acme --project shop \
  --notify you@example.com --notify them@example.com \
  --approve <the plan's bucker.batchDigest>
```

## What it finds

| Source | Read from | Becomes |
| --- | --- | --- |
| Vercel Cron | `vercel.json` `crons` | a cron monitor (UTC) |
| GitHub Actions | `.github/workflows/*.yml` `on: schedule:` | a cron monitor (UTC) |
| node-cron | `cron.schedule('…')` in a file that imports `node-cron` | a cron monitor |
| BullMQ | `pattern` / `every` in `upsertJobScheduler` or `repeat` | a cron or interval monitor |

It never invents a schedule. A job is **found, not monitored**, with the reason printed, when its
expression is a six-field cron (a seconds field), a macro such as `@daily`, a variable or a template
instead of a string, or when its timezone is not a literal; and a `schedule()` call in a file that
does not use `node-cron` is not read as a cron at all.

The production URL comes from `--url` or `package.json` `homepage`, and only when it is `https` on a
public host. A loopback, private-network, bare-IP or `.internal` name is refused with the reason,
because the check runs from Bucker's address towards that host. The plan keeps the origin and path
and drops any query string.

## What it costs

The plan prices itself from the weights register, in the same units your usage page shows.
HTTP-class and cron checks are **unmetered** (weight 0, never upsold). A cron check-in is an
internal request: 0 units in the ledger, and the one-unit floor at the accept decision, so the plan
states both numbers. The SDK's own volume depends on your traffic and is shown as such until you pass
`--errors-per-day`; one error is one unit.

## Two halves, reviewed separately

- **The repository half** is the installer you already know (`create-bucker`'s plan, with a diff for
  every file and a stop on a dirty tree). You commit it.
- **The Bucker half** is a list of creations in your account (cron monitors, the URL check, the
  e-mail channels for the two people, the alert rule, the draft status page) under **one digest**.
  You approve it once: `--approve <digest>` binds exactly what you read (a plan that changed since
  has a different digest and is refused), or answer the prompt at a terminal. `--yes` does not approve
  it: that flag is about edits to your own code. Re-running adopts what already exists.

Publishing the status page is never a step: it is yours to do, from the dashboard. Deleting anything
is never a step either; the receipt lists what the plan created so you can remove it.

The Vercel half (drains, deploy webhooks and `BUCKER_DSN` in the Vercel environment) waits for the
Vercel marketplace integration and is listed in the plan as **not available**.

## The receipt

After applying, the tool reports which signals the plan named and the **server** decides what each
one's status is from what exists in your project:

| Status | Meaning |
| --- | --- |
| `installed` | the object exists (the monitor, the check, the page, the rule, or the SDK receipt) |
| `first_event_seen` | it has produced something: a check-in, a probe result, a real issue |
| `not_seen` | not there yet, or there and silent |
| `skipped` | the plan found it and did not plan it (a six-field cron, no URL, nobody to alert) |

The server signs one `stack_receipt` claim into your organization's receipt log. It carries ids,
statuses and times, never a path, URL, schedule or address, and `bucker-verify verify-log` checks it
offline. A cron that has not ticked yet reads `installed`; run `create-bucker --stack --receipt-only`
after it has to file a fresh receipt (the old one stays in the log). Read the newest with
`GET /orgs/:org/projects/:project/stack-receipt`.

## What the coding-agent run never sees

`--json --dry-run` makes no network call and needs neither a DSN nor a token; every line it prints
passes the output guard that redacts DSN- and token-shaped strings, and the addresses you name appear
masked (`a***@example.com`). The DSN is written to your env file by the installer and never printed.
