flipbook

Special workflow for testing FlipbookCore changes through the StudioPlugins Flipbook plugin. Use only when: the engineer explicitly asks to verify changes through StudioPlugins, mentions StudioPlugins with local FlipbookCore rotriever builds, or says the StudioPlugins watcher is already running.

Load-bearing design decisions, invariants, and known weak points of Flipbook's architecture. Use when understanding or extending system design, debugging architectural mismatches, or validating deep changes (PR

Understanding the Flipbook build system from environment setup through final deployment; source→rbxm pipeline with deep focus on Darklua require transformation, environment globals injection, and dead-code elimination

Classification, gating, and review discipline for Flipbook changes: branch/PR workflow, version gating, CI gates, change-type decision table, community-first and telemetry-privacy doctrine, and the non-negotiables with their historical incidents. Use when authoring a PR, reviewing change control, understanding release requirements, or evaluating whether a change is safe to merge.

Community-first doctrine, telemetry/privacy posture, ecosystem positioning vs web Storybook and UI Labs, and claim discipline for Flipbook features

Configuration axes (env vars, injected globals, build channels/targets, user settings); adding new config; re-verification commands

Symptom→solution runbook for Flipbook runtime issues: stale plugin behavior, stories not hot-reloading, controls re-rendering excessively, crashes on state mutations, test failures, missing logs, plugin freezing or opening uninvited. Use when you encounter a runtime symptom and need to isolate root cause quickly via discriminating experiments.

Instrumentation and observability: how to measure Flipbook's runtime behavior. Use when: debugging why a story doesn't load (add logging), validating a performance fix (measure rerenders), verifying build inclusion (inspect sourcemaps/cache), or filtering tests. Covers logging system, test output parsing, build-cache inspection, sourcemap require-path tracing, and rerender accounting. Complements flipbook-validation-and-qa (evidence standards for fixes) by providing the measurement tools.

Flipbook documentation estate: Docusaurus site, code-sample extraction, Obsidian vault (flipbook-docs branch), house style, and PR descriptions. Use when maintaining or extending the docs of record, writing new user or contributor docs, writing or revising a pull request description, enforcing prose/markdown conventions, or creating templates for documentation pages and skills.

Story/Storybook formats and contracts, Storyteller architecture, module reload semantics, plugin security contexts, React-in-Roblox essentials, 11 control types. Use when: explaining how stories work, debugging story loading, learning the UI framework contract, understanding why hot-reload can break, implementing new story/control features, or advising on embedding.

Chronicle of all major Flipbook investigations, dead ends, reverted features, and unresolved bugs with evidence and current status. Check this before attempting a "new" fix to avoid re-fighting settled battles and knowing why workarounds exist.

First-principles analysis methods for Flipbook: six recipes to prove claims via mechanism, not inspection. Includes require-graph verification, module-reload isolation, rerender measurement, build determinism auditing, type-level proof via Luau analysis, and dependency-contract reading. Use when validating a build change, debugging state bugs, or claiming a fix works—before trusting the build, measure the mechanism.

Release runbooks, deployment orchestration, artifact conventions, CI/CD environments, and operational history; for releasing versions and managing production deployments

Open research problems where Flipbook advances SOTA beyond web Storybook and uilabs: in-experience collaboration, automated visual regression, agent-driven development. First steps, blockers, milestones.

The disciplined evidence-bar, hypothesis-prediction, idea-lifecycle, and community-feedback research protocol that turns hunches into accepted changes in Flipbook. Use when designing experiments, evaluating PR readiness, validating mysterious bugs, documenting dead ends, or understanding why certain workarounds exist.

Runbook for story controls work: reproducing gaps, ranked solutions with implementation paths, validation gates. Use when tasked with UILabs story compatibility, adding new control types, fixing control re-render bugs, or validating controls refactor. Start with PHASE 1 (reproduce and characterize), then PHASE 2 (choose a solution), then implement and validate. All phases include exact commands and expected observations.

Acceptance discipline: what counts as proof a change works, test anatomy, spec-writing guide. Use when: you need to prove a fix is correct (learn the evidence bar), writing unit tests, adding specs to a PR, or understanding why a test matters. Three tiers of validation: Lint (static checks) → Analyze (type safety) → Test (behavior in real Roblox). For measurement/instrumentation to *find* the bug, see flipbook-diagnostics-and-tooling.

Run validation checks in Flipbook, Storyteller, or ModuleLoader. Use when: running tests, lint, analyze, CI checks, quality checks, or verifying changes in the Flipbook repo family.

Set up or repair the Flipbook, Storyteller, or ModuleLoader development environment. Use when: first-time setup, installing dependencies, managing .env files, troubleshooting rokit/wally/lute, or repairing stale tooling in the Flipbook repo family.

Verify local Storyteller or ModuleLoader changes inside Flipbook by overlaying built binaries. Use when: you changed storyteller or module-loader and need to test the changes in Flipbook, or when the engineer explicitly asks to verify a dependency change through Flipbook.