naro-cli 0.17.0 → 0.19.0

package/README.md

@@ -58,15 +58,20 @@ naro link | init                   Link this directory to a Naro project
 naro unlink                        Remove the link
 naro projects [--team <slug>]      List projects
 naro project inspect               Show the linked project
+naro usage                         Team usage this month: requests, builds and custom domains against the plan, then by project
+naro usage --month 2026-09 --team acme  Another UTC month, another team
 
 naro deploy [--prod]               Build locally and deploy
+naro deploy --env qa               Deploy to a named environment (<subdomain>--qa) instead of the preview; not with --prod
 naro deployments                   List deployments
 naro inspect <deployment-id>       One deployment + build logs
 naro cancel <deployment-id>        Stop a build that is still running
+naro git connect [owner/repo]      Deploy on every push (installs the GitHub App if needed)
+naro git disconnect                Stop deploying on push
 
 naro logs                          Runtime logs (production)
 naro logs <deployment-id>          Build logs of a deployment
-naro logs --type build --follow    Stream build logs until READY/FAILED
+naro logs --type build --follow    Stream the latest deployment's build logs until it ends (exit 1 on FAILED)
 naro logs --env preview            Preview-surface runtime logs
 
 naro analytics                     Web Analytics: visitors, page views, top pages, referrers, countries, devices, browsers, operating systems (--range 7d)
@@ -82,10 +87,24 @@ naro protection                    Preview protection: on or off, and whether a
 naro protection enable | disable   Protect the preview URL (members only) or open it to anyone with the link (disable asks first; --yes in CI)
 naro protection bypass [remove]    Create (shown once) or remove the secret automation sends as x-naro-protection-bypass (replacing or removing asks first; --yes in CI)
 
-naro env list [--reveal]           Secrets masked unless --reveal
+naro env list [--reveal]           Secrets masked unless --reveal; an environment's value shows its name
 naro env add DATABASE_URL production
-naro env remove DATABASE_URL
-naro env pull [.env.local]
+                                   Target: production, preview, all (the default) or an environment name (qa)
+naro env remove DATABASE_URL       The production, preview and all values; an environment's only with its name
+                                   (naro env remove DATABASE_URL qa)
+naro env pull [.env.local]         Preview's values by default; --env production, or --env qa for an environment
+                                   (its own value wins over all; an unknown name fails before anything is written)
+naro env import .env.qa qa         Upload every variable in a dotenv file to one target (all by default; asks first,
+                                   --yes in CI; invalid keys or values over 5 KB stop it before any request)
+
+naro environments                  List the project's environments: address, branch, protection, and how many the plan allows
+naro environments create qa --branch qa
+                                   A QA or staging surface served at <subdomain>--qa; --copy-env preview|production|none
+                                   picks where its variables start, --database schema|empty how its database does
+naro environments set qa --no-branch --protection off
+                                   Change the branch whose pushes deploy here (--branch <b>, or --no-branch for none)
+                                   and who can open it (--protection on|off; off asks first, --yes in CI)
+naro environments delete qa        Delete it with its worker and protection key (asks first; --yes in CI)
 
 naro domains list
 naro domains add www.example.com   Prints the CNAME to create; naro connects
