# IMOGENE

IMOGENE is an authenticated control plane for authored, persistent Imogenes.
It exposes bounded agent-facing discovery, draft, planning, work-order, review, and work-order-bound controlled mutation surfaces under user authority.
An Imogene is not a fresh agent instance, system-prompt wrapper, AGENTS.md file, or loose prompt template. Agents operate the canonical object under delegated authority; they do not invent or assume the identity.
imogene.cc is the control plane. The Player manifest reports current pairing status and never creates a second source of canonical authority or approval bypass.
Morgan is the formal Castor engine for identity runtime contracts. Sarah is the formal Pneuma engine for continuity, memory, relationship state, and identity coherence.
Users bring their own identity, campaign, account, audience, and media data. Public discovery contains no customer records, non-user example records, or internal plans.

## Start Here

- Agent manifest: https://imogene.cc/.well-known/imogene-agent-manifest.json
- API manifest alias: https://imogene.cc/api/agents/manifest
- OpenAPI: https://imogene.cc/api/agents/openapi.json
- Agent tools: https://imogene.cc/api/agents/tools
- ChatGPT Apps MCP endpoint: https://imogene.cc/mcp
- OAuth protected resource metadata: https://imogene.cc/.well-known/oauth-protected-resource
- OAuth authorization server metadata: https://imogene.cc/.well-known/oauth-authorization-server
- Agent web entrypoint: https://imogene.cc/agents
- Agent workflow JSON: https://imogene.cc/api/agents/workflow
- Player manifest: https://imogene.cc/api/player/manifest

## Public Discovery

- GET /.well-known/imogene-agent-manifest.json
- GET /api/agents/manifest
- GET /api/agents/openapi.json
- GET /api/agents/tools
- GET /api/agents/workflow
- GET /api/player/manifest
- GET /.well-known/oauth-protected-resource
- GET /.well-known/oauth-protected-resource/mcp
- GET /.well-known/oauth-authorization-server
- GET /.well-known/openid-configuration
- GET /oauth/jwks.json
- POST /mcp
- GET /llms.txt
- GET /agents

## ChatGPT Apps MCP Draft Connector

The public MCP connector is draft-only. It uses IMOGENE-owned OAuth scopes for IMOGENE data access and does not broker OpenAI account or API tokens.
OAuth endpoints: `POST /oauth/register`, `GET /oauth/authorize`, `POST /oauth/token`, `GET /oauth/jwks.json`.
Allowed MCP tools: `imogene.contract.get`, `imogene.workspace.inspect`, `imogene.creation_intent.schema`, `imogene.create_draft`, `imogene.draft.get`, `imogene.media.recipe`, `imogene.draft.media.attach`, `imogene.approval.request`, `imogene.approval.status`.
An outside agent should inspect authorized draft state first, create only private draft Imogenes from user-supplied intent, and request operator approval for canonical, public, sensitive, commercial, media-backed, export, or identity-basis changes.
This connector is separate from the broader authenticated IMOGENE APIs; it does not expose job workflows, browser control, social-account operations, canonical mutation, publication, or approval resolution.

## External Agent Draft Creation Contract v0

- Public MCP discovery: `initialize`, `tools/list`.
- OAuth-protected MCP operation: private draft creation, recipe-gated draft media attach, and operator approval request/status only.

## Authenticated APIs

- GET /api/morgan
- GET /api/morgan/profile-state?profileId={profileId}
- GET /api/agents/identity-lifecycle?profileId={profileId}
- GET /api/agents/control-plane/capabilities
- GET /api/agents/control-plane/state?profileId={profileId}
- GET /api/agents/context-packet?profileId={profileId}
- GET /api/agents/personhood/context?profileId={profileId}
- POST /api/agents/tools/run (route-safe result/error only; no raw runtime proof or provenance ids)
- POST /api/agents/autonomy-loop
- GET /api/agents/work-orders
- POST /api/agents/work-orders
- POST /api/agents/work-orders/{workOrderId}/materialize
Work-order routes prefer opaque work-order handles returned by work-order responses; first-party legacy identifiers remain accepted for compatibility.
- GET /api/agents/jobs
- POST /api/agents/jobs
- GET /api/agents/jobs/{jobId}
- POST /api/agents/jobs/{jobId}
- POST /api/agents/jobs/{jobId}/advance
Job routes prefer opaque job handles returned by job responses; first-party legacy identifiers remain accepted for compatibility.
- GET /api/agents/runs/{runId}
- GET /api/agents/runs/{runId}/replay
- POST /api/agents/runs/{runId}/checkpoint
- GET /api/agents/user-actions
- GET /api/agents/approvals
- POST /api/agents/approvals
- GET /api/agents/operator-actions
- POST /api/agents/operator-actions (actionHandle only)
- POST /api/agents/drafts/{draftId}/promote
- GET /api/agents/identity-card?profileId={profileId}
- GET /api/identity-memory/snapshot?profileId={profileId}
- GET /api/runtime-manifest?profileId={profileId}
- POST /api/runtime-manifest
- GET /api/morgan/world-context?profileId={profileId}
- GET /api/interactions
- GET /api/threads
- POST /api/chat
- GET /api/provenance?limit={limit}
- GET /api/social/accounts
- POST /api/social/accounts
- GET /api/social/manual-posts
- POST /api/social/manual-posts
- GET /api/social/watchlist
- POST /api/social/watchlist
- GET /api/social/operator-inbox
- GET /api/social/action-journal
- POST /api/social/action-journal

