wawesome 0.17.0 → 0.18.1

package/README.md

@@ -1,998 +1,36 @@
 # wawesome
 
-> Official CLI for bundling and deploying serverless WebAssembly functions on the
+> Official CLI for bundling and deploying serverless functions on the
 > [wawesome.io](https://wawesome.io) platform.
 
 [![npm version](https://img.shields.io/npm/v/wawesome.svg?color=cyan)](https://www.npmjs.com/package/wawesome)
 
 Write a TypeScript function, deploy it from your terminal, and get back the address it answers on.
-
----
-
-## Quick start
-
-### 1. Create an account
-
-Sign up for free at **[https://wawesome.io](https://wawesome.io)** to set up your workspace.
-
-### 2. Authenticate the CLI
-
-Log in through your browser:
+You need Node 22.13 or newer. There is nothing to install, because `npx` fetches the CLI each time you
+name it.
 
 ```bash
 npx wawesome login
 ```
 
-### 3. Initialize a project
-
-Create a new directory and scaffold a WebAssembly TypeScript starter function:
+Your browser opens and signs you in. First time here, this makes the account too.
 
 ```bash
-mkdir my-wasm-app && cd my-wasm-app
+mkdir hello && cd hello
 npx wawesome init
 ```
 
-`init` asks for the function name and for the **App slug**. An App groups the Functions of one
-project, and its slug is part of the public URL your client sees. Both default to the directory
-name, so naming is usually a matter of pressing enter.
-
-An App slug must be a legal hostname label: lowercase letters, numbers, and single hyphens between
-them (no leading or trailing hyphen, 63 characters at most). Type something else, such as
-`My Client`, and the CLI shows you the slug it would become (`my-client`) and asks again, rather
-than rewriting your answer behind your back.
-
-#### Starting from a template
-
-`npx wawesome templates` lists what is available; `--template` starts from one:
-
-```bash
-mkdir acme-store && cd acme-store
-npx wawesome init --template stripe-webhook
-```
-
-This goes from nothing to a deployed Function in one command. The template is downloaded over
-plain HTTP and unpacked, so **git is not required** on any platform, and its files land exactly as
-they are published. Only three things are touched: the `name` in `package.json`, the App and
-Function names in `wawesome-function.json`, and the `wawesome` dependency. That last one is so the
-project you get depends on the CLI that scaffolded it rather than the one the template was released
-against.
-
-Templates declare what they need rather than shipping placeholders. The CLI asks for each
-environment variable the template requires, showing where in the provider's own dashboard to find
-the value. It stores them (secrets write-only), enables any outbound providers the template calls,
-and deploys. If a value does not exist yet, leave it blank; the CLI tells you the `env set` command
-to run once it does.
-
-The CLI installs your dependencies with whatever package manager launched it (`npx`, `pnpm dlx`,
-`bun x`), so the types are there when you open the project and the bundler can resolve the
-template's imports. Pass `--no-install` to do it yourself. A failed install never stops the flow,
-and the CLI prints the command to re-run.
-
-Before any of that is sent anywhere, the CLI shows you the **public URL your Function will have**
-and offers to change your workspace address. That is the part of the URL which is yours rather
-than this project's, and it is the same one `wawesome workspace show` prints. Signup mints it at
-random and it stays changeable until your first deploy, at which point it locks for good, because
-live URLs carry it. Press enter to keep it. If it is already locked, the CLI does not make the
-offer and says why.
-
-The CLI checks you are logged in **before** the first question rather than at the deploy. An
-expired session offers you a login there and then, and declining still leaves you the project plus
-the two commands that finish it.
-
-Run it in an empty directory. If any file would be overwritten, nothing is written at all and the
-CLI names the collision.
-
-### 4. Build and deploy
-
-Deploy your serverless function to the platform:
+Two questions, both defaulting to the directory name, then a project with `src/index.ts` in it.
+Add `--template <name>` to start from one that already works.
 
 ```bash
 npx wawesome deploy
 ```
 
----
-
-## Command reference
-
-| Command                                 | Description                                                         |
-|:----------------------------------------|:--------------------------------------------------------------------|
-| `npx wawesome login`                    | Authenticate CLI with your Wawesome account via browser             |
-| `npx wawesome logout`                   | Log out and clear saved credentials from your machine               |
-| `npx wawesome whoami`                   | View current logged-in user, workspace, and gateway info            |
-| `npx wawesome templates`                | Browse the template catalog (no login required)                     |
-| `npx wawesome init`                     | Scaffold a new serverless function project in the current directory |
-| `npx wawesome init --template <name>`   | Scaffold from a catalog template, wire up what it needs, and deploy |
-| `npx wawesome build`                    | Bundle TypeScript entry code into an optimized JS bundle            |
-| `npx wawesome deploy`                   | Build, upload, and promote a function version to production         |
-| `npx wawesome logs [func]`              | List recent past invocations for a function                         |
-| `npx wawesome logs --invocation <id>`   | Fetch full stdout/stderr log body for a specific invocation         |
-| `npx wawesome logs <func> --follow`     | Follow live output (waits for the next invocation if needed)        |
-| `npx wawesome invoke [func]`            | Fire a function run immediately and follow its output live          |
-| `npx wawesome cron [func]`              | List schedules for a function or app                                |
-| `npx wawesome cron pause <name>`        | Pause a schedule by name (survives future deploys)                  |
-| `npx wawesome cron resume <name>`       | Resume a paused schedule (no backfill)                              |
-| `npx wawesome cron history [func]`      | Read background run history for scheduled and manual runs           |
-| `npx wawesome version list`             | List version history for the current function                       |
-| `npx wawesome version switch <v>`       | Roll back or promote a specific function version                    |
-| `npx wawesome env list`                 | View environment variables for the current app                      |
-| `npx wawesome env set <key> <val>`      | Set an environment variable (add `--secret` for write-only)         |
-| `npx wawesome env rm <key>`             | Delete an environment variable                                      |
-| `npx wawesome domains`                  | Show the app's domain, its state, and the DNS records to add        |
-| `npx wawesome domains adopt`            | Write the domain the app answers at into wawesome-function.json     |
-| `npx wawesome domains detach <host>`    | Stop serving the app at a domain you attached                       |
-| `npx wawesome credentials`              | List deploy credentials: name, prefix, capabilities, Apps, last use |
-| `npx wawesome credentials mint <name>`  | Mint a deploy credential and print its secret, once                 |
-| `npx wawesome credentials regenerate <name>`| Replace a deploy credential's secret, keeping its name          |
-| `npx wawesome credentials revoke <name>`| Revoke a deploy credential by name or prefix                        |
-| `npx wawesome credentials delete <name>`| Delete a revoked or expired credential, freeing its name            |
-
----
-
-## Unsupported globals
-
-Every build scans the bundle it just produced against the platform's declared guest surface, and says
-nothing unless it finds something.
-
-- **`Intl` is not provided.** Where the bundle reaches it as it loads, in your own module scope or
-  a dependency's, the build is refused before a deploy uploads anything, because that bundle would
-  not evaluate on the platform. Where the reference sits inside a function that may never be called,
-  behind a `typeof` check, or inside a `try`, you get a warning and the deploy proceeds.
-- **`toLocaleString`, `toLocaleDateString`, `toLocaleTimeString`, `toLocaleLowerCase` and
-  `toLocaleUpperCase` ignore their locale argument.** They run and return an unlocalised answer, so
-  these warn.
-
-Each message names the global, the file and line in *your* source, and what to do about it. Declaring
-an `Intl` polyfill in your `package.json`, the same declaration [local parity
-reads](#testing-against-the-guests-javascript-surface), silences the report, as does installing one
-on `globalThis` in the bundle itself. The scan reads static references only: a global reached through
-`globalThis['Intl']` is invisible to it, so it never refuses a deploy on a guess. `deploy
---skip-build` scans the bundle it found on disk before uploading it.
-
-## Invocation logs
-
-Inspect past function runs or view raw `stdout` / `stderr` log outputs directly in your terminal.
-
-### 1. List recent invocations
-
-List past executions (including status, trigger type, timestamp, and duration) for the function in the
-current directory:
-
-```bash
-npx wawesome logs
-```
-
-Or list invocations for a specific function by name:
-
-```bash
-npx wawesome logs my-function
-```
-
-Filter by invocation status, to show only errors or timeouts:
-
-```bash
-npx wawesome logs my-function --error
-npx wawesome logs my-function --status timeout
-npx wawesome logs my-function --running
-```
-
-### 2. View the invocation log body (`stdout`/`stderr`)
-
-Fetch and print the captured `console.log` / `console.error` text for a specific invocation:
-
-```bash
-npx wawesome logs --invocation 019fb344-ea0c-78f2-8a9b-d04e188b9823
-```
-
-Or pass the UUID directly as the target:
-
-```bash
-npx wawesome logs 019fb344-ea0c-78f2-8a9b-d04e188b9823
-```
-
-### 3. Follow live output (`--follow`)
-
-Stream an invocation's output as it runs, like `tail -f` for your serverless function.
-
-#### Follow by function name (recommended)
-
-```bash
-npx wawesome logs my-function --follow
-```
-
-If the function is currently running, its output is streamed immediately. If the latest invocation
-already finished, the CLI **waits for the next invocation** to start and then streams it live.
-Press `Ctrl-C` at any time to stop.
-
-#### Follow a specific invocation by ID
-
-```bash
-npx wawesome logs 019fb344-ea0c-78f2-8a9b-d04e188b9823 --follow
-```
-
-#### Reconnection
-
-On a transient network error or a 5xx, the CLI reconnects with exponential back-off, up to three
-retries. It does not retry an authentication failure (401) or an unknown invocation (404). Those
-exit at once, naming what happened.
-
----
-
-## Manual invocation
-
-Fire a background run of a Function immediately without waiting for a schedule tick or deploying code:
-
-```bash
-# Invoke the function in the current directory and follow its output
-npx wawesome invoke
-
-# Invoke a specific function by name
-npx wawesome invoke my-function
-
-# Send custom HTTP method and request body
-npx wawesome invoke -m POST -d '{"event":"audit"}'
-
-# Fire without following live output
-npx wawesome invoke --no-follow
-```
-
----
-
-## Schedules and cron management
-
-Manage recurring Schedules and inspect background run history directly from your terminal.
-
-### 1. List schedules
-
-List a Function's Schedules with expression, state, and next run in UTC:
-
-```bash
-# List schedules for the function in the current directory
-npx wawesome cron
-
-# List schedules for a specific function
-npx wawesome cron list my-function
-
-# List schedules across all functions in an App
-npx wawesome cron list --app my-app
-```
-
-The output tells the three off-states apart:
-- `paused`: stopped by a user, resumable with `wawesome cron resume <name>`
-- `not in this config file`: disabled because it was removed from configuration, resumable only by declaring it again in code
-- `suspended`: suspended by the non-payment ladder, resumable only after settling workspace balance
-
-### 2. Pause and resume schedules
-
-```bash
-# Pause a schedule by name (stops queued ticks and survives future deploys)
-npx wawesome cron pause nightly-reconcile
-
-# Pause with an optional reason for incident context
-npx wawesome cron pause nightly-reconcile --reason "database maintenance"
-
-# Resume a paused schedule (recomputes next run from now, no catch-up backfilling)
-npx wawesome cron resume nightly-reconcile
-```
-
-### 3. Read run history
-
-Inspect past scheduled and manual runs, showing when each run was due, when it started, pool delay, and how it ended:
-
-```bash
-# View run history for the current function
-npx wawesome cron history
-
-# Filter run history by state (pending, running, dispatched, skipped, missed, cancelled, lost, failed)
-npx wawesome cron history my-function --state failed
-```
-
----
-
-## Deploy credentials
-
-A deploy credential is what a CI pipeline or an agent authenticates with, where there is nobody at a
-keyboard to log in. It belongs to the workspace rather than to you: it keeps working after you leave,
-and revoking it does not end your own session. Once you have one, [Deploying from CI](#deploying-from-ci)
-is what to do with it.
-
-Minting, listing, regenerating, revoking and deleting belong to the workspace owner. They are closed
-to deploy credentials themselves, whatever those carry, so a leaked credential cannot mint another or
-renew its own expiry. All five run on your ordinary `npx wawesome login` session.
-
-### Mint one
-
-```bash
-npx wawesome credentials mint ci-pipeline
-```
-
-The secret is printed once and never again. The platform stores a digest of it, so no later read
-can rebuild it. It goes to stdout on a line of its own and everything else the command prints goes to
-stderr, so a redirect catches the secret and not one character besides:
-
-```bash
-npx wawesome credentials mint ci-pipeline > secret.txt
-```
-
-A capability is one cell of a grid: a verb, `read` or `write`, and the resource it acts on. A
-credential carries the words a deploy needs, reaches every App in the workspace, and expires in
-ninety days unless you say otherwise:
-
-```bash
-# reads what ran and fires a run of what somebody else shipped, on one App, never expires
-npx wawesome credentials mint runner -c read:apps,read:functions,read:invocations,write:runs -a prod --expires never
-
-# ships code into an App it may create, and attaches the domain the project declares
-npx wawesome credentials mint ci -c write:apps,write:functions,write:env,read:tenant,write:domains -a prod
-```
-
-| Flag                 | Meaning                                                                       |
-|:---------------------|:------------------------------------------------------------------------------|
-| `-c, --capability`   | A `{read\|write}:{resource}` word — `read:apps`, `write:functions`, `write:env`, `write:runs` and the rest. Repeatable or comma-separated. Default: `write:apps`, `write:functions`, `write:env`, `read:domains`, `read:tenant` |
-| `--preset`           | The words one job needs, by the job's name: `viewer`, `deployer`, `member`. [Which credential for which job](#which-credential-for-which-job) is what each one grants. Not with `-c` |
-| `-a, --app`          | Restrict to these Apps, by slug. Repeatable. Default: every App in the workspace |
-| `--expires`          | Days, or `never`. Default: 90                                                   |
-
-The resources are `tenant`, `apps`, `functions`, `env`, `domains`, `invocations`, `runs`,
-`schedules`, `previews` and `egress`. A write reaches the read of the same resource, so
-`write:functions` carries `read:functions` and there is no reason to name both. The command prints
-the words the credential ended up with.
-
-Some things are a person's alone, whatever a credential carries: renaming the workspace, detaching a
-domain, widening the egress allowlist, billing, and this workspace's own credentials and members.
-Those are not words to mint — a credential asking for one is told a person has to be at the keyboard.
-
-An App named in a restriction does not have to exist yet. A pipeline whose first deploy creates the
-App it was minted for is the ordinary case. A restriction bounds what a credential reads as well as
-what it disturbs, and `write:functions` is the hole in it: a Function deployed into an App the
-credential does reach still reads the whole workspace's environment at runtime.
-
-### List them
-
-```bash
-npx wawesome credentials
-```
-
-Name, displayable prefix, capabilities, Apps, last use and expiry. Never the secret, which the
-platform no longer holds. `LAST USED` lags by a few minutes and reads `never` for a credential
-nothing has ever presented, which is a better reason to revoke one than any calendar date.
-
-### Rotate one
-
-```bash
-npx wawesome credentials regenerate ci-pipeline
-npx wawesome credentials regenerate ci --expires never --yes
-npx wawesome credentials regenerate ci-pipeline > secret.txt
-```
-
-Regenerating replaces the secret where it stands. The credential keeps its id, its name, its
-capabilities and the Apps it may reach, so the only thing to change in your CI settings is the secret
-itself. Its displayable prefix changes with it, since the prefix is what you match one against. The
-new secret is printed once, on stdout alone, exactly as at minting.
-
-It asks first, because anything holding the old secret stops working the moment this lands and has to
-be given the new one; `--yes` is the answer where nobody is at the keyboard. Without `--expires` the
-new secret lives ninety days, the same rule minting follows, including on a credential that never
-expired.
-
-An expired credential regenerates into a working one — that is the ordinary reason to reach for this.
-A revoked one is refused, because nothing un-revokes a credential.
-
-### Revoke one
-
-```bash
-npx wawesome credentials revoke ci-pipeline
-npx wawesome credentials revoke wawe_ab3k9x --yes
-```
-
-By name or by displayable prefix, whole or partial. It asks before it does it, `--yes` is the answer
-where nobody is at the keyboard, and a prefix naming more than one credential is refused rather than
-guessed at. A revocation lands on the very next request presenting the secret, and nothing un-revokes
-it.
-
-### Delete one
-
-```bash
-npx wawesome credentials delete ci-pipeline
-npx wawesome credentials delete wawe_ab3k9x --yes
-```
-
-Deleting is a second act, not a shortcut through revoking, so only a credential that has already
-stopped working can be deleted. Revoke a live one first. It resolves its target the way revoking
-does, by name or by displayable prefix, and asks before it does it unless you pass `--yes`.
-
-What deleting gives up is the reason revoking left the record behind. The credential leaves the
-listing, the name comes free to mint again, and a pipeline still presenting the secret is told the
-secret is unknown rather than that somebody revoked it. Whoever is debugging that pipeline goes
-looking in their CI settings instead of your dashboard.
-
----
-
-## Your agent, over MCP
-
-The same deploy credential connects a coding agent to your workspace, over MCP. Nothing to install and
-no local process to keep running: it is an endpoint on the gateway, `https://api.wawesome.io/v1/mcp`,
-and the credential is the whole of the authentication.
-
-### Install it
-
-In Claude Code, one command:
-
-```bash
-claude mcp add --transport http wawesome https://api.wawesome.io/v1/mcp \
-  --header "Authorization: Bearer wawe_..."
-```
-
-In Cursor, `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
-
-```json
-{
-  "mcpServers": {
-    "wawesome": {
-      "url": "https://api.wawesome.io/v1/mcp",
-      "headers": { "Authorization": "Bearer wawe_..." }
-    }
-  }
-}
-```
-
-In VS Code, `.vscode/mcp.json` in the workspace, or the file **MCP: Open User Configuration** opens.
-The shape is the same address and header map, under the key `servers` rather than `mcpServers`:
-
-```json
-{
-  "servers": {
-    "wawesome": {
-      "type": "http",
-      "url": "https://api.wawesome.io/v1/mcp",
-      "headers": { "Authorization": "Bearer wawe_..." }
-    }
-  }
-}
-```
-
-A file inside the project is a file your repository carries, and the secret with it. VS Code takes an
-`inputs` entry and a `${input:...}` placeholder in the header, so it asks once and holds the value
-itself. In Cursor, put the credential in `~/.cursor/mcp.json`, which is outside every repository.
-
-### Where a bearer credential reaches
-
-It works in Claude Code, the Claude Agent SDK, Cursor, VS Code, Windsurf, Zed and the Gemini CLI. It
-works in every agent framework that takes a URL and a header map, among them the OpenAI Agents SDK,
-LangChain, the Vercel AI SDK and Pydantic AI. Anything that speaks streamable HTTP MCP and lets you
-set a header can connect.
-
-Whichever protocol revision your client speaks, the endpoint answers it. It holds both eras at one
-address: the current revision, `2026-07-28`, and the three handshake-based ones the installed base is
-still on. A client ahead of your editor's next release connects, and so does one behind it.
-
-It does **not** work in the connector dialog in claude.ai or Claude Desktop, or in ChatGPT
-connectors. Those three accept "no authentication" or OAuth and have no field for a token, so there
-is nowhere to put `wawe_...`. Reaching them needs an OAuth authorization server, which the platform
-does not run today, and nothing you can configure works around that.
-
-### What your agent gets
-
-Every tool is listed for every credential, and each one names the capability it needs. A credential
-that does not carry that word is refused by name, so your agent tells you what to mint rather than
-concluding the platform cannot do it.
-
-| Tool                       | What it does                                                            | Needs         |
-|:---------------------------|:------------------------------------------------------------------------|:--------------|
-| `whoami`                   | The workspace, where it is administered, the words this credential carries and which of them a tool here asks for, the Apps it reaches | nothing       |
-| `list_templates`           | The template catalogue, with what each one is for                       | nothing       |
-| `get_template`             | One template's source, environment contract and outbound providers; its tests and build configuration are named, and read on request | nothing       |
-| `list_apps`                | The Apps the credential reaches, each with its address and its dashboard page | `read:apps`   |
-| `list_functions`           | The Functions in one App, and what their live version carries            | `read:functions` |
-| `list_versions`            | A Function's Versions, and which one is live                             | `read:functions` |
-| `get_function_source`      | The code a Function is running, and the static files it carries          | `read:functions` |
-| `get_usage`                | The Tenant's usage and headroom                                          | `read:tenant` |
-| `list_invocations`         | Recent Invocations of a Function, failures included                      | `read:invocations` |
-| `get_invocation`           | One Invocation by id                                                     | `read:invocations` |
-| `read_invocation_logs`     | An Invocation's log body, a page at a time                               | `read:invocations` |
-| `diagnose_latest_failure`  | The latest failure, its logs and the Version that ran it, in one call    | `read:invocations`, `read:functions` |
-| `deploy_function`          | Deploys code and the static files it carries                             | `write:functions` |
-| `deploy_status`            | How a deploy went, by the handle it answered with                        | `read:functions` |
-| `rollback_function`        | Puts a Version the Function already has back on its public address       | `write:functions` |
-| `request_upload`           | Asks the person you are working with for files the conversation cannot produce, and answers a link to give them | `write:functions` |
-| `list_uploads`             | What the person sent against one upload session, ready to declare on the next deploy | `read:functions` |
-| `set_env_var`              | Sets an App's environment variable, read at the next invocation          | `write:env`   |
-| `attach_domain`            | Attaches a domain to an App and answers the DNS records that make it work | `write:domains` |
-| `cancel_domain_claim`      | Gives up a domain claim nobody has proved control of, freeing the App's place | `write:domains` |
-| `check_domain`             | Where the domain attached to an App got to, asked at the certificate vendor | `read:domains` |
-| `invoke_function`          | Runs a deployed Function once and answers with the Invocation id         | `write:runs`  |
-| `fetch_function`           | Fetches one path from a Function's live Version and answers what it served | `write:runs`  |
-
-A word that writes reaches the read of the same thing, so `write:functions` needs no `read:functions`
-beside it, and the presets below are named in exactly these words.
-
-`whoami` is the one to call first. It answers the workspace, every word the credential carries and
-the Apps it reaches, and it asks for nothing — so your agent can say what it is able to do before it
-offers, rather than finding the edge by being refused in front of you. Each word also says whether a
-tool here asks for it. Your credential can carry `write:schedules` with no schedule tool on this
-endpoint, and the mark is what stops an agent offering to schedule a job: a word with no tool behind
-it is done on the dashboard rather than being withheld from you. A member's session calling the endpoint gets
-the same answer for the role they hold.
-
-A deploy is two calls. The first says which of your files the platform does not already hold, by
-content hash; your agent uploads those bytes to `PUT /v1/assets/{content_hash}` with the same
-credential and asks again, so a redeploy that changed only its code uploads nothing. The second
-answers with a handle rather than waiting for the build, because a dropped connection would otherwise
-cancel a deploy that was going fine. `deploy_status` reads the handle whenever your agent asks.
-
-When the deploy is out and something is wrong, `diagnose_latest_failure` answers the latest failed
-run of a Function, that run's log output, and the version that ran it, in one call. Mirroring the
-routes there costs four round trips and four chances to carry the wrong identifier between them.
-
-Log output comes back a page at a time, with a cursor for the next one, and nothing is held open.
-Your own `wawesome logs --follow` keeps running while your agent reads. One live tail per credential
-is all the platform permits, and an agent taking it would end yours.
-
-### Which credential for which job
-
-A credential carries the words its job needs and stops there. They are the same words
-[Deploy credentials](#mint-one) mints with, and `--preset` fills them in for you: it expands into the
-words below before the request is built, and the command prints the words the credential ended up
-with. A preset and `-c` together are refused rather than merged, since both name the same thing. The
-preset is the name of the job; the words are the grant, and they are what travels.
-
-A preset is a workspace role, and the ones offered here are the roles carrying nothing only a person
-can hold. The name a job is minted under and the standing a member is given are one thing, rather
-than two lists somebody has to keep level.
-
-**Read and investigate, without the ability to ship** — `viewer`, which is every `read:` word the
-platform has. The agent enumerates your Apps, reads Functions, Versions, Invocations and log bodies,
-diagnoses a failure, checks usage, and browses templates. Every tool that ships code or runs it
-refuses:
-
-```bash
-npx wawesome credentials mint reader --preset viewer -a prod
-```
-
-**Ship and read back** — `deployer`, which is every read plus `write:apps`, `write:functions`,
-`write:env` and `write:runs`. Deploy, run, diagnose, roll back, set a key. Every tool in the table:
-
-```bash
-npx wawesome credentials mint ci --preset deployer -a prod
-```
-
-**The whole workspace** — `member`, which is the deployer's words plus `write:schedules` and
-`write:previews`, for an agent that pauses a schedule or cuts a preview as well:
-
-```bash
-npx wawesome credentials mint agent --preset member -a prod
-```
-
-Add `write:domains` where the project declares a custom domain the deploy should claim, or where an
-agent attaches one for somebody who has no terminal — it also gives back a claim nobody has proved
-control of yet, and never takes a live name off an App. Nothing gives
-an agent billing, a plan change, credential management or the ability to rename your workspace: those
-are closed to every credential, whatever it carries. Reading the workspace's name and address is not
-among them — `whoami` answers both to any credential, which is how the agent knows where what it
-deploys will appear.
-
-Keep `-a` on all three. A credential restricted to one App is refused on every tool that names
-another, which is what stops an agent working on one client's project from touching another's.
-`get_invocation` and `read_invocation_logs` take an Invocation id rather than an App, and an id
-belonging to an App the credential cannot reach is answered as an id naming nothing. `list_apps`
-answers a set rather than one App, so it is narrowed instead of refused: the credential is listed the
-Apps it reaches and told nothing about the rest.
-
-### When a tool refuses
-
-A refusal is the tool's answer, not a protocol error, and it carries the same `reason` code the CLI
-prints:
-
-- `credential-missing-capability`. The credential does not carry a word this tool needs. The refusal
-  names the first in `missing_capability` and every one of them in `missing_capabilities`, which are
-  the words to mint a credential with. This one answers `403` rather than `200`, with a
-  `WWW-Authenticate: Bearer error="insufficient_scope"` challenge naming the same words and where
-  this endpoint's OAuth metadata is — a connector installed through consent reads it and asks its
-  human to widen the grant rather than to install again.
-- `app-outside-credential-scope`. The credential is restricted to named Apps and this is not one of
-  them. A wider capability changes nothing here.
-
-A `401` is the credential itself: revoked, expired, or one this platform never issued. Nothing else
-answers one — a workspace that cannot deploy for a lapsed plan or a restriction is refused under its
-own reason, and re-installing the connector would not fix either.
-
-A quota refusal carries its numbers under `allowance` beside the prose, so your agent reports
-"3 of 3 App slots" rather than handing you a sentence to read.
-
----
-
-## Configuration and a custom gateway
-
-### `wawesome-function.json`
-
-Every project directory includes a `wawesome-function.json` file generated during `npx wawesome init`:
-
-```json
-{
-  "app": "my-app",
-  "function": "hello-world",
-  "entry": "src/index.ts"
-}
-```
-
-`app` is the App this Function is deployed into, and it is client-facing. Every deploy from this
-directory is scoped to it.
-
-`function` is the address. Changing it does not rename anything: your Function's URL is built from
-its name, so the next deploy lands on a Function of its own and the old one stays live at the old
-URL, serving the code its callers already hold. The CLI remembers where this directory last
-deployed and asks before that happens, naming both URLs. If you meant it, delete the old Function
-from the dashboard once nothing calls it.
-
-### A site with no handler
-
-Leave `entry` out, write no `src/index.ts`, and point `"assets"` at the directory your build wrote
-its pages into:
-
-```json
-{
-  "app": "my-app",
-  "function": "root",
-  "assets": "dist"
-}
-```
-
-That deploys the pages and no code at all, and the site is live at your App's address. Nothing in the
-file declares a kind: a project with a handler is one that has an entry point, and a project with
-both deploys them together and rolls them back together.
-
-An `entry` you did name and that is not there is a hard error, so a typo never quietly becomes a site
-with nothing running behind it. Every deploy says which of the two it landed.
-
-One thing the deploy will warn you about: everything beneath a Function's address reaches that
-Function, so a page your root Function carries at `about/index.html` is shadowed by a sibling Function
-named `about`. The deploy says so and names both addresses. It refuses nothing — the two Functions are
-versioned independently, and either one may deploy first.
-
-### Static files
-
-Add `"assets"` to deploy static files beside your code:
-
-```json
-{
-  "app": "my-app",
-  "function": "hello-world",
-  "entry": "src/index.ts",
-  "assets": "dist/client"
-}
-```
-
-Everything under that directory is deployed with the version and served at its path beneath your
-Function's URL, so `dist/client/assets/index-a1.js` answers at `https://<app-host>/<function>/assets/index-a1.js`.
-The CLI hashes each file and asks the platform which of them it does not already hold, so a redeploy
-that changed one chunk uploads one chunk. A deploy that changed nothing at all is refused before a
-byte moves.
-
-Files are served straight from object storage; your Function is never invoked for one, and no
-invocation is recorded. They answer on your App's own hostname and nowhere else. On the
-development path form (`/x/<tenant>/<app>/<function>/...`) the same address reaches your handler
-as it always has, because a file on an origin every workspace shares would be same-origin with
-all of them. A file beneath `assets/` carries `Cache-Control: public, max-age=31536000, immutable`,
-so name your build output by content hash: its bytes must never change under a name a browser has
-already cached for a year. A file outside `assets/` keeps one name across every deploy, so it carries
-`max-age=300` instead — five minutes is inside the reach of a deploy and of a rollback, which a year
-is not. The content type comes from the extension against a fixed allowlist and is never sniffed;
-anything off it is served as a download.
-
-Two rules to know about:
-
-- **Everything beneath `assets/` is static**, whatever the deploy carries. A request there never
-  reaches your handler, and an unknown path under it is a 404 rather than a route for you to answer.
-- **A file outside `assets/` answers at its own name**, however many of them a deploy carries.
-  `favicon.ico`, `robots.txt` and a `.well-known/` directory are what that is for; hashed build
-  output belongs under `assets/`.
-
-**A version carries exactly the files its deploy declared.** Nothing is inherited from the version
-before it, so taking `"assets"` out of `wawesome-function.json` — or pointing it at a directory your
-build no longer writes to — is not an edit but every file on the site going at once. A deploy that
-would do that against a Function serving files today is refused, and tells you how many would go:
-
-```bash
-npx wawesome deploy --drop-assets
-```
-
-Removing *some* of the files is ordinary editing and needs nothing: only the wholesale drop is
-refused, because that is the shape of a mistake rather than of a decision.
-
-**A page is a file like any other.** An `index.html` your build wrote is deployed, hashed, retained
-and billed exactly as your other files are, and it is what a directory-style address resolves to: a
-path whose last segment carries no extension is served the `index.html` beneath it, so `/`, `/about`,
-`/about/` and `/blog/hello` each answer with a page. A page revalidates rather than being pinned for a
-year, wherever it sits, so deploying and refreshing is a loop that works.
-
-**An SVG is served inert.** Nothing you deploy as a resource should be able to run script on your
-App's own origin, and an SVG opened directly in a browser can: it runs script, and it renders whatever
-HTML a `<foreignObject>` holds. It is served rather than refused because making it inert costs the
-file nothing. An `<img src="logo.svg">` never ran that script and is never checked against the
-policy, so your drawings render as they always did. Every
-SVG and XML file carries `Content-Security-Policy: script-src 'none'; sandbox`, and only navigating
-straight to one loses anything. Such a file is sandboxed onto an origin of its own, so its links no
-longer navigate and a page embedding it through `<object>` or `<iframe>` cannot reach into its DOM.
-
-### Schedules
-
-Add `"schedules"` to run a Function on a recurring timer, with no caller:
-
-```json
-{
-  "app": "my-app",
-  "function": "nightly-reconcile",
-  "entry": "src/index.ts",
-  "schedules": [{ "name": "overnight", "expression": "0 3 * * *" }]
-}
-```
-
-An expression is **five fields, read in UTC**: minute, hour, day of month, month, day of week. There
-is no seconds field and no timezone. A local zone would make one night a year fire a job twice and
-another night not at all.
-
-The name is yours to choose and is what the platform keys the schedule by, so editing an expression
-is a change to the same schedule rather than the deletion of one and the creation of another. Its
-history and its paused state stay attached to it.
-
-Your deploy applies them and prints each one with the time it will next run. It is refused, before
-anything is built or uploaded, if an expression cannot be read, if it would run more often than every
-five minutes, or if one Function declares more than five schedules.
-
-Two rules worth knowing before you edit the file:
-
-- **A schedule you delete from the file is disabled, not deleted.** Its history stays, and declaring
-  it again is what turns it back on, so a typo costs you a deploy rather than a job's record.
-- **A deploy never resumes a schedule a person paused.** When it runs is code; whether it is running
-  is not, and an unrelated commit the next morning must not restart what you stopped at 3am.
-
-Leaving `schedules` out of the file entirely says nothing about them and changes nothing. Writing
-`"schedules": []` says this Function declares none, which disables the ones it used to have.
-
-### Keeping a Function off the web
-
-A job on a timer should not also be sitting at a guessable URL where a stranger can fire it. Add
-`"visibility"` to make a Function unreachable from the internet:
-
-```json
-{
-  "app": "my-app",
-  "function": "nightly-reconcile",
-  "entry": "src/index.ts",
-  "visibility": "private"
-}
-```
-
-A private Function has **no public address at all** in production, not a hidden one and not one
-behind a credential. A request for it against your App's own hostname is answered with the same 404
-as a Function that was never deployed. This is how you deploy a job with side effects without leaving
-it where a stranger who guesses the slug can fire it.
-
-Leave the line out and your Function is public, which is what every Function without it has always
-been.
-
-On your own machine, the local development surface serves Functions regardless of visibility, and
-honours an explicit `x-wawesome-trigger` header so you can exercise a scheduled run by hand:
-
-```bash
-# Exercise a private or scheduled function locally on the development path form:
-curl -X POST http://localhost:3000/x/my-tenant-slug/default-app/nightly-reconcile \
-  -H "x-wawesome-trigger: schedule"
-```
-
-Production strips the reserved header namespace inbound, so the same header against your App's own
-hostname reaches nothing that reads it: the run is a `caller`'s, and a private Function is a 404
-either way. Skipping your own authorization for a `schedule` run therefore opens nothing.
-
-Making a Function private takes nothing but the deploy. Making it public again does not: deleting
-the line is refused, and the deploy tells you so having written nothing.
-
-```bash
-npx wawesome deploy --publish
-```
-
-That is deliberate. The line that keeps a job off the internet is one line, and a deploy that
-quietly honoured its deletion would put the job back on the open internet with nothing said. Every
-deploy prints the visibility it landed, beside the URL or in place of it.
-
-### A domain of your own
-
-Add `"domain"` and your App answers at a name you own, beside the address it already has:
-
-```json
-{
-  "app": "my-app",
-  "function": "api",
-  "entry": "src/index.ts",
-  "domain": "shop.client.com"
-}
-```
-
-The deploy attaches it and prints three DNS records to add at your registrar. The TXT record proves
-you own the name. The `_acme-challenge` CNAME beside it issues the certificate and keeps renewing it
-for as long as it stays there, so nobody comes back to your registrar at renewal time — if an
-`_acme-challenge` TXT record is already at that name, delete it, because a TXT and this CNAME cannot
-both sit there. The last CNAME points traffic here, and you add that one once the certificate is
-issued, so a site that is already live never spends a minute answering on a certificate that is not
-there yet.
-
-Nothing you are asked to add ever changes. Copy a value into your registrar, come back an hour later,
-and it is the same value.
-
-Your deploy waits for neither. It attaches the domain, prints the records and finishes, and every
-later deploy states where the domain got to: not verified, ownership verified, certificate issued, or
-serving. A domain that is already serving is a line saying so and nothing else.
-
-The same block is there when you are not deploying:
-
-```bash
-npx wawesome domains
-```
-
-It prints the domain, where it got to, when the platform last checked, and the records to add. It
-changes nothing, and a deploy credential carrying `read:domains` can run it, so a pipeline reads the
-same thing you do. Where the platform does not hold a record yet it prints a row saying so rather
-than dropping the record from the list. That row is what this command fills in, and it is where the
-deploy sends you: deploying again would change nothing, and a deploy that changes nothing is
-refused.
-
-A custom domain is granted from the Solo plan upwards, one per App. On a plan that grants none, the
-deploy prints the refusal and lands everything else it was doing.
-
-The address derived from your workspace slug keeps serving after you attach a domain. Both names
-answer, so webhooks and integrations already pointed at the old one keep working.
-
-An apex domain, `client.com` with no `www`, claims `www.client.com` with it, and attaching the `www`
-claims the apex. Both halves are one domain against your App's one place, and both are printed with
-their own state and their own records, because a visitor typing either one should reach your site.
-Where your DNS provider cannot hold a CNAME at your zone root, that half is reported as not claimed
-with the reason, and attaching the same name again picks it up once your DNS can carry it.
-
-The file is not the only door. A domain can also be attached from the dashboard or by an agent, and
-then your App answers at a name `wawesome-function.json` has never heard of. A deploy says so and
-edits nothing — what was committed is what ships — so the file is written by a command of your own:
-
-```bash
-npx wawesome domains adopt
-```
-
-It writes the attached hostname into `wawesome-function.json` and changes nothing about the domain.
-Where the file already declares a *different* name, it refuses and prints both: an App carries one
-domain, and which of the two names it should be is yours to settle rather than a file to overwrite.
-
-Deleting the line detaches nothing. Detaching takes a live site dark, which is not something a
-deploy should infer from a deleted line. So the deploy reports the domain it found and left serving,
-names the command that writes it into the file, and names the one command that takes it off:
-
-```bash
-npx wawesome domains detach shop.client.com
-```
-
-The hostname is typed because an App carries exactly one domain, and the command that removes it
-should not be one you can run by reflex. It says what it is about to do first: the domain stops
-resolving here, this App's own address keeps serving, and the certificate is given back. Afterwards
-the name is free to attach again by declaring it and deploying, which is also what the next deploy
-does if you leave the line in the file.
-
-### Reserved headers
-
-`x-wawesome-*` belongs to the platform in both directions. It is stripped off the request before your
-handler sees it, and off your response before the caller does. So **do not name a header of your
-own on that prefix**. It is dropped silently rather than rejected, and you will not get an error
-telling you why it vanished.
-
-Five headers arrive or leave on it, and the stripping is what makes them worth trusting:
-
-| Header | Direction | What it means |
-| --- | --- | --- |
-| `x-wawesome-forwarded-prefix` | inbound | The mount that was stripped from the path. Join it to the path you observe to rebuild the caller's URL. |
-| `x-wawesome-trigger` | inbound | How this run started: `caller` when someone called your address, `schedule` when fired by a Schedule. A caller cannot forge it in production (stripped inbound). On the local development surface, pass `x-wawesome-trigger: schedule` to exercise a background run by hand with the collapsed budget. |
-| `x-wawesome-invocation-id` | outbound | The id of this run, the key to fetch its logs with `npx wawesome logs --invocation <id>`. |
-| `x-wawesome-error` | outbound | Present only when the platform failed, never when your Function did. Its *absence* means the status on the wire is yours, up to the moment your response is committed and no further. |
-| `x-wawesome-document` | outbound | Set it to the path of a document your own deploy carried (`index.html`) and the platform streams that file in place of the body you returned. Your status and your other headers stand; the content type and the length are the file's. Naming a path your deploy does not carry is a `500`, and your logs say which path you named. |
-
-### Testing against the guest's JavaScript surface
-
-Your Function does not run on Node. The engine has no `Intl`, and its `toLocaleString` ignores the
-locale you pass. `(1234.5).toLocaleString('en-US')` comes back as `"1234.5"`, not `"1,234.50"`. On
-Node both work, which is how a green suite ships a Function that throws in production, or renders
-markup the browser then refuses to hydrate.
-
-Point your test suite at the guest's surface instead:
-
-```ts
-// vitest.config.ts
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: { setupFiles: ["wawesome/vitest-setup"] },
-});
-```
-
-Templates scaffolded with `wawesome init --template` ship this already. With it in place `Intl` is
-gone, `MessageChannel` is the platform's own implementation rather than Node's, and the
-locale-sensitive methods throw with a message naming the remedy. They throw rather than return the
-engine's unlocalised answer because the platform declares them unsupported, and a wrong string that
-fails nowhere is the thing this is here to stop you shipping.
-
-If you bundle an `Intl` polyfill, declare it in your `package.json` as you normally would. A
-dependency that provides `Intl` is left in place rather than stripped out from under you.
-
-### Local development and gateway overrides
-
-If you are running a local gateway or self-hosted instance, you can configure your CLI Gateway URL using any of the
-following:
-
-#### 1. Custom settings (`~/.wawesome/settings.json`)
-
-Create `~/.wawesome/settings.json`:
-
-```json
-{
-  "gateway_url": "http://localhost:3000"
-}
-```
-
-#### 2. Environment variables
-
-```bash
-export WAWESOME_GATEWAY_URL="http://localhost:3000"
-```
-
-#### 3. CLI flag
-
-```bash
-npx wawesome login --gateway http://localhost:3000
-```
-
-A successful login records the gateway it used, and every later command goes there, because a token is only valid at
-the gateway that issued it. `login` itself ignores that record and reads only the three overrides above, so a bare
-`npx wawesome login` with none of them set goes to `https://api.wawesome.io`. `npx wawesome logout` clears the recorded
-gateway along with the credentials.
-
----
-
-## Deploying from CI
-
-A **deploy credential** is what deploys without a person at a keyboard. Your workspace mints one, and the CLI reads it
-from a single environment variable. There is no login, and no credentials file is involved at any point:
-
-```bash
-export WAWESOME_DEPLOY_CREDENTIAL="wawe_..."
-export WAWESOME_GATEWAY_URL="https://api.wawesome.io"
-
-npx wawesome deploy
-```
-
-The workspace is resolved from the credential itself, so nothing in your pipeline has to carry a workspace identifier.
-The variable name is prefixed and has no shorter alias, so it cannot collide with another tool's CI variable.
-
-While it is set:
-
-- it wins over any `~/.wawesome/credentials.json` on the machine, so a runner with a stale cached home directory still
-  deploys as the credential rather than as whoever last logged in there;
-- nothing is written to disk, and the secret stays in the environment where you put it;
-- a refusal names which of four things happened: the credential is unknown, revoked, expired, or does not carry what
-  the command needs. It does not ask you to sign in again, which a pipeline cannot do;
-- `login` and `logout` refuse, because neither would change what the next command authenticates as;
-- `credentials` is refused by the platform, because minting, listing, regenerating, revoking and
-  deleting are closed to credentials whatever they carry;
-- `whoami` names the credential by its prefix, so you can match it against the one in your CI settings.
-
----
-
-## Security and secrets
-
-Wawesome encrypts environment variables at rest using two-tier envelope encryption (AES-256-GCM with per-app data keys
-and AAD context binding). Use `--secret` when setting sensitive keys:
-
-```bash
-npx wawesome env set STRIPE_SECRET_KEY sk_live_xxx --secret
-```
-
----
-
-## Resources and support
+This bundles, uploads and promotes, then prints the URL. Every path beneath it reaches your function.
 
-- **Platform Homepage**: [https://wawesome.io](https://wawesome.io)
-- **Documentation**: [https://docs.wawesome.io](https://docs.wawesome.io)
+## Documentation
 
+[Getting started](https://wawesome.io/docs/getting-started) walks the three commands above with the
+output each one prints. The [CLI reference](https://wawesome.io/docs/cli) has every command, every
+flag, and the JavaScript globals the platform does not provide.

package/dist/index.mjs

@@ -905,7 +905,7 @@ async function buildHandler(entryInput, config, options) {
 * that has to name this version — `--version`, the dependency a scaffolded
 * project pins — reads it here, so a release bumps one file.
 */
-const CLI_VERSION = "0.17.0";
+const CLI_VERSION = "0.18.1";
 //#endregion
 //#region src/prompt.ts
 /**
@@ -1883,6 +1883,7 @@ function domainsUrl(creds, app) {
 function whereItGotTo(domain) {
 	const { state } = domain;
 	if (state.serving) return "serving";
+	if (domain.proxied_in_public_dns) return "the CNAME is in at Cloudflare with the proxy on, so set that record to DNS only";
 	if (state.certificate_active) return "certificate issued, so point the CNAME here to cut over";
 	if (state.ownership_verified) return domain.certificate_record_pending ? "name verified, and the certificate record is not ready" : "name verified, so add the certificate CNAME below";
 	if (domain.ownership_record_pending) return "not verified yet, and the TXT record is not ready";
@@ -2252,19 +2253,23 @@ function sha256(bytes) {
 }
 /**
 * What this deploy *is*: the server bundle together with the sorted set of
-* asset path and content-hash pairs.
+* asset path and content-hash pairs, and the **Fallback document** it declares.
 *
 * Computed here, before anything is uploaded, so a deploy that changed nothing
 * is refused before a byte moves. Mirrors `deploy_digest` in
 * `server/crates/core/src/features/assets/identity.rs` — the gateway recomputes
 * it from what actually arrives, so the two have to agree exactly.
+*
+* A deploy declaring no fallback contributes nothing here rather than a stated
+* absence, so every digest computed before fallbacks existed is unmoved.
 */
 const DEPLOY_DIGEST_DOMAIN = "wawesome-deploy-v1";
-function deployDigest(bundle, assets) {
+function deployDigest(bundle, assets, fallback) {
 	const digest = crypto.createHash("sha256");
 	digest.update(`${DEPLOY_DIGEST_DOMAIN}\n`);
 	digest.update(`${sha256(bundle)}\n`);
 	for (const asset of [...assets].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) digest.update(`${asset.path}\0${asset.content_hash}\n`);
+	if (fallback) digest.update(`fallback\0${fallback.path}\0${fallback.status}\n`);
 	return digest.digest("hex");
 }
 /** The manifest as the gateway reads it — the bytes on disk are the CLI's business. */
@@ -2903,11 +2908,12 @@ async function cronCommand(action, target, subtarget, options = {}) {
 //#region src/mount-shadow.ts
 /**
 * The address a **Document** answers at, relative to its Function's mount: a
-* request path whose last segment carries no extension has `/index.html`
-* appended, so the Document at `about/index.html` is the address `about`.
+* request path whose last segment carries no extension resolves to that path,
+* to it with `.html` appended and to it with `/index.html` appended, so both
+* `about.html` and `about/index.html` are the address `about`.
 */
 function documentAddressPath(assetPath) {
-	return assetPath.replace(/(^|\/)index\.html$/, "");
+	return assetPath.replace(/(^|\/)index\.html$/, "").replace(/\.html$/, "");
 }
 /** See **Mount** in `CONTEXT.md` for why only the root Function's can be. */
 function mountsCanShadow(functionSlug) {
@@ -2975,6 +2981,53 @@ function shadowingLines(shadowed) {
 	];
 }
 //#endregion
+//#region src/document-collision.ts
+/**
+* The addresses this deploy carries more than one file for.
+*
+* An address resolves to an ordered set of keys and the first one the version
+* carries answers, so `about`, `about.html` and `about/index.html` all sit at
+* `/about` and the first of them wins. Nothing is refused: a build that emitted
+* two is a worse day when the deploy fails than when it says which one answers.
+*/
+function collidingDocuments(assetPaths) {
+	const byAddress = /* @__PURE__ */ new Map();
+	for (const assetPath of assetPaths) {
+		const address = documentAddressPath(assetPath);
+		byAddress.set(address, [...byAddress.get(address) ?? [], assetPath]);
+	}
+	return [...byAddress].filter(([, carried]) => carried.length > 1).map(([address, carried]) => {
+		const [answers, ...shadowed] = [...carried].sort((one, other) => preference(one) - preference(other));
+		return {
+			address,
+			answers,
+			shadowed
+		};
+	});
+}
+/** Where a file sits in the candidate order the platform resolves an address through. */
+function preference(assetPath) {
+	if (assetPath === documentAddressPath(assetPath)) return 1;
+	return /(^|\/)index\.html$/.test(assetPath) ? 3 : 2;
+}
+/** What the deploy says about an address it carries two pages for. */
+function collidingLines(colliding) {
+	if (colliding.length === 0) return [];
+	const lines = [];
+	for (const [index, collision] of colliding.entries()) {
+		const at = collision.address === "" ? "/" : `/${collision.address}`;
+		lines.push("", `  ${index === 0 ? "Collision: " : "           "} \x1b[33m${collision.answers}\x1b[0m`, ...indented(`This page and ${collision.shadowed.join(", ")} both answer ${at}. ${collision.answers} is the one served there, and ${listed(collision.shadowed)} still answer${collision.shadowed.length === 1 ? "s" : ""} at its own name.`));
+	}
+	return [
+		...lines,
+		`${VALUE_COLUMN}Nothing was refused — every file this deploy declared is`,
+		`${VALUE_COLUMN}stored and served.`
+	];
+}
+function listed(paths) {
+	return paths.length === 1 ? paths[0] : `${paths.slice(0, -1).join(", ")} and ${paths[paths.length - 1]}`;
+}
+//#endregion
 //#region src/deploy.ts
 function declaredFields(declared) {
 	return {
@@ -2984,6 +3037,28 @@ function declaredFields(declared) {
 	};
 }
 /**
+* The fallback this project declares.
+*
+* A declaration missing either half is refused here rather than at the gateway,
+* because the pair is part of what the deploy identifies itself by and that is
+* computed before anything is sent. Which statuses a document may be sent with,
+* and whether the path names a file the deploy carries, are the platform's to
+* judge: duplicating either rule here is two places for it to drift.
+*/
+function declaredFallback(value) {
+	if (value === void 0 || value === null) return void 0;
+	const declared = value;
+	if (typeof declared.path === "string" && declared.path.trim() && Number.isInteger(declared.status)) return {
+		path: declared.path.trim(),
+		status: declared.status
+	};
+	console.error("[wawesome] Error: 'fallback' in wawesome-function.json must name a document and the");
+	console.error("[wawesome] status it answers at.");
+	console.error("[wawesome] A not-found page is \x1B[36m{ \"path\": \"404.html\", \"status\": 404 }\x1B[0m and a");
+	console.error("[wawesome] single-page application's shell is \x1B[36m{ \"path\": \"index.html\", \"status\": 200 }\x1B[0m.");
+	process.exit(1);
+}
+/**
 * The visibility this project declares, refused here rather than at the gateway
 * so a typo is a message at the keyboard.
 */
@@ -3031,7 +3106,8 @@ async function deploy(entryInput, options) {
 	const declared = {
 		visibility: declaredVisibility(config.visibility),
 		confirmPublish: Boolean(options.publish),
-		confirmAssetDrop: Boolean(options.dropAssets)
+		confirmAssetDrop: Boolean(options.dropAssets),
+		fallback: declaredFallback(config.fallback)
 	};
 	const domainName = declaredDomain(config.domain);
 	if (isVerbose) {
@@ -3076,6 +3152,7 @@ async function deploy(entryInput, options) {
 		}
 	}
 	const declaresSchedules = config.schedules !== void 0;
+	const declaresFallback = declared.fallback !== void 0;
 	const assets = config.assets ? collectAssets(path.resolve(config.assets)) : [];
 	const documents = assets.filter((asset) => isDocument(asset.path));
 	if (jsCode === null && documents.length === 0) {
@@ -3090,7 +3167,7 @@ async function deploy(entryInput, options) {
 	const uploadUrl = `${creds.gateway_url}/v1/apps/${encodeURIComponent(app)}/functions/${encodeURIComponent(funcName)}/code`;
 	if (isVerbose) console.log(`[wawesome:verbose] POST ${uploadUrl}`);
 	const declaredOnTheWire = declaredFields(declared);
-	const uploadRes = assets.length > 0 || declaresSchedules || Object.keys(declaredOnTheWire).length > 0 || jsCode === null ? await authorizedFetch(uploadUrl, {
+	const uploadRes = assets.length > 0 || declaresSchedules || declaresFallback || Object.keys(declaredOnTheWire).length > 0 || jsCode === null ? await authorizedFetch(uploadUrl, {
 		method: "POST",
 		headers: {
 			Authorization: `Bearer ${creds.tenant_jwt}`,
@@ -3100,6 +3177,7 @@ async function deploy(entryInput, options) {
 			...jsCode !== null ? { code: jsCode } : {},
 			...assets.length > 0 ? { assets: manifestOf(assets) } : {},
 			...declaresSchedules ? { schedules: config.schedules } : {},
+			...declaresFallback ? { fallback: declared.fallback } : {},
 			...declaredOnTheWire
 		})
 	}) : await authorizedFetch(uploadUrl, {
@@ -3223,6 +3301,7 @@ async function deploy(entryInput, options) {
 	}
 	if (domain) for (const line of domainLines(domain)) console.log(line);
 	for (const line of shadowingLines(shadowed)) console.log(line);
+	for (const line of collidingLines(collidingDocuments(assets.map((asset) => asset.path)))) console.log(line);
 	if (headroom) {
 		console.log("");
 		for (const line of headroom) console.log(line);
@@ -3261,7 +3340,7 @@ async function uploadAssets(creds, app, funcName, bundle, assets, declared, isVe
 			"Content-Type": "application/json"
 		},
 		body: JSON.stringify({
-			deploy_digest: deployDigest(Buffer.from(bundle, "utf-8"), assets),
+			deploy_digest: deployDigest(Buffer.from(bundle, "utf-8"), assets, declared.fallback),
 			assets: manifestOf(assets),
 			...declaredFields(declared)
 		})
@@ -5623,6 +5702,16 @@ function isExpired(credential, now) {
 	const at = new Date(credential.expires_at).getTime();
 	return !Number.isNaN(at) && at <= now;
 }
+/**
+* Which rows somebody here minted and which they authorized a product to hold.
+*
+* The product is named beside the word rather than left to the label the token
+* endpoint writes: the label is a convention and this is the row's own answer.
+*/
+function kindOf(credential) {
+	if (credential.kind !== "oauth") return "minted";
+	return credential.client ? `connector (${credential.client.name})` : "connector";
+}
 function statusOf(credential, now) {
 	if (credential.revoked_at) return "revoked";
 	if (isExpired(credential, now)) return "expired";
@@ -5745,6 +5834,7 @@ function formatCredentials(credentials, now) {
 	const rows = credentials.map((credential) => ({
 		name: credential.name,
 		prefix: credential.prefix,
+		kind: kindOf(credential),
 		capabilities: credential.capabilities.join(", "),
 		apps: namedApps(credential.apps) ?? "every App",
 		lastUsed: asUtc(credential.last_used_at),
@@ -5760,6 +5850,10 @@ function formatCredentials(credentials, now) {
 			header: "PREFIX",
 			of: (row) => row.prefix
 		},
+		{
+			header: "KIND",
+			of: (row) => row.kind
+		},
 		{
 			header: "CAPABILITIES",
 			of: (row) => row.capabilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wawesome",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "CLI tool for building and deploying serverless functions on wawesome.io platform",
   "type": "module",
   "bin": {
@@ -35,6 +35,9 @@
     "dist",
     "vite-env.d.ts"
   ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",