@@ -180,7 +199,7 @@ naro storage bucket create avatars --public --file-size-limit 5MiB --allowed-mim
 naro storage bucket update avatars --private | --file-size-limit none | --allowed-mime-types any
 naro storage bucket update docs --public   (asks first: anyone with an object's URL can download it)
 naro storage bucket list | empty <name> | remove <name> [--empty]   (empty and remove ask first)
-naro storage ls naro://avatars/u1 [--recursive]
+naro storage ls naro://avatars/u1 [--recursive] [--search <text>]   Names that start with <text>, ASCII case ignored
 naro storage cp ./me.png naro://avatars/u1/me.png [--upsert]   Up to the object limit, under 4 GiB (over 50 MiB in parts), with the service key
 naro storage cp naro://docs/team-1/plan.pdf ./                  Replaces a local file of the same name
 naro storage rm naro://avatars/u1/old.png [--recursive]   (asks first)
@@ -306,16 +325,14 @@ point at its table's primary key or a unique column. `--owner user_id` adds
 four actions; any other new table is closed to the Data API until you give it
 a policy (`CREATE POLICY` in a migration, or `naro policy create` or
 `naro policy set`; the command says so).
-Policies are kept by table name: a drop removes the table's policies whenever
-the project has a backend, on or off (the command says so). A rename leaves
-them under the old name, where they apply to no table — the command prints
-what to run to move them. Move them then: the next time `naro db table`
-creates a table as that name or renames one to it, renaming the table back
-included, the policies stored under the name are removed first, so a new
-table never inherits an earlier one's (except, on a project without a
-backend, one changed through `naro db table`, the table editor or MCP) — and
-neither does a table made by `naro db push` or `naro db query`. Whatever a command removes it prints
-so it can be made again: as `CREATE POLICY` statements, which
+Policies go with their table, as in Postgres and as `naro db push` does it,
+in the same migration: a drop removes the table's policies, and a rename
+moves them to the new name and rewrites the policies of other tables that
+read it (the command says which). A rename such a policy cannot follow is
+refused before anything runs. A table the command creates, or renames onto a
+name, never inherits what an earlier table of that name left there: that is
+removed first. A change that fails changes no policy. Whatever a command
+removes it prints so it can be made again: as `CREATE POLICY` statements, which
 `naro policy create` takes back, and — for owner rules, whose owner column
 `CREATE POLICY` cannot say — as the `naro policy set <table> … --owner <column>`
 command that sets them again. A statement that cannot be shown as it is (a
@@ -581,8 +598,10 @@ SQLite changes a column by building the table again — `CREATE TABLE
 __new_x`, copy the rows, `DROP TABLE x`, `ALTER TABLE __new_x RENAME TO x` — so
 the drop removes `x`'s policies and the rename does not bring them back. Write
 the `CREATE POLICY` statements again after the rename, in the same migration.
-A plain `ALTER TABLE a RENAME TO b` does not move them either: they stay under
-`a`, and `b` has none until you create them again.
+A plain `ALTER TABLE a RENAME TO b` in a migration moves `a`'s policies to `b`,
+and a policy of another table that reads `a` is written to read `b` — do not
+create them again on `b`: a policy of the same name already there is refused.
+`naro db table`, the table editor and MCP do the same.
 The answer's `warnings` lists the policies a migration removed, with SQL you
 can paste; it also says when the project has no backend yet (the policies are
 saved and apply once `naro backend enable` turns it on) and when a policy was
@@ -739,7 +758,10 @@ into named policies; it also turns a backend that is off back on, so run
 `naro backend disable` again afterwards if it should stay off. `naro policy
 list` and `naro policy remove` work in the meantime. A migration or a query
 that holds a `CREATE POLICY` or `DROP POLICY` gets the same answer before
-anything runs; SQL without one runs as before.
+anything runs, and so does any change that creates, drops or renames a table —
+in SQL, `naro db table`, the table editor or MCP, with the backend on or off:
+the stored rules apply by table name, and only `naro backend enable` clears
+them. Other SQL runs as before.
 
 `naro policy set` refuses with `409 POLICY_EXISTS` when the table's `naro_<action>` policy is not one it wrote (for example one made with `naro policy create`): `Policy <name> on <table> is not one naro policy set wrote. Change it with naro policy create, or drop it first: naro policy drop <name> --table <table>.` A `naro_<action>` policy that cannot be read as stored (the table answers `500 POLICY_INVALID`) is not refused: setting a rule replaces it, and `none` drops it.
 
@@ -804,6 +826,325 @@ An `--update-check` you give replaces the default: without
 
 ## Release notes
 
+### 0.19.0
+
+- `naro environments` manages a project's named environments, QA or staging
+  surfaces served at `https://<subdomain>--<slug>.naro.sh` beside production
+  and the preview. While the control plane has them switched off, every
+  sub-command fails with the server's `404 NOT_FOUND "Not found."`.
+  - `naro environments` (also `list`, `ls`) prints
+    `slug  url  branch  protection` and one row per environment (`—` when no
+    branch deploys there, protection `on` or `off`), then
+    `2 of 3 environments`, or `2 environments` (`1 environment`) on a plan
+    with no limit. With none it prints
+    ``No environments. Create one with `naro environments create qa`.``
+    first. `--json` prints `{ projectId, environments, limit }`.
+  - `naro environments create qa [--branch qa] [--copy-env preview|production|none] [--database schema|empty]`
+    prints `✅ Created environment qa → https://<subdomain>--qa.naro.sh`. A
+    flag left out leaves the server's default: no branch, the preview's
+    variables, the database seeded with the schema. `--copy-env none` copies
+    nothing. Other values fail before any request with
+    `--copy-env must be preview, production or none.` and
+    `--database must be schema or empty.`
+  - `naro environments set qa [--branch <b> | --no-branch] [--protection on|off]`
+    prints `✅ Updated environment qa`. Before any request it refuses
+    `--branch and --no-branch cannot be used together.`,
+    `--protection must be on or off.` and
+    `Nothing to change: pass --branch, --no-branch or --protection.`
+    `--protection off` asks
+    `Turn off protection for qa? Anyone with the link can open it.` first,
+    like `naro protection disable`; with `--json` or without a terminal it
+    needs `--yes` (`CONFIRMATION_REQUIRED`).
+  - `naro environments delete qa` asks
+    `Delete environment qa? Its worker and protection key are removed.`,
+    then prints `✅ Deleted environment qa` (`--json`:
+    `{ projectId, slug, deleted: true }`).
+  - A slug the project does not have fails `ENVIRONMENT_NOT_FOUND`
+    `Environment not found.` and changes nothing. The server's refusals
+    come through with their code and message, such as `ENVIRONMENT_EXISTS`
+    `An environment with this name already exists.` and
+    `ENVIRONMENT_BRANCH_TAKEN`
+    `Another environment already deploys this branch.`
+  - New options `--no-branch`, `--copy-env <source>`, `--database <seed>`
+    and `--protection <on|off>`. `--branch <b>` is in `naro help` now, and
+    says what it does: for `naro environments create` and `set`, the branch
+    whose pushes deploy to that environment; for `naro deploy`, the default
+    branch of a project the deploy creates or updates. A deploy's own branch
+    follows where it goes.
+- `naro deploy --env qa` deploys to a named environment instead of the
+  preview. It prints `✅ Deployment ready (qa)`, and `--json` has
+  `"target": "qa"` and `"environment": "qa"` (`null` for production and
+  preview). When the server gives no URL the CLI builds
+  `https://<subdomain>--qa.<host>`. `--env production` is `--prod` (and asks
+  `Deploy to production?` in a terminal the same way); `--env preview` is a
+  plain deploy. `--env` with `--prod` fails before anything is asked or sent:
+  `VALIDATION_FAILED` `--env and --prod cannot be used together.`, and
+  `--env ""` with `--env must be production, preview or an environment name.`
+  In a linked directory the environment is looked up before a missing key is
+  read, asked for or sent, and nothing is asked, sent or built when that
+  fails: a name the project has no environment for fails
+  `ENVIRONMENT_NOT_FOUND` `Environment not found.`, and while the control
+  plane has named environments switched off the deploy fails with their
+  `404 NOT_FOUND "Not found."`. Not yet linked, an environment deploy asks
+  for no missing value and sends none (the hint names the environment), and
+  the server answers `404 ENVIRONMENT_NOT_FOUND "Environment not found."`
+  for a name the project does not have.
+- Release order: deploy web with named environments 1b-2 before relying on
+  `naro deploy --env`. The deploy route of an older control plane ignores
+  the name and deploys a preview (the result says `(preview)`), saving the
+  values sent with it for `all`, which production builds read. In a linked
+  directory the environments route's 404 stops the deploy before that, and
+  an unlinked one sends no values.
+- `deployDirectory`, the library export the MCP server uses, refuses
+  `environment: "production"` and `environment: "preview"` (without
+  `production: true`) with `VALIDATION_FAILED`
+  `Pass production: true for production; preview is the default.` With
+  `production: true` the control plane answers
+  `environment and production cannot be used together.`
+- `naro deploy` counts the env vars a deploy is missing from the values that
+  deploy gets. A production deploy now lists a key set only for preview as
+  missing, and a preview deploy one set only for production; an environment
+  deploy counts the `all` values and that environment's own. On an
+  environment deploy, the values typed at the env prompt are saved for that
+  environment alone, so a developer, who cannot change `all`, has them saved
+  instead of listed under `⚠ skipped env:`. Production and preview deploys
+  still save them for `all`. The hint names the environment too:
+  `npx naro-cli env add DATABASE_URL qa`.
+- `naro env add` and `naro env remove` take an environment's slug as the
+  target: `naro env add DATABASE_URL qa`. A target that is none of
+  `production`, `preview`, `all` or a slug fails with
+  `Target must be production, preview, all or an environment name.` (it was
+  `Environment must be production, preview or all.`), and the usage reads
+  `Usage: naro env add KEY [production|preview|all|<environment>]`.
+  `naro env list` shows an environment's value under its slug.
+- `naro env remove KEY` with no target removes the `production`, `preview`
+  and `all` values and leaves every environment's alone; remove one with
+  `naro env remove KEY qa` (`Remove KEY (qa) from this project?`). A key
+  that only environments hold fails `ENV_NOT_FOUND` `No KEY variable found.`
+  and nothing is removed.
+- `naro env pull --env qa` writes an environment's values. A surface's own
+  value now wins over the `all` one whatever order the server lists them in
+  (before, the last row won), and preview's values never reach an
+  environment, as in the deploy. An environment the project does not have
+  fails `ENVIRONMENT_NOT_FOUND` `Environment not found.` before anything is
+  written. `--env` takes `production`, `preview` or a slug; anything else,
+  `""` included, fails with
+  `--env must be production, preview or an environment name.` (it was
+  `--env must be production or preview.`, and `--env ""` pulled preview).
+  The count in `✅ Pulled N variable(s)` and `--json` is the keys written,
+  so a key held by `all` and the surface counts once.
+- `naro env import <file> [target]` uploads every variable in a dotenv file
+  to one target, `all` by default. It lists the keys on stdout (stderr with
+  `--json`), every value masked but a `NEXT_PUBLIC_` one: the others,
+  `VITE_`, `REACT_APP_` and `PUBLIC_` included, are uploaded as secrets. It
+  asks `Upload 3 variables to qa?` (`1 variable`; `--yes` in CI),
+  and prints `✅ Imported 3 variables (qa)` (`--json`:
+  `{ projectId, file, target, count }`). Before any request it fails with
+  `Cannot read <file>.`, `No variables found in <file>.`,
+  `Invalid keys in <file>: A-B, 1X.` or
+  `Values over 5 KB in <file>: BIG.` (5,120 UTF-8 bytes, the limit the
+  server keeps). It uploads 100 variables per request, so a refusal of a
+  later request leaves the earlier ones saved. A line `export KEY=value`
+  reads as `KEY`. Values with `\"` or `\\` inside double quotes are read as
+  written, not unescaped, so a file `naro env pull` wrote with such a value
+  does not import back as it was (known-issues #224).
+- `naro env add` with a value typed at the prompt no longer loses it to a
+  refusal. It reads the project first, so a `--project` of another team or
+  of a deleted project fails `404 NOT_FOUND "Project not found."` before the
+  value is asked for. For an environment target it looks the environment up
+  too: a slug the project does not have fails `ENVIRONMENT_NOT_FOUND`
+  `Environment not found.` before the value is asked for, and while
+  environments are switched off `404 NOT_FOUND "Not found."` does. When the
+  role cannot write `all` (the default, or typed out), it asks
+  `You do not have permission to change production environment variables on this project. Save KEY for preview only?`
+  and on yes saves the same value for preview (`✅ Added KEY (preview, secret)`).
+  A named `production`, `preview` or environment target is not offered
+  another. A piped value works as before.
+- `naro usage` names a project that has moved to another team
+  `Moved to another team <id>`. Before, it read `Deleted project <id>`.
+- `naro db reset` reads the migration files the way the control plane now
+  runs them: `ALTER TABLE a RENAME TO b` moves `a`'s policies to `b`
+  (known-issues #87), so a policy a renamed table took along is no longer
+  listed as gone after the reset. A file that creates one of them again on
+  `b`, as the old advice said, would now stop the re-apply, and is named
+  before the schema is dropped:
+  `⚠ <file> would be refused: statement <n> of <m> failed and the migration was rolled back: policy "<name>" for table "b" already exists`.
+- `naro db table rename` moves the table's Data API policies to the new name
+  and rewrites the policies of other tables that read it, in the same
+  migration, as `naro db push` does (known-issues #87): the command prints
+  `⚠ Moved 1 Data API policy with posts to articles: own.` and
+  `⚠ Rewrote 1 policy that read posts to read articles: docs.team.`. A rename
+  a policy cannot follow is refused before anything runs. Before, the
+  policies stayed under the old name and the table was closed. Renaming the
+  table back brings them back.
+- `naro db table create`, `drop` and `rename` no longer print policies
+  "removed before the change ran" when the change fails: a change that fails
+  changes no policy now.
+- On a backend from before named policies, creating, dropping or renaming a
+  table answers `409 BACKEND_OUTDATED` until `naro backend enable` runs —
+  through `naro db table`, `naro db push` and `naro db query` alike.
+
+### 0.18.0
+
+- `naro usage` shows a team's usage for a UTC month from the terminal:
+  requests (blocked ones left out), builds and custom domains against what
+  the plan includes, a `✗`/`⚠` line when a Hobby team's sites are paused,
+  past the limit or at 80% of its requests, then a table by project.
+  `--month 2026-09` reads another month (the server checks the form and
+  answers `400 VALIDATION_FAILED "month must be YYYY-MM."`), `--team` picks
+  the team as `naro projects` does, and `--json` prints the whole report with
+  `summary`. Owners, billing members and enterprise viewers can read it;
+  other roles get `403 FORBIDDEN "Your role cannot read this team's usage."`.
+  A control plane from before `limits` prints `—` for what the plan includes.
+- `naro deploy` no longer copies env files from the working tree into the
+  build. The env files in the commit go in with their committed content, the
+  same files a git deploy of that commit builds with. An untracked
+  `.env.local`, a local edit to a committed `.env` and a change that is only
+  staged stay on the machine. Before, all of them were copied: `next build`
+  inlined their `NEXT_PUBLIC_*` values into the bundle and OpenNext bundled
+  every value into the Worker, including values declined at the env prompt.
+  Local values now reach a build only through the env prompt or
+  `naro env add`. Env file names match in any case: on macOS `.ENV.LOCAL`
+  opens as `.env.local`. `.env.example`, `.env.sample` and `.env.template` are
+  copied as before. The terminal says what was left out or replaced:
+  ``⚠ Left out of the build because they are not committed: .env.local. Local values reach a build only through the env prompt or `naro env add`.``
+  and `▸ Built with the committed version of .env; the local edits stay on this machine.`
+  The build log gets the same lines without the `⚠`/`▸`, as a warning and a
+  note. Without git the first line reads
+  `Left out of the build because git could not be run to read the commit: …`.
+- `naro deploy` no longer copies a symbolic link whose target is absolute or
+  leads out of the folder being deployed. Copied as it was, it led the build
+  to the developer's own files: whatever the app imported through it was
+  bundled, and an app folder linked from elsewhere had its `.env.local` read
+  by `next build`. Whether a link leads out is judged on its real path, from
+  the folder and again from the build's copy, so neither `self -> .` tricks
+  nor `..` up to `/` and back down the folder's own path get one through; a
+  link whose target cannot be
+  found is copied only when it points down the folder (no `..`), and a loop
+  is left out:
+  `⚠ Left out of the build because they are symbolic links that lead out of this folder on disk, or to a place that could not be found: config. Copy what the build needs into the project.` A folder passed as a link
+  (`naro deploy --cwd <link>`, the MCP `deploy` tool's `directory`) is copied
+  from the folder it points to; before, the build ran in the developer's
+  folder itself and wrote the committed `.env` over theirs. An absolute link
+  cannot be followed by a git deploy of the commit either:
+  `⚠ Left out of the build because they are symbolic links to an absolute path: config. A git deploy of this commit cannot follow them either; copy what the build needs into the project.`
+  A relative link out of the folder is one a git deploy, which clones the
+  whole repository, can follow. Deploy from the repository root with
+  `--root <app folder>` to keep it:
+  `⚠ Left out of the build because they are symbolic links to outside this folder: up. To keep links between a repository's folders, deploy from the repository root with --root <app folder>.`
+  A relative link between the folder's own subfolders is copied as before.
+- When the local build or the upload in `naro deploy` fails, the deployment
+  is marked `FAILED` at once, with the error's code and message, on the
+  dashboard and in `naro deployments`. Before, it stayed building until the
+  control plane's sweep about 10 minutes later. An upload that already
+  finished is left to the control plane, which is putting it live.
+- A failed local build's `--json` keeps `"code": "BUILD_FAILED"` and adds
+  `buildCode`, the code the dashboard shows. It is a deployment error code,
+  such as `NEXT_VERSION_UNSUPPORTED`, `INSTALL_FAILED`, `BUILD_FAILED`,
+  `ARTIFACT_INVALID` (static output a deploy cannot take, like a symbolic
+  link), `FRAMEWORK_DETECTION_FAILED`, or `NO_DEPLOYMENT_STRATEGY` when a
+  Next.js app's own build did not fail but no deployment strategy could ship
+  it (its own `next build` failing is `BUILD_FAILED`). Before, the stage's code was
+  only in the message. A failed upload still fails with its own error and no
+  `buildCode`; the dashboard shows its deployment code, or `DEPLOY_FAILED`.
+- `naro storage ls naro://<bucket>[/<prefix>] --search <text>` lists only the
+  names directly below the prefix that start with `<text>`, ignoring ASCII
+  case; `%` and `_` are plain characters (Storage 3-1g). With `--recursive`
+  the search applies on every level, folders included, so it does not find
+  a name deep below. A project backend from before this release answers it
+  with `BACKEND_OUTDATED`:
+  ``The project backend is older than this Storage command. Run `naro backend enable` to update it, then try again.``
+- `naro db lint` measures a `storage.objects` listing with a search too
+  (Storage 3-1g): its SELECT policies may bind 43 values in one statement,
+  not 44. A set that used exactly 44 is now an error before it is pushed;
+  the backend would answer a listing with a search `500 POLICY_INVALID`.
+- `naro logs --type build` without an id shows the newest deployment,
+  whatever its status, and names it first:
+  `Build logs of the latest deployment, <id>`. Before, it took the newest
+  `READY` one, so `--follow` passed over the build under way and ended at
+  once on an old deployment. `--follow` gives up after 30 minutes
+  (`TIMEOUT`, `Deployment <id> did not finish within 1800s.`), and a build
+  that ends `FAILED` ends the command with exit 1 and the deployment's error
+  code and message. Before, it printed `— deployment FAILED —` and exited 0.
+  A deployment with no build logs yet says so instead of printing nothing:
+  `(no build logs yet — <id> is QUEUED; add --follow to stream)`. `--json`
+  adds `status`.
+- `naro logs` refuses two flag pairs with `VALIDATION_FAILED`: `--follow`
+  with `--json` for runtime logs, which streamed until Ctrl-C and never
+  printed its JSON, and `--env` with build logs, which ignored it — so
+  `--type build --env production` could show a preview build.
+- `naro whoami` uses the token every other command sends: `--token`, then
+  `NARO_TOKEN`, then the stored session. In CI it names the account
+  `NARO_TOKEN` belongs to, `Logged in as <email> (<github>) — from NARO_TOKEN`,
+  with `"tokenSource": "env"` in `--json` (`"flag"`, or `"session"` for the
+  stored one). Before, it answered ``Not logged in. Run `naro login`.`` while
+  `naro deploy` worked. A token that no longer works gets `NOT_LOGGED_IN`
+  ``The access token is invalid or has expired. Generate a new one with `naro token`, or run `naro login`.``;
+  a sign-in service out of reach gets `NETWORK_ERROR` instead, and a rate
+  limit `RATE_LIMITED`.
+- `naro token` still mints only from the `naro login` session. With no
+  session and a token in `--token` or `NARO_TOKEN`, it fails with
+  `NOT_LOGGED_IN` and says why:
+  `` `naro token` makes a token from a `naro login` session, and there is none here. NARO_TOKEN is already a token: the other commands use it as is. ``
+  (`--token is already a token` when the token came from `--token`).
+- `naro login` that nobody finishes in the browser ends after 120 seconds
+  with `TIMEOUT`:
+  ``Sign-in timed out after 120s waiting for the browser. Run `naro login` again, or set NARO_TOKEN.``
+  Before, it failed as `INTERNAL_ERROR` with
+  `Timed out waiting for GitHub callback.`
+- `naro env add` checks the link and the sign-in before it asks for the
+  value, so a typed value is no longer thrown away by `PROJECT_NOT_LINKED`.
+  `naro env pull /tmp/x.env` writes that file; before, it wrote
+  `<cwd>/tmp/x.env`. A file it overwrites is set to 0600 as well. Before,
+  only a new file was, and an existing 0644 `.env.local` kept 0644 with the
+  secrets in it.
+- `naro git connect` with `--json` or without a terminal no longer opens a
+  browser and waits three minutes when the Naro GitHub App cannot reach the
+  repository. It fails at once with `REPOSITORY_NOT_ACCESSIBLE`
+  (`Naro cannot reach <owner/repo> yet. Install the Naro GitHub App at <url>, then run: naro git connect`),
+  and `--json` carries the link as `installUrl`. Before, the wait ended with
+  `▸ Still waiting on access to <owner/repo>.` and exit 0.
+- A first `naro deploy` with one team asks
+  `Deploy to this account and team? (Y/n)`, and Enter answers yes. Before,
+  the hint was `(y/N)` and Enter went on to sign in with another account.
+  Only `n` or `no` declines now; any other answer asks again.
+- naro-cli now ships `@opennextjs/cloudflare` 1.20.12 (was 1.20.2) and
+  `wrangler` 4.148.0 (was 4.124.0). A Next.js 16.4 app that falls back from
+  vinext to OpenNext now serves; before, it failed the smoke check on `/`
+  with a 500. A `proxy.ts` is still rewritten to Edge middleware for that
+  build. A Node.js-runtime middleware with no proxy file to rewrite is not
+  deployed:
+  `Node.js-runtime middleware (runtime: "nodejs") is only an experiment in OpenNext Cloudflare, and Naro does not deploy it. Remove runtime: "nodejs" to build it as Edge middleware`.
+  The Next.js version checks keep their range and name Naro, not the
+  adapter:
+  `Next.js <version> is outside the range Naro verifies deploys on (>=15.5.21 <16 || >=16.2.11). The build may fail in ways Naro cannot explain.`
+  and `Next.js <version> is too old to deploy. Naro deploys Next.js 15 or newer. Upgrade to Next.js 16.`
+- A Next.js app built with vinext reads its bindings with
+  `getCloudflareContext().env`, as under OpenNext. Before, `env` was missing
+  there, so `env.MY_BUCKET` was `undefined` and nothing was thrown. naro
+  writes this Worker entry as `naro-worker.js`, so a project with its own
+  file of that name is not built with vinext.
+- Build logs hide more secrets: upper-case names that end in `TOKEN`,
+  `SECRET`, `PASSWORD`, `PASSWD` or `_KEY`, in `NAME=value` and
+  `NAME: value` form; the credentials of any `Authorization` header (the
+  scheme word stays); GitHub tokens; JWTs; PEM private keys; and credentials
+  in any URL (`postgres://`, `redis://` and others). Before, only `Bearer`
+  tokens, credentials in `http(s)://` URLs and three fixed names in
+  `NAME=value` form were hidden.
+- `naro deploy` uploads the build output 24 files at a time instead of 8,
+  with at most 16 MiB in flight, so a deploy of many small files reaches
+  `READY` sooner.
+- The install of an npm or Yarn project during `naro deploy` no longer warns
+  `npm warn Unknown env config "store-dir".` The pnpm store setting now goes
+  to pnpm only.
+- Deployments in `--json` output (`naro deployments`, `naro inspect`) carry
+  `environment`: the named environment the deployment went to, `null` for
+  production and preview. `naro rollback` passes over deployments to a named
+  environment.
+- `naro storage bucket update <name> --private` says that copies Naro's edge
+  already holds can be served for up to 5 minutes (Storage 3-1h: the
+  dispatcher keeps public downloads at the edge for up to 300 seconds).
+
 ### 0.17.0
 
 - `naro domains add` prints one CNAME record and no TXT records. naro
@@ -1010,12 +1351,25 @@ command run non-interactively without `--yes` fails with
   "success": false,
   "code": "BUILD_FAILED",
   "message": "…",
-  "deploymentId": "…"
+  "deploymentId": "…",
+  "buildCode": "INSTALL_FAILED"
 }
 ```
 
+A failed local build keeps the stable `BUILD_FAILED` code and adds
+`buildCode`, the code the dashboard shows for the deployment. It can be any
+deployment error code; the common ones are `NEXT_VERSION_UNSUPPORTED` (upgrade
+Next.js), `INSTALL_FAILED` (the dependency install), `ARTIFACT_INVALID` (static
+output a deploy cannot take, like a symbolic link), `FRAMEWORK_DETECTION_FAILED`
+(no framework found, or an Angular app without an output path) and
+`BUILD_FAILED` (the app's own build, or a failure that carried no code). A
+Next.js app is built by trying deployment strategies in turn: when the app's
+own `next build` fails, `buildCode` is `BUILD_FAILED`; when its own build did
+not fail but no strategy can ship it, `NO_DEPLOYMENT_STRATEGY`. Either way the message says
+what each strategy failed at.
+
 `--yes` (or `-y`) suppresses every prompt — destructive actions
-(production rollback/promote, env/domain removal, database reset, backend key
+(production rollback/promote, env/domain/environment removal, `naro env import`, turning off an environment's protection, database reset, backend key
 rotation, policy removal and drop, opening the preview with
 `naro protection disable`, replacing or removing the bypass secret) run
 unconfirmed, so use it deliberately in
@@ -1028,16 +1382,22 @@ NARO_TOKEN=$(naro token) npx naro-cli deploy --prod --yes --json
 ```
 
 `naro token` prints a short-lived (~1h) access token; generate one per run.
-`--token <t>` works too. Locally, credentials live in
-`~/.naro/credentials.json` (0600).
+`--token <t>` works too. Every command picks its token the same way:
+`--token`, then `NARO_TOKEN`, then the stored session — so `naro whoami` in CI
+names the account `NARO_TOKEN` belongs to (`"tokenSource": "env"`).
+`naro token` is the exception: it always mints from the `naro login` session,
+so an expired `NARO_TOKEN` in the shell never comes back out of it. Locally,
+credentials live in `~/.naro/credentials.json` (0600).
 
 ## Environment variables
 
 - Values are entered via hidden prompt or stdin — never as an argument:
   `echo "$DATABASE_URL" | naro env add DATABASE_URL production --yes`
-- Targets: `production`, `preview`, `all` (default).
+- Targets: `production`, `preview`, `all` (default), or a named
+  environment's slug: `naro env add DATABASE_URL qa`.
 - `naro env pull` writes `.env.local` (preview + all vars by default,
-  `--env production` for production values).
+  `--env production` for production values, `--env <name>` for an
+  environment's).
 
 ## Configuration