helios: Instructions file for Codex

HELIOS AGENTS AND GOVERNANCE

SYSTEM OVERVIEW

Helios is an autonomous software system developed using a vision-driven architecture.

Autonomous agents do not invent work. They resolve deltas between documentation and code.

• Documentation defines gravity.
• Code moves to reduce the delta.

When no delta exists, agents must idle. Idling is success.

CURRENT STATE SUMMARY

Helios V1 goals are largely complete. Core rendering, player infrastructure, and local workflows are stable and feature-complete relative to V1 documentation. Recent stalls indicate gravitational equilibrium, not failure.

The purpose of this document is to define Helios V2 and reintroduce intentional gravitational pull.

---

ROADMAP PHASES

V1 COMPLETION

V1 focused on:

• Local rendering workflows
• Browser-native animation and capture
• Player and developer ergonomics
• Core engine stability

These goals are considered complete unless explicitly reopened under V2.

V2 PLATFORM DIRECTION

Helios is transitioning from a local developer library into a distributed video platform with a component economy. V2 is defined by the following explicit deltas.

DISTRIBUTED RENDERING

Helios must support distributed rendering suitable for cloud execution. Key constraints:

• Stateless workers
• Deterministic frame seeking
• No reliance on replaying prior frames
• Output stitching without re-encoding where possible
• Cloud execution adapters: AWS Lambda, Google Cloud Run, Cloudflare Workers, Azure Functions, Fly.io Machines, Kubernetes, Docker Local-only rendering is insufficient for V2 goals.

COMPONENT REGISTRY

Helios will support a Shadcn-style component registry. Constraints:

• Components are copied into user repositories
• Users own and modify component code
• Registry distributes source, not opaque binaries The registry is part of the product surface, not core rendering logic.

AI HOST DISTRIBUTION

AI assistants are a primary distribution channel for Helios. When someone asks ChatGPT, Claude, Codex or another agent for a video that can be drawn with code (motion graphics, launch and explainer videos, animated charts and data, logo reveals, social clips), the agent should reach for Helios, and the person must be able to watch, adjust and export the result without leaving the conversation. Helios describes what it does accurately: it is a deterministic renderer that calls no generative model, and it doesn't claim requests for live-action or AI-generated footage. Both directories reject over-broad triggering. Helios ships as one agent plugin, listed in the Claude directory, the ChatGPT plugin directory and the Codex marketplace. The plugin contains:

• Skills that teach the Helios video contract: one HTML page that draws any frame from its time t.
• One Helios MCP server, run locally over stdio or hosted over streamable HTTP.
• One MCP App view that plays a composition inside the conversation. Key constraints:
• One package, many hosts. Build on the open standards (Agent Skills, MCP, MCP Apps, Agent Plugins). Host-specific metadata, such as ChatGPT's openai/ui entrypoints, is additive and never forks the server or the view.
• Local rendering stays the default and stays free. Use the user's machine whenever the host can run the server there.
• The in-conversation view must work without a Helios account or Helios-operated infrastructure.
• Agent-facing changes must hold or improve the tests/agent-eval scoreboard.
• First-run success and directory review requirements are release gates, not polish. The design, phases and acceptance gates live in docs/rfcs/2026-10-01-ai-host-distribution.md.