[codex] Layer Summon terminology across docs and demos

README.md

@@ -1,13 +1,18 @@
 # Summon
 
-Sandboxed, self-contained generative UI. An LLM streams HTML, CSS, and
-JavaScript into a locked-down iframe; the UI communicates with the host only
-through a typed intent bridge. Data in, data out, nothing leaks.
+Summon renders AI-generated UI in a locked iframe. The generated UI can only use
+host tools you register, so the host keeps control of data, actions, credentials,
+network access, state, and persistence.
 
-Summon is also an adoption architecture. Hosts declare capabilities, compile
-prompt and validation contracts, harden the streamed protocol, and render only
-accepted output inside the sandbox. The model can propose UI, but the host owns
-network, credentials, state, handlers, grants, and persistence.
+The adopter mental model is intentionally small:
+
+| Term | Meaning |
+| --- | --- |
+| Surface | The generated UI Summon renders. |
+| Host tool | A host-owned data source or action the surface may request. |
+| Sandbox | The locked iframe where generated UI runs. |
+| Surface config | The host's choice of what the surface is allowed to do. |
+| Diagnostics | Stream and Devtools information used when something breaks. |
 
 ## Project Status: Beta
 
@@ -34,9 +39,9 @@ pnpm dev:gallery
 
 Open `http://localhost:5174`.
 
-The Surface Gallery is the first OSS demo: curated live presets that show
-static, host-resource, host-action, approval-gated, component-island, and
-worker-backed Summon surfaces without exposing workbench controls.
+The Surface Gallery is the first OSS demo. It shows static surfaces, host-backed
+search, host-owned actions, approval flows, trusted host components, and
+background host work without exposing the maintainer workbench.
 
 For the maintainer workbench:
 
@@ -46,64 +51,52 @@ pnpm dev:all
 
 Open `http://localhost:5173/generate.html`.
 
-1. Choose the **Host-resource search** showcase scenario.
-2. Confirm the contract cockpit shows
-   `explore/declarative/host-resource/read/replayable` with the `search` grant.
-3. Run it, submit a generated search, then inspect the **Stream** and
-   **Devtools** drawers.
+1. Choose the **Host Data Search** showcase scenario.
+2. Confirm the run is interactive and only the `search` host tool is allowed.
+3. Run it, then submit a generated search such as `chicken pasta`.
 4. Open `http://localhost:5173/adversarial.html` and confirm the sandbox
    boundary still holds.
 
 The full guided path lives in
 [docs/adoption/quickstart.md](docs/adoption/quickstart.md).
 
-## Architecture
-
-Summon's supported integration path is intentionally narrow:
+## How It Fits Together
 
-```txt
-host capability registry
-  -> SurfacePolicy: tier/grants/components/purpose/persistence
-  -> compiled SurfacePlan: purpose/runtime/data/authority/persistence
-  -> createCapabilityRegistry(...).toContract()
-  -> compileSystemContracts()
-  -> protocol hardener + repair feedback
-  -> SectionAccumulator + StreamGraph
-  -> PolicyEngine + spawnSandbox()
-```
+Summon's supported integration path is narrow:
 
-No generated artifact gets to mint permissions for itself. Artifact-declared
-intents are advisory; execution is governed by host grants.
+1. Register the host tools and trusted host components the surface may use.
+2. Choose a surface config for the run.
+3. Generate the surface on the server.
+4. Render accepted output in the sandbox.
+5. Use diagnostics when generation or interaction fails.
 
-Surface policy is Summon's lifecycle layer. A host declares the public tier,
-grants, trusted components, purpose, and persistence before generation starts.
-Summon compiles that policy into the stricter `SurfacePlan` contract the model
-sees and cannot widen.
+The model can propose UI, but it cannot give itself permissions. Generated
+requests are advisory until the host validates them and dispatches them through
+registered host tools.
 
 ## Demo Map
 
 - `examples/surface-gallery` - first-run OSS gallery with curated live presets,
