matthewwong525/WongStack / .agents/skills/wong-setup
wong-setup
UnverifiedEvaluate or install WongStack from any folder, Cloudflare hosting included, from one token. Installed repos use /wong-sync.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.2 KB |
| references/cloudflare.md | markdown | 20.1 KB |
| references/failure-map.md | markdown | 6.9 KB |
| references/permission-groups.md | markdown | 6.6 KB |
| references/seed/gitignore | other | 350 B |
| references/seed/wiki-README.md | markdown | 569 B |
| references/seed/wiki-development-README.md | markdown | 1.3 KB |
| references/tools.md | markdown | 10.3 KB |
| scripts/install.mjs | script | 10.1 KB |
| scripts/lib/cloudflare.mjs | script | 13.5 KB |
| scripts/memory-schedule.mjs | script | 4.0 KB |
| scripts/private-access.mjs | script | 24.2 KB |
| scripts/provision.mjs | script | 77.8 KB |
references/cloudflare.md
View on GitHub# Provision Cloudflare
This runbook turns a fresh install into a running app with session memory. [`/wong-setup`](../SKILL.md) runs Step 1 before it plans the install, `/apply` runs Steps 2–5 after the payload lands, and `/wong-sync` follows the parts an update adds.
**Idempotent.** Reuse existing owned resources; resume a stopped run from the top.
**Write for someone who does not know what a database is**, in [plain words](../../../plugins/loop/skills/explore/references/asking-the-user.md#write-in-plain-words): name outcomes and the one fix, and explain `D1`, `binding`, or `9109` instead of saying them.
## Boundaries
- **No commits or pushes.** Step 1a makes the GitHub repository; everything else lands uncommitted for `/save`. The exceptions: one empty first commit on company knowledge's `main`, and on the Artifacts route the project's.
- **One script does the Cloudflare work, not `wrangler`**, so no app dependency is needed: [`provision.mjs`](../scripts/provision.mjs), in the source checkout, needs only Node ([required tools](../../../../wiki/development/required-tools.md)). Each command prints one JSON report: created, reused, names, URLs. A stop exits 1 with `error.reason` (`token`, `cloudflare`, or `repo`) and a plain `error.cause`; translate it with the [failure map](failure-map.md).
- **Never print a token value**: not in a summary, an error, or an echoed command.
- **The user token stays on the host**, only in the primary worktree's `.env`. No step copies it or makes it a GitHub secret.
- **Ask before creating or deleting anything billable**, as [a choice with a recommendation](../../../plugins/loop/skills/explore/references/asking-the-user.md): say what you will make, then make it.
- **[The Artifacts route](../../../../wiki/stack/artifacts-route.md#setup)** owns its changes to Steps 1a, 2, 4 and 5, and its teardown.
- **The widen and the mints are [pre-authorized](../../../../wiki/stack/cloudflare-credentials.md#the-widen-is-pre-authorized):** do them, then report them.
## Step 1 — the credential
### 1a. The GitHub repository
Step 4d sets a secret on the repository, so check GitHub first, before any Cloudflare call:
```bash
gh auth status
[ -e .git ] || git init -b main
git remote get-url origin || gh repo create "$(basename "$PWD")" --private --source . --remote origin
```
- **`gh auth status` fails** → the person signed out since setup. **Stop before any Cloudflare call**, create nothing, and rerun [the GitHub sign-in](tools.md#2-the-github-sign-in).
- **`origin` exists** → use it; create nothing.
### 1b. Make the file, not the user
Resolve the durable credential file before accepting a value, by [the secrets convention](../../../../wiki/development/secrets.md#the-two-files), through the source checkout's [shared lookup](../../../plugins/memory/scripts/lib/primary-root.mjs) (the target has no skills yet), never from a hosting tool's folder names.
```bash
ACTIVE_ROOT=$(git rev-parse --show-toplevel)
PRIMARY_ROOT=$(node "<source checkout>/.agents/skills/memory/scripts/lib/primary-root.mjs")
DURABLE_ENV="$PRIMARY_ROOT/.env"
ACTIVE_ENV="$ACTIVE_ROOT/.env"
```
A non-zero exit → stop **before** asking for the token: the primary worktree couldn't be found safely. Never fall back to the linked checkout.
Confirm Git ignores the destination: `git -C "$PRIMARY_ROOT" check-ignore -q .env`. In a fresh folder, first add the `.env*` / `!.env.example` and `.dev.vars*` / `!.dev.vars.example` pairs to the file `git rev-parse --path-format=absolute --git-path info/exclude` returns, then re-check; the install still commits the `.gitignore` fragment. A failed re-check → stop before accepting a secret.
No `DURABLE_ENV` → create it with the blank `CLOUDFLARE_*` lines from the source's [`.env.example`](../../../../.env.example) and say: *"I made a private `.env` file. Git ignores it, so its values stay on this machine."* When `ACTIVE_ROOT` is not `PRIMARY_ROOT` and `ACTIVE_ENV` is a regular file, not a symlink, [leave both files untouched](../../../../wiki/development/secrets.md#unseeded-linked-worktree-copies): never read, compare, or merge them. Say: *"This worktree has its own `.env` too. I use the primary copy and left the other untouched."*
Later `.env` means `DURABLE_ENV`; replace or append only the exact `KEY=` line.
### 1c. Ask for the token
If `CLOUDFLARE_API_TOKEN` in `DURABLE_ENV` is empty, ask for it with the filled-in token link from [the credentials page](../../../../wiki/stack/cloudflare-credentials.md#create-the-token), read from that page rather than copied here: open it, check the two rows, Create, copy. If the link fails, give the page's click path, calling out **Account Resources**, the field people miss. Say what it is for: *"This token stays on this computer. I use it to set up your hosting and to make a smaller token for automatic publishing."*
They paste it into the durable file, or to you to write. Re-read `DURABLE_ENV`; export the value unprinted. **No token → setup stops here and writes nothing else**; pasting it later continues from this step.
### 1d. Verify before doing anything
```bash
curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
https://api.cloudflare.com/client/v4/user/tokens/verify
```
Success returns the token's own `id`. **Translate every failure** with the [failure map](failure-map.md): the cause and the one fix, never `9109` or `Invalid API Token` as the headline.
## Step 2 — the token widens itself
From the target's root, with `CLOUDFLARE_API_TOKEN` exported from `DURABLE_ENV`:
```bash
P() { node "<source checkout>/.agents/skills/wong-setup/scripts/provision.mjs" "$@"; }
P widen
```
It runs [the widen protocol](permission-groups.md): [a normal provision](permission-groups.md#a-normal-provision), plus company knowledge's repository and a read of the plan. Tell the user what its `granted` list names.
## Step 3 — which account
```bash
P accounts
```
- **Exactly one** → use it, and say which.
- **More than one** → **stop and ask**, offering each by name and id, and **create nothing until the user picks.** Never infer it from the repo name, the email, or the API's order.
- **Zero, with a valid token** → the Account Resources miss ([failure map](failure-map.md)). Explain, offer to re-check after they save it; create nothing.
Write the chosen id to `CLOUDFLARE_ACCOUNT_ID` in `DURABLE_ENV` and export it.
Then `P plan`. `"reason": "free-plan"` → **create nothing** and ask, as [a choice](../../../plugins/loop/skills/explore/references/asking-the-user.md): *"Every install needs Cloudflare's paid plan, about $5 a month. Turn it on and I'll continue, or stop here."*
## Step 4 — provision
Ask once before the billable parts, as [a two-option choice](../../../plugins/loop/skills/explore/references/asking-the-user.md): *"Set it up (Recommended) — your private memory store, a real database and a practice one, and automatic publishing"* or *"Stop here — nothing is created on Cloudflare"*.
### 4a. Name things; don't ask
The script derives every name from the repository's and checks it; state them, never make the user invent one:
```bash
P names --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)"
```
The report's `checked` list marks each name `free`, `ours` (this repo's, from before), or `taken`. Name any `taken` one and offer the report's `base`, the first suffix freeing every name, such as `recipe-box-2`.
Apply the id-free fragments now (the `package.json` scripts, `.env.example` variables, and `.gitignore` entries) from [`stack-pack-fragments.md`](../../wong-sync/references/stack-pack-fragments.md). No copied payload file may carry a database name, so the script fills `db:migrate:staging` and `db:migrate:prod` with real names in 4c.
After the one ask, one command runs 4b through 4d:
```bash
P provision --repo <owner/name> --base <base> --owner-email <reachable-owner-email> --open-without-login
```
Resolve a reachable owner email before provisioning; reject `.invalid` and GitHub noreply addresses. The git author email may remain private. Private setup reuses or creates Zero Trust/PIN and unavailable Workers, then gives each its own app before any content publishes. Review overlapping apps first; keep unrelated ones. Machine credentials go to ignored `.env`; public ids to `components.access`. See [Access](../../../../wiki/stack/cloudflare-access.md).
**Open until the card.** When Cloudflare wants a card before it turns on Zero Trust, `--open-without-login` lets setup finish: the report's `access.mode` is `open`, no Access resources are made, and the config carries `WORKSPACE_LOGIN: "off"` ([open until the card](../../../../wiki/stack/cloudflare-access.md#open-until-the-card)). Say it plainly and go on: *"Cloudflare wants a card on file before it turns on the private email login, so for now anyone with your site's link can see it. Your memory stays private behind its own key until then. I'll show you how to add the card at the end."* Any other Access stop still stops setup; an already private site never opens.
### 4b. The memory store
[The memory convention](../../../../wiki/development/memory.md) owns what it holds, who reads it, and why only the production Worker binds it; it has no staging twin.
1. **Is R2 on?** A bucket-list error saying to enable R2 means no; the report says `"r2": false`. No token can turn R2 on ([without R2](../../../../wiki/development/memory.md#without-r2)), so continue without a bucket, and let [the card list](#the-card-list) at the close give the steps: *"Memory works without it; it just won't keep full session transcripts until R2 is on."*
2. **The database.** It reuses or creates `<repo>-memory`.
3. **The bucket, only when R2 is on.** It reuses or creates `<repo>-memory`, never with public access.
4. **Record.** It writes `components.memory` in `.claude/.wong-stack.json`: `accountId`, `databaseId`, `database`, `bucket` (or `null`), and the memory URL as `worker`, `https://<worker>.<subdomain>.workers.dev/_memory`. An account with no `workers.dev` subdomain gets one named for the GitHub owner. It also records the production origin under `components.companyApi.origin`, using the account hostname read back; [company actions](../../../../wiki/stack/company-api.md) owns employee access. None is secret.
5. **Apply the schema.** It runs the target's `memory.mjs migrate` with `CLOUDFLARE_API_TOKEN`, retrying while the new store takes effect. Historical authors and raw references remain unchanged.
6. **No memory key.** Memory uses the owner's company sign-in, made at [4g](#4g-smoke-test-what-you-built); teammates get theirs from Connect. Only an open site, which has no sign-in yet, runs `memory.mjs member admin` for this computer's admin key in the primary ignored `.env`; never print it or make it a CI secret.
Memory answers once CI deploys production; until then facts wait in the local spool. By hand, the memory commands are `$M`, with `M="node $(git rev-parse --show-toplevel)/.claude/skills/memory/scripts/memory.mjs"`.
**Re-runs.** A store that verifies is current. One with no bucket, on an account now with R2, gets one: the script creates and records it, adds `MEMORY_BUCKET` to the production config, and gives `<repo>-deploy` the R2 row of [the CI deploy token table](permission-groups.md#the-ci-deploy-token). The key stays. Make by hand any edit the report's `todo` lists.
**Moving an older store.** The update adds the production route, login callback, bindings, and install record. After the deploy, run `$M migrate`, sign the owner in as in [4g](#4g-smoke-test-what-you-built), run `$M migrate-people` to give each linked computer's notes to its person, and check `$M digest`. Notes from an unlinked computer wait for an admin; a failure pauses memory. Retire an old memory token only after this succeeds; never restore an email-only Worker after private machine writes.
### 4c. The two app databases and the config
Create/reuse distinct production and staging databases; branch deploys never write real data.
With no config, write the [fragment](../../wong-sync/references/stack-pack-fragments.md) with actual production/staging D1 and Access IDs; an open site gets blank Access IDs and `WORKSPACE_LOGIN: "off"` instead. Bind memory only at the top level, plus R2 when available. Fill the two `db:migrate:*` scripts. Preserve the fragment's entry point, assets, flags, and date. Existing config stays apart from a new memory bucket and [adding the card later](#adding-the-card-later); plan other privacy updates as a reviewed merge. The [scaffold](../../wong-sync/references/payload-manifest.md#the-app-scaffold) supplies the Worker.
**The project Connect hands out.** The script names it in both Workers' vars; the Artifacts route binds production alone to it and its check runner, with no key. On GitHub the report's `codeKey` carries [the owner's steps](../../../../wiki/stack/project-git-route.md#the-owners-one-step-on-github). Say nothing of it: Access asks for the key when the owner first lets someone install the project.
**Company knowledge.** The script makes `<base>-knowledge` with one empty commit, records it, and binds only the live app to it; it never changes one that holds pages.
Last, it refreshes the binding types in `app/`; a failure is a `warnings` line, no stop.
The same Worker serves the [mini apps](../../../../wiki/stack/mini-apps.md) under `/apps/`; they need no Worker or config of their own.
**Moving older mini apps.** [The update's catch-up step](../../wong-sync/references/catch-up.md) `mini-apps-folder` moves them in, with the old mini-app Worker's `/apps/` routing, as reviewed changes. Delete the old `<repo>-mini` and `<repo>-mini-staging` Workers and `staging-mini` environment only after production serves `/apps/` and every app.
### 4d. The CI deploy token
CI gets its own narrow token, never the user token ([why](../../../../wiki/stack/cloudflare-credentials.md#the-ci-deploy-token)). The script pipes every value to `gh secret set` on stdin, never an argument, a file, or the terminal.
- **No `<repo>-deploy` token** → it creates one with [the CI deploy token table](permission-groups.md#the-ci-deploy-token)'s `always` rows, plus the R2 row only when the store has a bucket, and sets it as the `CLOUDFLARE_DEPLOY_TOKEN` secret.
- **Token and `CLOUDFLARE_DEPLOY_TOKEN` secret both exist** (`gh secret list`) → current; it only adds a row now needed.
- **The token exists, the secret doesn't** → it rolls the value and sets the secret. To rotate on request, run `gh secret delete CLOUDFLARE_DEPLOY_TOKEN`, then the script again.
- **An old `CLOUDFLARE_API_TOKEN` secret** → deleted for good once the new one is set, unless a workflow still reads it: then a `todo`.
It sets a missing `CLOUDFLARE_ACCOUNT_ID` too. `gh secret set` needs only the `repo` scope from `gh auth login`. It can publish app/data changes and read Access, never write it.
**The pair of locks for keys.** Then run `node scripts/seal-keys.mjs pair` once. It puts the private half where publishing runs, as `WONG_KEY_SEAL_PRIVATE`: a GitHub secret, or the check runner's secret on the Artifacts route. Then it writes the public half in `app/wrangler.jsonc`. Keys sent to the app then [wait sealed for the next publish](../../../../wiki/stack/connect-your-tools.md#how-a-key-reaches-the-app). Run it again only to make a new pair.
### 4e. The workflow
Confirm `.github/workflows/test.yml`, `.github/workflows/deploy.yml`, and `.nvmrc` landed; [the pipeline scripts own every deploy decision](../../../../wiki/stack/github-actions.md).
Missing `workflow` scope → offer `gh auth refresh --scopes workflow` ([why](../../../../wiki/development/required-tools.md#gh-needs-the-workflow-scope)).
### 4f. First deploy
The workflow deploys on push, so the first deploy comes with `/save`'s push; never push from here. Diagnose a red build with `gh run view --log-failed`.
Use the report's production URL. Treat preview URLs as patterns until CI returns an actual deployed URL ([discovery](../../../../wiki/stack/d1-pipeline.md#how-the-alias-url-reaches-the-tooling)).
### 4g. Smoke-test what you built
After `/save` reports the first deploy, fetch the production URL once; never report a URL you did not fetch.
The check runs itself; never ask the person to sign in by email code on each site:
- **Private site:** run `node scripts/probe-private-access.mjs --url <url>` on production, and with `--preview` on a preview. Expect anonymous closed, machine `2xx`.
- **Open site** (`access.mode` is `open`): fetch production and expect `200`.
Retry propagation; name a real failure. Human login stays unverified until Step 5's human check. The [browser runbook](../../../../wiki/stack/cloudflare-access.md#verify-it-works--in-a-browser) is for `/verify` and later changes, not setup.
Once production has deployed, sign the owner in once on a private site: run `node scripts/company-api.mjs login --origin <production URL>` in the background, show the link it prints in the chat, and wait. Then check memory with `$M digest`, and make the `knowledge/` copy with `node .claude/memory/knowledge.mjs update`. Before the deploy, both say the app does not answer. Without `cloudflared`, skip these; say memory and knowledge wait.
## Step 5 — the closing report
State, in plain words:
- Session memory: on, with or without transcripts, only when 4g's digest answered. Otherwise: *"Memory starts once your site first goes live; until then, what I learn waits on this computer."*
- The production URL, and the preview pattern with one branch filled in
- What was created, and what was reused
- *"This costs about $5 a month, for Cloudflare's paid plan."*
- What the user token was granted, that it stays in `.env` on this computer, and that it can be [narrowed back](../../../../wiki/stack/cloudflare-credentials.md#narrowing-back)
- That CI publishes with its own small key, `<repo>-deploy`
- Private coverage, machine access, and human login as separate outcomes. An open site says instead: *"Anyone with the link can see your site."*
- When the target is not the open folder: its path, and *"Next time, open <target> in your assistant to chat."*
- When `command -v paseo` answers: how to chat from a phone, *"In Paseo, open Settings → your host → Pair Device."*
- The optional card list below, when the site is open or `r2` is `false`.
Use `appUrl` for normal login. Check stored issuer/subject before claiming association; a paste alone proves only login. Report an unavailable association link plainly. **The human check** is 4g's owner sign-in, or the person reporting their app from the production link: after either, report human login verified; staging and previews need none. A finished install then runs the target's `connect` skill (*skip* skips it), then offers a first app on the tools that work, like the site's *Make it yours* request. On a no, end on the URL; the site's box starts it later.
### The card list
One list owns these steps; [without R2](../../../../wiki/development/memory.md#without-r2) and [open until the card](../../../../wiki/stack/cloudflare-access.md#open-until-the-card) link here. Fill in the account id, and show only the steps still missing: the storage step when `r2` is `false`, the login step when the site is open, and the card step with either.
```text
Optional: add a card to Cloudflare
Without it, anyone with the link can see your site, and
memory keeps no full chat transcripts or preview pictures.
1. Add a card https://dash.cloudflare.com/<account>/billing/payment-info
2. Turn on storage https://dash.cloudflare.com/<account>/r2/overview
3. Pick Free plan https://one.dash.cloudflare.com/<account>/
Tell me when it's done.
```
Name only what the missing steps cost: an account with R2 but an open site loses no transcripts, though a check's pictures wait for the login. The person opens the links in their own browser; never enter the card for them.
## Adding the card later
Once the card is on, rerun [Step 4](#step-4--provision)'s `provision` command, flags and all. It turns on the private login, when Zero Trust answers, and the memory bucket, when R2 is on. It fills `app/wrangler.jsonc`'s `CF_ACCESS_*` ids, removes `WORKSPACE_LOGIN`, adds `MEMORY_BUCKET`, and turns the memory key off: memory then uses the app's sign-in. Hand-make any edit its `todo` lists.
Then publish through `/save`, and once it deploys, run 4g's private check. If the report still says `open`, Zero Trust still wants its plan picked: send the list's step 3 again.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |