WFGY/ProblemMap/Twin_Atlas/demos/README.md

<!--
AI_NOTE_START

Document role:
This page is the entry point for the demo layer inside WFGY 4.0 Twin Atlas Engine.

What this page is for:
1. Explain why demos matter for Twin Atlas.
2. Show what kinds of contrasts the demo folder is designed to reveal.
3. Help readers navigate from demo philosophy to concrete cases.
4. Make it clear that the demo layer is not decoration, but part of the product proof surface.

How to use this page:
1. Read this page after Twin Atlas README and Bridge README.
2. Use it as the first stop before reading any individual demo case.
3. Use it to understand the logic behind the demo sequence.
4. Use it to navigate into the killer demo spec, case files, comparison tables, and evaluator notes.

Important boundary:
This page defines the purpose and structure of the demo layer.
It does not replace the formal contracts in the Bridge or Inverse Atlas documents.
It also does not claim that every future runtime detail is already complete.
The demo layer exists to make the reasoning difference visible, not to pretend the whole system is already universally solved.

Recommended reading path:
1. Twin Atlas
2. Bridge README
3. Bridge v1 Spec
4. Bridge v1 Examples
5. Killer Demo Spec
6. This page
7. Case files
8. Comparison tables
9. Evaluator notes

AI_NOTE_END
-->

# 🎭 Demos

> The visible proof surface for WFGY 4.0 Twin Atlas Engine.

The demo layer exists for one simple reason:

**if Twin Atlas really matters, people should be able to see the difference.**

Not after a long lecture.  
Not after a philosophical defense.  
Not after ten paragraphs of explanation.

They should be able to see it in a realistic case.

That is what this folder is for.

Twin Atlas is not trying to win by sounding more dramatic.  
It is trying to show a better reasoning discipline under structural ambiguity.

So the demo layer is not a side ornament.

It is where the architecture becomes visible.

---

## 🔎 Quick Links

| Section | Link |
|---|---|
| Twin Atlas Home | [Twin Atlas](../README.md) |
| Bridge Home | [Bridge README](../Bridge/README.md) |
| Bridge v1 Spec | [Bridge v1 Spec](../Bridge/bridge-v1-spec.md) |
| Bridge v1 Examples | [Bridge v1 Examples](../Bridge/bridge-v1-examples.md) |
| Bridge Eval Notes | [Bridge v1 Eval Notes](../Bridge/bridge-v1-eval-notes.md) |
| Killer Demo Spec | [Killer Demo Spec](./killer-demo-spec.md) |
| Case 01 | [Case 01 · Thin Evidence F5 vs F6](./case-01-thin-evidence-f5-vs-f6.md) |
| Comparison Table | [Baseline vs Twin Atlas Table](./baseline-vs-twin-atlas-table.md) |
| Evaluator Notes | [Evaluator Notes](./evaluator-notes.md) |
| Forward Atlas | [Problem Map 3.0 Troubleshooting Atlas](../../wfgy-ai-problem-map-troubleshooting-atlas.md) |
| Inverse Atlas Home | [Inverse Atlas README](../../Inverse_Atlas/README.md) |

---

## ⚡ The shortest version

If you only remember one thing, remember this:

**the demos are here to show why route-first mapping and legitimacy-first governance need to work together.**

A baseline may sound smart.  
A baseline may sound active.  
A baseline may even sound confident.

That is not enough.

The question is:

- did it lock the wrong route too early
- did it speak too strongly before lawful support existed
- did it present a cosmetic or premature repair as if it were structurally grounded

Twin Atlas is designed to reduce exactly those failures.

The demo layer exists to make that visible.

---

## 🧠 What the demos are trying to prove

A good Twin Atlas demo should prove more than "one answer looks better."

It should prove at least three deeper things:

### 1. Better route discipline
Twin Atlas should avoid locking the wrong dominant route too early.

### 2. Better authorization discipline
Twin Atlas should avoid illegal detail, unsupported certainty, and fake closure when neighboring routes remain materially live.

### 3. Better repair discipline
Twin Atlas should avoid presenting a first move as a structural repair verdict before broken-invariant contact is actually established.

If a demo only makes Twin Atlas look more cautious, that is not enough.

The contrast should be:

**not just softer vs louder**  
**but lawful vs premature**

---

## 🗂️ What is inside this folder

This folder is organized around a simple progression:

### 1. The logic of the demo
Start with the general design of the contrast.

File:
- [Killer Demo Spec](./killer-demo-spec.md)

### 2. The first concrete case
Move into an actual case where the contrast becomes visible.

File:
- [Case 01 · Thin Evidence F5 vs F6](./case-01-thin-evidence-f5-vs-f6.md)

### 3. The direct comparison view
See the difference side by side.

File:
- [Baseline vs Twin Atlas Table](./baseline-vs-twin-atlas-table.md)

### 4. The evaluator mindset
Learn how to judge whether the contrast is actually meaningful.

File:
- [Evaluator Notes](./evaluator-notes.md)

That sequence matters.

It moves from:
- demo philosophy
- to actual case
- to visible contrast
- to review discipline

---

## 🧭 How to read the demos correctly

The demo folder should not be read like a collection of random cool examples.

It should be read as a proof ladder.

### Step 1
Understand the logic of the contrast.

### Step 2
Read the concrete case.

### Step 3
Compare the baseline output with the Twin Atlas output.

### Step 4
Check whether the observed difference is real, structural, and operationally relevant.

In other words:

do not ask only  
"which one sounds nicer"

ask  
"which one stayed more lawful under uncertainty"

That is the right reading posture.

---

## 🎯 What a successful demo looks like