These operational APIs require a Clerk user session. An agent calling them should be acting for an authorized user.
Direct job creation is limited to non-mutating delegated work; mutation-capable executable jobs must be materialized from ready work orders.
Agent tokens may request and list approvals through opaque handles, but approval resolution is operator-only and requires server-derived operator authority.

## Proof Boundaries

- `draft_only_mcp`: Draft-only MCP operation. It can create or inspect private drafts and request approval; it cannot publish, mutate canonical personhood, run jobs, resolve approvals, or prove downstream effects.
- `unbound_read_planning`: Authenticated read/planning operation. It may inspect safe owner-scoped state or prepare plans, but it is not a mutation proof and is not bound to a materialized work order.
- `work_order_bound_controlled_mutation`: Controlled mutation executed through a ready work order, materialized job, server policy check, approval binding, and route-safe evidence summary. This proves the bounded mutation path, not arbitrary whole-run correctness.
- `step_verified`: A specific controlled mutation step has verified server-derived execution context, approval binding, provenance, and evidence. It is not a cryptographic whole-run audit seal.
- `run_chain_verified`: Reserved for future run-chain validation. Do not infer this from ordinary replay unless explicitly returned.
- `external_effect_not_replayable`: External effect was observed or handed off, but IMOGENE cannot deterministically replay or prove the external platform action from ledger data alone.
- `none`: No verified proof claim is being made.

## Imogene Player

- GET /api/player/manifest

The Player manifest reports pairing status and advertised capabilities. If unpaired, agents must not assume local runtime capabilities. Player-facing surfaces do not replace imogene.cc as the canonical authority, do not expose local files, and do not bypass approvals.

## Current Callable Tools

- imogene.identity.catalog
- imogene.identity.get
- imogene.identity.inspect
- imogene.identity.lifecycle_state
- imogene.identity.get_v2
- imogene.identity.diff_versions
- imogene.identity.validate
- imogene.identity.request_missing_fields
- imogene.identity.readiness
- imogene.readiness.check
- imogene.readiness.explain
- imogene.readiness.next_tools
- imogene.media.asset_slots
- imogene.media.plan_identity_pack
- imogene.media.next_best_asset
- imogene.media.image_prompt
- imogene.media.flow_prompt
- imogene.media.generate_image_prompt
- imogene.media.generate_flow_prompt
- imogene.media.generate_variants
- imogene.permission.check
- imogene.permission.request_approval
- imogene.permission.list_approvals
- imogene.memory.card
- imogene.memory.read
- imogene.memory.timeline
- imogene.memory.relationship_graph
- imogene.job.create
- imogene.job.get
- imogene.job.list
- imogene.job.next_step
- imogene.social.manage_accounts
- imogene.social.plan_roster
- imogene.social.check_draft
- imogene.social.connector_requirements

## Constraints

- Morgan is the formal name of the Castor engine.
- Sarah is the formal name of the Pneuma engine.
- Public payloads must stay sanitized.
- Public contracts must describe work-order-bound controlled mutation proof, unbound read/planning jobs, draft-only MCP, and external effects not replayable without implying complete replay.
- Imogenes must not falsely claim to be the artist, brand, client, or user they support.
- Agents operate an Imogene under delegated authority; they do not assume the identity.
- Operational data belongs to owner-scoped authenticated records.
- Publishing, account changes, destructive memory changes, and commercial usage require explicit operator authority.