@somewhere-cloud/cli 0.38.14 → 0.38.16

package/CHANGELOG.md

@@ -0,0 +1,1378 @@
+# Changelog
+
+## 0.38.16
+
+### Added
+
+- `somewhere upgrade [--json]` moves every recorded CLI pin to the running CLI
+  and prints the `CHANGELOG.md` entries in between (`CHANGELOG.md` now ships in
+  the package). To reach the newest release: `npx -y @somewhere-cloud/cli@latest
+  upgrade`, then `npm install`.
+- New projects pin the CLI version they were created with (`init`, `project
+  create` and the temporary deploy record it, and send it to the platform as
+  `cli_version`). A different CLI run inside the project prints one line and
+  runs the installed pin. Skills are never updated on their own; `upgrade`
+  leaves them alone and says `skills update` is the explicit step.
+- The starter `AGENTS.md` names the data-and-code exits (`somewhere pull`,
+  `somewhere db dump`, CSV export, PostgreSQL in your own Neon account) and
+  points at `somewhere docs portability`.
+
+### Changed
+
+- README, LICENSE, the starter and `browser` help no longer name the old
+  package scope, the old domain or "legacy"; the copyright holder is
+  Somewhere HQ, Inc. A test refuses those words in what ships.
+
+## 0.38.15
+
+### Changed
+
+- `somewhere deploy` (and the patch path) waits up to 5 s for the blank-page check
+  that runs after the platform answers (`post_live_render: pending`), reading the
+  settled result from `GET /deploy/log?release_id=`. A page the check finds blank
+  fails the deploy with `DEPLOY_BLANK_PAGE` and the rejection, instead of being
+  rolled back silently after the command returned.
+- `somewhere rollback` prints the database notice in its plain-text output: a
+  code-only rollback across a schema change says the tables and columns added
+  since stay, with their data, and the target version ignores them.
+
+## 0.38.14
+
+### Added
+
+- `somewhere tasks delete <id> --reason <text>`, `somewhere tasks restore <id>
+  [--reason <text>]` and `somewhere tasks deleted`: delete a task from the
+  board, bring it back, and list deleted tasks. Only the board owner can use
+  them; anyone else is refused with `TASK_DELETE_FORBIDDEN`.
+
+### Changed
+
+- `somewhere deploy`: once the target project is known (a linked folder or
+  `--project`), the CLI asks the platform to start the project's compile
+  container while it packs and uploads, so a cold redeploy no longer waits for
+  that container after the upload. The request is sent once and never awaited;
+  any answer, including an older platform's 404, leaves the deploy unchanged.
+  `--dry-run` sends none.
+
+## 0.38.13
+
+### Changed
+
+- `somewhere init`: the starter's `AGENTS.md` points to `grant()` for sharing
+  your own rows with specific people (read-only sharing, co-authors):
+  `somewhere docs declared-data --section per-owner-sharing`. The agent
+  workflow names `anyOf(owner(), grant())` beside the other scopes, and the
+  green starter's access paragraph carries the same pointer.
+- The bundled skills pack is refreshed to the platform's current pack.
+
+## 0.38.12
+
+### Changed
+
+- `somewhere deploy --project <id>` from a folder with no recorded base: when
+  `<id>` is already a canonical project id, the live release it deploys against
+  is read alongside the project lookup instead of after it. The lookup still
+  binds the target first, a folder linked to a different project is still
+  refused before anything is uploaded, and the read is used only when the
+  lookup confirms the same project.
+
+## 0.38.11
+
+### Changed
+
+- `somewhere init`: the starter's `AGENTS.md` public-form example declares its
+  request body schema with `sw.endpoint`, and the agent workflow text is
+  re-synced to the platform's.
+
+### Fixed
+
+- `somewhere deploy-check --json` keeps the platform's error code, message and
+  request id instead of replacing them with `CLI_ERROR`.
+
+## 0.38.10
+
+### Added
+
+- `somewhere ai keys --project <project>` (also `list`, `ls`),
+  `somewhere ai keys set <anthropic|openai> --project <project> [--stdin]` and
+  `somewhere ai keys remove <anthropic|openai> --project <project>` (alias `rm`)
+  manage a project's own AI provider keys. `--project` is required on all
+  three; the destination is never taken from the linked folder.
+- The key is never a command-line argument: `set` reads it from a hidden
+  prompt or, with `--stdin`, from a pipe. Unknown options and stray values are
+  refused without being repeated, and a key is checked locally (not empty, no
+  spaces or line breaks, at most 4096 characters) before any request.
+- Until the platform serves the key-status read, `ai keys` reports
+  `AI_KEY_STATUS_UNAVAILABLE` instead of an empty list; `set` and `remove`
+  work now.
+
+## 0.38.9
+
+### Fixed
+
+- The sign-in code step in the starter that `somewhere init` writes now asks
+  for the 6-digit code from the email (heading "Check your email"), instead of
+  an "Authenticator or backup code". "Send a new code" requests a fresh code a
+  minute after each send and never sends automatically; the newest code is the
+  one to use, and a new code does not extend the 5-minute step. Refusals (send
+  limit, lockout, expired step, failed send) show the platform's own message.
+  "Sign in again" leaves the step.
+- The feature and minimal starters pin `@somewhere-cloud/sdk` 0.14.1, which
+  provides `resendMfaCode()`.
+
+## 0.38.8
+
+### Changed
+
+- The starter that `somewhere init` writes no longer shows a whole-page loading
+  screen ("Checking your session…"). Until sign-in is known, the app frame
+  renders at once with the app's name and no account controls.
+- The starter pins `@somewhere-cloud/sdk` 0.14.0 (the minimal template
+  `^0.14.0`). With 0.14.0 the platform's early session script starts the
+  sign-in check while the page is still loading.
+
+## 0.38.7
+
+### Changed
+
+- Before any command runs, the CLI deletes `last-run.json` (and
+  `last-run.json.tmp`) in the config directory (default `~/.somewhere`, or
+  `SOMEWHERE_CONFIG_DIR`). Versions before 0.38.6 saved command arguments and
+  output there in plain text. The file is never read or printed; only its path
+  and an error code are shown if it cannot be removed. At exit the CLI writes
+  the metadata-only record introduced in 0.38.6.
+- The `AGENTS.md` that `somewhere init` writes (default and `--bare`) points to
+  the declared-access recipes, readable with
+  `somewhere docs sw.db --section owner-or-member-and-parent-access`.
+
+## 0.38.6
+
+### Fixed
+
+- An expired temporary session (from deploying without logging in) no longer
+  blocks `init` or a fresh `deploy`. `init` writes the starter offline and
+  names the folder it wrote to; `deploy` says in one line that it replaced the
+  expired session.
+- Signed out, a deploy that names an existing project (`--project` or a linked
+  folder) now stops before contacting Somewhere with `SIGN_IN_REQUIRED` and
+  the two ways forward (sign in, or drop the target to start a new temporary
+  project), instead of creating a temporary account and then failing.
+- A file over the 5 MB per-file limit that would be published now stops
+  `deploy` and `preview` before any request (`FILE_TOO_LARGE`), instead of
+  being left out while the deploy goes live. `.gitignore` and
+  `.somewhereignore` still keep large files out on purpose.
+- When a deploy request may have reached Somewhere but no answer came back,
+  the CLI never sends it again. It reports the outcome as unknown
+  (`deployment_outcome: "unknown"` with `--json`) and says how to check.
+- `somewhere` needs Node.js 22.19.0 or newer and now says so on older Node.js,
+  instead of failing with a TypeError.
+- `auth set` reports only an HTTP 401 as an invalid token; an outage or other
+  failure says the token could not be verified and saves nothing. `whoami`
+  reports only a 401 as a login problem.
+- Commands piped into a reader that closes early (`docs | head -1`) end
+  quietly instead of reporting a network failure.
+- Anonymous deploy errors keep Somewhere's error code, status and request ids.
+
+### Changed
+
+- `typecheck` is read-only: it never installs packages. Missing type packages
+  stop it with an `npm install` instruction, it announces when it fetches
+  TypeScript with npx, and every check runs under a deadline
+  (`SOMEWHERE_TYPECHECK_TIMEOUT_MS`, default 300 s) that stops its processes.
+- `deploy --json` keeps stdout for the deploy result and lists every file left
+  out locally on stderr, by path and reason.
+- `preview` judges each save like a deploy: ignored files are not uploaded and
+  an oversize file holds the save without changing the last preview.
+- `somewhere api` refuses full URLs, control characters, `..` segments and
+  unsupported methods before sending anything; the request always stays on the
+  configured API.
+- `logs --tail` takes a whole number from 1 up. `dev` refuses extra arguments.
+- The local `last-run.json` records only the command, option names, exit code,
+  time and CLI version, never values or output. `env set` with a value on the
+  command line points to `--stdin`.
+- Declared-data and runtime types and the source lint are refreshed from the
+  live platform.
+- README and help text describe `dev`, `init`, `typecheck` and project delete
+  as they actually behave.
+
+## 0.38.5
+
+### Changed
+
+- Files blocked by the deploy's sensitive-path policy never leave your
+  machine. The CLI now applies the same policy Somewhere applies to every
+  uploaded path, while it collects files: before any file is read into an
+  upload and before any request. The policy matches file names only, in any
+  folder: private-key files (`id_rsa`, `*.pem`, `*.key`, `*.p12`, `*.pfx`),
+  `credentials` data files (`credentials.json`, `credentials.yaml`, …), secrets
+  files (`secrets.json`, `secrets.yaml`, …), `service-account.json`,
+  `service-account-key.json` and the Firebase Admin SDK key file
+  (`<project>-firebase-adminsdk-<id>.json`). Dotfiles such as `.env` were
+  already never uploaded. This filename policy does not detect secrets under
+  other names. Held-back files are listed under "Never uploaded", and neither
+  `--include` nor a `!` line in `.somewhereignore` or `.gitignore` publishes
+  them. `credentials.ts`,
+  `credentials.tsx`, `credentials.md`, `.well-known/` and ordinary config such
+  as `firebase.json` and `google-services.json` are not affected by this policy.
+- When your published code mentions one of those files by name, `deploy`,
+  `deploy --dry-run`, `deploy-check` and `preview` stop before contacting
+  Somewhere, name the file and the code that mentions it, and suggest storing it
+  as a project secret (`somewhere env set NAME --stdin < file`, read with
+  `sw.env.NAME` in a function). This is a filename match in your code, not an
+  import analysis; documentation such as `README.md` is not searched. If nothing
+  loads the file, add it to `.somewhereignore` or move it out of the folder.
+- `somewhere deploy --dry-run` now says, in its help and in its human-readable
+  output before it runs, that the files a deploy would publish are sent to
+  Somewhere to compute the change and that nothing is published. A dry run
+  still works this way. `--dry-run --json` output is unchanged.
+
+## 0.38.4
+
+### Changed
+
+- `somewhere deploy --dry-run` no longer creates anything. When there is no
+  usable credential (signed out, with no live temporary workspace) or no
+  existing project to compare against (no linked project, no `--project`), it
+  stops before contacting Somewhere: no temporary workspace, no project, no link
+  and no change to project or login files. It says so and points to
+  `somewhere typecheck` and `somewhere lint`, which check your code without
+  contacting Somewhere, or to `somewhere deploy`. With a usable credential and
+  an existing project it shows the deploy's changes as before, and it no longer
+  records the one-time "not published" notice in `.somewhere.json`.
+- Tests stay on your machine by default: `*.test.*` and `*.spec.*` source
+  files, and anything in a `tests/` or `__tests__/` folder, are listed under
+  "Not published". To publish one, use `somewhere deploy --include <path>` or a
+  `!<path>` line in `.somewhereignore`. `--include tests` or `!tests/` publishes
+  the helpers in that folder, for an app that imports them; a test-named file
+  inside it still needs its own opt-in. `.env` files stay excluded either way,
+  and `.well-known` keeps publishing.
+- No new commands, options or dependencies. `--include` now also takes a test
+  folder, as above.
+
+## 0.38.3
+
+### Changed
+
+- The starter's AGENTS.md shows webhook and streaming handlers with their
+  parameter types, `(req: Request, sw: SomewhereRuntimeContext)`, instead of
+  saying `somewhere typecheck` types unannotated handlers, which it does not:
+  under the starter's strict settings an unannotated handler is a type error.
+- The bundled realtime-and-background skill's example handler carries the
+  same annotation. The bundled skills match the platform's served pack.
+- No command, option or dependency changes.
+
+## 0.38.2
+
+### Changed
+
+- The bundled schema-changes skill says that `removedTable()` retires a deployed
+  table with 30-day data retention, instead of pointing to a description "above"
+  that the skill does not include. The bundled skills match the platform's served
+  pack.
+- The minimal starter's README keeps the booking and help-desk recipe command on
+  one line.
+- No command, option or dependency changes.
+
+## 0.38.1
+
+### Changed
+
+- `somewhere init` writes the current agent workflow, skills and minimal starter
+  guidance. `AGENTS.md` matches the published platform workflow: `id()` is a
+  random text key referenced with `text()`, fitting declared scopes stay in place
+  when an exceptional write needs `sw.db.server.tx`, and the sign-in starter modes
+  are listed on one line. The bundled skills match the platform's served pack.
+- The minimal starter's README says to delete a table declaration that was never
+  deployed and to use `removedTable()` for a deployed table, even an empty one.
+  It also notes that the greeting's `serverOnly()` scope is a demonstration, not
+  the default for app data, and points to the booking and help-desk recipes.
+- No command, option or dependency changes.
+
+## 0.38.0
+
+### Changed
+
+- The CLI is now published as `@somewhere-cloud/cli` (install with
+  `npm i -g @somewhere-cloud/cli`, or run `npx @somewhere-cloud/cli <command>`).
+  `@somewhere-tech/cli` stays installable at its existing versions. The command
+  name is still `somewhere`.
+- Defaults target somewhere.cloud: the API at `https://api.somewhere.cloud` and
+  MCP at `https://mcp.somewhere.cloud`.
+- An app's function URL comes from the platform (`app_url` in `.somewhere.json`,
+  printed by `somewhere status --json`), never from a project slug.
+- `somewhere init` writes the project contract (`AGENTS.md`, "somewhere.cloud
+  project contract") and the bundled skills pack from the current platform docs.
+  They name `@somewhere-cloud/cli` and `@somewhere-cloud/sdk`. Starters depend on
+  `@somewhere-cloud/sdk` 0.13.0.
+
+## 0.37.86
+
+### Fixed
+
+- The CLI now talks to Somewhere's current hosts (`api.somewhere.cloud`, `mcp.somewhere.cloud`, runner and site defaults). The previous release still defaulted to `api.somewhere.tech`, which has moved, so `somewhere deploy` from a fresh folder failed immediately. `init` → `deploy` works again with no login and no environment overrides.
+- The README quick start marks `somewhere login` as optional; `init` and `deploy` run anonymously and print a claim link.
+
+## 0.37.77
+
+### Fixed
+
+- `somewhere deploy --project <ref>` from a folder that is not linked to that project no longer fails with `BASE_REQUIRED` on every attempt. The CLI first resolves the ref to its project and reads the project's live release, declares that release as the deploy's base, and lets the platform's existing stale-overwrite check decide: a release that lands between that read and the publish is still refused (`STALE_RELEASE_BASE`), never overwritten, and the CLI never retries or forces. A linked folder keeps sending its own recorded base; a folder linked to a different project than `--project` names is refused with a clear message instead of being redeployed elsewhere; `--force` behaviour is unchanged. When the live release cannot be read, the `BASE_REQUIRED` recovery now names a path that terminates (`init --link`, `pull`, `deploy`) instead of a bare `somewhere pull`.
+
+## 0.37.76
+
+### Changed
+
+- The bundled agent skills pack is refreshed from the platform docs and gains a seventh skill, `design`: the UI kit in `src/ui`, the token rules, the `AuthCard` slots, and the two mistakes that make a generated page look unfinished. New starters install it in `.agents/skills/design`; `somewhere skills update` brings it to an existing project.
+
+## 0.37.75
+
+### Fixed
+
+- `somewhere init`: the generated `index.html` escapes `"` as `&quot;` in the app name, which is both the `<title>` text and the `description` attribute value, so a quote in a project name no longer ends the attribute.
+
+## 0.37.74
+
+### Added
+
+- `somewhere init` auth starters ship a UI kit in `src/ui` (`Button`, `TextField`, `SelectField`, `TextareaField`, `CheckboxField`, `FormRow`, `Card`, `Table`, `Stat`, `Badge`, `Tabs`, `Dialog`, `Notice`, `Skeleton`, `Stack`, `Grid`, `Inline`, `PageHeader`) with styled and headless twins that share props, and `src/pages/HomePage.tsx` is a worked example of them (header, stats, table in a card, dialog form) instead of an empty state. The README gains a "Look" section with the rules that keep generated pages consistent (tokens only, no global tag styles, one primary action, cards for peers).
+- Social sign-in is a config toggle: `SIGN_IN_PROVIDERS` (`src/config.ts`) starts as `['google']`, so a new app shows "Continue with Google" out of the box (the platform owns the OAuth client; nothing to configure); set it to `[]` for email-only sign-in or add `github` / `discord`. The "Continue with …" buttons, `src/auth/useProviderSignIn.ts` and the `/auth/callback` page (the SDK's `AuthCallback`) are already wired. `APP_TAGLINE` sets the sign-in page's one-line description.
+- `src/styles/tokens.css` gets a `prefers-color-scheme: dark` block, semantic tones (success/warning/danger/info), shadows and a cross-platform font stack, so the starter no longer falls back to Arial/Georgia off macOS. `index.html` gets description, `theme-color` and an SVG favicon.
+
+### Changed
+
+- `AuthCard` has permanent `providers` (above the form) and `children` (below it) slots; the magic-link module passes its form as a child instead of patching the card's markup, and nothing else is a sibling of the two-column `.auth` grid.
+- The "Verify your email" panel is a quiet notice with secondary buttons, not the page's loudest call to action. `MfaStep` uses the starter's panel and field classes.
+- Starter stylesheet: the notes status line is `.note-status` (`.notice` is the kit's notice component); `.alert` and `.section-title` live in the base stylesheet, so removing a module leaves no orphaned rules.
+- Social sign-in sends the browser to `/auth/callback?provider=<name>` and the callback page passes that provider to the SDK's `AuthCallback`, so a GitHub or Discord code is exchanged with the provider that issued it (the SDK defaults to Google). An unknown `?provider=` is ignored. With `SIGN_IN_PROVIDERS = []` the sign-in card has no providers slot, so no "or use email" divider is shown.
+
+## 0.37.72
+
+### Fixed
+
+- New apps from `somewhere init` use SDK 0.12.6. It keeps session verification outages as an unavailable response instead of reporting that the user signed out, and uses browser keepalive for refresh requests to reduce interruption during navigation. Keepalive is a limited mitigation, not full recovery from a lost refresh response (#96).
+
+## 0.37.71
+
+### Fixed
+
+- `somewhere logs` text output: every recorded stack line now starts with a fixed `stack | ` marker under its log row, so stack text can never pass as a log row. A stack longer than 30 lines ends with "… N more lines (--json shows the whole stack)". `--json` is unchanged (#90).
+- `somewhere support packet`: the packet's `omitted` list no longer names `emails`, `tokens` or `passwords`. The list names only the parts of a failure the packet builder never reads; it was never a guarantee that a collected field cannot contain such a value, so review a packet before you submit it (#92).
+
+## 0.37.70
+
+### Fixed
+
+- `somewhere support packet --trace`: the packet keeps a failure code only when it is one of the function runtime's own failure codes (the server-recorded response code first, then the logged code). Any other code, including an app-chosen `err.code`, is recorded as `APP_ERROR_CODE`, so a code-shaped value from your app never enters the packet. Your own logs still show the code as written (#88).
+- `somewhere logs` and `somewhere errors` text output: control characters in stored messages and stack frames (newlines, carriage returns, ESC/ANSI sequences, BEL, C1 controls, line/paragraph separators and bidi overrides) are shown as visible escapes, so each stored row prints as exactly one line and a message cannot fake another row or change the terminal. `--json` output is unchanged (#88).
+- `somewhere support packet --help` names exactly which fields the packet reads and how the code is restricted, instead of a blanket "never holds tokens or passwords" claim (#88).
+- `somewhere verify --keep-actors` help states the real lifetimes: a kept browser closes after 5 minutes idle, and at most 10 minutes after it started (#87).
+
+## 0.37.69
+
+### Added
+
+- `somewhere verify --keep-actors --resume-page`: an explicit warm continuation. A kept actor whose first segment starts at exactly the page path the last passed run left it on keeps that page as it was (no reload); any other actor, flow, project or start path, a start path with a query or fragment, or a kept browser that is gone reloads normally. `--resume-page` without `--keep-actors` is refused. The report lists resumed actors under `keep_actors.resumed_pages` with a note that the run does not prove the latest deployed code; run without `--resume-page` for that. The keep record stores the page pathname only (#85).
+- `somewhere logs --trace <trace id>` shows only that request's log lines, with any recorded stack under its line, so the `trace_id` from a `500 FUNCTION_ERROR` leads straight to the crash. Anything but a 32-hex id is refused before any request; plain `somewhere logs` is unchanged.
+- `somewhere support packet --trace <trace id> [--project <ref>]` builds the `somewhere.repro/1` packet for that failed request from the owner's log rows. It keeps only the error code, HTTP status, request and trace ids, method and a templated path (route words become `:id`/`:seg`); never the message, stack, body, query or headers. A failed mutating request is recorded as `unknown` and never rerun. It is written locally and submitted only if you choose (#83).
+
+## 0.37.68
+
+### Fixed
+
+- `somewhere verify --keep-actors`: when nothing is kept yet for this flow file and its actors in this folder (a first run, a new or renamed flow file, or a changed cast), one stderr line says the run starts fresh and will keep them for the next run of the same file. If other flows in the folder have kept actors, it also says they are not reused and that `--close-actors` closes them. No behaviour change (#82).
+
+## 0.37.67
+
+### Fixed
+
+- Starter apps from `somewhere init`: when the session check fails, the "We can't confirm your sign-in" panel says what broke (couldn't reach the server, the server had a problem (HTTP 5xx), too many checks (HTTP 429, wait a minute), an unreadable answer, or a refused check (HTTP 4xx)), that the sign-in may still be valid so try again before signing in again or asking for a new link, and a status-only code to report (`SESSION_CHECK_FAILED, HTTP n` or `no response`). It used to always blame the connection. Only the SDK's typed status is shown, never server text (#80).
+
+## 0.37.66
+
+### Added
+
+- `somewhere verify --keep-actors`: after a fully passed multi-user run, each actor's signed-in browser and test user are kept for the next run of the same flow (same owner, project, folder and cast). That run signs each actor in again and starts from each segment's path, but the browser keeps its earlier state, so a pass on a kept browser is a warm re-check; run without `--keep-actors` for a fresh first load. Any stop, failure or unconfirmed call cleans up as before. `--close-actors` closes the browsers and deletes the identities. The project folder's private `.somewhere/test/verify-actors.json` records ids and emails only (#74).
+
+### Fixed
+
+- After a failed `somewhere call`, `somewhere support packet` records the platform's HTTP status and trace id, so a definite refusal (for example a 404) is recorded as `refused` with its status, the same as the MCP packet, instead of `unknown` with no status or ids. A call that got no response at all (network or timeout) stays `unknown`, with no status invented. Only validated status and ids are kept (#76).
+
+### Changed
+
+- Internal: the `somewhere support packet` repro record uses the platform's shared `somewhere.repro/1` module (vendored byte-identical, with a checksum check). No behaviour change (#73).
+
+## 0.37.65
+
+### Added
+
+- `somewhere support packet [--json] [--out <file>]`: builds a local, redacted repro packet for the last failed command from typed fields only (CLI version, command names, validated error code, HTTP status, an id-templated operation, validated request/trace/project ids, retry verdict, outcome and duration). It never includes the message, hint, data, arguments, bodies, headers, SQL, URL query, emails, tokens, source or env. Nothing is uploaded (#67).
+
+### Fixed
+
+- A refused `somewhere verify` names the invalid field and limit (`start_error_details`: code, status, path such as `actions[2].timeout_ms`, `limit_ms`) instead of echoing the platform message (#67).
+- Text-mode output for a platform failure adds one line with its code and request/trace ids (for example `code PROJECT_NOT_FOUND · request req_… · trace …`). The message stays the platform's own; `--json` is unchanged (#71).
+- `somewhere lint` vendors the platform's source lint at somewhere-tech#714: a file exempted from the request-ownership trace by a genuine verifier call reports `coverage.request_ownership` as `partial` instead of `checked`. Warning metadata only; findings and exit codes are unchanged (#72).
+- `somewhere test-users prepare --help` no longer promises "about 1 hour" sessions or 24-hour identities. It says the session starts with the expiry prepare prints, that a refresh with saved-back state can renew it, and not to rely on expiry: remove the identities with `somewhere test-users cleanup`. A state copied before cleanup may keep working until its access token (JWT) expires (#70).
+
+## 0.37.64
+
+### Added
+
+- `somewhere verify` multi-user journeys report where their time went: each segment carries `timing` (the platform's own browser-call timing numbers and `browser_reused`, plus this CLI's `request_wall_ms`), and the journey adds `test_users_create_ms`, `segments_ms`, `cleanup_ms` and `test_users_delete_ms`. Reporting only; no behaviour, ordering or cleanup change (#68).
+
+### Fixed
+
+- Starter apps from `somewhere init` adopt `@somewhere-tech/sdk` 0.12.4 (feature starter exact `0.12.4`, basic starter `^0.12.4`), which issues an expiry on every cookie reply and reconciles an orphaned refresh marker without a rotation replay (#64).
+
+## 0.37.63
+
+### Added
+
+- `somewhere test-users prepare|address|inbox|cleanup`: prepares signed-in managed test users as standard Playwright `storageState` files (production origin only; state kept under `<project>/.somewhere/test/`, never the developer key, no token printed), gives a fresh `test.somewhere.site` address for real signup tests, reads only test-inbox mail newer than `--since` (the magic link only with `--json --include-link` or `--link-out`), and cleans up only the identities it created, with a readback receipt (#63).
+
+### Fixed
+
+- `somewhere whoami` says what its project count counts, so it reconciles with `somewhere projects` (for example "6 projects you own (`somewhere projects` lists 5 of them; not listed: 1 archived)"); `--json` still prints the raw account response. Shipped in 0.37.63; this entry was added afterwards (#66).
+- `somewhere deploy`: when the after-live reference check is still pending, text output names the existing read for this exact version (`somewhere call project_deploy_log '{"version":N}'`). `--json` is unchanged (#62).
+
+## 0.37.62
+
+### Fixed
+
+- `somewhere verify` reports and their printed text mask credential-bearing parts of URLs: URL userinfo; in the query or fragment, the value of a credential parameter (`token`, `access_token`, `refresh_token`, `auth_token`, `code`, `secret`, `signature`, `sig`, `key`, `api_key`, `apikey`, `creator_secret`, `dsn`, `password`, also percent-encoded or nested encoded in another parameter) or a JWT/key-shaped value under any name; and credential-shaped path segments. This covers a journey segment's `path` and `final_url`, each viewport's `final_url`, `target` and `goto` step labels. The browser still opens the original URL. Error messages and reports saved earlier are not rewritten (#57).
+- Starter apps from `somewhere init`: the email-verification panel offers "I already have a code" beside "Email me a code". It opens the code form without sending another email, so a code already received still works after a new tab or reload. A failed or rate-limited send still does not open the form (#59).
+
+## 0.37.61
+
+### Fixed
+
+- `somewhere verify --out <existing file>` still never overwrites a report, and now names the next free path to rerun with (for example `--out flows/run2-report-3.json`) (#56).
+- `somewhere pull` writes the starters' `.gitignore` when the folder has none, so the declarations `somewhere typecheck` generates (`__somewhere_data.d.ts`, `__somewhere_files.d.ts`) stay untracked in a pulled app. An existing `.gitignore` is never changed (#55).
+- `somewhere lint`: quoted verifier text can no longer hide a row-ownership warning; the exception now covers only executable verifier member calls. Vendored with the platform's source lint (#53).
+
+## 0.37.60
+
+### Fixed
+
+- `somewhere verify --out` no longer summarises a run in which no browser started as "0 failed steps": it says "Verify FAIL: no browser ran (<codes>); nothing was checked, so this is not an app result", and a partial journey names its unstarted segments. `--json` summaries add `segments_not_started` and `start_errors` (error codes only) (#50).
+
+## 0.37.59
+
+### Fixed
+
+- `somewhere deploy` in a folder whose `.somewhere.json` links a project this sign-in can't open (for example an expired, unclaimed temporary project) now explains that, says nothing was deployed, and lists the next steps: see your projects, `somewhere init --link --project <name-or-id>`, or delete the link and `somewhere init --bare --name <name>`. `--json` adds `linked_project_id`, `deployed: false` and `next_steps` (#51).
+- Project commands run in an unlinked folder (logs, errors, env, project view, open, verify, browser open, db, db rows, status, pull, rollback, run, git) name the exact link and create commands instead of "run from a linked directory" (#51).
+
+## 0.37.58
+
+### Fixed
+
+- `somewhere browser --actions` and `somewhere verify` flows keep an action's `"frame"` (frame name, URL substring, child index, or iframe CSS selector) and send it to the platform, so a framed `fill`, `eval` or `expect` runs inside the iframe instead of on the top page. Before, `frame` was dropped, and a framed `eval` could pass against the top page. Whole-page actions (`goto`, `dialog`, a fixed `wait`) and malformed frames are refused; the local browser refuses framed actions; `verify --schema` lists `frame` (#48).
+
+## 0.37.57
+
+### Changed
+
+- `somewhere lint --help` names every warning the lint reports: credentials in source, schema declarations, directory index routes, request input choosing row ownership on server writes, and `sw.email.send` awaited inside a loop (#47).
+
+## 0.37.56
+
+### Fixed
+
+- `somewhere docs constructor` (and other built-in object names such as `__proto__` or `toString`) now answers that no such documentation topic exists, instead of a false "Could not reach https://somewhere.tech — check your connection." Quick-link topic and alias lookups use own keys only.
+
+## 0.37.55
+
+### Added
+
+- `somewhere lint`: a new warning when `sw.email.send` is awaited inside a loop (each email waits for the previous delivery); it advises bounded batches only for independent emails (#43).
+
+## 0.37.54
+
+### Fixed
+
+- Signed out, `somewhere docs <topic>` resolves the same topic names the docs tool does: after an exact page id, it looks the name up in the public docs manifest's `aliases` (lowercased, then with non-alphanumeric runs as `-`), so `somewhere docs schema-changes` opens `sw.db`. A manifest without `aliases` keeps today's behavior, and a real page id always wins.
+
+## 0.37.53
+
+### Changed
+
+- `somewhere deploy --help` has a "No project yet?" section naming `somewhere init --bare --name <name>` (create a project in your account and link this folder), and `--project` now says it takes an existing project.
+- `somewhere projects` help and its empty-list line name `somewhere init --bare --name <name>`.
+- `somewhere project create` says how to deploy to the project it made (`somewhere init --link --project <id>` then `somewhere deploy`, or `somewhere deploy --project <id>`).
+- When the platform reports no live URL, the CLI names `somewhere project view <id>` instead of "check the dashboard".
+
+### Fixed
+
+- The signed-in "No project is linked" deploy message (since 0.37.49) recommended `somewhere link --project <name-or-id>`, which `link` does not accept. It now names `somewhere init --link --project <name-or-id>`, which does.
+
+## 0.37.52
+
+### Fixed
+
+- The expired temporary-session deploy message no longer opens with "expired … without being claimed", which contradicted its next step for someone who did claim the workspace in the browser. It now says this machine has no record of a claim; the first step is still "sign in with `somewhere login` if you claimed it".
+- `somewhere lint` no longer reads binary assets, and carries the vendored source-lint fix for a `user.id` false positive (#37).
+- `somewhere verify`: when a request you declared with `expect_requests` came back with a different status, the verdict now leads with that mismatch ("Expected /api/deny to return 200; saw 403.") instead of only reporting the status as undeclared. The pass/fail result and exit code are unchanged (#36).
+
+## 0.37.51
+
+### Fixed
+
+- Starter `AGENTS.md` (from `somewhere init`) follows the current platform agent workflow: test sign-in uses managed test identities, matching the platform docs (#32).
+- `somewhere email test-inbox` prints a message's `verification_code` in its human output when one is present, not only with `--json` (#32).
+
+## 0.37.50
+
+### Fixed
+
+- An expired temporary session's deploy message now first tells you to sign in with `somewhere login` if you claimed the workspace in the browser, before suggesting you delete `.somewhere.json`. The expiry message also appears only when the session's expiry time has actually passed (a session merely missing its token is no longer reported as "expired at" a future time).
+
+## 0.37.49
+
+### Fixed
+
+- `somewhere deploy` with an expired, unclaimed temporary session and a linked (or `--project`) project now stops before sending anything and says the temporary workspace expired and nothing was deployed. Previously it created a new temporary account and failed with PROJECT_NOT_FOUND. `--json` answers `TEMPORARY_SESSION_EXPIRED` with `temp_expires_at`.
+- Signed in with no linked project, `somewhere deploy` now names the exact next steps (`somewhere init --bare --name <name>`, `somewhere link --project <name-or-id>`, or `somewhere deploy --project <name-or-id>`) instead of "No project linked. Run `somewhere init`". It still never creates or links a project on its own.
+
+## 0.37.48
+
+### Fixed
+
+- `somewhere deploy` no longer reports "Your deploy was NOT applied" when its own automatic retry, sent after the first attempt timed out or lost its connection, is refused as STALE_RELEASE_BASE: the first attempt may already be live, so the CLI now says that and asks you to check the live release. `--json` adds `first_attempt_outcome: "unknown"` and `first_attempt_failure`. Other stale-base answers are unchanged.
+
+## 0.37.47
+
+### Changed
+
+- `somewhere init` starters use `@somewhere-tech/sdk` 0.12.3, which refreshes short-lived per-app sessions without making valid-token reads wait (0.12.1 could not refresh them). The feature starter keeps an exact pin; the basic starter keeps its caret range (#31).
+- New projects' `.gitignore` excludes the generated `src/__somewhere_data.d.ts` and `src/__somewhere_files.d.ts`; `typecheck`, `dev` and `deploy` regenerate them from `db/schema.ts`. Existing projects are untouched (#31).
+
+## 0.37.46
+
+### Added
+
+- `somewhere lint`: an offline, advisory source lint (warning-only; never blocks a deploy). Runs locally with no credentials; `--generic` also runs the project's own oxlint with a scrubbed environment and no shell (#26).
+- `somewhere lint` carries the platform's source-lint version 2 rules, re-vendored with full parity against the platform (#29).
+- `somewhere verify`: an actor may declare `{ "test_user": true }`. The run creates that many managed test identities in one request, signs each actor in once in its own browser, and deletes the identities after every browser closes (`--keep-test-users` keeps them; they expire after 24 h). No password or token is requested or reported (#27).
+- `somewhere verify`: a journey item may be `{ "parallel": [segment, segment] }` — 2–3 segments by different actors whose browser calls run at the same time, for realtime checks. Reports carry `parallel_group` (#28).
+
+## 0.37.45
+
+### Changed
+
+- `somewhere deploy` fetches project notices alongside the deploy instead of waiting for them first, so their round trip (about 0.1-0.9 s, up to a 3 s timeout) is no longer on every deploy's path. Notices still print once, on stderr, before the result or the failure and before a `--force` confirmation prompt.
+
+## 0.37.44
+
+### Fixed
+
+- `somewhere deploy --json` in a temporary (signed-out) session now prints the server's deploy result with the claim fields (`claim_url`, `expires_at`, `claim_connects_agent`) added. Before, it replaced the result, so `version`, `release_id`, `warnings`, `stage_timing_ms` and `reference_check` were dropped. Signed-in output is unchanged.
+
+## 0.37.43
+
+### Fixed
+
+- `sw.groups.add` and `sw.groups.delete` type-check in generated starters (TS2339 before): the vendored `runtime/declared-data.cjs` declaration is re-vendored from the platform (#22).
+
+## 0.37.42
+
+### Changed
+
+- Local checks read a bare `id()` in `db/schema.ts` as a random text key, the platform default since 2026-10-18; `id({ uuid: false })` declares an integer key. A foreign key must use its parent's key type (`text({ references })` for a random key).
+- `somewhere init --features private-data` keeps an integer key for notes, which its safe create retry needs. New starters otherwise get random text keys.
+
+## 0.37.41
+
+### Changed
+
+- The `AGENTS.md` written by `somewhere init` now says to set `auth` on every `sw.endpoint` (`'required'`, `'optional'`, or `'none'` when public on purpose), because a deploy refuses an endpoint without it. Webhooks, streams and custom responses still use a bare `export default async function (req, sw)`.
+
+## 0.37.40
+
+### Changed
+
+- Local declared-data checks understand `allOf(gate, who)` permission policies, matching the platform admission that is now live. The vendored declared-data code is refreshed from platform core ed285f7b.
+
+## 0.37.39
+
+### Fixed
+
+- `somewhere init` refuses a directory that holds only unrelated files, with no app source, before creating a remote project. It names those files and keeps them; `--bare` and `--link` still accept such a directory.
+- `somewhere verify` gives clearer guidance when a write gets a 409 in one viewport run but not another. Each viewport runs the flow separately, so creating the same record in each run is a possible cause. The run still fails and the 409 stays in the report.
+
+## 0.37.32
+
+### Changed
+
+- `somewhere init` keeps AGENTS.md and useful skills without installing command-running agent hooks or MCP registration. Existing local and global agent configuration stays unchanged.
+- The generated project guide asks agents to run `somewhere typecheck` after edits. Optional post-edit deploy-reference hooks remain available through explicit `somewhere hooks install --host <host>`; MCP setup remains explicit through `somewhere mcp install <host>`.
+
+
+## 0.37.9
+
+### Added
+
+- Every auth starter (plain `somewhere init` and `--features auth`) includes a "Verify your email" code panel for password accounts. It uses the SDK cookie session through the packaged `/api/auth` route, so the session decides the account and no token reaches page code. The starter pins `@somewhere-tech/sdk` 0.11.6.
+- `somewhere init --features magic-link` adds passwordless sign-in links: an "email me a sign-in link" form on the sign-in page and the `/auth/magic` page the email opens, routed in front of the sign-in gate. The page redeems the one-time token for the same cookie session, then opens the link's `redirect_uri` only when it is a page of this app. `sw.auth.invite` links land on the same page.
+- `somewhere init --subdomain <slug>` names the new project's subdomain (default: derived from `--name`). It cannot be combined with `--link`.
+
+### Changed
+
+- The bundled declared-data parser and generator are re-vendored from the current platform source.
+
+## 0.37.8
+
+### Fixed
+
+- Generated `AGENTS.md` now matches the current app workflow: start with the relevant docs, keep owner-scoped queries tied to the signed-in user, and authorize custom endpoints and server queries.
+
+## 0.37.7
+
+### Fixed
+
+- Self-update verifies the published provenance correctly. A refused update exits with an error and prints the npm installation fallback; versions at least one minor release behind get a daily warning.
+- `somewhere call` uses the linked project for tools that take `project_id`. An explicit ID wins; `--all-projects` omits the default and leaves scope to the tool.
+- `somewhere docs` opens the index instead of the entire manual. Use `docs search`, `--section`, or `--full` to read more.
+- Text output from `verify` includes eval results.
+- Browser commands support closing a named session and selecting an app user. User selection refuses an incomplete search rather than guessing.
+- `preview --once` syncs and exits; `preview link` produces a fresh link for an open preview.
+
+## 0.37.6
+
+### Added
+
+- `somewhere init --features agent` adds a signed-in assistant to the auth starter. It runs inline `sw.agent.run` with at most 4 steps and 10 cents per reply, and the conversation is saved on the server. It shows the tools each reply used. The assistant can read the user's tasks but only proposes new ones; a task is written when the user approves it. Approval and task creation are two writes, not one transaction: a task write that fails or whose outcome is unknown answers `TASK_CREATION_UNCONFIRMED` and never reopens the approval, so approving again cannot create a duplicate. Owner-scoped `tasks`/`proposals` tables are reached only through `api/chat.ts` and `api/proposals.ts`. `/fixtures?state=loading|empty|error|populated|long` renders preview states from static data without a request, and `flows/assistant-fixtures.json` screenshots them with `somewhere verify`. Durable runs, cancel, streaming and memory are not generated (`agent-durable` in `--catalog`).
+
+### Changed
+
+- The default auth starter and `--features` starters pin `@somewhere-tech/sdk` 0.11.3. Its auth code is identical to 0.11.2.
+
+## 0.37.3
+
+### Added
+
+- Advisor requests can reconnect to the same saved request after a terminal closes or a connection fails. Use `somewhere advisor --resume <request-id>`, `--status <request-id>`, or `--cancel <request-id>`. The CLI saves the receipt before starting paid work and keeps account and anonymous request ownership separate.
+- When the platform enables durable Advisor requests, the ordinary `somewhere advisor` command adopts the returned request automatically and waits for its result. Earlier platform responses continue to work. Ctrl-C leaves the request available to resume.
+
+### Fixed
+
+- Retrying a durable request uses its original receipt instead of creating another paid request. Cancellation records intent; an unknown dispatch remains an unknown outcome.
+
+## 0.31.12
+
+### Fixed
+
+- **File uploads work with attribute selectors.** `somewhere browser --upload`
+  read the file path from the FIRST `=` in the mapping, so a selector that
+  contains its own equals sign — `[data-testid=file]` — was cut in half and the
+  leftover text was treated as the path. The path is now read from the LAST `=`,
+  which leaves `#avatar=./photo.png` behaving exactly as before. For the rare
+  path that itself contains `=`, `--upload '<selector>::<file>'` states the split
+  explicitly. `--fill` and `--select` are unchanged: their values often contain
+  `=`, so they still split at the first one.
+- **`somewhere typecheck` no longer fails on a project you have not installed
+  yet.** A freshly created or freshly pulled project declares its type packages
+  in `package.json` but has nothing in place until dependencies are installed,
+  and the first check reported that absence as a dozen type errors in your own
+  code. The check now puts the type packages your project declares in place
+  before it runs, so the first answer is a real one. Only packages you already
+  declare are resolved, an import you never declared still fails with its real
+  error, and a project that is already installed does no extra work. If the
+  packages cannot be fetched, the check still runs and reports what it finds.
+
+### Added
+
+- **Scheduled triggers can be created in your own time zone.**
+  `somewhere cron create --timezone <IANA>` — for example
+  `--timezone America/Los_Angeles` — reads the cron expression in that zone and
+  handles daylight saving for you, so `0 9 * * *` means 9am locally all year.
+  The platform has accepted this since scheduling shipped; only the CLI was
+  missing the flag and its help text called every expression UTC. Omit the flag
+  and nothing changes: schedules are still read in UTC.
+- **Every command says it has started.** The CLI now prints
+  `starting somewhere CLI <version>` as its first line in an interactive
+  terminal, so a first run shows something immediately and names the version you
+  actually got. The line goes to the error stream and only ever appears on a
+  terminal, so piped output, `--json`, and scripts are byte-for-byte unchanged.
+  Note that a first `npx @somewhere-tech/cli …` on a cold cache can still sit
+  quiet for up to a minute BEFORE this line: npm downloads and installs the
+  package before running any of its code, and that download is silent by npm's
+  design — no code we ship can speak during it. Install once with
+  `npm i -g @somewhere-tech/cli` to skip that wait on every later run.
+
+## 0.31.11
+
+### Added
+
+- **Test passwordless sign-in without sending mail to a real inbox.**
+  `somewhere email test-inbox` reads the stored auth messages for an address
+  owned by the project and shows the extracted magic-link URL alongside the
+  rendered message.
+- **Browser checks can attach files and name screenshots.** `somewhere browser`
+  accepts repeatable `--upload <selector=file>` actions, while
+  `--screenshot <name>` saves a capture under the requested label. The same
+  actions work in shared browser and verification flow files.
+- **Authenticated pages can be verified at desktop and phone sizes.**
+  `somewhere verify --session` seeds an existing app session, and repeatable
+  `--cookie <name=value>` options carry existing cookies into every viewport.
+- **The catalog now explains how to call each tool.**
+  `somewhere catalog <tool>` prints the tool description and complete input
+  schema, including nested constraints and fields such as cron timezones.
+
+## 0.31.10
+
+### Fixed
+
+- **A preview that cannot finish verifying now says so, and retries itself.**
+  When the platform could not yet confirm the uploaded preview build, the CLI
+  reported a generic internal error and dropped the session. That case is now a
+  named, retryable condition: `somewhere preview` replays the same save once on
+  its own, and only reports a failure — with a reference you can quote — if the
+  retry also does not complete. Nothing is created or changed on the failed
+  attempt, and whatever is live stays live.
+- **`somewhere preview --json` always answers with JSON.** A refusal — the plan
+  does not include previews, or the project has never been published and
+  `--publish-first` was not passed — used to print human prose on a `--json`
+  run. It now returns the same typed JSON error shape as every other refusal,
+  so a script or agent can read the reason instead of parsing sentences.
+
+## 0.31.9
+
+### Added
+
+- **Cron and email are first-class CLI command groups.** `somewhere cron`
+  exposes list, create, update, delete, and run-once commands, while
+  `somewhere email` exposes transactional send. `somewhere cron run` accepts a
+  cron ID or a task name and runs it once without changing its schedule. Each
+  group names its commands and includes a copyable example in `--help`. During
+  the platform rollout, run-once exits with a typed
+  `CRON_RUN_NOT_AVAILABLE` message on older platform versions.
+- **Stale CLI installs get one concise update line.** The existing daily,
+  fail-open version check now has explicit newer/current and cache-throttling
+  coverage, and its notice fits on one line.
+
+### Fixed
+
+- **Every registered command owns its help output.** Command help can no
+  longer silently look like the generic top-level banner, and the complete
+  non-pass-through command surface is fixture-covered.
+- **Every bundled init template writes a valid `.gitignore`.** The current
+  green starter already emitted real line breaks; the older exported template
+  no longer carries literal `\\n` text.
+- **A pending package verdict is described as pending.** npm installation
+  continues without waiting for a result, without presenting that non-blocking
+  fallback as a failed install.
+
+## 0.31.8
+
+### Added
+
+- **`somewhere verify` runs a complete browser acceptance flow in one command.**
+  Give it a live or local URL and an optional flow file to get one report with
+  every named step, page/console/network health, and desktop and mobile
+  screenshots. `somewhere deploy --verify <flow.json>` can run the same check
+  immediately after publishing.
+  During the platform #24 rollout, hosted action flows on an older serving
+  release fail honestly with a missing-screenshot or unfiltered expected-
+  refusal health result; they do not crash or report a false pass. Re-run the
+  same command after the rollout reaches the project.
+- **Browser action files now have one canonical shape everywhere.**
+  `somewhere browser --actions` and `somewhere verify --flow` use the same
+  concise action array, such as `{"fill":"#email","value":"a@b.co"}` followed
+  by `{"click":"#save"}`.
+
+### Fixed
+
+- **Preview handoffs are directly runnable from any directory.** Every promote
+  command printed by `somewhere preview` carries its project context, and the
+  non-interactive form includes `--yes`. The watcher now notices a promotion
+  promptly and exits without consuming or silently dropping the next save.
+- **A first preview no longer looks frozen while it publishes production.**
+  `somewhere preview --publish-first` reports each bootstrap phase, elapsed
+  heartbeats, retries, and the platform's typed failure state.
+- **Preview access refusals are safe to automate.** Wrong-account lookups return
+  a stable `PROJECT_NOT_FOUND` result in human and `--json` output without
+  listing unrelated projects or attempting a deploy.
+- **`somewhere status` keeps production visible on Free plans.** It reports the
+  live production version and release even when private preview status is
+  unavailable on the account's plan.
+
+## 0.31.7
+
+### Added
+
+- **`somewhere init` now starts with a working full-stack TypeScript app.** In
+  an empty directory, the default starter includes a typed React page, a typed
+  server function, and a database schema, with exact dependency versions
+  installed before init reports success. Use `--bare` for the previous
+  metadata-only setup; existing source directories are still left untouched.
+
+### Fixed
+
+- **Project deletion now follows the platform's two-step confirmation flow.**
+  The CLI recognizes the successful `needs_confirmation` response as well as
+  the older error-shaped response. At a terminal it asks for the project name;
+  without a terminal it prints the exact `--confirm-code` command to run next.
+  Unrelated server errors continue to surface unchanged.
+- **A slow package verdict no longer turns into a failed install.** Verdict
+  lookups have a more realistic cold-start allowance. If that allowance is
+  exhausted, `somewhere npm install` says `verdict pending` and continues with
+  npm under the default fail-open policy.
+
+## 0.31.6
+
+### Added
+
+- **Device login now shows what is asking for access.** The approval page can
+  show the machine name, CLI and runtime versions, operating system, and the
+  requested project scope before access is allowed or denied. After approval,
+  `somewhere login` prints that scope, `somewhere whoami` names the current
+  session and its access, and `somewhere logout` revokes the session on the
+  server before removing the local credential.
+- **`somewhere browser` can drive routine flows without custom JavaScript.**
+  Repeatable `--fill`, `--select`, `--click`, and `--expect` flags run in command
+  order, while `--actions <file.json>` accepts the same shared action sequence
+  as the platform browser. `--expect-request <path:status>` treats an intended
+  response such as an authorization refusal as expected, and `--visible-only`
+  removes hidden controls from the page outline. Localhost session help now
+  says plainly that named sessions are unavailable there and points to a fresh
+  local browser run.
+- **`somewhere db apply-schema` prepares a managed database before the first
+  deploy.** It reads `db/schema.ts` by default, applies the declaration to the
+  production database without publishing the app, reports an already-current
+  schema as a no-op, and preserves the planner's exact safety message when a
+  removal needs an explicit `removed()` or `removedTable()` marker.
+
+### Fixed
+
+- **Local browser checks no longer stall when the CLI uses an isolated home on
+  macOS.** The headless browser still runs with a new scratch profile and no
+  extensions, while the CLI's credentials remain inside the isolated home.
+
+## 0.31.5
+
+### Fixed
+
+- **`somewhere dev` now moves past a busy default port automatically.** If
+  8787 is already in use, the local loop selects the next free port and prints
+  the choice before startup. Passing `--port` remains strict: a busy requested
+  port is an error, and the CLI names the process using it when the operating
+  system can identify one.
+- **Local database requests now explain where their time went.** Each
+  database-backed request in the local loop prints the complete database
+  round-trip beside the request total and includes the database execution time
+  reported by the platform when it is available. Working responses without
+  that field keep working and say that the timing was not reported.
+
+## 0.31.4
+
+### Fixed
+
+- **Status now shows which tested preview reached production.** When production
+  came from a promotion, `somewhere status` names the exact candidate and shows
+  a short content hash, so you can match the live app to the preview you tested.
+- **Promotion now uses the platform's own data notice and exact function count.**
+  The notice about preview rows is printed exactly as the platform sends it,
+  and the release summary says how many functions reached production when that
+  count is available. Older platform responses keep working quietly.
+
+## 0.31.3
+
+### Added
+
+- **`somewhere project allowed-origins list` and `… set` now exist.** Allowing
+  another web address to call your project from a browser was only possible
+  through the generic tool-call escape hatch with a raw project id — so the
+  command guidance told you to run was not a command the CLI had. It is now a
+  first-class command with the obvious spelling, it shows up in
+  `somewhere project --help`, and it takes `--project <ref>` like everything
+  else. `set` replaces the whole list (`--clear` empties it) and refuses an
+  address the allowlist could never match — a path, a query, a wildcard, a
+  trailing slash — before sending it, naming what is wrong. Your project's own
+  address and any verified custom domain are always trusted and never need
+  listing.
+
+### Fixed
+
+- **The promote command the CLI prints can now be run in the shell that printed
+  it.** `somewhere preview` and `somewhere status` printed
+  `somewhere promote <session> <preview>`, and `somewhere promote` then refused
+  that exact command whenever there was no terminal to confirm with — so in a
+  script, an agent, or a piped terminal the CLI handed you a command it would
+  reject. The printed command now matches the shell reading it: without a
+  terminal you get the runnable form, with `--yes` on it; at a keyboard you get
+  the ordinary confirming form first and the unattended one named beneath it.
+- **Promotion now says what happened to your data.** Promoting moved your app
+  and said nothing about the rows you created while previewing, which stay in
+  the preview database — the isolation is the point, but discovering it by
+  opening an empty production page and repeating your whole acceptance pass is
+  not. A successful promote now states that only the app was promoted, that
+  production is serving the data it already had, and that production is worth
+  checking and seeding before you call it shipped.
+- **One project now reports one size of itself.** The same directory was
+  described three different ways: `somewhere deploy` counted static files and
+  functions separately, `somewhere preview` reported a single "3 files" with the
+  function hidden inside it, and `somewhere promote` said "3 files + functions",
+  replacing the count with the word. Worse, deploy's number did not match what
+  the project itself listed. All three now print the same shape — `3 static
+  files + 1 function` — off the same counting rule, and promote reports what
+  production actually holds rather than a tally that disagreed with it.
+- **`--project` works on every command that names a project.** `logs`,
+  `errors`, `status`, `open` and `rollback` accepted only a positional project
+  and answered `unknown option '--project'`, while a dozen other commands took
+  the flag — so the syntax you learned on one command failed on the next. All of
+  them now take `--project <ref>`, the positional keeps working everywhere, and
+  naming two different projects in one command is refused rather than guessed.
+
+## 0.31.2
+
+### Fixed
+
+- **`somewhere dev` now runs the same entry files `somewhere deploy`
+  publishes.** A project whose `index.html` points at
+  `<script type="module" src="/src/main.js">` deploys and serves perfectly —
+  the platform serves plain JavaScript modules exactly as you wrote them,
+  rather than compiling them — but the local loop refused to start on it at
+  all, insisting on `.tsx`. It now follows the same rule deploy follows: your
+  `index.html` names the entry, `.tsx` / `.ts` / `.jsx` / `.mts` / `.cts` are
+  compiled, `.js` / `.mjs` / `.cjs` are served as written, and a page with no
+  module script at all (a browser-Babel page, a static site) simply runs. The
+  loop stops only when `index.html` names a file that is not in the directory
+  — and then it says which file, and which forms it accepts.
+- **The local runtime no longer suggests editing a package file outside your
+  project.** Running a function could print advice to add `"type": "module"` to
+  a `package.json` in a parent directory — on some machines, the one in your
+  home folder. The cause was a module-format lookup with no upper bound, which
+  walked straight past the project. The runtime now determines the format from
+  your project's own package file and your own source, stopping at the project
+  root, so no advice can ever name a file outside it. CommonJS and ES module
+  functions both keep working exactly as they do when deployed.
+- **`somewhere browser --eval` prints the evaluated value in normal output.**
+  The value came back correctly with `--json` but was dropped from the default
+  text report, so the command you use to check a live page did not show what it
+  found. Text output now prints the value under the step — strings as
+  themselves, objects readably indented — and an expression that returned
+  nothing says so instead of leaving a blank line.
+- **`somewhere deploy --temporary` means temporary, whether or not you are
+  signed in.** Being signed in used to override the flag and switch the deploy
+  to your account, which then failed in a directory with no linked project. The
+  flag is the request: it always deploys to a temporary workspace, never needs a
+  linked project, and prints the live URL, the claim link, and when the
+  workspace expires. Your account sign-in survives it untouched, the directory's
+  own link is left alone, and a second `--temporary` deploy in the same window
+  redeploys the same temporary app instead of creating another. A deploy without
+  the flag is unchanged.
+
+### Changed
+
+- `somewhere init` closes by naming what to run next on the platform —
+  `somewhere dev` to run your app here, `somewhere deploy` to publish it — and
+  notes that any coding agent can drive this CLI, in place of the previous
+  line naming one specific tool.
+
+## 0.31.1
+
+### Fixed
+
+- `tsk_5504e045` — **`somewhere preview` can no longer publish to production on
+  its own.** A preview builds on your app's live version, so a project that has
+  never been published needs one published first — and that publish is a real
+  production release, the one thing this command can do to your live site. It
+  was happening in two ways it should not have. On a project that was already
+  live, if the CLI could not read which version was live it treated the silence
+  as "this project has never been published" and went ahead and published your
+  working directory over the running app. And on a project that genuinely had
+  never been published, it published without asking at all.
+
+  Now: a version the CLI cannot read is unknown, and unknown never publishes —
+  the command stops, says what it could not read, and leaves your live site
+  exactly as it was. A publish happens only when the platform positively
+  confirms nothing is live AND you say so, either by answering the prompt or by
+  running `somewhere preview --publish-first`. A run that cannot be asked — a
+  script, an agent, a piped shell — is refused and told about the flag. Preview
+  on a project that is already live never publishes anything, as before.
+- `tsk_5504e045` — **the plan refusal stopped claiming your project is
+  unpublished.** On a Free or Builder account, `somewhere preview` on a live
+  project refused with "Nothing was created — this project has not been
+  published", which was simply untrue and sent people to re-deploy an app that
+  was already running. The refusal now says only what it did: nothing was
+  created or changed, and whatever is live stays live.
+
+### Changed
+
+- The dev compiler and function runtime are re-vendored from the platform at
+  `3237dc1e`, picking up the faster dependency install — a project with a
+  lockfile now installs the way the platform installs it, without development
+  dependencies. `somewhere dev` compiles your app with the platform's own
+  compiler, so this keeps what you see on localhost identical to what deploy
+  produces.
+
+## 0.31.0
+
+### Added
+
+- `tsk_5cfcfe00` — **`somewhere preview` is a command.** There are two loops and
+  they are now named after where the app runs: `somewhere dev` runs your app on
+  your machine, `somewhere preview` runs it on the platform. Every save goes to
+  a private URL reachable only by you; production keeps serving what you last
+  promoted until you run `somewhere promote`. Reach for it when you want the
+  real hosted app in front of you, or when your agent cannot serve on
+  localhost. `dev --cloud` still starts it and prints one line naming the new
+  command.
+
+### Fixed
+
+- `tsk_33023348` — **`somewhere promote` never reports an outcome it does not
+  know.** It used to print "Promote failed / Unknown error" for a promote that
+  had already shipped, and the obvious retry then said "Production was not
+  changed" about production that the first command had changed. Promote is the
+  one irreversible step in the loop, so it now separates a refusal the platform
+  AUTHORED (reported as written) from a response the CLI could not READ. In the
+  second case it reads what production is serving before and after and answers
+  from whether that moved — and a refusal claiming production was unchanged is
+  checked against the same evidence before it is allowed to stand. When neither
+  side can be read it says the status is unknown and points at your production
+  URL rather than guessing.
+- `tsk_74375b3c` — **a promote ends the preview cleanly.** Promoting closed the
+  preview, but the loop kept watching, and your next save came back with a
+  refusal written for an API client — then failed the same way on every save
+  after that. The loop now recognises the end of a preview and stops on it, in
+  two lines: what happened, and the one command that starts the next preview.
+- `tsk_5cfcfe00` — the preview copy no longer claims your preview has
+  production's data. A preview runs against a separate copy of your schema with
+  none of your production rows, which is exactly what makes it safe to try
+  things in.
+- `tsk_d63b3b6a` — **an unresolvable import is reported, not a crash.**
+  `somewhere dev` died on any import that could not be resolved — a typo'd
+  package, one you had not installed yet — with an internal error naming the
+  CLI's own bundler and nothing about your code, and every rebuild after that
+  failed too. It only happened when the command's error output went to a file
+  rather than a terminal, which is the normal case under an agent, a CI job, or
+  a session recorder. Now an unresolved import reads like a syntax error:
+  file:line:column, the specifier, and one sentence naming the fix — add it to
+  your package.json and install it, or, for a module the platform provides,
+  that it comes from the platform and should not be installed at all. The
+  server survives, the last working page stays up, and a save that fixes it
+  serves again.
+- `tsk_14c5408c` — a burst of saves stays one preview update. Saves inside the
+  debounce window accumulate into a single update, and a save that lands while
+  one is in flight re-arms instead of starting a second, so two previews are
+  never building at once.
+
+### Changed
+
+- The vendored platform runtime and compiler are re-synced to the current
+  platform build. Content is unchanged from 0.30.2 apart from the provenance
+  stamp — the compiler files hash identically — so this release changes no
+  build behaviour.
+
+## 0.30.2
+
+### Fixed
+
+- `tsk_a8cb3d23`, `tsk_f79d71ce` — `somewhere dev` and `somewhere deploy` now
+  derive dependency versions from the SAME code, so a build on your machine and
+  a build on deploy resolve the same libraries. The platform's compiler reads
+  your lockfile as of today: a version your lockfile pins is the version that
+  gets installed, provided it satisfies the range your `package.json` declares.
+  This CLI carries that compiler, so `somewhere dev` follows the identical rule
+  — it is one implementation, vendored, not two that agree by coincidence. A
+  project with NO lockfile is unchanged: the declared range still floor-pins.
+
+### Known difference
+
+- The JavaScript bundle `somewhere dev` builds and the one `somewhere deploy`
+  builds are not byte-identical, and the reason is now only bookkeeping: build
+  comments and source-map entries record where each module was read from, which
+  is your machine locally and the build image on deploy. It has no effect on
+  what your app does.
+- The dependencies your project DECLARES resolve the same on both sides. Their
+  own transitive dependencies are still resolved by npm from the parents'
+  ranges, so those can differ. Pin one exactly in `package.json` if it matters
+  to you.
+
+## 0.30.1
+
+### Added
+
+- `tsk_0e9e13b8` — `somewhere signup` exists. Someone who has never used the
+  platform ran `somewhere login`, and the CLI's answer assumed they already had
+  an account. `signup` prints the page that creates one, and `login` names it
+  too, so the front door is a door.
+- `tsk_c166924f` — `somewhere deploy` publishes your **app**, not the folder it
+  was built in. Notes, task lists, scratch files and agent instructions in your
+  project root stay on your machine: the deploy prints `Not published (N): …`
+  naming exactly what it held back, so the decision is visible rather than
+  silent. Publish one on purpose with `somewhere deploy --include <file>`, or
+  keep it permanently with a `!<file>` line in `.somewhereignore`.
+
+### Fixed
+
+- `tsk_926fbf8e` — `somewhere docs <topic>` answers from the public corpus with
+  no login. Reading the documentation used to require an account, which is the
+  wrong order: you read the docs to decide whether to make one.
+- `tsk_f250e561` — `somewhere status` exits 0 when the platform answers a plan
+  question. A feature your plan does not include is an ANSWER, not a failure;
+  exiting non-zero made every scripted `status` on a Free account look like a
+  broken command.
+- `tsk_a605ff7b`, `tsk_10be456b` — `somewhere browser` against a local URL now
+  fails inside a bound instead of hanging. Every wait on the local path has a
+  deadline, a port with nothing listening is reported as such with the remedy
+  named, and the browser's own favicon request — which the page never made — no
+  longer counts as your app returning a 404.
+- `tsk_9c5ed7f8` — a failed `somewhere deploy` now says something you can act
+  on. When the platform answers `retry: true` — its own statement that the
+  request changed nothing and the same one is safe to send again — the CLI
+  retries once instead of stopping (it parsed that field and never read it).
+  An error body it cannot classify prints the status and the response instead
+  of the bare words "Unknown error". And every deploy failure now prints the
+  request id from the response, so a failure you can see is a failure we can
+  find.
+- `tsk_eef0a0ef` — `somewhere dev` prints your app's output, not the platform's
+  telemetry. Database calls were emitting raw internal metrics JSON and a
+  repeated "deferred flush failed: HTTP 403" from a background channel you did
+  not ask for and cannot fix. Both are gone by default; set
+  `SOMEWHERE_DEV_TELEMETRY=1` to see them.
+- `tsk_a8cb3d23` — the local loop resolves a dependency at the version the build
+  image serves, for every package the image carries. This already held for
+  React; it now holds for the whole baked set (router, query, state, forms,
+  validation, http, dates, utils, styling, animation, charts, icons), so a
+  declared `^3.23.0` no longer compiles against 3.23.0 on your machine and a
+  newer one on deploy. A pin is taken only when the image's version satisfies
+  the range you declared — a project on a major the image does not carry is
+  untouched.
+
+### Known difference
+
+- The JavaScript bundle `somewhere dev` builds and the one `somewhere deploy`
+  builds are built by the same compiler, from the same source, with the same
+  toolchain. They are not byte-identical, and there are two reasons rather than
+  one. Build comments and source-map entries record where each module was read
+  from — your machine locally, the build image on deploy — which has no effect
+  on what your app does. Separately, the two builds can still resolve DIFFERENT
+  VERSIONS of an app dependency: `somewhere dev` uses the tree you installed,
+  while `somewhere deploy` resolves the range your `package.json` declares and
+  does not yet read your lockfile. If that matters to a library you depend on,
+  pin it exactly in `package.json` and both sides agree.
+
+  **Superseded by 0.30.2**, which closes the version difference. The paragraph
+  above describes 0.30.1 only, and is kept because that version is published.
+
+## 0.30.0
+
+### Added
+
+- `tsk_9ec50c84` — `somewhere browser` now drives a **localhost** target. The
+  app `somewhere dev` is serving used to be the one address this CLI's own
+  browser would not visit, so every visual and DOM check had to wait for a
+  production deploy. A loopback URL is now driven by the browser already
+  installed on your machine — no new dependency and nothing to download. Each
+  run gets an empty throwaway profile, so it never reads or writes your real
+  browser profile. If there is no browser at all, the CLI says so and names the
+  environment variable to point at one. Flags only the hosted browser can honour
+  (`--store`, `--session`, `--extract`, non-`dom` `--include`) are refused by
+  name rather than silently dropped from a report that still looks complete.
+- `tsk_70fd0f63` — `somewhere errors` gained a `kind` column and an
+  `--exceptions` flag, so you can see only what actually broke.
+
+### Fixed
+
+- `tsk_bdd72f02` — `somewhere browser --snapshot` now asks for the map it
+  prints. `--snapshot` renders the interactive-element outline, but it never
+  requested that section, so it printed whatever the response happened to carry
+  — usually nothing. `browser --wait button --snapshot` would match a button and
+  then report "dom: 0 interactive elements" on a page with three buttons and two
+  inputs. It now adds `dom` to the requested sections, merging with an explicit
+  `--include` rather than replacing it. The local outline comes from the
+  platform's own probe, so it is a preview of the hosted answer rather than a
+  second opinion.
+- `tsk_ea4274ca` — `somewhere errors` no longer calls a working auth gate an
+  exception. If you probed your own endpoint signed out — deliberately, to prove
+  the gate holds — your 401 was listed as the only exception in 24 hours. Rows
+  now show their kind: **refused** for a 4xx your handler returned on purpose,
+  **exception** for an uncaught throw or a 5xx, with the summary line splitting
+  the counts. Nothing is hidden by default.
+- `tsk_ea4274ca` — a stored screenshot printed as a storage path, which reads as
+  a URL and is not one, so the one value the command handed back for "here is
+  your screenshot" could not be used to see it. The report now leads with the
+  link that opens it and keeps the stored path on its own line, because that is
+  the handle for reading or replacing the file later.
+- `tsk_53badecf` — `somewhere dev --check` and `somewhere deploy` no longer
+  report the `somewhere/db` import from our own managed-schema documentation as
+  a missing npm package whose remedy is installing an unrelated package. The
+  specifiers the platform provides are now treated as provided. A genuinely
+  missing package still warns, and still names every file that imports it.
+- `tsk_a21bc829` — `somewhere dev` no longer asks you for a variable the
+  platform writes. It warned that `APP_URL` had no local value on projects whose
+  source never mentions `APP_URL` — it never would, because deploy writes that
+  key. The local loop now fills it with the local origin, or with the project's
+  public URL when nothing is being served locally. Keys you genuinely own are
+  still named, which is the point of that warning.
+- `tsk_6a2a09bc` / `tsk_320a0bc6` — the local loop now declares tables the way
+  deploy declares them. It kept only the owner column and dropped the intent, so
+  `sw.db.from` on a `shared()` table answered "this table has no declared
+  intent" locally while working fine on the same deployed project. Intents,
+  owner scopes and the owner-identity mode now cross over exactly as the deploy
+  bundle bakes them.
+- `tsk_4df056ea` — when your plan does not include reaching the project database
+  from the local loop, `somewhere dev` now says so **once, at startup**, before
+  you write a line of code. It previously started a clean serving loop and let
+  you discover at the first request that every `sw.db` call was refused — with a
+  message that called it a connection problem and suggested redeploying, which
+  could never help. The loop still runs: the frontend compiles and serves, hot
+  reload works, and every function that does not touch the database still runs.
+  Deploying is unaffected on every plan, and the deployed app reads and writes
+  its database normally. `somewhere status` reports the same answer, including a
+  `local_dev_db` object in `--json`.
+- `tsk_a21bc829` — `--check`'s help now says what the documentation says: it
+  needs a real `npm install`, because the typechecker reads package types out of
+  `node_modules` and the CLI's dependency cache does not stand in for that.
+
+### Changed
+
+- The vendored platform runtime and compiler are re-synced to the current
+  platform. For the local loop this brings `owner()` scoping on visitor-mode
+  projects, exact 64-bit integer fidelity on structured writes and batches, and
+  the plan-derived local-database answer above.
+
+
+## 0.29.1
+
+### Changed
+
+- `tsk_0100d8e5` — the local loop now runs the CURRENT platform runtime. The
+  copy the CLI carried had frozen several months behind, so `somewhere dev` was
+  quietly running your `api/` functions against an older `sw.*` than your
+  deployed ones. Re-synced deliberately, with a hash guard so it cannot drift
+  silently again. What this changes for you is below.
+- `tsk_0100d8e5` — the structured database API works locally: `sw.db.from`,
+  `.insert`, `.update`, `.delete`, `.count`. Tables need a scope declaration for
+  the platform to scope them to the signed-in user; an undeclared table returns
+  a clear error naming the table.
+- `tsk_0100d8e5` — also newly available in the local loop: sign-in with GitHub
+  and Discord, roles and moderation (`sw.auth.requireRole`,
+  `sw.auth.moderation.*`), plans and entitlements (`sw.billing`), scheduling
+  (`sw.calendar`), contacts, and durable agents (`sw.agent`). Email gains
+  delivery `status` and `history`, payments gains `quote` and a per-user billing
+  portal, and search gains `add`.
+- `tsk_0312cf17` — `somewhere dev` now builds with the same React version the
+  deploy image builds with. It previously installed the lowest version your
+  range allowed (`^19.2.0` became 19.2.0) while deploy used 19.2.7, so the loop
+  and production could differ by a patch release you would only discover in
+  production.
+- `tsk_106f7ab1` — one vocabulary for previews across the CLI. Commands and
+  messages say **preview** and **production**; `somewhere promote` names its
+  arguments `preview_session_id` and `preview_id`. `--draft` still works as an
+  alias of `--preview`, so nothing you already type breaks.
+
+### Fixed
+
+- `tsk_8a9d2d1a` — `somewhere deploy` no longer tells you "Next.js apps don't
+  run here" when your app is not a Next.js app. Any project with a `src/pages/`
+  folder tripped it — including the app `somewhere init` creates, so this was
+  often the first thing a new project printed. A Next.js app is now identified
+  the way the platform identifies one: a `next` dependency or a `next.config`
+  file.
+- `tsk_cf48f4ab` — `somewhere dev --cloud` on a plan without private previews
+  now refuses before doing anything, instead of publishing a first production
+  version and only then telling you the command is unavailable. Nothing is
+  created.
+
+### Known difference
+
+- The JavaScript bundle `somewhere dev` builds and the one `somewhere deploy`
+  builds are the same code, built by the same compiler — but they are not
+  byte-identical. Build comments and source-map entries record where each module
+  was read from, which is your machine locally and the build image on deploy.
+  It has no effect on what your app does.
+
+  **Correction (0.30.1):** this entry also said the two builds use the same
+  dependency versions. That was not true — they can resolve different versions
+  of a dependency whose range you left open. See the Known difference under
+  0.30.1 for what actually holds and what to do about it.
+
+## 0.29.0
+
+### Added
+
+- `tsk_95377909` — `somewhere dev` is now a LOCAL loop. It serves your app on
+  localhost and compiles it with the platform's own compiler — the same
+  `compile-core` the deploy pipeline runs, vendored into the CLI at the exact
+  esbuild version the compile container pins, with a hash manifest and a test
+  that fails if anyone edits it. No install step, no build step, no deploy:
+  a fresh `somewhere init` scaffold starts in a couple of seconds and a saved
+  TSX or CSS edit is on the page in a few hundred milliseconds. Compile errors
+  print file:line:column in the terminal and show on the page with the last
+  working page still underneath; `api/` functions run in local Node with
+  `sw.db` / `sw.fs` / `sw.ai` / `sw.auth` calling your real project.
+  There is no dev version of your app — same app, same data, same build.
+  Functions execute in your machine's Node during the loop rather than on the
+  platform's runtime, so a deploy is still what proves a function in production.
+- `tsk_737ff0d2` — the local server now answers on both `127.0.0.1` and `::1`,
+  so the `http://localhost:...` URL it prints opens in a browser that resolves
+  `localhost` to IPv6 first. Non-loopback addresses are still refused.
+- `tsk_3269026d` — `api/` functions resolve npm packages through the same
+  search path the compiler used, so a fresh scaffold's routes work with no
+  `npm install`. The project's own `node_modules` always wins.
+- `tsk_8796c588` — the pre-start typecheck is skipped, with one line saying
+  why, when the project has no `node_modules` — instead of reporting dozens of
+  unresolvable-type errors about code you did not write.
+
+### Changed
+
+- `tsk_95377909` — the cloud preview watcher, which used to be bare
+  `somewhere dev`, is now `somewhere dev --cloud`. `--local` is still accepted
+  and does what bare `somewhere dev` does. `somewhere dev <cmd...>` still runs
+  your own command with the project's environment variables injected.
+
+### Fixed
+
+- `tsk_8a3f6540` — `somewhere dev --cloud` on a project that has never been
+  published now publishes the first version once, announced in plain words,
+  instead of failing the initial sync. A private preview is a candidate built
+  against your live version, so there was previously nothing for the first one
+  to build on.
+- `tsk_e929774b` — the `--json` contract test no longer deploys to the live
+  platform on every `npm test`. It ran logged out with no API URL, so
+  `deploy`, `deploy-check` and `browser` reached production and minted a real
+  temporary account and a real project per run — while asserting nothing about
+  what those deploys did. The shape contract now runs against the local stub,
+  and the one test that does deploy for real
+  (`test/deploy-outcome-live.test.mjs`) uses an explicitly created throwaway,
+  asserts the deploy outcome and what the live URL serves, purges the
+  throwaway and confirms it is gone, and skips with a named reason when there
+  is no signed-in credential.
+
+## 0.24.0
+
+### Security
+
+- `tsk_f7ba3b57` — credential-at-rest hardening. Config is now written atomically at `0600` (a pre-existing world-readable `~/.somewhere/config.json` is tightened on every write, not just on create). `logout` now revokes the session server-side (best-effort) in addition to removing the local token.
+
+### Breaking
+
+- `tsk_f7ba3b57` — `auth set <token>` no longer accepts the token as a positional argument (it was visible in the process table to other local users). Provide the token via the `SOMEWHERE_TOKEN` environment variable or stdin: `printf %s "$TOKEN" | somewhere auth set`.
+
+## 0.23.1
+
+### Fixed
+
+- `tsk_e67bcc16` — made JSON mode a CLI-wide success/error contract, added JSON output to `docs`, `api`, and `init`, and covered every registered `--json` command with a parseability test.
+- `tsk_c6035afa` — duplicate of `tsk_06c1f77a`; rollback failures now remain structured JSON in JSON mode.
+- `tsk_41ee402b` — replaced the stale-era rollback snapshot wording with current recovery guidance; restoring the previous promoted release still requires the platform follow-up noted below.
+- `tsk_971775dc` — `logs --follow` now keeps polling after an empty initial query and suppresses overlapping records.
+- `tsk_8dc77749` — deploy requests now have an abortable long-call deadline, progress heartbeat, and one bounded retry instead of waiting without a terminal result.
+- `tsk_05a3cf11` — fixed the no-`node_modules` typecheck fallback to run `npx -y -p typescript tsc`.
+- `tsk_451eb155` — added non-interactive `init --link --project <ref>` with exact ID/name/slug/subdomain matching and JSON output.
+- `tsk_1584392a` — duplicate of `tsk_43fe9ff0`; corrected direct-run documentation for the multi-bin npm package.
+- `tsk_0160bfd4` — retained and regression-tested log-ID deduplication across follow polling cycles.
+- `tsk_208f7583` — replaced the confusing fresh-project rollback snapshot wording; the snapshot-selection platform follow-up is noted below.
+- `tsk_06c1f77a` — rollback API and network failures emit parseable JSON error envelopes.
+- `tsk_e6293ee2` — deploy warnings already present in the build log are no longer printed a second time.
+- `tsk_43fe9ff0` — documented the correct multi-bin invocation: `npx -y -p @somewhere-tech/cli@latest somewhere <command>` (or the equivalent `npm exec --package ... -- somewhere`).
+- `tsk_b210d436` — bare `somewhere docs` now streams the full reference; the topic menu remains available at `somewhere docs --list`.
+- `tsk_873f694c` — retained and regression-tested the real two-step project deletion confirmation flow and truthful server errors.
+
+### Platform follow-up
+
+- `tsk_41ee402b`, `tsk_208f7583` — rollback must select and restore the previous live/promoted release snapshot, not an intermediate deploy version, and every fresh deploy/promote path must persist the restorable snapshot before changing the live pointer.