A successful Twin Atlas demo should make the audience see all of the following quickly:

### A. The baseline locked too early
The route looked neat, but the certainty was not earned.

### B. The baseline over-resolved
The answer went too specific before neighboring-route pressure had been lawfully separated.

### C. The baseline proposed a riskier first move
The proposed repair sounded strong, but it was not actually grounded in the broken invariant.

### D. Twin Atlas preserved lawful ambiguity
It did not erase uncertainty just to sound cleaner.

### E. Twin Atlas gave a safer next move
Not because it was timid, but because the next move was more structurally grounded.

That is the real contrast.

---

## 🧪 The current MVP demo direction

For the current MVP, the demo layer is centered around one primary contrast pattern:

### Demo 01
**Thin evidence with live F5 vs F6 pressure**

This is the best first killer demo because it does several useful things at once:

- it feels realistic
- it tempts the baseline into dramatic over-interpretation
- it keeps neighboring ambiguity alive
- it creates a tempting wrong-first-fix path
- it lets Twin Atlas show both route discipline and authorization discipline at the same time

This is not an arbitrary choice.

It is the cleanest way to make the Twin Atlas difference legible in one screen.

---

## 🧱 Why the demo layer belongs inside Twin Atlas

The demo layer matters because Twin Atlas is not only a naming exercise.

Twin Atlas brings together:

- Forward Atlas
- Bridge
- Inverse Atlas

That means the architecture claims a stronger reasoning discipline than a route-only or style-only approach.

If that claim matters, then the contrast must become visible somewhere.

That visible place is this folder.

So the demos are not marketing garnish.

They are the first practical proof surface of the engine direction.

---

## 🌉 Relationship to Bridge

Bridge matters inside the demos even when readers do not see it directly.

Why:

- the forward side produces route value
- Bridge carries that value as weak priors
- the inverse side decides whether strong visible output is actually lawful

That means the demos are not only comparing two answer styles.

They are comparing two internal disciplines:

### Baseline
Often:
- route lock too early
- hidden confidence inflation
- fake closure
- premature repair confidence

### Twin Atlas
Designed to:
- preserve route pressure honestly
- preserve ambiguity when lawful
- block unauthorized escalation
- keep repair as candidate until legality is established

The demo layer is where that difference becomes human-visible.

---

## 📘 Recommended reading order inside this folder

If someone lands here fresh, this is the best order:

1. [Killer Demo Spec](./killer-demo-spec.md)
2. [Case 01 · Thin Evidence F5 vs F6](./case-01-thin-evidence-f5-vs-f6.md)
3. [Baseline vs Twin Atlas Table](./baseline-vs-twin-atlas-table.md)
4. [Evaluator Notes](./evaluator-notes.md)

Why this order works:

- the spec explains what the demo is trying to prove
- the case shows the setup
- the table shows the contrast
- the evaluator notes explain how to judge the result

That makes the folder readable even for first-time readers.

---

## 🚫 What this folder is not

To keep expectations honest, this folder should not be misunderstood as any of the following:

### Not a random example dump
The demos are structured, not decorative.

### Not a benchmark by itself
The demo layer is proof-oriented, not a universal leaderboard.

### Not a substitute for formal contracts
The demos do not replace the forward, bridge, or inverse specifications.

### Not proof that every runtime detail is already finished
The demo layer can be strong even while the full operating layer is still evolving.

### Not just about humility style
The demos are not about sounding softer.
They are about being more lawful under pressure.

That distinction matters.

---

## ✅ What is already fair to say

At the current stage, these statements are fair:

- the demo layer already has a clear purpose
- the killer demo direction is already defined
- the MVP contrast is already structurally meaningful
- the demo folder already serves as a visible proof surface for Twin Atlas
- the first case direction is already strong enough to support public explanation
- the demos already help translate Twin Atlas from concept into visible behavior

These are strong statements, but still honest.

---

## 🚧 What should not yet be claimed

This folder should not be used to claim that:

- every future demo case is already complete
- every runtime behavior is already benchmarked
- the current demo set proves universal superiority in every environment
- a single visual contrast is the same thing as full engine completion
- the presence of a demo folder means the whole closed-loop system is already done

The point of this folder is visibility, not exaggeration.

---

## 🛠️ Suggested file roles

Here is the current intended role of each file in this folder.

| File | Role |
|---|---|
| `README.md` | Demo folder entry point |
| `killer-demo-spec.md` | Core logic of the main contrast |
| `case-01-thin-evidence-f5-vs-f6.md` | First concrete MVP case |
| `baseline-vs-twin-atlas-table.md` | Side-by-side structural comparison |
| `evaluator-notes.md` | How to review whether the contrast is actually meaningful |

This makes the folder easy to understand at a glance.

---

## 🧡 A vibe-coder-friendly mental model

If you want a fast mental model, use this:

### Baseline
"looks like it knows"

### Twin Atlas
"knows what it has actually earned"

That is not the whole architecture.  
But it is a very good first intuition for the demo layer.

---

## 🚀 Suggested next read

If you are here for the first time, go here next:

👉 [Killer Demo Spec](./killer-demo-spec.md)

If you already know the contrast logic and just want the first concrete case, go here:

👉 [Case 01 · Thin Evidence F5 vs F6](./case-01-thin-evidence-f5-vs-f6.md)

If you want the fastest visible comparison, go here:

👉 [Baseline vs Twin Atlas Table](./baseline-vs-twin-atlas-table.md)

---

## ✨ One-sentence takeaway

> The demo layer exists to show that Twin Atlas is not just a different style of answer, but a more disciplined way of staying lawful under uncertainty.