Topolo Director

Public overview of Director as the Topolo workspace for proof-driven product demo runbooks and readiness gates.

publicverified 2026-07-28directordemosrunbooks

What It Is

Topolo Director helps authenticated teams coordinate proof-driven demo runbooks, chunked human recording, production readiness gates, raw-footage archive handoff, timed script review, voice-render requests, and narration for product walkthroughs. When a script should sound like a specific person, Director is the intended consumer of Agent-owned person profiles for writing and speaking style rather than the owner of reusable likeness data.

Teams can separate initiatives into Director workspaces and create recording projects inside each workspace. A project can start with a complete ordered shot plan and then create one or more recording sessions without exposing projects from another workspace.

Architecture

Director runs as a Cloudflare Worker application with Topolo Auth protecting its workspace API. The shared platform chrome displays the first-party short name Director, while the browser title and social metadata use the canonical Topolo Director name. The app persists demo runbooks, required active inputs, human presenter cues, recording sessions, recording chunks, chunk takes, take trash/flag/R2 sync status, composition manifests, proof gates, narration review, timed script-pass events, voice-render requests, and bridge readiness in its own Director data store and exposes a TopoloOne widget for live workspace visibility. The workspace is split into focused sections for overview, sessions, runbooks, proof gates, script review, and capture readiness rather than a single long dashboard. Runbook queue, detail, create, and edit are separate workspace states, with edit persistence for runbook metadata and required active inputs. The paired local bridge writes raw capture manifests to a local bytes/director/raw spool so teams can opt into automatic TopoloBytes sync and backup without losing the original take. Each runbook declares the inputs it needs from Mac screen, camera, phone mirror, OBS, and CTA overlay, and scenes must use only those active inputs rather than naming unavailable devices. The bridge can install polished Director | ... OBS scenes for available inputs, mirror camera self-view sources, clean the local Mac desktop non-destructively for screen recordings, and show or hide animated Topolo lower-third, CTA, and voice-cue overlays when those graphics are active for the runbook. Human notes and teleprompter prompts are written as off-record sidecar files and are not opened in the captured browser or added to OBS scenes. Human take controls are shown as dockable native floating macOS glass panels with a movable script strip, separately movable icon controls, capture hiding, adaptive color profiles, automatic review remux, and immediate playback.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

  • production: https://director.topolo.app
  • staging: https://director.stg.topolo.us

API Reference

Director exposes a curated authenticated API for workspace-scoped recording project creation and retrieval, project session creation, runbook management, session tracking, off-record session prompter retrieval, chunk/take cataloging, take selection/trash/flag/R2 sync state, composition manifest generation, recorded-session script passes, cue approval, voice-render request tracking, proof-gate review, bridge pairing, bridge heartbeat, and the TopoloOne widget. Workspace discovery itself comes from the platform-owned Auth catalog.

Auth and Permissions

Director resolves its concrete Topolo Auth app id at runtime from service slug topolo-director, with workspace read and write permissions in the Auth service catalog.

Data Ownership

Director owns demo runbook, required-input, off-record human cue, recording-session, recording-chunk, chunk-take, take-control state, media-catalog, composition-manifest, proof-gate, narration, voice-render request, bridge-readiness, and recording-event content for its workspace surface. The paired local bridge owns raw footage and off-record prompter/control sidecars until the workspace enables TopoloBytes backup. R2 sync requests are queued as take state until a TopoloBytes/R2 binding performs the transfer. Agent owns reusable person-profile writing/speaking metadata, Voice owns reusable voice-profile metadata, and generated voice audio stays with the downstream Nexus voice provider until an output path is attached for Director review. Topolo Auth owns user identity, organization context, service entitlement, and the company-admin boundary for using another human user's likeness.

Mobile Experience

The checked-in mobile experience contract is approved in native_capability mode. Its fallback route is /runbooks, its offline policy is read_through_cache, and it requires organization context.