-  compact host contracts, a sandboxed surface, and a small event strip.
-- `/generate.html` - contract cockpit with scenario grants, compiled surface plans,
-  static/declarative/scripted/worker tiers, component islands, host resources,
-  token overrides, repair diagnostics, edit/replay, Ghost steering, Devtools,
-  and stream graph events.
-- `/batch.html` - parallel prompt harness for prompt coverage, intent wiring,
+  compact host tools, a sandboxed surface, and a small event strip.
+- `/generate.html` - maintainer workbench for surface configs, allowed host
+  tools, trusted host components, token overrides, validation retries,
+  edit/replay, Ghost steering, Devtools, and stream diagnostics.
+- `/batch.html` - parallel prompt harness for prompt coverage, host tool wiring,
   direction-token visual coverage, throughput, and consistency checks.
 - `/adversarial.html` - sandbox boundary checks for network, storage, parent
-  access, and ungranted intents.
-- `/strict.html` - trusted host overlay for sensitive input inside an outer
+  access, and unallowed host tool requests.
+- `/strict.html` - trusted host overlay for sensitive input inside a generated
   sandbox description.
 - `/fatal.html` - sandbox startup failure handling.
 
 ## Public Packages
 
-- `@anarchitecture/summon` - curated host-authoring helpers, policy helpers,
-  and surface-plan APIs. Advanced browser, engine, host, policy, envelope,
-  assets, and Devtools APIs live on explicit subpaths.
+- `@anarchitecture/summon` - curated host-authoring helpers, surface config
+  helpers, and explicit subpaths for advanced browser, engine, host, policy,
+  envelope, assets, and Devtools APIs.
 - `@anarchitecture/summon-server` - provider-neutral generation lifecycle,
-  repair, summaries, and model-provider interfaces.
-- `@anarchitecture/summon-react` - `SummonSurface` and React component island
+  validation retries, summaries, and model-provider interfaces.
+- `@anarchitecture/summon-react` - `SummonSurface` and React trusted-component
   adapter. `react` and `react-dom` are peer dependencies.
 
 ## Workspace Map
@@ -113,10 +106,11 @@ sees and cannot widen.
   `packages/sandbox-runtime`, `packages/server`, `packages/react` - private
   implementation workspaces published only through the public facades.
 - `examples/surface-gallery` - first-run live example app for OSS adopters.
-- `apps/server` - Anthropic-backed demo server, direction loading, repair
-  feedback, and demo backing routes.
-- `apps/demo` - Vite workbench for generation, batch runs, adversarial checks,
-  strict input, Ghost steering, repair diagnostics, and fatal sandbox testing.
+- `apps/server` - Anthropic-backed demo server, direction loading, validation
+  retry feedback, and demo backing routes.
+- `apps/demo` - Vite maintainer workbench for generation, batch runs,
+  adversarial checks, strict input, Ghost steering, diagnostics, and fatal
+  sandbox testing.
 
 ## Adoption Docs
 
@@ -127,18 +121,18 @@ sees and cannot widen.
   and frameworkless hosts should import built Summon packages.
 - [Mobile WebViews](docs/adoption/mobile-webviews.md) - web-first requirements
   for iOS/Android WebView embedding.
-- [Security Posture](docs/adoption/security.md) - production tiers, host rules,
+- [Security Posture](docs/adoption/security.md) - surface types, host rules,
   and browser-test expectations.
-- [Debugging](docs/adoption/debugging.md) - validation, repair, stream graph,
-  and Devtools diagnostics.
+- [Debugging](docs/adoption/debugging.md) - diagnostics for failed generation,
+  broken controls, missing data, trusted components, and sandbox safety.
 - [Agent skill](.agents/skills/summon/SKILL.md) - repo-local operating guide
   for AI agents working on Summon.
 
 ## Security Boundary
 
 Summon renders generated UI in a null-origin iframe with a restrictive CSP and a
-typed postMessage bridge. The host grants intents and capabilities explicitly;
-artifact-declared permissions are never executable authority.
+typed postMessage bridge. The host explicitly chooses the allowed host tools for
+each run; declarations from generated UI are never executable authority.
 
 Run the safety harness before changing iframe sandbox attributes, CSP,
 postMessage routing, bootstrap startup checks, or script execution behavior:

apps/demo/batch.html

@@ -14,7 +14,7 @@
 </nav>
 
 <h1 class="page-title">Batch testing</h1>
-<p class="lede">Fire N generations in parallel. Same prompt to compare consistency, or a seeded random sample from the curated intent pool to compare coverage.</p>
+<p class="lede">Fire N generations in parallel. Same prompt to compare consistency, or a seeded random sample from the curated prompt pool to compare coverage.</p>
 
 <div class="controls">
   <label>Direction <select id="direction"></select></label>

