How to run FrameloopOS locally.
This is the operating manual for the current local cockpit: what it records, how to run it, what the empty states mean, and how to verify the system before you trust a render pass.
Launch the local cockpit.
FrameloopOS is still local-first. The UI is a production surface over manifest state, not a cloud app.
pnpm typecheck pnpm build PORT=5175 pnpm start # hot reload while developing: PORT=5175 pnpm dev
Then open http://localhost:5175. If 5175 is occupied, pick another free localhost port. The root scripts delegate into orchestrator/; direct equivalents are pnpm --dir orchestrator start and pnpm --dir orchestrator dev.
The UI scans known roots for frameloop.json projects, then renders the selected project with a status strip, workbench shot board, selected-shot inspector, and observational copilot rail.
What Frameloop actually produces today.
Three project-type plugins are registered in the orchestrator, each a self-contained action set — not a roadmap slide.
Song + concept -> shot list -> Seedance generation -> watermark scrub -> mux -> 16:9/9:16/1:1 masters.
regenerate_shotscrub_allmux_allassemble_mastergenerate_portraitbuild_gallerydubstub
Markdown script + narration -> compiled shots (NASA / motion / Manim / citation / local sources) -> takes -> master mux with music ducking.
compile_scriptresolve_shotrender_shotassemble_takesassemble_masterreview
Long-form source -> transcript-aligned clip mining -> themed frame generation -> caption burn-in -> contact sheet -> vertical export packaging.
ingest_sourcetranscribe_sourcepropose_clipsapprove_cutsgenerate_theme_assetsapprove_themerender_batchbuild_contact_sheetpackage_exports
The current surfaces.
Everything visible in the cockpit must be backed by manifest or ledger state. Empty states are intentional; they mean the workflow has not recorded that class of event yet.
Summarizes project health, shot completion, review warnings, attempt counts, failure counts, fallback counts, and paid/planned ledger totals.
Shows the prompt, refs, outputs, attempt history, provider routes, review gates, export readiness, provenance, and explicit action buttons for the selected shot.
What the new records mean.
The ledger turns the manifest into production memory. It records what happened, what it cost, and what the operator should trust.
| Record | Purpose | Current usage |
|---|---|---|
attempts | Execution history, costs, artifacts, failures, fallback notes. | Action jobs write attempts automatically; portrait generation enriches them with real OpenAI accounting. |
provider_routes | Why a provider/model was selected and what it was expected to cost. | Dreamina stub and OpenAI portrait path now write selected routes. |
review_gates | Preflight/output/export review verdicts. | Essay review now records an output gate and links RENDER_REPORT.md. |
provenance_records | Source/license trace for reusable assets. | Schema/UI support is present; workflows should start filling it next. |
Smoke tests before trusting a release.
Run code checks first, then verify behavior in the browser with a real project selected.
pnpm verify # or run the pieces: pnpm --dir orchestrator exec bun test src/shared/manifest-ledger.test.ts pnpm --dir orchestrator typecheck pnpm --dir orchestrator build pnpm --dir site verify
- Project loads without a blank screen.
- Status strip, inspector, and copilot rail render.
- Selecting a different shot updates the inspector.
- If an attempt exists, its timestamps/costs/refs render.
- No console/page errors during the interaction.
What still needs to land
Real provider execution for more routes, enforced review gates, a global asset brain, speaker-documentary mode, and public-proof screenshots from the local cockpit once the browser automation path is stable.
Empty states are receipts too.
If the cockpit says “Not recorded yet,” the system is telling the truth: that part of the workflow has not written a durable record. The right fix is to teach the action to write the ledger, not to hide the gap.