Published permissions: workspace:read, workspace:write.

  • /overview uses /api/director/status with the record.detail template and director.status.detail data source.
  • /runbooks uses /api/director/runbooks with the record.list template and director.runbooks.list data source.
  • /runbooks/:runbookId uses /api/director/runbooks/:runbookId with the record.detail template and director.runbooks.detail data source.
  • /proof uses /api/director/status with the workflow.inbox template and director.proofGates.list data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Director deploys from apps/TopoloDirector to the production and staging Worker routes documented in /systems/topolo-director.

Failure Modes

  • missing Auth session
  • missing service entitlement
  • incorrect environment Auth proxy configuration
  • stale service catalog snapshot
  • expired bridge pairing or offline local bridge
  • blocked proof gates before export
  • source proof explicitly blocked for a source used by the runbook
  • runbook scenes that reference inputs not selected for that runbook
  • selected person profile is not owned by the subject user or available to an organization admin
  • narration cues not approved before voice render
  • voice render marked ready without output evidence
  • teleprompter or operator notes placed inside a captured display
  • floating take controls run without macOS screen-capture hiding enabled
  • composition blocked by a missing or blocked selected take

Debugging

Use /systems/topolo-director for deployment detail and the internal handbook for route-level debugging notes.

Use It

Open Topolo Director for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-director --json
topolo actions --service topolo-director --json
topolo actions capabilities --service topolo-director --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Topolo Director and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Verified the native_capability mobile experience contract and its 4 published route(s) against apps/TopoloDirector origin/staging d82379409330 on 2026-07-27.

  • Reconciled this page against apps/TopoloDirector origin/staging adabc3049ce3 on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Added Director workspace resource discovery, workspace-scoped recording projects, complete initial shot plans, and project session creation on 2026-07-14.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloDirector commits through 9b24a23; reviewed 321 commits since 2026-05-14, including 9b24a23 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 98349a3 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); d3d78af Adopt canonical Topolo typography; e986fbd Split Director startup bundle.

  • Updated the public Director overview on 2026-05-06 for short platform chrome naming plus favicon, app manifest, Apple touch icon, and PNG Open Graph assets.

  • Updated the public Director overview on 2026-05-13 for runtime Auth app identity resolution from slug topolo-director.

  • Added public application coverage on 2026-05-06 so Director is represented consistently in Docs, the systems registry, and the generated Auth catalog.

  • Updated the public Director overview on 2026-05-06 for the D1-backed production workflow and local bridge contract.

  • Updated the public Director overview on 2026-05-06 for raw Bytes archive handoff and record-first narration.

  • Updated the public Director overview on 2026-05-06 for recorded-session script passes and cue approval.

  • Updated the public Director overview on 2026-05-06 for persisted voice-render requests.

  • Updated the public Director overview on 2026-05-06 for optional camera and phone source readiness.

  • Updated the public Director overview on 2026-05-06 for runbook-owned active input declarations and clean scene naming.

  • Updated the public Director overview on 2026-05-06 for off-record human cues and teleprompter sidecars.

  • Updated the public Director overview on 2026-05-06 for bridge-controlled OBS scene, mirror, and CTA overlay controls.

  • Updated the public Director overview on 2026-05-06 for focused workspace sections.

  • Updated the public Director overview on 2026-05-06 for separate runbook queue, detail, create, and edit states.

  • Updated the public Director overview on 2026-05-06 for bridge-installed polished OBS scenes and operator overlays.

  • Updated the public Director overview on 2026-05-06 for local bridge desktop hygiene.

  • Updated the public Director overview on 2026-05-07 for chunked human recording, take cataloging, and composition manifests.

  • Updated the public Director overview on 2026-05-07 for off-record operator controls, take trash/flag metadata, and R2 sync queue state.

  • Updated the public Director overview on 2026-05-07 for native floating macOS take controls.

  • Updated the public Director overview on 2026-05-07 for compact glass-style macOS take controls.

  • Updated the public Director overview on 2026-05-07 for dockable macOS take controls with color profiles.

  • Updated the public Director overview on 2026-05-07 for split movable icon controls and automatic review playback.

  • Updated the public Director overview on 2026-05-07 for Agent/Auth likeness authorization rather than GDPR-style Consent.

  • Updated the public Director overview on 2026-05-07 for Agent person-profile consumption in script generation.

  • Reverified the public Director overview on 2026-05-12 for the opaque Auth app id and current app repository path.