apps/demo/generate.html

@@ -33,12 +33,12 @@ <h1 class="page-title">Generate</h1>
     <section class="stage-context" aria-label="Selected scenario">
       <div>
         <div class="stage-eyebrow" id="scenario-active-category">Showcase</div>
-        <h2 id="scenario-active-title">Host-resource search</h2>
+        <h2 id="scenario-active-title">Host Data Search</h2>
         <p id="scenario-active-desc">Host-owned data with explicit read authority.</p>
       </div>
       <div class="stage-fingerprint">
         <span id="scenario-active-fingerprint">pending</span>
-        <strong id="scenario-active-grants">0 grants</strong>
+        <strong id="scenario-active-grants">0 host tools</strong>
       </div>
     </section>
 
@@ -75,7 +75,7 @@ <h2 id="scenario-active-title">Host-resource search</h2>
       <div class="iframe-wrap">
         <iframe id="sandbox" class="h-640" title="Summon generate sandbox"></iframe>
         <div class="iframe-welcome" id="welcome">
-          <div class="welcome-text" id="welcome-text">Host-resource search awaits generated UI.</div>
+          <div class="welcome-text" id="welcome-text">Host Data Search awaits generated UI.</div>
         </div>
       </div>
     </div>
@@ -85,7 +85,7 @@ <h2 id="scenario-active-title">Host-resource search</h2>
 
   <aside class="contract-inspector" aria-label="Contract inspector">
     <div class="inspector-heading">
-      <span>Contract Inspector</span>
+      <span>Surface Inspector</span>
       <span id="inspector-status">pending</span>
     </div>
     <div class="contract-summary" id="contract-summary"></div>
@@ -124,9 +124,9 @@ <h2 id="scenario-active-title">Host-resource search</h2>
           <label><input type="radio" name="mode" value="static" checked><span>Static</span></label>
           <label><input type="radio" name="mode" value="interactive"><span>Interactive</span></label>
         </div>
-        <label class="repair-toggle" title="Enable targeted repair">
+        <label class="repair-toggle" title="Enable validation retry">
           <input id="repair-enabled" type="checkbox">
-          <span>Repair</span>
+          <span>Validation retry</span>
         </label>
       </div>
 
@@ -145,10 +145,10 @@ <h2 id="scenario-active-title">Host-resource search</h2>
     <section class="custom-contract">
       <label class="custom-contract-toggle">
         <input id="custom-contract-enabled" type="checkbox">
-        <span>Custom Contract</span>
+        <span>Custom Surface Config</span>
       </label>
       <div id="custom-contract-panel" class="custom-contract-panel" hidden>
-        <div class="surface-controls" aria-label="Surface plan">
+        <div class="surface-controls" aria-label="Surface config controls">
           <select id="surface-purpose" class="pill-select" title="Surface purpose"></select>
           <select id="surface-runtime" class="pill-select" title="Surface runtime"></select>
           <select id="surface-data" class="pill-select" title="Surface data"></select>

apps/demo/index.html

@@ -11,7 +11,7 @@
   <div class="landing-content">
     <header class="landing-header">
       <h1 class="landing-title">summon</h1>
-      <p class="landing-tagline">Sandboxed, self-contained generative UI. An LLM streams HTML/CSS/JS into a locked-down iframe; the only way out is a declared vocabulary of intents.</p>
+      <p class="landing-tagline">Summon renders AI-generated UI in a locked iframe. The UI can only use host tools this app allows.</p>
     </header>
 
     <div class="landing-grid">

apps/demo/src/batch-main.ts

@@ -197,7 +197,7 @@ function makeTile(prompt: string, tokensCss: string, interactivity: Interactivit
         if (handleRef.current) handleRef.current.pushState(state);
       },
       onHandlerError: (intent, error) => {
-        markIntent(`handler error (${intent}): ${error.message}`, true);
+        markIntent(`host handler error (${intent}): ${error.message}`, true);
       },
     });
   }
@@ -223,7 +223,7 @@ function makeTile(prompt: string, tokensCss: string, interactivity: Interactivit
       void policy?.dispatch(intent, args);
     },
     onIntentRejected: (reason) => {
-      intentEl.textContent = `rejected: ${reason}`;
+      intentEl.textContent = `request rejected: ${reason}`;
       intentEl.classList.add('on', 'err');
     },
   });