docs: auto-sync cloud-agent with merged PRs (through 2026-11-04)

packages/kilo-docs/pages/code-with-ai/platforms/cloud-agent.md

@@ -61,14 +61,30 @@ On the **General** tab:
 - **Default sandbox** — the sandbox for new sessions when a repository has no override. The dialog names the sandbox that **Platform default** resolves to, so you can see what a session uses when nothing else applies.
 - **Repository overrides** — set or clear a sandbox and an [agent environment profile](#agent-environment-profiles) for an individual repository.
 
-The **Profiles** tab hosts the full profile manager: the profile list on the left and a detail pane on the right with **Overview**, **Variables**, **Setup**, **Slash Cmds**, **MCP**, **Skills**, and **Agents**.
+The **Profiles** tab hosts the full profile manager: the profile list on the left and a detail pane on the right with **Overview**, **Variables**, **Setup**, **Slash Cmds**, **MCP**, **Skills**, **Agents**, **Instructions**, and **Import**.
 
 Each change saves as you make it. In an organization, members see the settings read-only; only owners and admins can change them.
 
 When you start a session, the sandbox is resolved in this order: the sandbox you pick in the new-session field, then the repository override, then the owner default, then the platform default. A saved choice that is no longer offered, or that is not available for the repository, falls through to the next level. The new-session picker preselects the sandbox that applies and tags it **Default**.
 
 Vercel sandboxes are offered for GitHub repositories only. If your account cannot select a sandbox, the settings show where sessions run as plain text and the new-session page hides the picker.
 
+## Repository environments
+
+Each repository can have one saved environment that applies automatically when a session starts, so you do not set up the same workspace for every chat. A repository environment holds:
+
+- A sandbox size
+- One setup script
+- Variables, including secrets (encrypted at rest)
+
+Open **Env** beside a repository to create or edit its environment. In an organization, owners and admins can manage repository environments; other members see them read-only.
+
+When a repository environment applies, its setup script replaces the setup commands from the selected [agent environment profile](#agent-environment-profiles). The profile's variables and agent settings still apply. A warning beside the profile picker explains when a profile's setup is replaced.
+
+Repository environments follow the same automatic-resolution policy as automatic profiles: sessions started by automated code reviews, Security Agent sessions, and unknown origins do not automatically receive a repository environment.
+
+Setup scripts run through Bash with `-e -o pipefail`, so the script stops at the first failing command. New and replaced variable values are encrypted; values stored before encryption remain compatible.
+
 ## Queueing follow-up messages
 
 The composer stays editable while a session is being prepared or finalized, so you can keep typing and send follow-up messages without waiting for the current turn to finish. Sent messages are queued and processed in order, and the composer shows the current phase while it waits. While a session is still loading, when its connection is unresolved, or when a chat is read-only, the composer does not accept submissions, but anything you have typed is preserved.
@@ -112,6 +128,18 @@ Standard-input prompts must be valid UTF-8 and contain no more than 100,000 char
   - Expect slightly longer setup after idle periods
   - Inactive cloud agent sessions are deleted after **7 days** during the beta, expired sessions are still accessible via the CLI
 
+## Delegating to child sessions
+
+A Cloud Agent session that you start interactively — from the web app, the desktop app, or Agent Manager — can launch child Cloud Agent sessions to work on part of the task. Each child runs in its own isolated sandbox.
+
+A session cannot launch child sessions when any of these apply:
+
+- **It is itself a child.** Child sessions cannot delegate further, so delegation stays one level deep.
+- **It runs on a shared sandbox.** Shared sandboxes do not support child sessions. Start the session on an isolated sandbox instead.
+- **It was started by a bot.** Sessions created by code reviews, security reviews, and triggers never get this capability.
+
+Sessions created before this capability became available keep it disabled. Start a new session to launch child sessions.
+
 ## Worktrees and chats
 
 A worktree is a checkout of your repository on its own branch. It can host multiple chats with separate conversations, but edits from one chat are visible to the others. Use separate worktrees for tasks that need separate checkouts.
@@ -138,6 +166,12 @@ Use the side-by-side toggle in the file viewer to switch between a unified diff
 
 These are saved snapshots, not a live view of the checkout. Diffs may be unavailable for binary, unsupported, or large files, or when there are too many changes to save in full.
 
+## Previewing a running app
+
+You can preview a web app running inside a Cloud Agent session's sandbox. When a session serves an app on a port, the web interface shows a preview button and preview links, and selecting one opens the running app in a new browser tab. Each preview is served from its own hostname that targets the session's workspace and port, so different sessions and ports do not collide.
+
+Preview is available to every Cloud Agent account.
+
 ## Agent Environment Profiles
 
 Agent environment profiles are reusable bundles of environment settings for cloud-agent sessions. A profile can include:
@@ -150,6 +184,16 @@ Profiles are owned by either a user or an organization. Names are unique per own
 
 In the web app, manage profiles from the **Profiles** tab of the [Cloud Agent settings dialog](#choosing-where-sessions-run).
 
+Only organization owners and admins can create, edit, or delete an organization-owned profile. Other members can open the profile and use it for a session, but they see its settings read-only. Personal profiles are unaffected — every account can create and manage its own.
+
+### Importing a local configuration
+
+You can import a local Kilo configuration ZIP into a profile to move your agents, slash commands, skills, and instructions into the cloud. Open the profile in the **Profiles** tab and use the **Import** tab.
+
+Kilo validates the archive and shows a preview of what it contains before anything is saved. Review the preview, then confirm to replace the profile's agents, slash commands, skills, and instructions. Definitions that match keep their IDs, and definitions missing from the archive are removed; variables, setup commands, and MCP servers are not changed. If the archive is invalid — for example, it uses a reserved built-in agent name — Kilo shows the validation error and disables the import.
+
+Imported instruction files appear on the profile's **Instructions** tab.
+
 ## Environment Variables & Secrets & Startup Commands
 
 You can customize each Cloud Agent session by also defining env vars and startup commands on the fly. These will override any Agent Environment Profile you've selected:
@@ -185,6 +229,10 @@ Cloud Agents support project-level [skills](/docs/code-with-ai/platforms/cli#ski
 Global skills (`~/.kilo/skills/`) are not available in Cloud Agents since there is no persistent user home directory.
 {% /callout %}
 
+### Skills from skills.sh
+
+An [agent environment profile](#agent-environment-profiles) can also install public skills from [skills.sh](https://skills.sh). Open the profile's **Skills** tab and add a qualified reference such as `anthropics/skills@frontend-design` or a skills.sh skill URL. Cloud Agent installs the referenced skill and its companion files when it prepares a session, so the contents always come from upstream rather than a snapshot saved in the profile. Because there is no Markdown snapshot to edit, you enable, disable, or delete a referenced skill instead of editing it. Manual skills and ZIP uploads work the same as before.
+
 ## Remote Connections
 
 Remote Connections let you access and control local CLI sessions from the Cloud Agents web interface. Your computer handles the compute; the cloud gives you a window into it from any device.
@@ -248,18 +296,44 @@ When creating a trigger, you choose an **activation mode** that cannot be change
 
 ### Configuration
 
-Triggers utilize [agent environment profiles](#agent-environment-profiles) to configure the execution environment for triggered sessions. The agent resolves the profile at runtime, so profile updates apply automatically to future executions. Profiles referenced by triggers cannot be deleted until those triggers are updated or removed.
+Triggers can use an [agent environment profile](#agent-environment-profiles) to configure the execution environment for triggered sessions, or run without one and use the repository and account defaults. The agent resolves the profile at runtime, so profile updates apply automatically to future executions. Profiles referenced by triggers cannot be deleted until those triggers are updated or removed.
+
+Which profiles a trigger offers depends on how it runs. Organization triggers run as the organization webhook bot by default and select organization profiles; a trigger created with **Run as webhook creator** selects personal profiles instead. Clearing a profile returns the trigger to the repository and account defaults, and existing triggers keep the profile they already have until you change it.
 
 For models that support it, webhook and scheduled triggers can set a **reasoning effort** next to the model selector. **Default** leaves the model's behavior unchanged; a specific effort applies to each session the trigger starts.
 
 Triggers do not support manual env var or setup command overrides at this time.
 
+### Request body validation
+
+Webhook triggers can validate each request body against a JSON Schema before the request is captured. When a body does not match the schema, Kilo rejects it with HTTP 400 and does not capture or queue it.
+
+The schema editor supports standard JSON Schema keywords, including `pattern`, `const`, `enum`, nested objects and arrays, required fields, and value limits. Matching uses native ECMAScript regular expressions, which are not bounded in matching time, so prefer `const` for a fixed value such as a URL and `enum` for a fixed list over a complex pattern.
+
+### Sandbox selection
+
+When your account can choose a sandbox, the trigger form shows a **Sandbox** field. Choices are grouped by provider and filtered to the runtimes available for the selected repository, including the Cloudflare Containers runtime where it applies. **Automatic** keeps the default Cloud Agent routing.
+
+Existing triggers keep any allocation they already have. Legacy allocations are not offered when you create a trigger or change its sandbox.
+
+### Run as webhook creator
+
+By default, organization triggers run as the organization webhook bot. When you create an organization trigger, you can instead select **Run as webhook creator** so each session runs with your identity. Organization billing and repository scope stay with the organization.
+
+Creator-run sessions also resolve GitHub credentials with your own authorization when it is available, so commits and pushes are attributed to your GitHub identity instead of the organization bot. This matches interactive Cloud Agent web sessions. If your account has not authorized the GitHub App, or the repository permissions do not allow it, the session falls back to the installation bot. Organization-bot triggers keep using the organization bot identity.
+
+This is a create-time choice and cannot be changed later. Only you, the creator, can edit a creator-run trigger or run it on demand. Existing triggers keep using the organization webhook bot; create a new trigger to use creator mode.
+
+Creator-run webhooks require shared-secret authentication. Set a header name and a secret of at least 16 characters when you create the trigger, and send the same header with every request. Kilo revalidates your account, the organization, and your direct membership before each delivery and retry. If that authorization fails, the request fails instead of falling back to the organization bot.
+
 ### Scheduled Triggers
 
 Scheduled triggers fire on a recurring schedule using cron expressions. You can configure them with a simple frequency picker (every 10 minutes, hourly, daily, weekly) or enter a raw cron expression for full control. Each trigger has a configurable timezone (default: UTC) and handles daylight saving time transitions automatically.
 
 The minimum schedule interval is 10 minutes. Scheduled triggers use `{{scheduledTime}}` and `{{timestamp}}` as prompt template variables (webhook-specific variables like `{{body}}` are not available since there is no inbound HTTP request).
 
+Scheduled triggers do not accept inbound requests. They run only from their schedule or from the invoke action described below.
+
 ### Invoking a scheduled trigger on demand
 
 To run an active scheduled trigger immediately, select the **Play** action on its row and confirm. When editing one, use **Save and invoke now** to save your changes before starting the run. Paused triggers cannot be invoked, and webhook triggers have no invoke action.
@@ -317,6 +391,8 @@ You can reference data in a trigger’s prompt template using these placeholders
 - `{{scheduledTime}}` - the time the schedule fired (ISO string)
 - `{{timestamp}}` - capture timestamp (ISO string)
 
+Kilo expands placeholders in the prompt template once. A placeholder that arrives inside captured request data, such as `{{headers}}` within a webhook body, stays as literal text and is not expanded again.
+
 {% callout type="warning" title="Security Considerations" %}
 Care should be taken when deciding to use webhooks as they are susceptible to prompt injection attacks. Especially in scenarios where webhook payloads may contain untrusted input. At this time we recommend using webhooks only for trusted sources.
 {% /callout %}