@blocofy/cli 0.9.0 → 0.11.0

package/README.md

@@ -10,63 +10,487 @@ cd path/to/theme
 npx @blocofy/cli theme dev       # http://localhost:3030 — local theme + live data, livereload
 ```
 
+`login` saves the site under a named **context** (default: the site's slug) in
+`~/.blocofy/credentials.json`. `blocofy link <dir> --context <name>` (or a pull into an empty
+directory) then binds a project directory to that site so every command run inside it always
+targets the right one — see [Contexts and project binding](#contexts-and-project-binding).
+
 ## Commands
 
-```bash
-blocofy login [--url <url>] [--token <bcf_…>]
-                          # Save your platform URL + dev token (~/.blocofy/credentials.json, 0600).
-blocofy theme dev [dir]   # Local dev server. Prints 3 views — local preview, a live-domain
-                          # preview link, and the theme editor — all auto-reloading on save.
-                          # --port <n> (default 3030), --no-sync (local preview only),
-                          # --name <name> (name the draft when first created)
-blocofy theme pull [dir]  # Download the live theme to disk.
-blocofy theme push [dir]  # Write the local theme to a DRAFT by default (create/update; no
-                          # delete) — preview & publish from the admin panel. --live writes
-                          # to the live site immediately (asks to confirm; add --yes for CI).
-                          # --name <name> names the new draft (draft mode only).
-                          # --prune also removes target files deleted locally (lists them
-                          # first; on the live theme asks to confirm — --yes for CI).
-blocofy theme rename <handle> <new name>
-                          # Rename a theme (label only). Works on any theme, live included.
-                          # Handle from the panel theme card or `blocofy status`.
-blocofy login --api-key [--api-url <url>]
-                          # Save a v1 API key (blcf_live_…) for the `pages media-*` commands.
-                          # The flag takes NO value: the key is typed into a hidden prompt, so
-                          # it never lands in argv or shell history. Non-interactive shells use
-                          # BLOCOFY_API_KEY + BLOCOFY_API_URL instead (no prompt, nothing
-                          # written without them). --api-url defaults to https://app.blocofy.com.
-blocofy pages media-uses <page-handle> [--json]
-                          # List a page's localized-media decisions on its newest draft
-                          # (v1 API, pages:read) with the draft revision id/version.
-blocofy pages media-decide <page-handle> --decisions <file.json>
-                          [--expected-revision-id <n> --expected-version <n>] [--json]
-                          # Apply the file's { "decisions": [...] } (max 20) to the draft
-                          # atomically (v1 API, pages:write). Without the --expected-* pair
-                          # the CLI GETs the draft first and uses its current revision;
-                          # items without idempotency_key get a random UUID. Exit 0 applied
-                          # (or "No changes" when already recorded), 1 usage/auth/network/5xx
-                          # (no retry), 2 server refusal (4xx) — {error} JSON on stderr.
+### Login & contexts
+
+```
+blocofy login [--context <name>] [--url <url>] [--token <bcf_…>] [--keychain]
+```
+Verify a dev token against its site (`GET /api/dev/whoami`) and save it as a named context
+(default name: the site's slug). Nothing is saved if verification fails. Get a token from the
+admin panel → Settings → Theme CLI tokens.
+- `--keychain` — keep the secret in the macOS keychain (or `BLOCOFY_SECRET_STORE=keychain`);
+  default is `~/.blocofy/secrets.json` (0600).
+
+```
+blocofy login --api-key [--context <name>] [--api-url <url>]
+```
+Verify a v1 API key (`blcf_live_…`, `GET /api/v1/ping`) and add it to a context. The key is
+read from a **hidden prompt** — the flag takes no value, so it never lands in argv or shell
+history. If the context already has a dev token for another site, nothing is saved
+(`TARGET_CREDENTIAL_MISMATCH`).
+- `--api-url <url>` — API origin (default `https://app.blocofy.com`).
+- Non-interactive shells: set `BLOCOFY_API_KEY` + `BLOCOFY_API_URL` instead.
+
+```
+blocofy contexts [--json]          # list saved contexts (never prints secrets)
+blocofy use <name>                 # default context for status / target / pages check outside a project
+blocofy logout --context <name>    # remove a context and its secrets
+```
+
+### Project binding
+
+```
+blocofy link [dir] --context <name> [--adopt]
+```
+Bind a project directory to the context's (verified) site: writes `.blocofy/project.json`
+(commit it), `.blocofy/local.json` (your context; git-ignored) and `.blocofy/.gitignore`.
+Refuses to rebind a directory bound to another site unless `--adopt`.
+
+```
+blocofy target [dir] [--context <name>] [--json]
+```
+Show which site a command in `[dir]` would hit (verified), without writing anything.
+
+### Theme
+
+```
+blocofy theme dev [dir] [--port <n>] [--no-sync] [--name <name>]
+```
+Start a dev server and print 3 auto-reloading views — Local, live-domain Preview, and the theme
+Editor. Press `l` / `p` / `e` to open each, `q` to quit. Edit a file and save → every open view
+reloads. Saves sync to a **draft** theme only (never the live site). `dir` defaults to cwd.
+The target site is verified once at start; a long session keeps that target (restart it after
+changing credentials, context or the project binding).
+- `--port <n>` — local port (default 3030).
+- `--no-sync` — local preview only (skip draft sync + remote views).
+- `--name <name>` — name the draft when it is first created (ignored if it already exists).
+
+```
+blocofy theme pull [dir] [--draft] [--instance <handle>]
+```
+Download the live theme to disk. `dir` defaults to cwd.
+- `--draft` — pull the draft theme (what `theme dev` syncs into) instead of live; creates the
+  draft if missing, so it needs a bound project.
+- `--instance <handle>` — pull a specific theme by its handle (admin panel theme card, or
+  `blocofy status`).
+
+```
+blocofy theme push [dir] [--live] [--yes] [--instance <handle>] [--prune]
+                    [--name <name>] [--dry-run | --validate] [--diff]
+                    [--idempotency-key <k>]
+```
+By **default** writes to a draft theme (create/update; no delete) — preview & publish it from
+the admin panel, never touching the live site. Publish it with `blocofy theme publish`.
+- `--live` — write to the LIVE site immediately (no preview). Asks for confirmation first;
+  non-interactive shells must add `--yes`.
+- `--draft` — explicit draft (same as the default; safe).
+- `--yes` — confirm a `--live` push without prompting (CI/agents).
+- `--instance <handle>` — push to a specific theme by its handle (safe targeted write — no
+  live-confirmation prompt).
+- `--name <name>` — name the new draft (draft mode only; ignored on `--live`/`--instance`).
+- `--dry-run` / `--validate` — check the push on the server without writing; the two flags are
+  aliases. The dry run covers exactly the files the push would send (remote-only files it keeps
+  included; with `--prune`, without the ones it would remove). A current platform plans the whole
+  deploy and prints the target, its pointer version and what happens to each file
+  (`+` created, `~` updated, `-` removed; unchanged files are counted).
+- `--diff` — show what a push would change vs the target (read-only), then stop.
+- `--idempotency-key <k>` — attach a key so a retried push is not double-applied.
+- `--prune` — also remove target files that no longer exist locally (`locales/` included);
+  lists them first, and on the live theme asks to confirm (non-interactive shells add `--yes`).
+
+Every push first runs that dry run, then writes the same files. On a current platform the write is
+bound to the dry run: it is refused, with nothing written, if the files differ from what was checked
+(`manifest_mismatch`), the target theme was deployed again in between (`pointer_version_conflict`),
+or the push would now write to another theme than the one its dry run planned against — the live
+theme was switched, or the draft to reuse changed (`target_changed`: nothing was deployed, though a
+draft push may have created a new, empty draft that the next push reuses; run the push again).
+A write that gets no answer (network error, 429/502/503/504) is resent (up to 3 times) under the same
+key; a push the platform already committed is then reported as deployed (`already applied by an
+earlier push with the same idempotency key`). If that resend is refused, the refusal cannot say
+what the earlier attempt did: the message says whether it was committed or its outcome is
+unknown (`details.earlierAttempt`), never "Nothing was written". Check the theme the dry run bound
+the write to (`details.expectedTargetInstance`, not the current target a refusal names) with
+`blocofy theme push --diff --instance <handle>` — or, for a new draft, find it with `blocofy status` —
+before running the push again. A write whose last answer is still not definite (HTTP 500 or another
+5xx, a 503, a 502 `readback_unverified` with `outcomeUnknown`, or no answer) has an unknown outcome
+(`details.outcome: "unknown"`): the message names the push's key (`details.idempotencyKey`); run the
+same command again with `--idempotency-key <that key>`, and a push that was deployed is reported as
+deployed instead of being written again.
+If the dry run would remove a file the push did not carry, the push stops
+(`THEME_PUSH_TARGET_CHANGED`). The message says which case each file is:
+- a path the push cannot send (not a file inside a theme folder, e.g. a bare `layout` row; listed in
+  `details.notCarryable`) stops every run the same way, and only `--prune` gets past it (it removes
+  the file);
+- any other file was either added while the push was running, and running the push again keeps it,
+  or the push cannot read it (for example a theme file that is not published): then it stops every
+  run the same way, and you add `--prune` to remove it or add a local file at that path to replace it.
+
+`Deployed atomically` is printed only when the server read the written files back and they match;
+an older platform that does not read back gets `Deployed: … not verified`.
+
+```
+blocofy theme rename <handle> <new name> [--dir <dir>]
+```
+Rename a theme (the name is just a label). Works on any of your themes, including the live one.
+- `--dir <dir>` — the bound project whose site the theme is on (default: cwd).
+
+```
+blocofy theme publish [dir] [--instance <handle>]
+```
+Publish a draft theme to the LIVE site: it replaces the live theme for every visitor. With no
+flag, publishes the draft that `theme dev` / `theme push --draft` writes into. The server
+refuses to publish a theme that has no pages (it would 404); preview first. The site is the one
+`[dir]`'s project is bound to (`dir` defaults to cwd), so `blocofy theme push ./shop && blocofy
+theme publish ./shop` always publishes `./shop`'s site, whatever directory you run it from.
+- `--instance <handle>` — publish a specific theme.
+
+### Status
+
+```
+blocofy status [dir]
+```
+Show the live theme, page distribution per instance, drafts, and a health flag (`ok` /
+`live_instance_empty` / `pages_split`). For a problem it names the theme holding the pages, the
+missing pages, why, and safe preview-first next steps — never a one-line fix.
+
+### Pages
+
+```
 blocofy pages pull [dir] [--strict]
-                          # Download published pages, one folder per language:
-                          # pages/<locale>/index.json and pages/<locale>/routes/<path>/index.json.
-                          # Old-layout files are reported, never deleted or overwritten. If the site
-                          # cannot export every page, nothing is written (PAGES_EXPORT_INCOMPLETE).
-blocofy pages push [dir] [--dry-run] [--strict]
-                          # Update EXISTING pages only. Every file is checked first; any invalid file,
-                          # duplicate target or folder/locale mismatch changes NO page. An error after
-                          # that check may leave some pages applied: the per-file result is printed,
-                          # exit 1, and re-running is safe. --dry-run checks on the server, writes nothing.
+```
+Download published pages, one folder per language: `pages/<locale>/index.json` (home) and
+`pages/<locale>/routes/<path>/index.json` (everything else). Files from the old flat layout
+(`pages/<slug>.json`) are reported, never deleted or overwritten. If the site cannot export
+every published page, nothing is written, every reason is printed
+(`PAGES_EXPORT_INCOMPLETE`) and the exit code is 2 (`--strict`: warnings exit 1).
+
+```
+blocofy pages push [dir] [--dry-run] [--strict] [--force --reason <text>]
+```
+Write `pages/**.json` to the site. Updates **existing** pages only — never creates or deletes a
+page; unchanged pages are skipped. Every file is checked first: an invalid file, two files
+pointing at the same page, or a folder/locale mismatch changes **no** page. Every pulled file
+carries `base_revision` (the page as you pulled it); the push first asks for a plan (per page:
+action, live/draft, changed fields), prints it, then pushes exactly that plan.
+- If a page changed on the site since you pulled it (`PAGES_REVISION_CONFLICT`) or a file has no
+  `base_revision` (`PAGES_BASE_REVISION_REQUIRED`), nothing is changed: run `blocofy pages pull`,
+  merge your edits, and push again.
+- If the site changes between the plan and the push, nothing is changed either
+  (`PAGES_PLAN_STALE`) — run the push again.
+- `--force --reason <text>` — overwrite anyway (reason: 1–500 characters); the forced pages are
+  listed. Against an older server that cannot check revisions, the push runs as before with a
+  warning.
+- `--dry-run` — print the plan, write nothing.
+- If publishing stops unexpectedly after the plan (`PAGES_APPLY_FAILED` or another publish
+  error), some pages may already be applied: the per-file result printed is authoritative, the
+  exit code is non-zero, and re-running the push is safe.
+
+```
 blocofy pages check [dir] [--strict]
-                          # Offline file/path/layout checks; with login also the server dry run.
+```
+Check page files. Offline: paths, JSON, layout, duplicates, missing `base_revision`
+(`PAGES_BASE_REVISION_MISSING` warning). Logged in: also the site's languages and a server-side
+dry run. Exit 1 on errors (`--strict`: warnings too).
+
+```
 blocofy pages migrate-layout [dir] [--dry-run | --write] [--strict]
-                          # Move old-layout files (pages/<slug>.json) to language folders. Any
-                          # ambiguity or conflict moves nothing (exit 1).
+```
+Move old flat-layout files (`pages/<slug>.json`) to language folders. `--dry-run` (default)
+prints the plan; `--write` moves only proven files. Any ambiguity or conflict: nothing is moved,
+exit 1. Files without `"locale"` use the site's default language (needs login); with `--write`
+outside a bound project only explicit `--context`/env credentials are used.
+
+```
+blocofy pages media-uses <page-handle> [--dir <dir>] [--json]
+```
+List a page's localized-media decisions on its newest **draft** (v1 API, `pages:read`). Prints
+the draft's revision id/version needed by `media-decide`. `--dir <dir>` (both media commands):
+the bound project whose site the page is on (default: cwd).
+
+```
+blocofy pages media-decide <page-handle> --decisions <file.json>
+                            [--expected-revision-id <n> --expected-version <n>] [--dir <dir>] [--json]
+```
+Apply one or more media decisions to the page's draft atomically (v1 API, `pages:write`). The
+file is `{ "decisions": [ { path, facet, decision, target_asset?, alt?, caption?, decorative?,
+idempotency_key?, witness? } ] }` (max 20). Without the two `--expected-*` flags the CLI first
+`GET`s the draft and uses its current revision id/version; items without an `idempotency_key`
+get a random UUID. Transient failures (429/502/503/504, network) are retried against the same
+idempotency key, so a retry replays the same batch. Exit 0 on success (or "No changes" when
+every item was already recorded).
+
+### Settings
+
+```
+blocofy settings pull [dir]
+blocofy settings push [dir] (--instance <handle> | --live [--yes])
+```
+Download / upload `config/settings.json` (theme tokens/settings + color schemes). A push
+**names its target** — there is no implicit live write, and the command refuses with neither
+flag:
+- `--instance <handle>` — write that theme's settings; a draft shows them in its preview and
+  goes live with `blocofy theme publish --instance <handle>`.
+- `--live` — write the LIVE theme (asks to confirm; non-interactive shells add `--yes`).
+
+After a push the CLI says where it applied (preview now / live now / after deploy).
+
+### Site (declarative state)
+
+The `site` commands move a whole site — pages, navigation, theme source, settings, chrome,
+translations, media — as one declarative tree on disk (`blocofy-site.json` + `site/**` +
+`theme/**` + `pages/**` + `media/**`), instead of the per-scope `theme`/`pages`/`settings`
+commands above.
+
+```
+blocofy site export [dir]
+```
+Download the whole site as a declarative tree into `[dir]`, plus every media file's bytes at
+`media/files/<sha256>` (downloaded and hash-verified). Refuses to overwrite a directory bound to
+another site (same binding rule as every other pull).
+
+```
+blocofy site validate [dir]
+```
+Check an exported (or hand-authored) tree **offline** — zero network requests: paths, the
+path↔content binding (a page file's locale/slug must match its folder/name, and so on),
+duplicate identities, the size/count limits, and the tree against its own manifest digest.
+- `--strict` — warnings also exit non-zero.
+
+```
+blocofy site migrate [dir] [--dry-run | --write]
+```
+Turn a directory left by the **older separate** `theme pull` / `pages pull` / `settings pull`
+into the site-state v1 tree layout (theme directories at the root → `theme/**`,
+`config/settings.json` → `theme/config/settings.json`). Purely local: no network request, no
+target/identity check, `.blocofy/` project binding untouched. `pages/**` files are never moved
+(the location is already identical); a file still at the old flat page layout is left alone with
+a note to run `blocofy pages migrate-layout` first.
+- `--dry-run` (default) — print the plan: every move, every file left alone, every conflict.
+- `--write` — perform it.
+- Any ambiguity or conflict (a target already exists with different content, an unreadable or
+  symlinked entry, a path the shared site-state rules refuse): zero moves, exit 1.
+- Never invents the parts a directory of separate pulls never had (`blocofy-site.json`,
+  `site/locales.json`, globals, navigation, translations, `theme/chrome/**`) — it says so and
+  points at `blocofy site export` for those.
+
+```
+blocofy site plan [dir] [--target new|<handle>] [--mode same_site|restore]
+                  [--accept-live-effects locales] [--json]
+```
+Ask the site what applying this tree **would** do — no write. Needs **both** a dev token and a
+v1 API key (the dev token is what a theme deploy uses later). Prints the status (`planned` /
+`awaiting_assets` / `awaiting_theme_source` / `draft_complete`), the steps, and any missing
+assets or a differing theme source.
+- `--target new|<handle>` — a fresh draft theme version (default), or a specific one you own
+  (from a previous plan/apply's target instance).
+- `--mode same_site|restore` — `same_site` refuses a page that changed on this site since the
+  tree was exported; `restore` (default) does not.
+- `--accept-live-effects locales` — required before a state that adds a language may be applied
+  (publishing a language prepares its homepage LIVE).
+
+```
+blocofy site apply [dir] [--target new|<handle>] [--mode same_site|restore]
+                   [--accept-live-effects locales] [--json]
+```
+Build the state into a **draft** theme version — the live site is never touched. Loops: plan →
+(upload missing media via the v1 API, or deploy the theme source via the same canonical path
+`theme push --instance` uses) → plan → apply, until the target reports `draft_complete` or 5
+passes are used. Safe to re-run: every step is idempotent and a re-plan picks up exactly what is
+left, so an apply interrupted by anything (network, Ctrl-C, a crash) resumes with the same
+command. Preview it from the admin panel, then run `blocofy site publish`.
+
+```
+blocofy site publish [dir] [--target new|<handle>] [--mode same_site|restore] [--yes]
+```
+Make an applied state the LIVE site: pointer swap, then navigation, then settings. Refuses (exit
+2) if the state is not fully applied yet — run `site apply` first. Separate live gate: asks to
+confirm (non-interactive shells must add `--yes`).
+
+```
 blocofy --version
 blocofy --help
 ```
 
+## Contexts and project binding
+
+A **context** is one named operator profile for one site. It references two **separate**
+credentials, each kept in the secret store and never printed: the theme dev token (`bcf_…`,
+verified with `GET /api/dev/whoami`) and the v1 API key (`blcf_live_…`, verified with
+`GET /api/v1/ping`). They stay two credentials with their own scopes — the CLI never merges them
+into one token and never sends one to the other's endpoint. Both pairs of a context must resolve
+to the same site (`TARGET_CREDENTIAL_MISMATCH`); a secret of the wrong type in either slot is
+refused before any request (`TARGET_CREDENTIAL_WRONG_TYPE`, exit 1 — e.g. a `blcf_live_…` key in
+`BLOCOFY_TOKEN`).
+
+Every remote command verifies its site first and prints a `Target` block on stderr (`--json`:
+the same as a `{"target":…}` line with `platform_origin`, `context_source`,
+`context_overrides`, `command` and `mode`):
+
+```
+Target:    Alpha Bakery · s1a2b3 · alpha.myblocofy.com
+Platform:  https://app.blocofy.com
+Context:   alpha (from .blocofy/local.json)
+Binding:   .blocofy/project.json
+Operation: theme push · draft
+```
+
+The context is chosen in this order:
+
+1. `--context <name>`
+2. `BLOCOFY_CONTEXT`
+3. env credentials (`BLOCOFY_URL` + `BLOCOFY_TOKEN` and/or `BLOCOFY_API_URL` + `BLOCOFY_API_KEY`)
+4. `.blocofy/local.json` (the project's own context choice)
+5. the one saved context matching the project's site
+6. (terminal) pick from the matches
+7. outside a project, and only for `status`, `target` and `pages check`: the `blocofy use` default
+
+**Conflicts fail closed.** `BLOCOFY_CONTEXT`, the env credentials and `.blocofy/local.json` are
+each a choice. When two of them name different contexts, the command is refused before
+anything is read or written (`TARGET_CONTEXT_CONFLICT`, exit 3) — e.g. `BLOCOFY_URL`/
+`BLOCOFY_TOKEN` exported in a shell that then runs inside a project whose `local.json` names a
+context. Settle it with `--context <name>` (or unset the others); the `Context` line then lists
+what it overrode, e.g. `alpha (from --context; overrides env credentials)`.
+
+Inside a **bound project**, `blocofy use` is ignored — the project's binding decides, not the
+global default context. Outside one, the `use` default serves only `status`, `target` and
+`pages check`, and the `Context` line says so (`from default context (blocofy use)`); every other
+command in an unbound directory needs `--context`, `BLOCOFY_CONTEXT` or env credentials, so a
+`use` in another terminal never changes what a diff, dry run or plan compares against. Commands
+that change a site (`theme push`/`publish`/`rename`, `theme dev` sync, `pages push`, `settings
+push`, `pages media-decide`) need a bound project; a pull into a new empty directory binds it
+automatically. A wrong project/site pairing changes nothing (`TARGET_SITE_MISMATCH` — pass
+`--adopt` on `link` to rebind deliberately).
+
+Every command resolves its binding from the directory it acts on — the `[dir]` argument (or
+`--dir <dir>` for `theme rename` and `pages media-uses|media-decide`), else cwd.
+
+**CI:** commit `.blocofy/project.json` (never `local.json`) and set the env pairs the job needs
+(`BLOCOFY_URL` + `BLOCOFY_TOKEN` for theme/pages/settings, plus `BLOCOFY_API_URL` +
+`BLOCOFY_API_KEY` for the v1 commands and `site plan`/`apply`). The env credentials are then the
+only choice, and each command still verifies they belong to the committed binding's site.
+
+A binding made against an older server has no recorded `platform_origin`: it still matches the
+same site (one warning printed; run `blocofy link --adopt` to record it). A server that reports
+no origin cannot serve a binding that records one — that refuses with `TARGET_UNVERIFIED` (the
+server cannot prove it is the platform the binding was made against).
+
+A refusal in this area (`TARGET_SITE_MISMATCH`, `TARGET_UNVERIFIED`, `TARGET_CREDENTIAL_MISMATCH`,
+`TARGET_CONTEXT_CONFLICT`, `TARGET_CONTEXT_REQUIRED`, `TARGET_CONTEXT_UNKNOWN`,
+`TARGET_BINDING_INVALID`, and `TARGET_CREDENTIAL_WRONG_TYPE` with exit 1) always means:
+**nothing was read or written** — the command stops before it touches the site or the local
+project files, and exits 3 (see [Exit codes](#exit-codes)).
+
+`blocofy site migrate` is the one exception: it never resolves a target or a context at all (no
+network, no identity call), so it leaves any `.blocofy/` binding in the directory completely
+untouched.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Ok. |
+| 1 | Usage / network / HTTP 5xx / a local check that refuses before any request (e.g. a `site migrate` conflict, a `pages migrate-layout` ambiguity). |
+| 2 | The server refused the request (HTTP 4xx) — its `{error}` JSON is printed. |
+| 3 | Target/binding refusal — nothing was read or written (see [Contexts and project binding](#contexts-and-project-binding)). |
+| 4 | `site apply` only: not finished within its bounded pass count. Every step already applied is safe — re-run the same command to resume. |
+
+`--json`: every failure prints `{"error":{"code","message","details"}}` as the **last** stderr
+line; the target block (`{"target":…}`) and any warning lines are printed on stderr before it.
+
+Retries: network errors and HTTP 429/502/503/504 are retried up to 3 times (`Retry-After`
+honoured, max 30s per wait; else 0.3s/0.9s/2s), resending the identical request (`pages push`
+carries one `x-idempotency-key` per push). HTTP 500 is never retried, nor is a `theme push` dry
+run answered 502 `readback_unverified` (a verdict on a rolled-back plan, not a transient failure).
+Each retry prints a notice on stderr.
+
 ## Changelog
 
+- **0.11.0** — One named context per site, one explicit target (customer item 1.8).
+  The dev token and the v1 API key remain two separate credentials; a context references both.
+  - **Breaking:** conflicting context choices now fail closed. When `BLOCOFY_CONTEXT`, the env
+    credentials (`BLOCOFY_URL`/`BLOCOFY_TOKEN`, `BLOCOFY_API_URL`/`BLOCOFY_API_KEY`) and a
+    project's `.blocofy/local.json` name different contexts, the command stops with
+    `TARGET_CONTEXT_CONFLICT` (exit 3) instead of silently taking the first. A shell that exports
+    the env credentials inside a project with a `local.json` must pass `--context <name>` (or
+    unset them). An explicit `--context` still wins, and the target block lists what it overrode.
+  - **Breaking:** outside a bound project the `blocofy use` default is used only by `status`,
+    `target` and `pages check` (as contract C2 specified). `theme push --diff/--dry-run`,
+    `pages push --dry-run`, `site plan`, `theme dev --no-sync` and `pages media-uses` in an unbound
+    directory now need `--context`, `BLOCOFY_CONTEXT` or env credentials
+    (`TARGET_CONTEXT_REQUIRED`).
+  - The target block shows the platform the site was verified on and where the context choice
+    came from (`Platform:` line; `Context: <name> (from …)`); `--json` adds `platform_origin`,
+    `context_source`, `context_overrides`, `command` and `mode`.
+  - `theme publish [dir]` and `status [dir]` take the project directory as an argument, and
+    `theme rename` / `pages media-uses|media-decide` take `--dir <dir>`. Before, they always used
+    cwd, so `theme push ./a && theme publish` run from another project published that project's
+    draft. A directory that does not exist, or one given where the command takes none (a second
+    positional to `target`/`status`/`theme publish`, any directory positional to
+    `pages media-uses|media-decide`), is a usage error (exit 1) before any request.
+  - A secret of the wrong type (a `blcf_live_…` key as the dev token, a `bcf_…` token as the API
+    key) is refused before any request with `TARGET_CREDENTIAL_WRONG_TYPE`, naming the variable
+    or context — it was sent to the wrong endpoint and reported as `TARGET_UNVERIFIED`.
+    `login --token blcf_…` points at `login --api-key`.
+  - Theme push preflight bound to the write (customer item 6.5):
+    - `theme push` checks the MERGED payload (local files plus the remote-only files it keeps) in its
+      dry run, then writes exactly those files with the dry run's `manifestHash` and
+      `expectedPointerVersion`, and — when the platform names it — the theme the dry run planned
+      against (`expectedTargetInstance`; refused with `target_changed` if the target moved). The dry
+      run carries its own throwaway idempotency key, so
+      `--idempotency-key` retries of a committed push still converge.
+    - A write resent after an attempt without an answer is reported as deployed when the platform
+      had committed it. A refusal of such a resend says the earlier attempt's outcome is unknown (or
+      that it was committed) instead of "Nothing was written", and `details.earlierAttempt` names it.
+    - A write that gets no definite answer (a 5xx, a 503, `readback_unverified` with an unknown
+      outcome, or no answer after the resends) is reported as an unknown outcome, not a failure: the
+      message names this push's key, to run the same command again with `--idempotency-key <key>`
+      (the platform then reports the committed deploy instead of writing it again); `--json` details
+      carry `outcome: "unknown"` and `idempotencyKey`.
+    - A `target_changed` refusal names the theme the dry run planned against and the current target,
+      and says "Nothing was deployed" (a `--draft` push may have created a new, empty draft, which
+      the next push reuses). After a write's `readback_unverified` the CLI points at
+      `theme push --diff --instance <handle>` for the theme the write was bound to (or `blocofy status`
+      for a new draft), not at a plain `--diff`, which compares with the live theme only.
+    - Per-file outcomes are printed for the push and for `--dry-run`. `Deployed atomically` appears only
+      with a verified readback. New refusals with messages: `pointer_version_conflict`,
+      `site_state_version_conflict`, `manifest_mismatch`, `readback_unverified` (worded for the dry
+      run, where nothing was written, or for the write; `details.phase` says which) and the preflight path
+      errors (`path_too_long`, `reserved_path`, `binary_content_rejected`…, naming the file).
+    - A push stops with `THEME_PUSH_TARGET_CHANGED` when the dry run would remove a file the push did
+      not carry; the message says whether a re-run can keep it or only `--prune` gets past it, and
+      `details.notCarryable` lists the paths the push cannot send. `--prune` lists them for
+      confirmation instead. `--dry-run --prune` now plans the pruned set.
+    - Against an older platform the write body is unchanged from 0.10.
+- **0.10.0** — Named contexts + verified project binding, and a declarative whole-site state.
+  - `login` now saves a **named context** (`--context <name>`, default the site's slug) instead
+    of one global credentials pair; `blocofy contexts` / `use` / `logout` manage them, and
+    `blocofy link [dir] --context <name> [--adopt]` binds a project directory to one verified
+    site (`.blocofy/project.json`, committed; `.blocofy/local.json`, git-ignored).
+    `blocofy target [dir]` shows which site a command would hit without writing anything.
+    `login --keychain` keeps the secret in the macOS keychain instead of
+    `~/.blocofy/secrets.json`. A pre-0.10 `credentials.json` is migrated on first use (backup:
+    `~/.blocofy/credentials.v1.bak.json`).
+  - New `blocofy site export/validate/migrate/plan/apply/publish`: pull a whole site as one
+    declarative tree, check it fully offline, turn an older separate-pulls directory into that
+    tree layout (`site migrate`), ask what applying it would do, build it into a draft theme
+    version, and make it live. `site apply` is resumable — every step is idempotent and picks up
+    exactly what is left.
+  - `pages push` speaks page revision CAS: every pulled file carries `base_revision`, a push
+    previews its plan before writing, and a page changed on the site since the pull (or missing
+    `base_revision`) refuses with nothing changed instead of silently overwriting — recover with
+    `pages pull` + push again, or `--force --reason <text>`.
+  - `settings push` now **requires** `--instance <handle>` or `--live` — there is no longer an
+    implicit live write.
+  - Consistent exit codes across every command (see [Exit codes](#exit-codes)) and a `--json`
+    envelope (`{"error":{code,message,details}}`) as the last stderr line on any failure.
+
 - **0.9.0** — Locale-aware page files for multilingual sites (needs a platform with page file protocol 2;
   against an older server page commands stop with `PAGES_SERVER_UPGRADE_REQUIRED` and write nothing).
   `pages pull` writes `pages/<locale>/index.json` and `pages/<locale>/routes/<path>/index.json`, so the same
@@ -148,11 +572,13 @@ editor — without affecting your published theme. Save a file and **every open
 (the platform-rendered pages connect back to the local dev server's reload channel). Publish
 the draft from the theme editor when you're ready.
 
-Credentials come from `~/.blocofy/credentials.json` (written by `blocofy login`) or the
+Credentials live in `~/.blocofy/credentials.json` (contexts, no secrets) + either
+`~/.blocofy/secrets.json` (0600) or the macOS keychain — written by `blocofy login`, or the
 `BLOCOFY_URL` + `BLOCOFY_TOKEN` environment variables (for CI/automation). The v1 API commands
-(`pages media-uses`, `pages media-decide`) use a separate `blcf_live_…` key from the same file
-(written by `blocofy login --api-key`) or `BLOCOFY_API_KEY` + `BLOCOFY_API_URL` — both variables
-together; with only one set the CLI fails instead of falling back to the file.
+(`pages media-uses`/`media-decide`, `site plan`/`export`/`publish`) use a separate
+`blcf_live_…` key from the same file (written by `blocofy login --api-key`) or `BLOCOFY_API_KEY`
++ `BLOCOFY_API_URL` — both variables together; with only one set the CLI fails instead of
+falling back to the file.
 
 ## Theme structure
 
@@ -165,12 +591,17 @@ A theme is a directory of files grouped by top-level folder:
 | `block/` | Repeatable pieces used inside sections |
 | `partial/` | Shared snippets (header/footer, …) |
 | `asset/` | CSS and static files (`theme.css`) |
+| `locales/` | Legacy Liquid translation files (`<tag>.json`, `<tag>.default.json`) |
 | `pages/<locale>/index.json`, `pages/<locale>/routes/<path>/index.json` | Page content, one folder per language (`blocofy pages pull/push/check/migrate-layout`). The old `pages/<slug>.json` layout is still read, with a warning |
-| `config/settings.json` | Theme settings + color schemes |
-| `config/settings_schema.json` | Theme settings panel schema (synced with `pull`/`push`) |
+| `config/settings.json` | Theme settings + color schemes (`blocofy settings pull`; `settings push` needs `--instance <handle>` or `--live`) |
+| `config/settings_schema.json` | Theme settings panel schema (synced with `theme pull`/`push`) |
 
 Liquid templates use the `.liquid` extension; files under `asset/` are served as-is.
 
+`blocofy site export` pulls the same content plus navigation, chrome and translations as one
+declarative tree instead (see [Site (declarative state)](#site-declarative-state)); `blocofy
+site migrate` turns a directory built from the commands above into that tree's layout.
+
 ## Development
 
 Zero runtime dependencies (Node built-ins only). Run the tests with: