lukebuehler · Oct 4, 2026 · Oct 4, 2026 · Oct 4, 2026 · Oct 4, 2026 · Oct 4, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -29,4 +29,4 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "0.3.0"
+version = "0.4.0"
diff --git a/README.md b/README.md
@@ -8,6 +8,12 @@
 
 <p align="center"><strong>Run thousands of agents. Efficient, durable, auditable.</strong></p>
 
+<p align="center">
+  <a href="https://ls.bot/" target="_blank">Website</a> ·
+  <a href="https://ls.bot/docs/" target="_blank">Documentation</a> ·
+  <a href="https://ls.bot/demo" target="_blank">Demo</a>
+</p>
+
 Lightspeed is open-source infrastructure for running managed agent fleets as durable workflows.
 
 "Managed agents" is an emerging pattern that separates the core agent loops from the VM or sandbox they use. Agents survive restarts, can run for months, and stay cheap when idle. When they
@@ -126,7 +132,7 @@ The current implementation includes:
 - [x] **Workflow-backed plugins**: external Temporal workflows can extend session with various tools and custom logic
 - [x] **One backend binary**: run every runtime role in one process or scale them independently across Temporal workers
 
-**Borrowed compute**
+**Attached compute**
 
 - [x] **Dedicated VMs**: attach an existing machine or provision one through the
   included Incus provider

diff --git a/docs/documentation/deployment/configuration.md b/docs/documentation/deployment/configuration.md
@@ -120,11 +120,16 @@ it. Deployment-level `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` are fallback
 credentials when the corresponding universe record is absent. A disabled or
 broken stored record blocks fallback.
 
-`LIGHTSPEED_CHAT_PROVIDER` and `LIGHTSPEED_CHAT_MODEL` change the runtime's
-default provider ID and model name. Its default API kind remains
-`openai:responses`; changing a provider ID alone does not switch wire formats.
-For Anthropic or another route, select provider, API kind, and model explicitly
-in a profile. See [Models and credentials](../using-lightspeed/models-and-credentials.md).
+Choose each universe's agent and speech-to-text defaults under **Models →
+Defaults**, or through `lightspeed model defaults`. Each selection names a
+provider, API kind, and model. New sessions use an explicit session model,
+then the profile model, then the universe default; existing sessions keep
+their resolved model. There is no deployment-wide model fallback.
+
+Remove `LIGHTSPEED_CHAT_PROVIDER` and `LIGHTSPEED_CHAT_MODEL` from older
+configuration: the runtime rejects them at startup. See
+[Models and credentials](../using-lightspeed/models-and-credentials.md#choose-universe-defaults)
+for setup and precedence.
 
 ## Choose the blob backend
 

diff --git a/docs/documentation/deployment/troubleshooting.md b/docs/documentation/deployment/troubleshooting.md
@@ -49,6 +49,7 @@ If the runtime exits before serving, check the error against these dependencies:
 | Object-store configuration | A nonempty bucket when any `LIGHTSPEED_OBJECT_STORE_*` variable is set, plus the intended endpoint and credentials. |
 | Role or environment routing | Valid roles and the internal environment gateway URL/token on every process without that role. |
 | Secret configuration | A base64 master key decoding to 32 bytes, matching the stored encrypted state. |
+| Retired model variables | Remove `LIGHTSPEED_CHAT_PROVIDER` and `LIGHTSPEED_CHAT_MODEL`; configure each universe's model defaults through Models or `lightspeed model defaults`. |
 
 The Platform needs its own database and authentication settings. Its migrations
 run before HTTP serving. Do not point it at the runtime database or reset
@@ -130,6 +131,22 @@ not confuse removal with disabling access. A coding-agent subscription login
 also does not authenticate Lightspeed's own session inference. Follow
 [Models and credentials](../using-lightspeed/models-and-credentials.md).
 
+If session creation reports `model_default_unset`, select an explicit session
+or profile model, or configure **Models → Defaults → Agent runs**. A provider
+key alone does not choose a model. Voice preparation and dictation need the
+separate **Speech-to-text** default.
+
+For context-length errors, inspect the effective compaction policy and recovery
+attempts in session settings. Enabled sessions can compact and retry within
+the same run; Disabled and historical omitted policies do not recover
+automatically. A protected input larger than the usable window can still fail.
+See [Manage long conversations](../using-lightspeed/sessions-and-runs.md#manage-long-conversations).
+
+If a specific entry keeps making the provider reject requests, stop active
+work and use [CLI context repair](../using-lightspeed/cli.md#repair-rejected-context)
+to inspect and replace a user message or tool result. This preserves the
+event history; do not rewrite the stored log to repair active context.
+
 If discovery succeeds but an agent has no expected tool, inspect its profile's
 capability grants and the MCP server/tool selection. Registering a server
 does not grant every session permission to use it. Also distinguish a tool

diff --git a/docs/documentation/deployment/upgrades-and-recovery.md b/docs/documentation/deployment/upgrades-and-recovery.md
@@ -56,13 +56,38 @@ not guarantee compatibility with saved session configuration or workflow
 histories. Use matching clients and review daemon changes even when protocol
 mismatch would not trigger an automatic daemon update.
 
+## Review model and context configuration
+
+Remove `LIGHTSPEED_CHAT_PROVIDER` and `LIGHTSPEED_CHAT_MODEL` from the runtime
+environment before starting current workers; both variables are retired and
+cause startup to fail. After the runtime is available, save the intended
+provider/API/model route in each universe's **Agent runs** default using
+**Models → Defaults** or `lightspeed model defaults set agent-run`. Configure
+**Speech-to-text** separately for dictation and channel voice messages.
+Deployment provider credentials remain supported, but do not choose a model.
+See [Configure universe model defaults](../using-lightspeed/cli.md#configure-universe-model-defaults).
+
+Existing sessions retain their stored model. Historical sessions with an
+omitted compaction policy also retain their disabled replay behavior. New
+sessions and configuration replacements resolve omission to automatic
+standalone compaction; preserve an explicit Disabled setting when automatic
+compaction and context-limit recovery should stay off. Review these settings
+when applying a profile or replacing configuration during an upgrade.
+See [Manage long conversations](../using-lightspeed/sessions-and-runs.md#manage-long-conversations).
+
+Audio integrations must transcribe before session admission. Run start,
+context append, and steering reject raw audio; use the
+[standalone transcription flow](../integrating-and-extending/api-and-typescript.md#transcribe-audio-before-submitting-session-input)
+and submit prepared text.
+
 ## Enable company sign-in on an existing Platform
 
 The company-identity migration adds identity provenance, session revocation
 versions and durable access records. Existing users remain local and keep
 their memberships; the migration does not grant company or emergency access.
-The current Platform schema revision is 3. Startup applies the generated
-Platform migrations before serving requests.
+The required Platform revision is `LIGHTSPEED_PLATFORM_SCHEMA_REVISION` in
+the target release's [metadata](../../../release/metadata.env). Startup applies
+the generated Platform migrations before serving requests.
 
 Before enabling OIDC, designate an existing local password admin through
 `LIGHTSPEED_PLATFORM_ADMIN_EMAIL` and verify its emergency login. Use a

diff --git a/docs/documentation/development/testing-and-evaluation.md b/docs/documentation/development/testing-and-evaluation.md
@@ -227,8 +227,8 @@ Without `--model`, the harness uses the provider's model environment variables
 and then its compiled default. OpenAI Responses checks
 `OPENAI_RESPONSES_MODEL`, Completions checks `OPENAI_COMPLETIONS_MODEL`, and
 both fall back to `OPENAI_LIVE_MODEL`. Anthropic checks
-`ANTHROPIC_MESSAGES_MODEL`, then `ANTHROPIC_LIVE_MODEL`. The product's
-`LIGHTSPEED_CHAT_MODEL` setting does not configure this harness. Provider base
+`ANTHROPIC_MESSAGES_MODEL`, then `ANTHROPIC_LIVE_MODEL`. Universe model
+defaults do not configure this evaluation harness. Provider base
 URL overrides are honored too; record them with a comparison.
 
 ### Add a case with observable assertions

diff --git a/docs/documentation/environments/using-environments.md b/docs/documentation/environments/using-environments.md
@@ -95,11 +95,20 @@ support the operation, and its operating-system permissions still apply.
 read instructions from an attached environment independently of whether it
 permits commands.
 
-The session's context includes an **Environment catalog** listing every
-attachment with its display name, status, access, working directory, and
-which one is active, so the agent knows what it may use before calling a
-tool. After a switch, the old catalog is removed until the next idle refresh.
-Use `environment_list` or `environment_read` for current status during a run.
+The session's **Environment catalog** lists attached machines with their
+references, display names, default markers, and access grants. Selection and
+lifecycle changes do not replace this directory. Use `environment_read` for
+current selection, status, and working directory; it remains available when
+environment selection tools are disabled.
+
+Long environment IDs appear to the model as short `env:` references in
+catalogs, control results, and job handles. These resolve only against the
+session's authorized attachments. Full IDs remain accepted and are still the
+identities stored in profiles and public API records. An ambiguous short
+reference is rejected; use the full ID in that case. Short references do not
+grant additional access. Skill and prompt discovery remains tied to the
+selected machine, as described in
+[Workspaces and skills](../using-lightspeed/workspaces-and-skills.md#discover-skills-installed-on-a-machine).
 
 ## Keep files in the right domain
 

diff --git a/docs/documentation/getting-started/quickstart.md b/docs/documentation/getting-started/quickstart.md
@@ -120,7 +120,7 @@ session. A saved key needs access to the model you will select.
 
 1. Open **Sessions** and choose the plus button labeled **New session**.
 2. Enter `First conversation` as the **Name** and leave **Profile** at
-   **No profile (engine defaults)**.
+   **No profile (universe default)**.
 3. Choose **Customize setup…**. Under **Model configuration → Model**, select
    a conversational model from the provider you just connected.
 4. Choose **Create session**.
@@ -130,9 +130,11 @@ session. A saved key needs access to the model you will select.
 *Demo mode: choose **Customize setup…** to select a model before creating
 the conversation.*
 
-Select the model explicitly. Adding a credential does not change the
-deployment's default model, so leaving **Deployment default** selected can
-send the request to a different provider.
+Select the model explicitly for this walkthrough. Alternatively, an Operator
+or Admin can choose **Agent runs** under **Models → Defaults** and leave
+**Universe default** selected in session setup. Adding a credential alone
+does not select that default. If neither the session nor its profile supplies
+a model and the universe has no default, session creation fails.
 
 Send a short message: