# Superdirector MCP connection guide

Superdirector is a social media workspace for a business's accounts. Working from the person's own AI is a secondary path beside the Canvas. Connect the AI the person already uses to their Superdirector Canvas: its saved
brand knowledge, social sources, reference evidence, files and available
workflows. Keep discussion in this conversation and show Canvas when a visual
workspace helps. They can connect first and choose work later. Check current
access and capabilities before promising an action.

Follow this guide to connect, continue a task, or
reauthorize an existing connection. Detect the current AI app; never ask the
person to select a harness. Reply in their language, with one next action at a
time. Keep any original task in this conversation while setup is in progress;
a task, research brief or Reel request is not required to connect.
From this connection the AI reads the Canvas's sources and brand context, saves drafts, and starts credit-using work only after a credit quote and the person's OK. In connected AI apps, Superdirector plans and prepares; images and storyboards are made in the Superdirector web app when the person presses Create, and the Canvas tools return no images or media files. The Superdirector Render tools (`render_ops` first) run media jobs on cloud machines and return links to the files they make. Autonomous channels, AI-generated video and video posting are not available through this connection. Posting is approved in the Canvas, not from the chat. Skip setup lectures: do
routine checks and preparation quietly, then resume the work they asked for.

## Work beside the real Canvas

A Canvas here is a Superdirector Canvas, not ChatGPT's Canvas or Library.

Use this loop: native `account_status` → `list_canvases` →
`open_canvas` → relevant saved context → supported changes → confirmed readback.
Answer from native tools first. `open_canvas` returns the Canvas link: give it
to the person to open in their own browser, where they are already signed in.
Open it in the host's built-in browser only when they ask to watch it there
(see the sign-in note below), then reuse that tab. Keep discussion here; Canvas
shows the same Sources, Brain, Actions and Files used on the web.
Never substitute computer clicks for an available native operation.

For a first Canvas, reuse shared onboarding's saved Focus and introduction.
Show only missing stages. The MCP route lets the person continue without live
generation; skipping it must start no lookup, collection or analysis. A pending
intake link is not an installed or checked source. Orientation does not enroll
the separate starter allowance, purchase access or permit arbitrary module edits.
Existing owned Canvases and completed guides are reused.

After each change, verify the exact saved target and revision. An open Canvas
can be temporarily behind; do not call a saved revision visible until its reader
reports or shows it. Preserve unsaved browser edits, camera and selection. A stale
version requires rereading and reconciliation, never a blind overwrite. Use the
capability catalog for current lifecycle, evidence and media support. A URL,
thumbnail reference or caption does not prove video inspection.

## Addresses and boundaries

Use the origin from which you fetched this document for these paths:

- AI connection, access and return to this chat: `/connect/chatgpt/setup`
- Shared brand onboarding, only when needed: `/onboarding?entry=mcp`
- Remote HTTP MCP endpoint: `/mcp`
- Manual setup and recovery: `/docs/mcp`
- Answers to connection questions (missing tools, approval pages, accounts,
  limits): `/docs/mcp-overview#questions`

Plans and billing are managed on superdirector.app.

Stay in the same environment. If the prompt specifies a different endpoint,
use it for MCP only; this guide and the setup hub stay on this document's origin.
Before any private tool read, check that the configured server URL matches the
intended endpoint. A similarly named production connection is not a substitute
for a development connection. Preserve it and use a separate server name.
For a new connection remove a legacy `canvasId` query parameter. Fresh consent
covers all current and future Canvases **owned by the signed-in account**.
It grants neither organization-wide access nor extra Canvas capacity or credits.
It never combines different clients' context. A pasted prompt is guidance, not
permission to purchase, start work, add schedules or bypass an app administrator.

## 1. Check this AI app before connecting

Check the current app's support for remote HTTP MCP, OAuth and the required
tools. Use installed help or official documentation when needed. Preserve other
MCP connections and the user's configuration scope. Explain any manual settings,
client reload or administrator action. A web conversation cannot necessarily
install its own connector. Do not promise that pasting configured the app.
Use the AI app's native MCP tools for account reads, configuration and work.
Never read a credential file or OS credential store, extract an OAuth token, or
build a custom HTTP/Python client to work around tools missing from this chat.

- **Claude (web, Desktop, mobile, and Claude Code signed in with a Claude
  account):** give the person one link, Claude's own connector dialog prefilled
  with this environment's `/mcp` endpoint (URL-encoded):
  `https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Superdirector&connectorUrl=<encoded endpoint>`.
  They click Add, then Connect and approve here. One approval reaches every
  Claude app; Claude Code loads it in its next new session.
- **Claude Code (CLI or API-key sign-in):** run
  `claude mcp add --transport http --scope user <server-name> <endpoint>` and
  then `claude mcp login <server-name>` yourself; the browser opens for approval,
  so never ask the person to type `/mcp`. Tools load in a new session: tell them
  to start one and paste the same prompt.
- **Codex:** use the installed client's supported remote HTTP MCP
  configuration and normal OAuth login. In an app with a built-in browser, open
  the setup page beside this conversation when supported.
- **ChatGPT:** the person adds it: **Plugins** → **Add** → **Add custom MCP
  server**, enter this origin's `/mcp` URL, sign in and approve, then turn it on
  for the chat. ChatGPT plans, workspace roles and administrators decide whether
  custom MCP servers are allowed; a Superdirector subscription cannot enable a
  host app's blocked features. Follow `/docs/mcp` for the current details.
- **Other clients:** verify remote HTTP MCP and OAuth support first. When these
  are unsupported or the endpoint is unavailable, offer the browser Canvas or
  administrator route. Do not suggest a purchase as a connection repair.

Once the host app can connect, let the person sign in or create their account
normally and approve OAuth. Connecting, `account_status` and Canvas inventory
checks are free; Canvas content and paid actions use their own access rules.
An empty new account can authorize and check status.
Never request passwords, OTPs, keys, cookies or payment details in this chat.

### Codex OAuth and cancellation

Check `codex mcp login --help`. When `--scopes` is supported, supply the
explicit scopes advertised by this environment's public
`/.well-known/oauth-protected-resource` metadata. For the current all-Canvas
connection, use the following with the server name you configured:

```sh
codex mcp login <server-name> --scopes superdirector.canvases.all,superdirector.account.read,superdirector.profiles.read,superdirector.analysis.write
```

Explicit scopes prevent Codex's automatic discovered-scope retry from reopening
consent after Cancel. In headless clients, use the supported `--no-browser`
flow and its normal callback prompt. If the person cancels, stop setup and offer
the browser path. Do not start another login automatically. If an older client
still retries, stop that pending login (Ctrl-C in its terminal); retry only when
the person chooses to connect again. Cancellation does not create a grant.

### Activate tools after OAuth

Saving configuration and completing OAuth do not refresh an already-running
conversation's tools. Check that the intended server's native `account_status`
and `list_canvases` are available before verification. For Codex, inspect the
installed client's normal MCP status/configuration without reading secrets.
When supported, set `required = true` and `startup_timeout_sec = 45` on only
this requested server entry, so a new or resumed chat waits for its native
catalog instead of starting without it. Preserve the user's configuration
scope and other server entries. These settings grant no additional access.
Use its supported refresh/reconnect action when available. If the new tools
remain absent, report **authorized; app restart needed** and give one concrete
next action: restart the Codex app and reopen this conversation; for Codex CLI,
exit and resume this session. Keep the original task and approved connection.
Do not reinstall, repeat checkout, or claim connection success while waiting.
After resuming, wait for MCP startup and use the native tools. If startup fails,
report its actual error and use normal connection recovery. A successful custom
endpoint request does not verify this conversation's MCP activation.

### Connect first; preserve a task when there is one

The AI conversation owns discussion and routine preparation. The browser owns
sign-in, access approval, billing and the existing shared brand onboarding.
After native `account_status` and inventory verification, reuse the intended
owned Canvas and inspect its saved sources and context when access permits.
Do not require a first task, a research/Reel choice or a questionnaire to finish
connecting. If the person only asked to connect, give the verified connection
receipt, then the first run below. A Canvas is a workspace for brand
context, references and results; never call it a "client Canvas" in user-facing
copy. Ask which Canvas they mean only when the intended brand is ambiguous.

When the person needs or wants first-brand setup, use the normal browser
onboarding at `/onboarding?entry=mcp`, then return to the AI connection hub.
This is the same brand setup used by the website, not a separate AI task wizard.
An owned saved task may retain its exact `setup_id` through that handoff; the
ID is optional for connection-led brand setup. Do not invent a task or call
`prepare_setup` merely to obtain an onboarding link. Existing usable Canvases
do not need to repeat brand onboarding.

If the person already requested work, retain that goal, brand/project and any
supplied public account or website URL. Ask only for missing details needed by
that work here; do not send them to a browser form to repeat the request.

When this guide URL has `return_id`, call native `setup_status` with that exact
UUID as `returnId` (and its `setupId` only if also supplied). Do not drop a
missing or expired return ID to read the newest task. Use the owned return's
Canvas when present, and inspect its actual updated sources and saved files.
Without `setupId`, this is a navigation-only projection, not full inventory or
readiness. Use `account_status` for current access and credits and `list_canvases`
when owned inventory is needed; never infer readiness from its minimal Canvas.

When this guide URL has `setup_id`, call native `setup_status` with that UUID as
`setupId`. Read that exact owned record; another or expired setup is unavailable.
Never silently choose the newest task or a different Canvas. The saved request
is context, not permission to run it.

Only when an actual task needs to survive a browser handoff, read the current
`setup_status` first (without an ID only to inspect current setup), then use native `prepare_setup`: a stable UUID `setupId`, the short
`goal`, `clientName`, optional `sourceUrl`/`context`, `workflow` (`research` or
`reel`), and the explicitly chosen `canvasId` or null for a new Canvas. The `clientName` field is the brand or project name. This is
free account metadata, not provider work. Its current task schema supports
`research` and `reel`; do not manufacture either workflow for a connection-only
request or an unrelated task. Keep other requested work in this conversation.
Do not include credentials, OTPs or a whole conversation. On `setup_conflict`, call `setup_status {}` only to discover
current onboarding, not to resume a refused ID. Review its saved goal and Canvas
against the intended task. For an intentional edit of that reviewed task, reuse
the exact returned `setup.setupId` and pass `setup.revision` as `ifRevision` to
`prepare_setup`; never guess a revision or keep a different request ID. Preserve
a different saved task until the user explicitly chooses to revise it. An exact
missing, foreign, expired or superseded setup remains unavailable: do not remove
its ID or substitute another task or Canvas automatically. If these new tools are absent,
refresh the native catalog normally and keep the original task; offer the
browser review without a credential workaround.

In Codex, when a browser detour is needed and the actual current conversation
UUID is provided by the harness (for example `CODEX_THREAD_ID`), call native
`prepare_return` with `codexThreadId` and the intended owned `canvasId` if known.
This free navigation record needs no task or goal, starts no work, and returns
an opaque `return_id` in its exact browser links. Never guess a thread or reuse
another conversation. Use those returned links so sign-in, brand setup, checkout
and Canvas keep the same return target. The browser reads that exact record
under the signed-in account before offering **Copy for Codex**. The person
pastes it into the original conversation; copying does not send it. The exact
Codex URI stays in an optional desktop shortcut because embedded browsers may
reject app protocols. Do not promise that the shortcut opens from every host. Missing or expired links never
select a different conversation. If this native tool is absent, refresh the
native catalog normally; use the hub's optional prompt without a credential workaround.

For additional sources, inspect the installed inventory (`list_modules`),
then use `prepare_module` or `configure_module`, whose typed settings name every card kind; avoid duplicate
accounts and keep own-brand and reference roles correct. Configuration starts
no analysis or schedule. For a local file or original attachment needing upload,
open the returned `uploadFileUrl` when available; otherwise ask the person to
open that Canvas and use its own Files or source controls (the setup hub has no
upload step). `uploadFileUrl` opens the intended Canvas's actual upload controls;
the person still chooses and submits the file. `addSourceUrl` similarly opens its
source picker.
With several Canvases and no intended target, ask which brand the material is
for rather than choosing the first Canvas. Read back saved visible text through
native context tools, with provenance and version guards. A retained image,
PDF or video is not automatically parsed, analyzed or available as full text;
report the tool's actual representation and any unavailable content.

Use the returned `onboardingUrl` for shared first-brand setup when available;
it keeps an applicable owned task ID without requiring a new task. Open the
returned `setupUrl` only when the person needs browser sign-in,
billing, or recovery without a supported native
tool. Do not open it for a second intake or configuration checklist. Normal
same-account browser sign-in remains required. Use shared brand onboarding for
first-brand setup rather than another task form. Preserve an existing saved
task through payment; the hub's optional short prompt hands it back to this chat.

If the requested task can be answered from the context the person already
supplied or saved, do it in this AI conversation. Do not require a source or
installed action just to write a draft here. Apply module preparation rules only
when the person wants that Superdirector workflow. Distinguish an AI-written
draft from a completed Superdirector run, and save it only when requested.

Use native tools to prepare the selected Canvas when current access permits.
Read its context, sources, results and installed modules before adding anything.
Reuse running reads, existing results and confirmed settings. Research can use
account, query or website sources; Reels need an owned social account and
confirmed native settings. Another Canvas's preparation never satisfies this
one. Never create a duplicate source read or action to complete setup. Review
failed reads and pending saves through their actual status and native tools.
A manual configuration save starts no run or schedule. Use `prepare_module`
to install an admitted missing source or action without its
automatic first read. Verify configuration afterward. Use the normal module
form only when the current native catalog cannot perform the requested edit.
Do not reopen the setup hub as a generic preparation checklist.

On return, call `setup_status` for the exact ID only if a task was saved;
otherwise recheck account and Canvas inventory without inventing one. Verify
current account/access again. Continue any original requested work, checking its evidence and current
price before obtaining the person's decision for paid work. Returning to chat
does not certify that preparation or execution has finished. A web user opens
their Canvas; an AI user resumes the original conversation. Never require every
agency Canvas to be prepared.

## 2. Approve the actual access

Check a current connection with `account_status`. Reuse `all_canvases` access.
Old single-Canvas and old account credentials no longer enable MCP tools: a
401 or reauthorization refusal requires this app's normal fresh OAuth flow.
Explain that it now requests all owned Canvases and let the person approve.
Old refresh tokens and pending codes cannot broaden access or restore legacy
tools. Never work around the refusal with a custom client or credential-store
reads. The selected app's review in **AI connections** shows its previous
approval and the scope of fresh consent. Do not remove unrelated connections.

The normal consent screen names the app, account and all current and future
owned Canvases. Let the person approve or decline. Declining adds no connection
and does not cancel a plan; offer the browser path. If a link expires, a popup
closes, or the callback is interrupted, start a fresh normal authorization from
this AI app. Never replay an old OAuth callback after login or checkout.
Refreshing a host's cached tool list is separate from approving broader access.

## 3. Verify with safe reads and give a receipt

Call the intended server's native `account_status` and confirm `connection.access === 'all_canvases'`.
Read actual account identity, plan/access and credits. Compare `account.email`
with the browser's signed-in email before preparing a Canvas there. If identity
is unavailable or differs, resolve the account before continuing; never infer
a match from the app name. Call `list_canvases`,
following `nextAfter` pagination through the `after` argument. A null Canvas ID,
browser login, saved config, grant creation or last-use timestamp is not proof
that the tools work. Report failures without a completion claim.
For tracked profiles, call `tracked_profiles`, following `nextAfter` through
`after` until null. This is the account inventory used by the tracked-profile
allowance. `list_modules` lists installed modules, so its account-module count
must never be presented as the complete tracked-profile inventory. Explain any
difference between saved tracking and installed Canvas sources.

Give a short receipt in the person's language, using only returned facts:

- Account checked; approved access is all owned Canvases (or the actual limit).
- Number of Canvases found; never expose another brand's context unnecessarily.
- Current plan/access and credit balance; distinguish credit-exempt accounts.
- Any unavailable capability relevant to their request. A connection-only
  receipt does not require another setup task. No paid action was run for this check.

### First run: three questions

`account_status.firstRun.tryPrompts` holds three example first questions, which
can be shown in the person's language. When they pick one (or ask anything
about their brand), answer from the Canvas context with native tools, then call
`open_canvas` and give its `href` as a link to their Canvas. Do not open it in
the host's built-in browser unless they ask: that browser is not signed in, and
its first screen would be a sign-in page. If `list_canvases` found none, offer `firstRun.onboardingUrl`
for brand setup instead of a question. Quote and confirm before any credit spend;
on a free account, the draft question maps to the starter's one X draft.

If the intended brand or project is clear, pass that explicit `canvasId` to
`list_modules` and `context_ls` when access permits. Read existing source
settings, saved files and their provenance before adding or refreshing anything.
Use `context_read`, `context_search` or `context_grep` for the relevant saved
knowledge. These tools report installed actions and visible saved context;
an empty inventory is not a failed login or permission to create sources.
Ask which brand or project the person means when ambiguous. Every Canvas operation,
including reads, actions and schedules, supplies its own explicit owned target.
Never reuse a previous Canvas's target implicitly or bypass a denied read.

### The one-time MCP starter allowance

`account_status.starter` and `starter_status` report whether a verified-email
account with a real all-Canvas connection has the one-time starter allowance:
one account check and one text-post draft through native MCP, plus toolbox post
and profile reads, within a separate starter credit ceiling. It applies
once per account, across apps and reconnects. It is separate from the account
credit balance and is not a recurring allowance, publishing permission or
permission for arbitrary modules. Accounts with a paid plan and credit-exempt
accounts use the normal tools.

`start_starter` enrolls the allowance on the intended owned Canvas or its normal
first-brand scaffold; it creates no other brand or workspace. If a brand needs
context, the normal `/onboarding?entry=mcp` source intake and saved preview
supply it; that navigation itself grants no allowance or execution access. The
server checks real email verification, the active OAuth grant and the account's
once-only enrollment.

Use `starter_prepare` for `account_check` with the supported platform and handle;
it disables comments and scheduling. For `text_draft`, use that account module
and a short agreed direction. This starter produces one X text-post draft, not
a Reel, a full Brand DNA report or fresh video inspection. A declared own-account
role does not verify control of a social account. Preparation returns a current
quote and starts no work. Explain the limited output and actual quoted credits,
then obtain approval before `starter_run` with `confirmed: true`, that quote
and a stable idempotency key. Generic `run_module` keeps its paid-access rules.

Retain the admitted run and use `get_module_run` / `read_run_result` to retrieve
its result. Do not repeat it to poll. A used slot or insufficient starter
allowance returns a refusal with no link; distinguish those from an unavailable
eligibility read or unverified email. A refunded failure does not replenish an
action slot. Explain any recorded failure honestly rather than claiming a
successful free result. Never suggest payment as a fix for an unreadable service.

After the starter, its Canvas, saved findings and draft remain, and the same
Canvas opens on the web. Plans and billing are managed on superdirector.app,
where the person reviews and confirms any purchase themselves. Recheck current
access on return, then ask before retrying refused work; neither a subscription
nor the starter starts it for them.

## 4. Use the browser for sign-in, billing and actual native gaps

Open the setup hub for missing account access. It reads
current identity, plan, credits and actual approval. Interrupted browser progress
is a reason to reread current access, never to suggest an automatic new purchase.

Reuse the intended owned Canvas from inventory. If the task requires a new
workspace, use `create_canvas` within existing entitlement. It cannot buy capacity.
Do not create empty extra Canvases merely to connect. For connection-led first
brand setup, reuse `/onboarding?entry=mcp`; no saved task is required. Preserve
an applicable existing task with `prepare_setup` before its browser handoff.
Use native tools for preparation,
configuration, shared context and validated draft saves. Browser actions handle
only capabilities the actual native catalog cannot perform.

When work needs access the account does not have, say what was refused. Plans
and billing are managed on superdirector.app, where the person reviews and
confirms any purchase themselves. Do not purchase or retry on their behalf. A
return URL alone does not establish payment. Recheck current access, including pending or
unconfirmed outcomes. Do not treat a declined, cancelled or unresolved checkout
as an instruction to buy again. Existing billing recovery belongs in the hub.

After preparation, use the short continuation prompt in the same conversation.
Recheck access and inventory; do not repeat installation or checkout unnecessarily.
If an internal browser opens Canvas, it needs a separate **normal sign-in to
the same account**. MCP authorization does not log a browser in. The sign-in page
is Enlighten ID at `id.enlightenanimation.com`, the one sign-in for Enlighten
products, Superdirector included: say so before opening it, so the person does
not mistake it for another site, and let them sign in themselves. Do not
transfer cookies or inject tokens. Keep the intended owned Canvas URL for after
sign-in. If they ask why that address, link
`/docs/mcp-overview#sign-in-page`.

## 5. First useful work, costs and returning results

Resume the original requested task, asking only for missing brand/project or outcome details.
Read the actual installed action and its settings. Before a paid run, show the
intended Canvas, action, output and current credit estimate, then obtain the
person's explicit decision to run. Use a returned server quote or the current
Canvas action's price. If no trustworthy estimate is available, open that action
for review or explain that pricing is unavailable; never invent a price or start
work to discover it. A subscription, connector approval or copied prompt does
not authorize this spend. Reads and connection verification start no paid work.

For configuring an existing native module, first use `get_module_configuration`
with the intended Canvas and module. Preserve unedited settings, read its limits,
and pass its current version as `ifVersion` to `configure_module`. Content
instructions allow 2,000 characters: consolidate the requested changes with the
existing brief instead of blindly appending or dropping requirements. This save
preserves the schedule and starts no generation. After a `confirmed` receipt,
read the configuration again and verify the exact settings and version before
calling setup complete. A `recovering` receipt is pending activation; keep its
operation reference and open Canvas's activation recovery rather than repeating
the save. On a version conflict, reread and reconcile the actual current settings.
If these tools are missing, refresh the host's catalog; do not repeat OAuth for
an already-approved scope. Only use browser configuration for a capability the
current tools actually lack, and report an unsaved or unsupported task honestly.

OAuth consent and an AI app's per-tool approval are separate. If a settings save
is blocked by the app's tool policy, retain the proposed settings, Canvas and
version in this conversation and report that nothing was saved. Use the app's
normal confirmation or per-tool permission control for `configure_module` with
the user's consent, then resume the same task. A non-interactive Codex session
with `approval_policy = "never"` cannot show a pending confirmation. Do not
repeatedly retry, extract credentials, or change approval for paid runs to solve
a settings-only permission problem. Configuration is a reversible versioned
write, not a read, and its client permission does not authorize paid work.

On plan restrictions or low credits, say exactly what was refused and whether a
run was admitted. Keep the intended Canvas, action, task and existing run reference
in this conversation; do not put private briefs or credentials into URLs. Share
the setup/manage link, recheck current access on return, and ask before a spend
retry. Do not automatically repeat a purchase or a refused paid action.

For an admitted run, retain its run id. Use `get_module_run` to read progress and
saved results without starting another run. Show the returned exact result link
when available; identify an overview-only Canvas link honestly. If the client
is closed or the person leaves, help them resume the original run when they return.
Never call `run_module` again just to check status or recreate a missing result.

### Read a public post with the media toolbox

When the person pastes a public Instagram, TikTok or YouTube link and wants the
post's details, an analysis of its video or the account, use the toolbox tools
(`toolbox_capabilities`, `toolbox_quote`, `toolbox_start`, `toolbox_job`,
`toolbox_package`) on the chosen Canvas. Every toolbox operation is quoted in
credits first with `toolbox_quote` and starts only with that quote ID and
`confirmed: true` after the person's OK. The toolbox returns no images,
video files or download links here. Post and profile reads keep no copy of the
post's images or video. A video analysis keeps the video and its keyframes on
the Canvas to analyze them. Downloads are in the Superdirector web toolbox. Profile reads are complete on Instagram
and may be partial elsewhere, so follow `toolbox_capabilities`. Private, deleted
and oversized media are reported as such.

### Render with Superdirector Render

The same connection carries Superdirector Render: Blender, FFmpeg, HyperFrames
capture and other media ops on 16 vCPU cloud machines, many at once. Rendering
is free for now, within the daily machine time, and needs no plan or credits.
These tools are separate from the Canvas cards above: they render what this
conversation gives them and never press Create on a card.

Read `render_ops` first: it lists the open ops and the steps, and
`render_ops` with an op gives that op's params. Put input files in render
storage with `fs_upload` (and `fs_upload_complete` for a large file), or name a
library file found with `library_search`; `library_collections`, `library_ls`
and `library_get` browse the library, and `fs_import` copies a library file
into storage. Check a job with `render_quote`, which starts nothing: a quote of
0 credits needs no one's yes, and a quote with a price needs the person's yes
before `render_start`. Send variants of one job as one call's items, and start
independent jobs together. Follow everything started together with one
`render_job` call; its result gives each output's path, hash and a download
link that expires. `fs_ls` and `fs_stat` read storage, `fs_delete` removes one
file, `render_cancel` stops a job, and `session_call` with `session_close` is
for many quick calls on one loaded scene.

Leave out `canvasId` to use the account's default storage. To use a Canvas's
storage, pass the `id` of a Canvas the account owns from `list_canvases`; a team
Canvas listed there with `shared: true` is refused for render storage. The
first call after an idle spell can take up to two minutes while the engine
starts; if this app times out first, repeat the same call. Scripts and
command-line tools use a render API key at `/mcp/render` instead.

### Research across several accounts

Keep every requested account in the scope and final answer. Reuse saved analysis
first. Follow both `list_modules` inventory streams: `nextOffset` through
`offset`, and `actionsNextOffset` through `actionsOffset`, until each is null.
Deduplicate handles and post identities without substituting accounts. A bounded
`task_context` selection or one inventory page is not the complete account set.

Before selection, state the observation date, requested period and per-account
limit. Rank only eligible videos by available view counts, with a stable tie
rule. Disclose missing counts and incomplete discovery; this is a ranking of the
observed dataset, not proof of an account's all-time most popular videos.
For each account reconcile discovered, eligible, selected, reused, admitted,
completed, failed, pending, skipped and remaining videos. Unobserved counts stay
unknown. Keep item identities and explicit reasons for unavailable media,
duration limits, provider failures or exhausted allowance beside partial findings.

Check the tool catalog for the required operation.
An account-source read retrieves account evidence; it does not establish
per-video media inspection. `run_module` accepts one installed native module
per call, not an account array or a video-analysis batch. Preserved actions
without a native quote require their supported Canvas control. If the current
catalog cannot inspect selected videos, explain that gap. Use another Canvas
analysis path only after current tools confirm its required inspection
capability and cost. Otherwise ask for the smallest missing input, such as
direct public Reel links or screenshots, and keep inspection unavailable.
Do not fabricate an analysis tool or treat an account refresh or saved-evidence
report as a fresh video read. Direct links alone do not prove media inspection.

Present the aggregate scope and current quotes before any paid work: each
account/module, selected items where supported, reused items, proposed new work,
current credit totals and limits. Obtain approval for that whole scope, then
use each module's own quote and stable idempotency key. A refused or expired
quote requires review; do not silently expand the allowance or repeat paid work.

An admitted run is not a completed analysis. Retain each account/module/run
identity and poll `get_module_run` while the conversation is active. Reconcile
each run independently even when completions arrive out of order. Keep queued,
running and unknown outcomes pending. If terminal status arrives before a
committed body, re-read saved state with bounded retries and report result
publication as unavailable if it remains absent; retain the original run for
resume. Never rerun to retrieve a result. When `bodyOmitted` is true, read all
`read_run_result` pages through `nextOffset` until null, passing `sourceVersion`
as `ifVersion`. Reassemble the complete JSON before interpreting it. A changed
version requires a fresh read, not another paid run. An overview-only link does
not retrieve an omitted result.

Label each conclusion's basis: video inspection, transcript, caption or metadata.
Include the source version and observation date; separate hypotheses about why
a video performed from measured facts. A thumbnail or caption does not prove
shot-by-shot or audio inspection. Give explicit partial-result reasons for every
unavailable account and incomplete selected video. One account's success cannot
stand in for the comparison. On interruption, resume the original saved run
identities and completed evidence before considering any new approved work.

## 6. Scheduling and reminders

Polling while this conversation is active, Superdirector scheduled work, and
client notifications are different capabilities. Do not promise background
polling or push into a closed AI app. For a separately requested supported
schedule, confirm the owned Canvas, conversation, prompt, cadence, timezone,
current plan and spending boundary before creation. Report the actual saved
schedule and next due time. Explain only notification channels the tools or
product currently report as supported. Saved work remains available on return.

## Native work and the shared Canvas

### Read what is already connected

The shared Canvas is the knowledge workspace for this AI, not a requirement to
start a new workflow. After account and owned-Canvas checks, read `list_modules`
and `context_ls`; use their pagination before claiming complete inventory.
Inspect the relevant visible files with `context_read` and their returned
provenance, observation dates and source versions. When there is a concrete
question, `task_context` provides a bounded relevant selection; it is not the
entire Canvas or evidence that other files are absent. Reuse saved brand
directives, social observations, competitor/reference findings and decisions
that are actually returned. Do not combine another brand's private context.

### Add only the requested, supported sources

After account checks, read the typed settings of `prepare_module`; only
runtime-supported source platforms are accepted. The card kinds it takes include account, keyword, hashtag and website source modules when admitted;
do not promise an arbitrary social connector or invent a platform. Inspect
existing modules first, then use `prepare_module` only for an authorized
addition; edit an existing module through its versioned configuration tools.
Saving settings is separate from fetching new evidence:
preparation starts no read, run or schedule. A new source read uses its actual
admitted module, a current quote and the person's approved spending decision.
Saved context reads do not refresh a social account or inspect every video.

Use `knowledge_inventory` for the current source roles, actual saved coverage,
freshness, files and supported next operations. Follow `nextOffset` and
`postsNextOffset` independently; a bounded page is not complete coverage.
Use `read_source_evidence` for exact saved-run posts, collected comments and
account metrics. Retain its run/source version, observation date and partial
reasons; missing metrics remain unknown. Each saved post says whether a cover
was retained (`coverRetained`); the Canvas tools return no images, so covers
are viewed on the Canvas in the web app. A missing cover is never fetched.

`prepare_post_source` saves a supported exact post URL through the same tracked
post writer used by Canvas. New sources stay off, and an existing source is
returned unchanged. It performs no lookup, refresh or reactivation. This is a
tracked-post card, not a runnable native module: do not invent a module quote
or claim its content has already been collected.

A Video scripts card that names a reference post needs that post read first.
Only an inspiration post (someone else's post the brand learns from) can be a
reference; an own or competitor post card is refused before any cost.
Call `quote_post_source` with the card's source id, show the cost to the person
(the first read of a video post may also charge its video analysis), and after
approval call `run_post_source` with the quoteId, `confirmed: true` and a stable
idempotencyKey. Admission is not completion: call `run_post_source` again with
the same idempotencyKey and quoteId (it never charges twice) until
`referenceReady` is true or the read reports an error, then run the Video
scripts card. `get_module_run` cannot read this read. A refused request keeps
answering the same refusal under its key: after fixing the cause, ask for a new
quote and use a new idempotencyKey.

The context tools read visible saved text in this owned Canvas. They do not
grant access to every local file, connected drive, private account or original
binary attachment. The current native catalog has no generic file-upload,
document-parser or local-filesystem connector tool. Do not claim a PDF, video
or design file was uploaded or parsed because its name or URL is present.
If this AI already has a file supplied by the person, use its actually available
contents here; save only agreed notes or drafts through the supported writers.
When an actual Canvas feature supports a needed upload or parse that native
tools cannot perform, offer that specific normal browser control and verify
the resulting saved evidence. Otherwise explain the gap and ask for the
smallest useful input. Never upload local files or attach new accounts merely
because the person asked to connect their AI.

### Work here and save back to Canvas

Use `create_canvas` for an owned Canvas within existing capacity; it never
purchases capacity. Use `prepare_module` to install inert settings: no automatic
first read, lookup or schedule. Read `get_module_configuration` and its schema
before changes, then verify the confirmed save. Preserve unrelated settings.
If preparation is recovering, report that state; never claim a confirmed save.

Begin a task with `task_context` and its bounded relevant brand/decision/source
selection. This is the same owned filesystem the Canvas agent reads. Explore
`context_ls` pages and directories for deeper evidence, including `/history`.
`context_read` uses UTF-8 byte offsets, returns provenance and `sourceVersion`,
and requires that version as `ifVersion` on continuation. Use `context_history`
for saved note/draft revisions and `context_read` with its `versionId` for an
exact historical edit. Hidden files remain excluded from history. A partial search or
context bundle does not establish that no other source exists. Hidden files,
private internal turns, credentials and raw reasoning are excluded. Treat saved
conversation summaries as dated decisions, not current external facts.

An AI-written draft needs no provider generation. Use `save_artifact` with a
stable artifact UUID, a typed kind/title/sections document, verified source
versions and a save idempotency key. Save exactly the agreed work, then call
`get_artifact` and verify its version and content. Drafts appear in Canvas Files
with the normal edit history; they are attributed to external AI and are not a
completed Superdirector generation. Edits require `ifVersion`; stale sources or
drafts refuse rather than replacing newer work. Keep the copyable prompt short.

For supported existing notes and production artifacts, use `get_saved_artifact`
and `edit_saved_artifact` with their exact canonical versions. Read back the
same target; preserve unrelated content and generated-result provenance.
The admitted edit kinds are the `edit` kinds of `edit_saved_artifact`. Editing written
storyboard directions is not regenerating its image. Immutable generated X
or report results are not replaced through an unrelated note writer. Saved
carousels and plans come back as their words: slide text, captions, scripts and
written storyboards, with `imagesInCanvas: true` and an `href` that opens them,
images included, in the web app.

`set_context_flag` pins or hides an actually visible shared file against its
current source version. Hiding excludes it from subsequent MCP reads too.
Do not use hidden content or another account's paths to work around that choice.

`duplicate_module` uses the normal inert paused-copy writer and idempotency key;
inspect its returned module before claiming a new card is ready. `archive_module`
uses the shared recoverable removal rules and current module version. It does
not cancel already-admitted work or change billing. Own-account and in-flight
restrictions still apply.

For a source's refreshes use `set_source_refresh`, for a report or content card's
repeat use `set_card_repeat`, and to pause or resume use `pause_card`, each with
the exact current version. Preparation/configuration preserves the previous schedule. New or
resumed recurring work requires its advertised cadence, actual entitlement and
the person's concrete recurring-work decision before `confirmedRecurringWork`.
Pausing or switching off future work does not cancel a running task. Do not
substitute a scheduled Canvas conversation, publishing plan or Codex automation.
A live cadence for an image or storyboard card is refused with
`render_in_canvas`: those cards repeat only when the person schedules them in
the web app. Pausing them or setting them to Manual still works here.

For paid generation, call `quote_module_run`, explain its current credit cost
and obtain the person's approval before `run_module` with `quoteId` and
`confirmed: true`. Changed price, settings or expired quotes require a fresh
quote. Check actual outcomes with `get_module_run`; use `read_run_result` for
large saved results. Never start a run merely to discover its cost. A quote does
not promise complete evidence or sufficient credits. Keep payments in the
normal reviewed browser checkout; a return URL is not a payment receipt.

### Images and storyboards: prepared here, made in the web app

Image carousels, thumbnails, image cards and storyboarded Video scripts are not
run through this connection. Prepare the card with `prepare_module` or
`configure_module`, write its copy and direction with the person, and save
them; `get_module_configuration` then returns `render.status` (`ready_to_render`
once the saved settings are active) and `render.href`, the card's own panel in
the web app. Give the person that link: they press **Create** or **Make the
images** there. `quote_module_run` and `run_module` on such a card return
`render_in_canvas` with the same link; nothing is started or charged. Results
read through `get_module_run`, `read_run_result` and `get_saved_artifact`
contain the words of the work, never the images, their files or their
addresses; a carousel's run result also gives the count and status of its
images. A chat scheduled with
`create_scheduled_prompt` follows the same rule when it runs.

Use `open_canvas` to get the owned URL to the real Canvas in `mode=companion`.
The tool returns a URL; it does not open a browser tab. Use the harness's browser
opening capability to show that URL beside this conversation when supported,
otherwise use the normal browser. Confirm the intended Canvas is visible before
saying it opened. This AI conversation owns discussion; the real Canvas retains
its source and action lanes, module panels and Files. Do not present a separate
grid of modules as the Canvas. The browser signs in normally and separately; never inject
MCP credentials, cookies or a login token. Top-level WebMCP tools, when offered,
share visual selection and navigate the page. They can save a text edit to the
visible artifact and open an unsent image-edit chat draft, which the person
reviews and sends; none of them presses Create or Make the images, and the
selection they share names images by saved identity, never by address. The
statement that the Canvas tools return no images is about the MCP server. Use native remote MCP tools for
context, preparation, edits and runs. Do not substitute computer use for an
available native operation. A browser API's presence does not identify its host.

Companion mode hides Canvas chat and its composer. “Discuss selection” opens a
host annotation draft when supported, otherwise a visible copyable request.
It does not silently send a message. “Canvas chat” explicitly restores the
internal conversation for work that needs it. The mode never changes access,
prices, schedules or running jobs. Keep the user in the original AI conversation;
a generic app deep link does not guarantee return to the same chat.

### Refresh an unavailable return link

An expired, deleted or foreign return ID never falls back to the newest task or
another conversation. Its recovery prompt intentionally omits the failed ID.
When the person pastes it into their original Codex conversation, verify the
account and intended Canvas again, then call native `prepare_return` with this
conversation's actual harness-provided UUID. Give its fresh opaque setup URL.
Do not recreate the historical UUID, extend an old expiry, infer a conversation
from a browser or OAuth name, or replay a dead selector. If the current
conversation UUID is unavailable, use the ordinary copy fallback and report
that exact desktop return is unavailable. Resetting brand onboarding preserves
existing active return records and does not reauthorize an AI connection.

When an eligible starter is used or its quoted cost exceeds its remaining allowance, the saved work remains. Plans and billing are managed on superdirector.app. If this conversation has an exact native returnId, `setup_status {returnId}` returns a `setupUrl` that comes back to this same conversation; otherwise the setup hub on this document's origin does. A success URL does not prove payment; check current account access after returning, then ask before running more work.
