Bp docs language tweaks

sites/browserpod/src/content/docs/00-overview.mdx

@@ -1,7 +1,7 @@
 ---
 title: BrowserPod
 shortTitle: Overview
-description: Run sandboxed backend services directly in a client browser's tab.
+description: A universal execution layer for running code safely in the browser sandbox.
 ---
 
 import LinkButton from "@leaningtech/astro-theme/components/LinkButton.astro";
@@ -29,8 +29,9 @@ import { DISCORD_URL } from "@/consts.ts";
 	</a>
 </div>
 
-**BrowserPod** is a **sandbox API**. It provides in-browser runtimes for common backend languages, libraries and frameworks.
-Instead of provisioning a cloud server, BrowserPod's API enables a client browser to host full runtimes compiled to WebAssembly (Wasm), running at native speed.
+**BrowserPod** is a universal execution layer that brings native-grade compute to the browser. By targeting a Linux-compliant syscall interface via WebAssembly, BrowserPod allows you to run unmodified language runtimes and full-stack workloads directly on the client side.
+
+This architecture flips the economics of code execution: by moving compute from costly cloud-side sandboxes to the user's local device, you eliminate per-session infrastructure costs while achieving near-zero latency.
 
 <div class="m-4 flex justify-center">
 	[Get started](/docs/getting-started/quickstart) · [Basic
@@ -39,44 +40,42 @@ Instead of provisioning a cloud server, BrowserPod's API enables a client browse
 	[Licensing](/docs/more/licensing)
 </div>
 
-BrowserPod is ephemeral by design. Each **pod** (_see [pod](/docs/more/glossary#pod)_) runs inside a browser tab and ends when the tab closes or reloads. Because BrowserPod runs inside the browser, each Pod is constrained by the browser’s security model, isolated from the user’s OS, with limited access (via syscalls) to local files or system resources unless you explicitly provide it.
+## Beyond the Language Sandbox
+
+Unlike environment-specific tools that rely on JavaScript shims or polyfills, BrowserPod is **foundationally system-agnostic**. It provides a true virtualization layer—complete with a POSIX filesystem, multi-threading via WebWorkers, and a syscall interface—that treats language runtimes as modular engines.
+
+While we are launching with **Node.js**, the platform is designed to host any native runtime (Python, Ruby, Go, Rust) and, eventually, full Linux containers.
 
-At a high level, BrowserPod gives you:
+## Use Cases
 
-- A **backend runtime** running in the browser (e.g., Node.js, Python, Ruby)
-- A **Linux‑like virtual filesystem** for files and folders
-- **Portals** that can expose local servers at public URLs
+### **Development & Interactive Docs**
+Power full-stack IDEs and documentation with real package installs, dev servers, and build tools. Because BrowserPod executes at the system level, these environments maintain 1:1 fidelity with native local development.
 
-Everything runs client‑side within the browser sandbox, so users don’t need to install anything.
+### **Agentic Workloads & AI Sandboxes**
+Run AI-generated code or untrusted scripts in a secure, isolated environment next to the user. This eliminates the "cold start" overhead of cloud-based VMs and ensures that sensitive data stays within the browser’s security boundary.
 
-## What you can do with BrowserPod
+### **Zero-Infrastructure Education**
+Provide high-fidelity learning environments without managing a backend. BrowserPod scales horizontally for free, as every new student provides their own compute resources via their browser.
 
-- **Execute AI code safely**: Execute untrusted or user‑provided code in a contained environment for AI agents or automation flows.
-- **Live product demos**: Ship a demo that runs the real backend logic in the browser without backend provisioning.
-- **Interactive docs and tutorials**: Let users run actual servers, seed data, and see real responses while following along.
-- **Collaborative tools**: Build multi‑user apps like whiteboards, editors, or chat that run locally and sync via portals.
-- **Browser‑based _server_ functions**: Run tasks that usually need cloud provisioning—like HTTP APIs, background jobs, or file processing entirely inside the user’s browser.
+## How it works: The Lifecycle of a Pod
 
-## Why pick the BrowserPod API?
+![BrowserPod Architecture Diagram](/docs/assets/Browserpod-diagram_2.webp)
 
-- **Full-stack development**: BrowserPod runs full instances of backend frameworks enabling full-stack development without cloud provisioning.
-- **Real filesystem**: Create directories and files inside a virtual POSIX‑like tree.
-- **Portal URLs**: BrowserPod Portals allow to share working applications over a temporary, private and secure URL.
-- **Security**: The BrowserPod API boots instances in the browser's sandbox, inheriting its security.
-- **Cost**: Because BrowserPod runs instances in the browser, it comes at a fraction of the cost of cloud sandboxes, with a generous free tier.
 
-## How it works (high level)
+BrowserPod does not "imitate" a runtime; it executes the actual runtime binary within a virtualized environment:
 
-- BrowserPod ships a build of Node.js that targets CheerpOS (a runtime that provides a Linux‑like syscall interface to Wasm).
-- The browser’s JavaScript engine executes the Node runtime in the page.
-- Your project files live in a virtual filesystem inside the pod.
-- When your app listens on a port, BrowserPod can open a portal URL that forwards traffic into the pod.
+1.  **Modular Engines:** BrowserPod loads a language engine (e.g., Node.js) compiled to Wasm. These are not shims; they are full runtimes that interact with a virtualized Linux kernel interface.
+2.  **Stateless Compute, Persistent Data:** While the **compute** session is ephemeral (tied to the lifecycle of the browser tab), the **filesystem** is persistent. Disk state is provided via block-based streaming; changes are stored locally and can be rehydrated across sessions.
+3.  **True Concurrency:** Using WebWorkers, BrowserPod supports real process isolation and multi-threading, enabling modern build pipelines and complex toolchains to run without modification.
+4.  **Instant Networking:** Through **Portals**, any service listening on a port inside the pod is instantly accessible via a shareable, secure URL, handled entirely on the client side.
 
-See the [hosting guide](/docs/guides/hosting) for details on headers and setup.
+## 2026 Roadmap
 
-## Supported runtimes
+BrowserPod currently supports **Node.js**. Our goal is to expand this into a language-agnostic platform throughout 2026, with planned milestones across the year:
 
-BrowserPod currently supports Node.js runtime, support for Python and Ruby is coming soon.
+* Command-line tools (bash, git, coreutils), followed by **Python** and **Ruby** support.
+* Support for **Go** and **Rust** engines.
+* **Linux-class workloads** via CheerpX virtualization.
 
 ## Community and support
 

sites/browserpod/src/content/docs/01-alt_fluffier_overview.mdx

@@ -0,0 +1,80 @@
+---
+title: BrowserPod
+shortTitle: Overview
+description: A universal execution layer for running code safely in the browser
+---
+
+import LinkButton from "@leaningtech/astro-theme/components/LinkButton.astro";
+import { DISCORD_URL } from "@/consts.ts";
+
+<div class="%BP_LATEST%" />
+
+<div class="not-prose flex gap-2 mb-2">
+    <img src="https://img.shields.io/badge/version-%BP_LATEST%-orange" alt="Version %BP_LATEST%" />
+    <a href="https://discord.leaningtech.com/">
+        <img src="https://img.shields.io/discord/988743885121548329?color=%237289DA&logo=discord&logoColor=ffffff" alt="Discord server" />
+    </a>
+    <a href="https://github.com/leaningtech/browserpod-meta/issues">
+        <img src="https://img.shields.io/github/issues/leaningtech/browserpod-meta.svg?logo=github" alt="GitHub issues" />
+    </a>
+</div>
+
+**BrowserPod** is a universal execution layer for browser-based compute. It provides a sandboxed runtime API that enables client browsers to host full runtimes—compiled to WebAssembly (Wasm)—with near-native performance. 
+
+Instead of provisioning costly cloud servers, BrowserPod allows you to execute full-stack workloads directly within the user's browser tab. Each **pod** is ephemeral, constrained by the browser's security model, and isolated from the host operating system via a dedicated syscall layer.
+
+<div class="m-4 flex justify-center">
+    [Get started](/docs/getting-started/quickstart) · [Basic Tutorial](/docs/getting-started/expressjs) · [API reference](/docs/reference) · [GitHub repository](https://github.com/leaningtech/browserpod-meta) · [Licensing](/docs/more/licensing)
+</div>
+
+## The Shift: Moving Compute to the Client
+
+Traditional sandboxed environments rely on cloud-side virtualization. While effective, this model introduces recurring infrastructure costs, network latency, and data privacy complexities.
+
+**BrowserPod flips the economics of code execution.** By leveraging the user's local CPU and the browser's security model, you eliminate per-session infrastructure overhead. This makes it financially viable to scale applications—like AI code interpreters or interactive coding platforms—to millions of users without the linear growth of a cloud bill.
+
+## Use Cases
+
+### **Development Tools & Interactive Content**
+BrowserPod is built to power the next generation of web-based IDEs and full-stack development environments. By supporting package installs, dev servers, and build tools with high fidelity, it allows developers to create "real" workflows in the browser. This extends to documentation and live demos, where you can turn static examples into runnable environments that users can modify and execute without leaving the page.
+
+### **Safe Execution of Untrusted Code**
+Whether you are running AI-generated code, user scripts, or agent-assembled programs, BrowserPod provides a secure sandbox with zero "cold start" latency. Because execution happens on the client side, you tighten security boundaries by keeping sensitive data within the user's local environment.
+
+### **Privacy-First Applications and Education**
+By keeping inputs and outputs on the user's device, BrowserPod enables privacy-conscious applications that bypass the jurisdictional risks of cloud data transfer. For educators, this model removes the operational burden of managing per-student sandboxes, making hands-on technical education economically feasible at any scale.
+
+## How it works
+
+![BrowserPod Architecture Diagram](/docs/assets/Browserpod-diagram_2.webp)
+
+To understand how BrowserPod achieves high-fidelity behavior in a browser, it helps to look at the execution flow:
+
+1.  **Runtime Loading:** BrowserPod delivers complete runtime engines (starting with Node.js) compiled to WebAssembly. These engines target a Linux-compliant syscall interface rather than a limited JavaScript shim.
+2.  **Execution:** The browser’s JavaScript engine executes the Wasm-compiled runtime using WebWorkers for true multi-threading and process isolation. This allows for complex, multi-process workloads that would normally require a full OS.
+3.  **Resource Virtualization:** A block-based streaming virtual filesystem provides full POSIX compatibility. Disk images are streamed on-demand, and any file changes stay local to the browser session.
+4.  **Networking via Portals:** When a service inside the pod listens on a port, BrowserPod automatically creates a **Portal**. This secure URL routes external traffic directly to the service running in the browser, enabling live previews and collaboration without any backend servers.
+
+## Roadmap
+
+BrowserPod currently supports **Node.js**. Our goal is to expand this into a language-agnostic platform throughout 2026, with planned milestones across the year:
+
+* Command-line tools (bash, git, coreutils), followed by **Python** and **Ruby** support.
+* Support for **Go** and **Rust** engines.
+* **Linux-class workloads** powered by CheerpX, enabling any unmodified Linux container to run in the browser.
+
+## Community and Support
+
+<LinkButton
+    type="discord"
+    href={DISCORD_URL}
+    iconLeft="fa-brands:discord"
+    label="Join our Discord server"
+/>
+
+<LinkButton
+    type="secondary"
+    href="https://twitter.com/leaningtech"
+    iconLeft="fa-brands:twitter"
+    label="Follow us on Twitter"
+/>

sites/browserpod/src/content/docs/10-getting-started/01-quickstart.md

@@ -3,6 +3,8 @@ title: Quickstart
 description: Getting started with BrowserPod
 ---
 
+BrowserPod provides a sandboxed runtime for executing code safely in the browser. This quickstart will get you running your first BrowserPod application in minutes.
+
 ## 1. Register a free account
 
 In order to use BrowserPod, you need to obtain an API key.

sites/browserpod/src/content/docs/10-getting-started/02-expressjs.md

@@ -3,8 +3,7 @@ title: Set up a basic NPM-based project
 description: In this tutorial you will set up a simple NPM project that runs an HTTP server using Express.js
 ---
 
-During this tutorial we will set up a basic project that uses BrowserPod to run
-a web server application entirely client side in the Browser.
+In this tutorial, we'll set up a basic project that uses BrowserPod to run a web server application entirely in the browser, with no backend infrastructure.
 
 ## 1. Get the code
 

sites/browserpod/src/content/docs/11-understanding-browserpod/06-portals.md

@@ -3,9 +3,19 @@ title: Portals
 description: How Portals expose Pod servers to the outside world
 ---
 
-A **Portal** is BrowserPod’s way of exposing a server running inside a Pod to the outside world.
+A **Portal** is BrowserPod's controlled networking feature that exposes services running inside a Pod through secure, shareable URLs.
 
-When code inside the Pod starts listening on a port, BrowserPod creates a public URL that forwards traffic to that internal server.
+When code inside the Pod starts listening on a port, BrowserPod automatically creates a public URL that forwards traffic to that internal server. This unlocks powerful use cases that would traditionally require provisioning dedicated backend infrastructure for each session.
+
+## What Portals enable
+
+Portals unlock use cases that typically require backend infrastructure:
+
+- **Live previews**: Run a dev server in the browser and share the preview URL with teammates or stakeholders. Changes update in real-time without deploying to staging environments.
+- **Interactive demos**: Let users interact with working applications directly in documentation or product tours, without standing up demo infrastructure.
+- **Collaborative workflows**: Enable pair programming, troubleshooting sessions, or live code reviews by sharing a running environment via a simple URL.
+- **Shareable environments**: Create "click-to-open" demos where anyone with the link can access a fully functional application running in someone else's browser.
+- **Testing across devices**: Scan a QR code on your phone to test the server running on your laptop's browser, with changes reflected instantly.
 
 ## What a Portal is
 

sites/browserpod/src/content/docs/14-more/00-glossary.md

@@ -9,7 +9,7 @@ The server-side part of a system that runs outside the browser.
 
 ## BrowserPod API
 
-The set of methods (like `pod.run` and file APIs) used to control the pod. New processes are started through the API, not by typing in the terminal.
+The JavaScript API for controlling a Pod. Provides methods for booting pods, running processes (`pod.run`), managing the virtual filesystem, and handling Portals. Used to execute code and manage the runtime environment entirely within the browser.
 
 ## CheerpOS
 
@@ -29,11 +29,11 @@ A filesystem created and managed in software rather than on the user’s real di
 
 ## Pod
 
-A running BrowserPod instance
+A running BrowserPod instance. Each Pod provides a sandboxed runtime environment with its own virtual filesystem, process space, and network layer. Pods run entirely in the browser and are ephemeral by design—they exist only while the browser tab is active.
 
 ## Portal
 
-A public URL that forwards external traffic to a port inside the pod.
+A secure, shareable URL that routes external traffic to a service listening on a port inside the Pod. Portals are created automatically when code binds to a port, enabling features like live previews, interactive demos, and collaborative workflows without requiring dedicated backend infrastructure.
 
 ## REPL