docs: a page per example-agent demo, plus demos on the landing page

site/app/(landing)/Landing.tsx

@@ -10,6 +10,7 @@ import { Wordmark } from "@/components/Wordmark";
 import { SiteFooter } from "@/components/SiteFooter";
 import { DiscordIcon, GitHubIcon } from "@/components/BrandIcons";
 import { DISCORD_URL } from "@/lib/site";
+import { getAsset } from "@/lib/manifest";
 import { OWASP, coverageSummary } from "./owasp";
 
 const REPO = "https://github.com/authzed/openagentprimitives";
@@ -428,6 +429,23 @@ function InstallTerminal() {
   );
 }
 
+/* A narrated demo clip, resolved from the docs media manifest. The narration
+ * is the point, so there is no autoplay: it starts on a click, unmuted, from
+ * its poster frame. */
+function DemoClip({ name, caption }: { name: string; caption: ReactNode }) {
+  const asset = getAsset(name);
+  if (!asset || (!asset.webm && !asset.mp4)) return null;
+  return (
+    <figure className="lp-clip">
+      <video controls playsInline preload="metadata" poster={asset.poster}>
+        {asset.webm && <source src={asset.webm} type="video/webm" />}
+        {asset.mp4 && <source src={asset.mp4} type="video/mp4" />}
+      </video>
+      <figcaption>{caption}</figcaption>
+    </figure>
+  );
+}
+
 function SectionHead({
   kicker,
   children,
@@ -508,6 +526,15 @@ export function Landing() {
           </div>
           <div className="lp-hero-aside">
             <InstallTerminal />
+            <DemoClip
+              name="reviewbot-demo"
+              caption={
+                <>
+                  Watch one: <a href="/docs/reviewbot">reviewbot</a> reviews a
+                  pull request read-only and records a Check Run.
+                </>
+              }
+            />
           </div>
         </header>
 
@@ -634,6 +661,10 @@ export function Landing() {
               </div>
             ))}
           </div>
+          <DemoClip
+            name="builder-first-agent"
+            caption="One build end to end in the real web UI: describe the agent, answer its questions, approve the stage once, test it live, and keep the draft."
+          />
           <div className="lp-hero-cta lp-section-cta">
             <a className="lp-btn lp-btn--ghost" href="/docs/agent-builder">
               Read the Agent Builder guide

site/app/(landing)/landing.css

@@ -538,6 +538,42 @@ body:has(.lp) {
   color: var(--lp-term-muted);
 }
 
+/* ---------------------------------------------------------------- clips --- */
+
+/* Narrated demo clips, framed like the terminal. Posters carry the frame;
+   the narration means no autoplay, so the video waits for a click. */
+.lp-clip {
+  margin: 0;
+}
+
+.lp-hero-aside .lp-clip {
+  margin-top: 16px;
+}
+
+.lp-section .lp-clip {
+  margin-top: 40px;
+  max-width: 860px;
+}
+
+.lp-clip video {
+  display: block;
+  width: 100%;
+  border: 1px solid var(--lp-line);
+  border-radius: var(--lp-radius);
+  background: var(--lp-term-bg);
+}
+
+.lp-clip figcaption {
+  margin-top: 8px;
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--lp-muted);
+}
+
+.lp-clip figcaption a {
+  color: var(--lp-link);
+}
+
 /* ---------------------------------------------------------------- slabs --- */
 
 /* Cells fused into one slab by a 1px gap over a line-colored ground, so

site/content/docs/codebot.mdx

@@ -0,0 +1,51 @@
+export const meta = {
+  title: 'codebot',
+  section: 'Guides',
+  group: 'Example agents',
+  order: 70,
+  description: 'A passthrough coding agent that plans, gets one scoped approval, and opens a pull request as the person who asked.',
+}
+
+# codebot
+
+<div className="doc-lede">
+  codebot is a coding agent that clones a repository, makes the change with the requester's own
+  Claude Code subscription, commits as the requester, and opens a pull request. It runs in
+  passthrough identity mode, so the platform never holds the person's credentials — they are
+  injected into the sandbox at session start and discarded with it.
+</div>
+
+<Clip name="codebot-demo" />
+
+## What the demo shows
+
+Jordan asks codebot to fix a flaky test in `acme/widget`. The agent proposes a plan, and a single
+approval covers both the plan and the repository it names — the approval is slotted to
+`acme/widget`, so the steps inside the plan run without prompting again, ending in an opened pull
+request. When Jordan then asks for work in a different repository, the slotted approval does not
+stretch to cover it: a fresh approval is required.
+
+The demo is a scripted Slack simulation; its people, companies, repositories, and results are
+fictional.
+
+## The controls at work
+
+- [Plan gating](/docs/plan-gating) — a person approves the plan once, and every later action is
+  checked against it.
+- [Passthrough identity](/docs/passthrough-vs-agent) — the work runs as Jordan, under Jordan's own
+  GitHub and Anthropic credentials, which the platform never stores server-side.
+
+## Install it
+
+The bundle is in the repository at
+[`examples/codebot`](https://github.com/authzed/openagentprimitives/tree/main/examples/codebot),
+packaged as a [`.oap` agent container](/docs/packaging-oap):
+
+```bash
+oap agent lint    examples/codebot
+oap agent install examples/codebot --namespace default
+```
+
+The install prompts one question — which language toolchains the coding sandbox
+should get. After install, each user links their own GitHub and Anthropic
+credentials once via the identity portal.

site/content/docs/example-agent-builder.mdx

@@ -0,0 +1,32 @@
+export const meta = {
+  title: 'Agent Builder',
+  section: 'Guides',
+  group: 'Example agents',
+  order: 78,
+  description: 'One build in the real web UI: describe an agent, answer its questions, approve the stage, test it live, and keep the draft.',
+}
+
+# Agent Builder
+
+<div className="doc-lede">
+  Agent Builder is an OAP agent that creates other agents. In the real web UI, a person describes a
+  new limerick agent in plain language; the builder asks questions one at a time, gets a stage
+  approval, builds a draft, lets the person test it live on the page, and offers an
+  admin-reviewed install.
+</div>
+
+<Clip name="builder-first-agent" />
+
+## What the demo shows
+
+Unlike the other example-agent demos, this is footage of the real product, end to end: one
+description, a few questions, one approval per stage, a live test of the draft in an embedded
+session, and a saved draft the person keeps. Installing it for real records a request for a
+platform administrator; nothing runs until they approve it.
+
+## Where to go next
+
+- [Agent Builder](/docs/agent-builder) — what the builder is, how it's turned on, and the controls
+  it follows.
+- [Your first custom agent](/docs/agent-builder-first-agent) — this same build walked through
+  stage by stage, with the page as the guide.

site/content/docs/hubspot-companies.mdx

@@ -0,0 +1,48 @@
+export const meta = {
+  title: 'hubspot-companies',
+  section: 'Guides',
+  group: 'Example agents',
+  order: 72,
+  description: 'A read-only HubSpot CRM reporter: a scheduled company digest, with private contacts gated behind the owner of the data.',
+}
+
+# hubspot-companies
+
+<div className="doc-lede">
+  hubspot-companies is a read-only HubSpot CRM reporting agent. On a schedule it reports the
+  companies created inside a window that cleared a minimum fit score, mentioning each company's
+  assigned owner in the channel. Contacts on a named company are gated behind an owner-approval
+  flow — the person who owns the record decides, not whoever asked.
+</div>
+
+<Clip name="hubspot-companies-demo" />
+
+## What the demo shows
+
+A scheduled digest highlights the companies that passed the fit threshold. When Sam asks for
+Circldot's contacts, the agent does not answer Sam directly: the approval routes to Circldot's
+owner, Jordan, who sees what would be shared, with whom, and why. Only after Jordan approves does
+the agent return the contacts to Sam.
+
+The demo is a scripted Slack simulation; its people, companies, and results are fictional.
+
+## The controls at work
+
+- [Triggers](/docs/triggers) — the digest is a scheduled run, not a person typing.
+- [Shared permissions](/docs/shared-permissions) — the approval routes to the data's owner, and
+  the data is shared only after that owner says yes.
+
+## Install it
+
+The bundle is in the repository at
+[`examples/hubspot-companies`](https://github.com/authzed/openagentprimitives/tree/main/examples/hubspot-companies),
+packaged as a [`.oap` agent container](/docs/packaging-oap):
+
+```bash
+oap agent lint    examples/hubspot-companies
+oap agent install examples/hubspot-companies --namespace default
+```
+
+The install applies the bundled manifests, then drives each required channel's
+wizard. The HubSpot OAuth credential is minted separately by the identity setup
+flow described in the bundle's README.

site/content/docs/pm-bot.mdx

@@ -0,0 +1,48 @@
+export const meta = {
+  title: 'pm-bot',
+  section: 'Guides',
+  group: 'Example agents',
+  order: 76,
+  description: 'A read-only product-manager agent that reports how GitHub and Linear work in flight aligns with product goals.',
+}
+
+# pm-bot
+
+<div className="doc-lede">
+  pm-bot is a read-only product-manager agent. It reads the GitHub repositories it was granted and
+  the Linear issues in the linked workspace, then reports how the work in flight aligns with stated
+  product goals. It never writes to either system.
+</div>
+
+<Clip name="pm-agent-demo" />
+
+## What the demo shows
+
+pm-bot reads its granted repositories and linked issues, groups the work in flight by product
+goal, and posts a summary that recommends a next step — without changing anything in GitHub or
+Linear.
+
+The demo is a scripted Slack simulation; its people, repositories, issues, and results are
+fictional.
+
+## The controls at work
+
+- Which repositories the agent may read is an install question, answered by the administrator who
+  installs it — not something the agent discovers at runtime.
+- [Safe tools](/docs/safe-tools) — read-only is a property of the tool contracts the session is
+  offered, checked on every call.
+
+## Install it
+
+The bundle is in the repository at
+[`examples/pm-agent`](https://github.com/authzed/openagentprimitives/tree/main/examples/pm-agent),
+packaged as a [`.oap` agent container](/docs/packaging-oap):
+
+```bash
+oap agent lint    examples/pm-agent
+oap agent install examples/pm-agent --namespace default
+```
+
+The install asks its two questions — which repositories the agent may read, and
+the read-only GitHub PAT it authenticates with. It applies no privileged
+resources, so it is safe to install into a shared namespace.

site/content/docs/reviewbot.mdx

@@ -0,0 +1,50 @@
+export const meta = {
+  title: 'reviewbot',
+  section: 'Guides',
+  group: 'Example agents',
+  order: 74,
+  description: 'An automated pull-request reviewer: triggered by a webhook, read-only by construction, concluded as a GitHub Check Run.',
+}
+
+# reviewbot
+
+<div className="doc-lede">
+  reviewbot is an automated GitHub pull-request reviewer. A push to a pull request arrives as a
+  signed webhook — no human starts the session — so the agent clones the diff read-only, drives an
+  inner Claude Code through its bundled review skills, delivers the summary to Slack, and records
+  the outcome as a GitHub Check Run on the pull request's head commit. It never writes to a
+  repository and never comments on a pull request.
+</div>
+
+<Clip name="reviewbot-demo" />
+
+## What the demo shows
+
+A pull-request update starts a read-only review. reviewbot posts its findings and a report
+reference in Slack, then concludes a Check Run on the reviewed commit. Nothing in the run can
+modify the repository or post PR comments — the write simply isn't among the tools the session is
+offered.
+
+The demo is a scripted Slack simulation; its people, repositories, and results are fictional.
+
+## The controls at work
+
+- [Triggers](/docs/triggers) — the session starts from a signed webhook, with HMAC verification
+  and event filtering enforced by the platform.
+- [Safe tools](/docs/safe-tools) — the read-only boundary is declared in the tool contracts and
+  enforced per call, not entrusted to the model or to a narrow upstream token.
+
+## Install it
+
+The bundle is in the repository at
+[`examples/reviewbot`](https://github.com/authzed/openagentprimitives/tree/main/examples/reviewbot),
+packaged as a [`.oap` agent container](/docs/packaging-oap):
+
+```bash
+oap agent lint    examples/reviewbot
+oap agent install examples/reviewbot --namespace default
+```
+
+The install prompts for reviewbot's own Anthropic API key when its Secret is
+absent, and runs the GitHub channel wizard. See the bundle's README for the
+prerequisites, including the Claude toolchain image its sandbox runs.