Start Here — RevFramework¶

This page shows you how to approach the framework, so you can start small, use what you need, and avoid extending the wrong layer.

The Big Picture¶

Every system follows the same documentation pattern:

Overview
→ Mental Model
→ Integration Surfaces
→ Public API
→ System Guarantees
→ FAQ
→ Teachable Panels
→ Samples

You do not need to read everything.

Start with the system you are using.
Go deeper only when you need to.

If You’re New¶

Start here:

1. Overview
2. Mental Model
3. Teachable Panels
4. Samples

👉 Stop here unless you need to extend something.

If You’re Integrating¶

Start here:

1. Mental Model
2. Public API
3. Teachable Panels
4. Samples
5. Runtime Code

If You’re Extending¶

Start here:

1. Mental Model (mandatory)
2. Public API
3. FAQ
4. Integration Surfaces
5. Teachable Panels
6. Samples

Teachable Panels¶

Teachable Panels are more than demos.

They are:

• live, in-editor learning tools
• built against the public API
• designed to show real runtime behaviour
• useful for checking how a system is expected to behave

If Something Isn’t Working¶

Check in this order:

1. FAQ
2. Teachable Panel behaviour
3. Sample scene
4. Mental Model
5. Public API

Runtime vs Docs vs Teaching¶

Mental Model vs Public API¶

You usually need both.

Why It Works This Way¶

Most of the reasoning lives beside the code it governs — in the documentation on a method, and in the README in each folder.

A handful of decisions are the exception. They are visible in your project long before you reach any explanation of them, and without one they read as mistakes: where the framework installs, why the scene services are large single files, where authority deliberately stops.

Those have their own section on the site. Read it when a choice looks wrong and you want to know whether it was considered:

👉 Why It Works This Way

Samples¶

Samples are:

• runnable
• editable
• intentionally focused

They are meant to be inspected, copied, and modified.

Cookbook¶

Samples and Teachables show you one system working. The Cookbook shows you several working together — compositions built only from public seams.

Use it when:

• you are comfortable with a system and wondering what else it can reach
• you want to see a composition before committing to designing one
• you want the traps someone else already hit

It is on the website, not in this package — deliberately. Recipes are reference implementations to copy, adapt and own, not part of the supported runtime surface.

👉 Browse the Cookbook

What You Can Skip¶

You can skip:

• systems you are not using
• internal folders
• advanced samples
• integration pages for systems you do not own

One Rule¶

If you are unsure where something belongs:

👉 go back to the Mental Model

TL;DR¶

RevFramework is designed to prove behaviour, not just describe it.