docs: sync from source repos 2026-11-12

content/cli/connect.md

@@ -174,10 +174,12 @@ to `/`.
 
 The project a command uses comes from, in order:
 
-1. `VOLCANO_PROJECT_ID`, which is deprecated and will be removed in a future
+1. `--project <name-or-id>`, on `volcano cloud` commands. It applies to that
+   one command and changes neither the link nor the saved project.
+2. `VOLCANO_PROJECT_ID`, which is deprecated and will be removed in a future
    release. A command that uses it prints a warning on stderr.
-2. The directory's link
-3. The project `volcano use` saved
+3. The directory's link
+4. The project `volcano use` saved
 
 `volcano use` run inside a linked directory updates the link. Elsewhere it
 saves the project for every directory without a link. Inside a linked

content/cli/functions.md

@@ -44,6 +44,43 @@ scope it declared, giving it every project variable. With no
 `volcano-config.yaml` at all there is nothing to declare and deploy runs
 normally.
 
+## Function layout
+
+Each supported file or directory directly under `volcano/functions` is one function.
+Names starting with `_`, such as `_lib/`, hold shared code that every function
+archive includes.
+
+| Entry | Function | Entry file |
+|---|---|---|
+| `hello.js`, `hello.mjs`, `hello.py`, `hello.rb` | `hello` | the file itself |
+| `hello.ts`, `hello.mts`, `hello.cts` | `hello` | the file itself, compiled by Volcano |
+| `checkout/` | `checkout` | `index.js`, else `main.py` or `main.rb`, else `index.cts`, `index.mts` or `index.ts`, the first found |
+
+### TypeScript
+
+The CLI uploads a TypeScript handler as source, and Volcano compiles it to
+JavaScript during the build, in the cloud and in local mode:
+
+- Types are removed without being checked, so a type error doesn't fail the
+  deploy. Run `tsc --noEmit` in your own CI to catch type errors.
+- `.mts` compiles to an ES module and `.cts` to CommonJS. `.ts` is an ES module
+  when the function's `package.json` sets `"type": "module"`, CommonJS otherwise.
+- Imports through `paths` in a `tsconfig.json` inside the function's directory
+  resolve. Packages from `package.json` load from the installed dependencies.
+- TypeScript never changes what an existing function deploys: `hello.js` or
+  `hello.py` beside `hello.ts` or `hello/index.ts`, or `checkout/index.js`,
+  `index.mjs`, `index.cjs`, `main.py` or `main.rb` beside `checkout/index.ts`,
+  deploys that file instead. A `hello/` directory beside `hello.ts` deploys the
+  directory.
+- Two TypeScript files with one name and no JavaScript, such as `hello.ts` and
+  `hello.mts`, stop the deploy until you keep one.
+- `.tsx` and declaration files such as `types.d.ts` aren't functions. A
+  directory needs its handler at its top, such as `checkout/index.ts`, not
+  `checkout/src/index.ts`.
+
+See [TypeScript](/platform/functions/creating-functions#typescript) for how the
+build compiles it.
+
 ## CLI operations
 
 | Operation | Command |

content/cli/index.md

@@ -146,6 +146,19 @@ suggests `volcano projects create <name>`.
 Inside a directory linked with `volcano connect`, commands use the linked
 project. See [connect.md](connect.md#linked-directories).
 
+To run one `volcano cloud` command against another project, pass
+`--project <name-or-id>`. Every `volcano cloud` subcommand accepts it, and it
+leaves the active project and any link unchanged:
+
+```bash
+volcano cloud functions list --project my-app
+volcano cloud lavaflow status --project eac37d5a-5f6f-42d8-acf6-0f2ae9c7a550
+```
+
+`--project` takes an exact project name or ID, like `volcano use`. A project
+it does not find fails the command before it runs, and exits `4`. Local
+commands refuse `--project`: local development has one project.
+
 ### Create a project from a cloud template
 
 Use `--template` to install a complete app in a new cloud project:

content/cli/scripting.md

@@ -21,6 +21,22 @@ failures apart without parsing the error text.
 process's exit code instead, and `124` on timeout. See
 [sandboxes.md](sandboxes.md).
 
+## Choose the project per command
+
+`volcano cloud` commands take `--project <name-or-id>` to run against a project
+for that one command, without changing the active project. A script or agent
+can check several projects in a row without `volcano use` between them:
+
+```bash
+for project in app-staging app-production; do
+  volcano cloud lavaflow status --project "$project" --json
+done
+```
+
+A project `--project` does not find exits `4`. See
+[connect.md](connect.md#linked-directories) for how the CLI picks a project
+otherwise.
+
 ## JSON output
 
 Commands that support `--json` print machine-readable JSON on stdout. These

content/platform/api-reference/functions.md

@@ -135,7 +135,7 @@ Direct API clients may upload ZIP or `tar.gz`; the API stores a normalized `tar.
 
 After dependencies are installed and the final image is built, the build rejects an image larger than 4096 MB.
 
-For direct API uploads, Volcano generates `.volcano/function-build.json` automatically. It infers `function_root` from the single runtime entry file (`index.js`/`index.mjs`, `main.py`, or `main.rb`), or from the only top-level directory when the archive has one. A Node.js archive with no JavaScript entry counts `index.ts`, `index.mts` and `index.cts` instead, unless the root found without them already holds the handler as `index.cjs`, an extensionless `index` file or an `index` directory holding a `package.json` or an index file, the `handler` names its own module (such as `src/handler.main`), or the project sets `NODE_PATH`. It selects `install_root` from the closest dependency manifest directory containing the effective handler module, relative to `function_root`. When no manifest contains the module and `function_root` is `.`, the fallback selects the longest nested manifest directory path. With no containing manifest or applicable fallback, installation uses `function_root`. See [direct-upload layout inference](../functions/upload-api.md#direct-upload-layout-inference) for handler resolution and tie-breaking.
+For direct API uploads, Volcano generates `.volcano/function-build.json` automatically. It infers `function_root` from the single runtime entry file (`index.js`/`index.mjs`, `main.py`, or `main.rb`), or from the only top-level directory when the archive has one. A Node.js archive with no JavaScript entry counts `index.ts`, `index.mts` and `index.cts` instead, unless the root found without them already holds the handler as `index.cjs`, an extensionless `index` file or an `index` directory holding a `package.json` or an index file, the `handler` names its own module (such as `src/handler.main`), or the project's `NODE_PATH` names a directory inside the function, where the handler could load from after the install. A `NODE_PATH` that names only directories outside the function doesn't count. It selects `install_root` from the closest dependency manifest directory containing the effective handler module, relative to `function_root`. When no manifest contains the module and `function_root` is `.`, the fallback selects the longest nested manifest directory path. With no containing manifest or applicable fallback, installation uses `function_root`. See [direct-upload layout inference](../functions/upload-api.md#direct-upload-layout-inference) for handler resolution and tie-breaking.
 
 **Runtimes** ([List Runtimes](#list-runtimes) returns the current set):
 
@@ -488,6 +488,35 @@ refused one deploys nothing.
 > forwards requests with no credential, and `http` + `none` serves its DNS
 > endpoint without a token.
 
+## Previews
+
+A preview (the API calls it a Candidate) is a copy of an ordinary function
+built from an uploaded source with the function's variables, run on its own
+runtime and invoked at `https://<candidate id>.<functions domain>` with the
+project's service key only, whatever the function's visibility. See
+[Function previews](../functions/previews.md).
+
+| Method   | Path                                                                         | What it does                                           |
+| -------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `GET`    | `/projects/{id}/functions/{functionId}/candidates`                           | List previews with their latest deployment             |
+| `POST`   | `/projects/{id}/functions/{functionId}/candidates`                           | Create a preview from `name`, `code` and `ttl_seconds` |
+| `GET`    | `/projects/{id}/functions/{functionId}/candidates/{candidateId}`             | Read one preview                                       |
+| `DELETE` | `/projects/{id}/functions/{functionId}/candidates/{candidateId}`             | Delete a preview                                       |
+| `GET`    | `/projects/{id}/functions/{functionId}/candidates/{candidateId}/deployments` | List a preview's deployments                           |
+| `POST`   | `/projects/{id}/functions/{functionId}/candidates/{candidateId}/deployments` | Deploy new `code` to a preview                         |
+| `POST`   | `/projects/{id}/functions/{functionId}/candidates/{candidateId}/promote`     | Point the function's traffic at the preview's runtime  |
+| `GET`    | `/projects/{id}/functions/{functionId}/serving`                              | Read what the function runs                            |
+| `POST`   | `/projects/{id}/functions/{functionId}/serving/rollback`                     | Roll back, or with `to_production` return to its build |
+
+Promote and rollback require the `expected_revision` read from `serving` and
+answer `200` once the pointer moved; nothing is deployed. Delete answers `202`
+with no body. Creating, deploying to and promoting answer `404` with code
+`feature_unavailable` while the `functions.candidates` capability is
+unavailable. Refusals answer `409` with the codes listed in the
+[guide](../functions/previews.md#error-codes). Fields that do not apply yet,
+such as a preview's `url` before its first deployment, are absent. A function's
+`serving_candidate_id` is the preview it runs, or null.
+
 ## Function Status
 
 - `provisioning` - Being deployed
@@ -498,6 +527,8 @@ Useful deployment fields in responses:
 
 - `invoke_url` - canonical DNS invoke URL for this function
 - `deployed_regions` - regions where the function is currently deployed
+- `serving_candidate_id` - the promoted preview whose runtime receives the
+  function's traffic, or null while it runs its own build
 
 ## See Also