Document playground deployments in the deployment workflow

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yc-software/qm",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "Control-plane CLI for portable QM deployments on Docker, Fly, and AWS.",
   "type": "module",

cli/templates/deployment/deployment.md

@@ -143,6 +143,29 @@ endpoints and the email gate in `env.portal`. For Google Workspace:
 }
 ```
 
+### Playground mode
+
+A playground is a public try-it deployment: unauthenticated visitors get
+anonymous browser-pinned identities instead of a sign-in page, while the one
+administrator still signs in through whichever route above the deployment
+configured. Enable it in `qm.config.jsonc`:
+
+```json
+"env": { "portal": { "PORTAL_PLAYGROUND": "1" } }
+```
+
+A playground must be its **own deployment**, never a flag on a working org's
+instance: every visitor is an ordinary internal principal of the deployment's
+org, so anything granted or published at org scope — including org-granted
+credentials — is theirs. Grant nothing sensitive at org scope, connect no real
+connector credentials, and load no company data. A cleared cookie is a fresh
+identity, so set `env.core.ORG_BUDGET_USD_PER_WINDOW` — the one hard spend
+ceiling — in the same pass, and from the Admin page after first boot restrict
+the model picker to the subset you want to offer (one model or several).
+Nothing garbage-collects an abandoned visitor's scope yet.
+`plugins/portal/README.md` § "Playground mode" covers the rest: per-address
+mint limits, the boot refusals, and what anonymous visitors are denied.
+
 ### The base model
 
 Whichever sign-in route the deployment takes, the base model needs a key in the

src/api/app-turn.ts

@@ -5,7 +5,7 @@ import { isHalt, routeWake, type Wake } from "../wake/wake.ts";
 import type { OrchestratorInput } from "../core/orchestrator.ts";
 import { resolveTurnOrigin } from "../core/turn-origin.ts";
 import { isTerminal, leaseLapsed } from "../runs/run-store.ts";
-import { turnModelOptions, validateWebTurnModelOptions } from "../core/turn-options.ts";
+import { turnModelOptions, validateWebTurnModelOptions, webTurnRuntimeModelRefusal } from "../core/turn-options.ts";
 import { isProjectGroupRef, projectIdFromGroupRef } from "../projects/project-store.ts";
 import {
   defaultModelForHarness,
@@ -172,7 +172,7 @@ export function createTurnMethods(
         const configuredWebuiModels = await deps.config.getWebuiModelsDurable(org);
         let enabledWebuiModels: string[] | null = null;
         if (configuredWebuiModels?.length) {
-          enabledWebuiModels = configuredWebuiModels;
+          enabledWebuiModels = [...new Set([...configuredWebuiModels, orgRuntime.modelId])];
         } else if (providers?.openrouter) {
           enabledWebuiModels = [
             ...new Set([
@@ -184,7 +184,9 @@ export function createTurnMethods(
             ]),
           ];
         }
-        const invalidModelOption = validateWebTurnModelOptions(req, enabledWebuiModels, providers);
+        const invalidModelOption =
+          validateWebTurnModelOptions(req, enabledWebuiModels, providers) ??
+          webTurnRuntimeModelRefusal(runtime.modelId, orgRuntime.modelId, configuredWebuiModels);
         if (invalidModelOption) return { status: "refused", reason: invalidModelOption };
       }
 

src/api/routes/surface.ts

@@ -1015,6 +1015,16 @@ async function getRuntimeConfig(ctx: ApiCtx): Promise<void> {
   return sendJson(ctx.res, 200, await runtimeConfigBody(ctx, target.scope));
 }
 
+async function webuiModelEnabled(ctx: ApiCtx, modelId: string): Promise<boolean> {
+  const config = ctx.deps.config!;
+  const picker = await config.getWebuiModelsDurable(orgScope(ctx.deps));
+  if (!picker?.length || picker.includes(modelId)) return true;
+  const org = orgScope(ctx.deps);
+  const stored = await config.getRuntimeSelectionDurable(org);
+  const orgModel = stored?.modelId ?? (await config.getBaseModelOwnDurable(org)) ?? runtimeFallback(ctx).modelId;
+  return modelId === orgModel;
+}
+
 async function putRuntimeConfig(ctx: ApiCtx): Promise<void> {
   if (!ctx.deps.config || !isObj(ctx.body)) return sendJson(ctx.res, 400, { error: "bad_request" });
   if (ctx.capability && ctx.capability.liveActor !== true)
@@ -1033,7 +1043,8 @@ async function putRuntimeConfig(ctx: ApiCtx): Promise<void> {
       if (
         legacyModel &&
         approved.includes(fallback.harnessId) &&
-        modelSupportedByHarness(legacyModel, fallback.harnessId)
+        modelSupportedByHarness(legacyModel, fallback.harnessId) &&
+        (await webuiModelEnabled(ctx, legacyModel))
       ) {
         await config.setRuntimeSelectionLatest(target.scope, { harnessId: fallback.harnessId, modelId: legacyModel });
       }
@@ -1047,6 +1058,7 @@ async function putRuntimeConfig(ctx: ApiCtx): Promise<void> {
       return sendJson(ctx.res, 400, { error: "harness_not_approved" });
     if (typeof modelId !== "string" || !modelSupportedByHarness(modelId, harnessId))
       return sendJson(ctx.res, 400, { error: "model_not_supported" });
+    if (!(await webuiModelEnabled(ctx, modelId))) return sendJson(ctx.res, 400, { error: "model_not_enabled" });
     await config.setRuntimeSelectionLatest(target.scope, { harnessId, modelId });
   }
   audit(ctx.deps, {

src/core/turn-options.ts

@@ -34,6 +34,16 @@ export function turnModelOptions(input: { triggered?: boolean; thinkingLevel?: s
   };
 }
 
+export function webTurnRuntimeModelRefusal(
+  runtimeModelId: string,
+  orgModelId: string,
+  configuredWebuiModels: readonly string[] | null | undefined,
+): string | null {
+  if (!configuredWebuiModels?.length) return null;
+  if (runtimeModelId === orgModelId) return null;
+  return configuredWebuiModels.includes(runtimeModelId) ? null : "that model is not enabled for the web UI";
+}
+
 export function validateWebTurnModelOptions(
   input: { model?: string; thinkingLevel?: string },
   enabledModels: readonly string[] | null,

test/admin-resources.test.ts

@@ -249,6 +249,19 @@ test("runtime-config lets a person set, keep, and inherit an approved personal r
     ]);
     assert.deepEqual(initial.modelsByHarness.codex, ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]);
 
+    const outsidePicker = await fetch(`${srv.base}/v1/runtime-config`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        principalId: "alice",
+        scopeId: "personal:alice",
+        harnessId: "claude",
+        modelId: "claude-haiku-4-5",
+      }),
+    });
+    assert.equal(outsidePicker.status, 400);
+    assert.equal(((await outsidePicker.json()) as { error: string }).error, "model_not_enabled");
+
     const set = await fetch(`${srv.base}/v1/runtime-config`, {
       method: "PUT",
       headers: { "content-type": "application/json" },

test/model-credential-route.test.ts

@@ -411,3 +411,38 @@ test("admin model credentials survive a second app instance on the same durable
   assert.doesNotMatch(JSON.stringify(await backing.all()), /durable-openrouter-key/);
   assert.doesNotMatch(JSON.stringify(await second.statuses()), /durable-openrouter-key/);
 });
+
+test("a stored scope override outside the configured picker refuses web turns; the org default stays exempt", async () => {
+  const srv = start({ anthropicApiKey: "deployment-anthropic-key" });
+  try {
+    srv.built.config.setRuntimeSelection("org:default-org", { harnessId: "mock", modelId: "claude-opus-4-8" });
+    srv.built.config.setWebuiModels("org:default-org", ["claude-sonnet-4-6"]);
+    await srv.built.config.flushScope("org:default-org");
+    await srv.built.config.setRuntimeSelectionLatest("personal:alice", {
+      harnessId: "mock",
+      modelId: "claude-haiku-4-5",
+    });
+    const turn = (threadRef: string, model?: string) =>
+      srv.built.app.turn({
+        surface: "web",
+        actor: { externalId: "alice" },
+        conversation: { kind: "dm", threadRef },
+        text: "hello",
+        ...(model ? { model } : {}),
+        async: true,
+      });
+
+    const stale = await turn("web:alice:stale-override");
+    assert.equal(stale.status, "refused");
+    assert.match(stale.reason ?? "", /not enabled for the web UI/);
+
+    const explicitOrgDefault = await turn("web:alice:org-default", "claude-opus-4-8");
+    assert.equal(explicitOrgDefault.status, "queued");
+
+    await srv.built.config.setRuntimeSelectionLatest("personal:alice", null);
+    const inherited = await turn("web:alice:inherited");
+    assert.equal(inherited.status, "queued");
+  } finally {
+    await srv.close();
+  }
+});

test/turn-options.test.ts

@@ -5,6 +5,7 @@ import {
   NON_INTERACTIVE_THINKING_LEVEL,
   turnModelOptions,
   validateWebTurnModelOptions,
+  webTurnRuntimeModelRefusal,
 } from "../src/core/turn-options.ts";
 
 test("triggered turns default to extra-high thinking and non-fast mode", () => {
@@ -30,6 +31,18 @@ test("web model controls are bounded by admin configuration", () => {
   assert.equal(validateWebTurnModelOptions({ model: "claude-opus-4-8", thinkingLevel: "high" }, null), null);
 });
 
+test("a resolved scope override outside the configured picker is refused, the org default is not", () => {
+  const picker = ["claude-sonnet-4-6"];
+  assert.equal(
+    webTurnRuntimeModelRefusal("claude-opus-4-8", "claude-sonnet-4-6", picker),
+    "that model is not enabled for the web UI",
+  );
+  assert.equal(webTurnRuntimeModelRefusal("claude-sonnet-4-6", "claude-opus-4-8", picker), null);
+  assert.equal(webTurnRuntimeModelRefusal("claude-opus-4-8", "claude-opus-4-8", picker), null);
+  assert.equal(webTurnRuntimeModelRefusal("claude-opus-4-8", "claude-sonnet-4-6", null), null);
+  assert.equal(webTurnRuntimeModelRefusal("claude-opus-4-8", "claude-sonnet-4-6", []), null);
+});
+
 test("interactive turns do not force model options", () => {
   assert.deepEqual(turnModelOptions({}), {});
 });