Restructure How it works: Configure, Control, Scale, Observe, Manage

apps/deploy.mdx

@@ -1,5 +1,7 @@
 ---
-title: "Deploying"
+title: "Deploy an App"
+sidebarTitle: "Deploy"
+description: "Deploy your app to KERNEL, set environment variables, and pass secrets"
 ---
 
 Kernel's app deployment process is as simple as it is fast. There are no configuration files to manage or complex CI/CD pipelines.
@@ -94,6 +96,87 @@ const client = new Kernel({ apiKey: process.env.MY_KERNEL_API_KEY });
 
 Now the API calls your app makes go out as your key. The deployment key stays in place for Kernel's own use — running the invocation and reporting its result — so your key only needs permissions for the calls you actually make.
 
+## Secrets
+
+Pass API keys and other secrets as [environment variables](#environment-variables) when you deploy, with `--env` or `--env-file`. Then read them in your app:
+
+<CodeGroup>
+```typescript TypeScript
+import Anthropic from "@anthropic-ai/sdk";
+import OpenAI from "openai";
+
+app.action('ai-action', async (ctx: KernelContext) => {
+  // Access API keys from environment variables
+  const anthropic = new Anthropic({
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  });
+
+  const openai = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  // Use the clients...
+});
+```
+
+```python Python
+import os
+from anthropic import Anthropic
+from openai import OpenAI
+
+@app.action("ai-action")
+async def ai_action(ctx: KernelContext):
+    # Access API keys from environment variables
+    anthropic = Anthropic(
+        api_key=os.environ.get("ANTHROPIC_API_KEY"),
+    )
+
+    openai = OpenAI(
+        api_key=os.environ.get("OPENAI_API_KEY"),
+    )
+
+    # Use the clients...
+```
+</CodeGroup>
+
+### Per-invocation secrets
+
+For use cases where different API keys are needed per invocation (such as platforms using end-user keys), pass the secrets at runtime using the [payload parameter](/apps/invoke#payload-parameter).
+
+Use encryption standards in your app to protect sensitive data.
+
+<CodeGroup>
+```typescript TypeScript
+import OpenAI from "openai";
+
+app.action('ai-action', async (ctx: KernelContext, payload) => {
+  // Decrypt the API key passed at runtime
+  const apiKey = decrypt(payload.encryptedApiKey);
+
+  const openai = new OpenAI({
+    apiKey: apiKey,
+  });
+
+  // Use the client with the user's API key...
+});
+```
+
+```python Python
+from openai import OpenAI
+
+@app.action("ai-action")
+async def ai_action(ctx: KernelContext, payload):
+    # Decrypt the API key passed at runtime
+    api_key = decrypt(payload["encryptedApiKey"])
+
+    openai = OpenAI(
+        api_key=api_key,
+    )
+
+    # Use the client with the user's API key...
+```
+</CodeGroup>
+
 ## Deployment notes
 
 - **The dependency manifest (`package.json` for JS/TS, `pyproject.toml` for Python) must be present in the root directory of your project.**

apps/develop.mdx

@@ -1,5 +1,7 @@
 ---
-title: "Developing"
+title: "Develop an App"
+sidebarTitle: "Develop"
+description: "Build an app with actions that run co-located with KERNEL browsers"
 ---
 
 In addition to our browser API, Kernel provides a code execution platform for deploying and invoking code. Typically, Kernel's code execution platform is used for deploying and invoking browser automations or web agents.

apps/invoke.mdx

@@ -1,5 +1,7 @@
 ---
-title: "Invoking"
+title: "Invoke an App"
+sidebarTitle: "Invoke"
+description: "Run an app action from the API or CLI, pass a payload, and stop a running invocation"
 ---
 
 ## Via API
@@ -154,4 +156,67 @@ See [here](/apps/develop#parameters) to learn how to access the payload in your
 
 If your action specifies a [return value](/apps/develop#return-values), the invocation returns its value once it completes. (The Kernel CLI uses asynchronous invocations under the hood)
 
+
+## Stop an invocation
+
+You can terminate an invocation that's running. This is useful for stopping automations or agents stuck in an infinite loop.
+
+<Info>
+Terminating an invocation also destroys any browsers associated with it.
+</Info>
+
+### Via API
+You can stop an invocation by setting its status to `failed`. This will cancel the invocation and mark it as terminated.
+
+<CodeGroup>
+```typescript Typescript/Javascript
+import Kernel from '@onkernel/sdk';
+
+const kernel = new Kernel();
+
+const invocation = await kernel.invocations.update('invocation_id', {
+  status: 'failed',
+  output: JSON.stringify({ error: 'Invocation cancelled by user' }),
+});
+```
+
+```python Python
+from kernel import Kernel
+
+kernel = Kernel()
+invocation = kernel.invocations.update(
+    id="invocation_id",
+    status="failed",
+    output='{"error":"Invocation cancelled by user"}',
+)
+```
+
+```go Go
+package main
+
+import (
+	"context"
+
+	"github.com/kernel/kernel-go-sdk"
+)
+
+func main() {
+	ctx := context.Background()
+	client := kernel.NewClient()
+
+	invocation, err := client.Invocations.Update(ctx, "invocation_id", kernel.InvocationUpdateParams{
+		Status: kernel.InvocationUpdateParamsStatusFailed,
+		Output: kernel.String(`{"error":"Invocation cancelled by user"}`),
+	})
+	if err != nil {
+		panic(err)
+	}
+	_ = invocation
+}
+```
+</CodeGroup>
+
+### Via CLI
+Use `ctrl-c` in the terminal tab where you launched the invocation.
+
 App invocations accrue compute usage separately from any browsers they create. See the [pricing FAQ](/info/pricing#faq) for how app invocations are charged.

apps/logs.mdx

@@ -1,5 +1,7 @@
 ---
-title: "Logs"
+title: "Invocation Logs"
+sidebarTitle: "Logs"
+description: "Stream an invocation's logs from the API or CLI"
 ---
 
 ## Via API

apps/status.mdx

@@ -1,5 +1,7 @@
 ---
-title: "Status"
+title: "Invocation Status"
+sidebarTitle: "Status"
+description: "Follow an invocation's status by streaming or polling"
 ---
 
 Once you've [deployed](/apps/deploy) an app and invoked it, you can monitor its status using streaming for real-time updates or polling for periodic checks.