WFGY/Avatar/docs/README.md

<!--
AI_NOTE_START

Document role:
This page is the main hub for the WFGY 5.0 Avatar docs layer.

Primary mission:
1. Present Docs as the operational layer of Avatar.
2. Make startup, reading, tuning, and recovery guidance easy to find without forcing readers into the heaviest theory first.
3. Keep Docs practical, route-aware, and GitHub-readable.
4. Show clear next steps for different reader intents without replacing Research or Eval.
5. Prevent Docs from becoming either a shallow product clone or a fake theory substitute.

Reader intent routing:
1. If the reader wants to start quickly, route to Quickstart and Boot Commands.
2. If the reader wants lawful reading order for the master file, route to How to Read the Avatar Master File.
3. If the reader wants bounded control steering, route to Parameter Tuning Cookbook and Avatar Tuning Workflow.
4. If the reader wants persona restoration after drift, route to Persona Recovery Operations.
5. If the reader wants deeper structural explanation, route to Research Hub.
6. If the reader wants pressure, drift, or readiness inspection, route to Eval Hub.

Reading priority:
1. Read this hub as the operational entry map.
2. Read Quickstart and Boot Commands first for first-time use.
3. Read How to Read the Avatar Master File before deep packed-master reading.
4. Read tuning and recovery pages only after startup grammar is understood.
5. Treat Research and Eval links as downstream branches, not replacements for Docs.

Allowed use:
1. Startup routing
2. Operational guidance
3. Reading-order guidance
4. Tuning and recovery routing
5. Cross-linking from product landing into practical use surfaces

Do not do:
1. Do not treat this hub as the packed master body.
2. Do not turn Docs into a research index.
3. Do not use Docs pages to overclaim engine completion.
4. Do not assume operational clarity replaces deeper structural reading.
5. Do not let docs sprawl become a fake completeness signal.

Layer relation:
1. Product landing explains what Avatar is.
2. Docs explains how to use Avatar.
3. Research explains why deeper structures exist.
4. Eval tests what survives pressure.

Boundary honesty:
1. This hub reflects the current public Docs layer of Avatar.
2. It is strong enough for startup, reading, tuning, and recovery routing.
3. It does not claim every future Docs surface is already complete.
4. It does not claim theorem-grade universal closure.
5. It does not claim that Docs pages replace Research or Eval.

Next-page routing:
1. For startup, go to Quickstart and Boot Commands.
2. For lawful reading, go to How to Read the Avatar Master File.
3. For tuning, go to Parameter Tuning Cookbook and Avatar Tuning Workflow.
4. For recovery, go to Persona Recovery Operations.
5. For deeper structure, go to Research Hub.
6. For pressure and inspection, go to Eval Hub.

AI_NOTE_END
-->

# 📘 Docs Hub

This page is the docs hub for **WFGY 5.0 Avatar**.

Avatar is not only a concept surface and not only a research body.

People also need to know:

1. how to start
2. how to boot
3. how to read the master correctly
4. how to tune bounded controls
5. how to recover after drift
6. how to move from first use into deeper branch work

That is what this Docs layer is for.

The Docs layer exists so the project can stay usable without forcing every reader to begin from the deepest research page or the heaviest packed-master section.

It is the operational entry layer of the Avatar branch.

---

## ✨ Why this layer exists

The **Docs** layer answers practical questions like:

1. how do I enter Avatar
2. which commands should I use
3. how should I read the master file
4. how do I tune the current branch
5. how do I recover after drift or thinning
6. where should I go next after startup

That is different from what the other layers do.

The **Research** layer answers deeper structural questions like:

1. what counts as execution
2. what counts as route law
3. what counts as runtime carry
4. why structured imperfection matters
5. what happens before public emission
6. how matrix accountability and audit burden work

The **Eval** layer answers pressure questions like:

1. what breaks under hostile reading
2. what remains stable under real use
3. what behavior should or should not receive credit
4. how multilingual status is being stated honestly

So the Docs layer is where operation becomes legible.

It does not replace the deeper body.  
It makes the deeper body usable.

---

## 🧭 How to use this hub

Use this hub in one of five ways.

### 1. I want to start quickly

Start here if your main question is:

1. what is Avatar
2. how do I boot it
3. what should I type first

Read in this order:

1. [⚡ Quickstart](./quickstart.md)
2. [⌨️ Boot Commands](./boot-commands.md)

This is the best route for first-time entry.

---

### 2. I want to understand how to read the master file

Start here if your main question is:

1. where do I begin
2. what order should I read different sections in
3. how do I avoid getting lost in a large one-file system
4. how does reading order change for article-grade tasks

Read:

1. [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)

This is the best route when your problem is not usage only, but lawful reading.

---

### 3. I want to tune the current branch

Start here if your main question is:

1. which knobs matter
2. what should be tuned first
3. how do I compare profiles safely
4. how do I diagnose too-flat, too-clean, too-generic, or too-aggressive behavior

Read:

1. [🍳 Parameter Tuning Cookbook](./parameter-tuning-cookbook.md)
2. [🛠️ Avatar Tuning Workflow](./avatar-tuning-workflow.md)

This is the best route for bounded calibration and branch steering.

---

### 4. I want to recover a persona after drift

Start here if your main question is:

1. what does `avatar++` do
2. when should I use `avatar++ reload`
3. what is the difference between recovery and re-booting
4. how do I tell if recovery actually worked

Read:

1. [🔧 Persona Recovery Operations](./persona-recovery-operations.md)
2. [⌨️ Boot Commands](./boot-commands.md)

This is the best route when continuity weakened after article, analysis, rewrite, search, or tool pressure.

---

### 5. I want to go deeper after Docs

Start here if your main question is no longer “how do I use it,” but instead:

1. what is actually happening underneath
2. how does execution work
3. what is runtime law
4. what is selector law
5. how is the packed master structured

Go to:

1. [🔬 Research Hub](../research/README.md)
2. [🧪 Eval Hub](../eval/README.md)

Docs gets you into the branch.  
Research and Eval tell you what that branch is actually doing and whether it survives pressure.

---

## 🧱 What belongs in the Docs layer

The Docs layer is where operational guidance lives.

Typical Docs-layer questions include:

1. how do I start
2. how do I boot a persona
3. how do I avoid false-trigger mistakes
4. how do I read the master file correctly
5. how do I tune the current controls
6. how do I recover after drift
7. where do I go when I need more than startup help

This layer should stay clear, practical, and route-aware.

It should not try to restate the entire research body.  
It should not try to replace evaluation pressure.  
It should not pretend a few instructions equal the whole system.

That restraint is what keeps Docs useful.

---

## 🧠 Current docs surfaces

The current Docs layer is organized into five major surfaces.

### 1. Startup surface

These pages help the reader begin.

1. [⚡ Quickstart](./quickstart.md)
2. [⌨️ Boot Commands](./boot-commands.md)

Use these when the question is:

1. how do I start
2. what do I type
3. what are the valid command families
4. how do I enter without guesswork

---

### 2. Reading surface

This page helps the reader approach the packed master correctly.

1. [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)

Use this when the question is:

1. where should I begin reading
2. what reading order should different reader types use
3. how does article-mode reading differ from casual reading
4. how do I avoid flattening the file into one giant prompt

---

### 3. Tuning surface

These pages help the reader steer bounded controls without turning tuning into random knob superstition.

1. [🍳 Parameter Tuning Cookbook](./parameter-tuning-cookbook.md)
2. [🛠️ Avatar Tuning Workflow](./avatar-tuning-workflow.md)

Use these when the question is:

1. which family should I tune first
2. how do I compare baseline, standard, and strong
3. how do I tune without damaging lawful floors
4. how do I move from diagnosis to bounded comparison

---

### 4. Recovery surface

This page helps the reader restore continuity after drift, thinning, or over-cleaning.

1. [🔧 Persona Recovery Operations](./persona-recovery-operations.md)

Use this when the question is:

1. when should I use `avatar++`
2. when should I use `avatar++ reload`
3. what does `avatar release` actually do
4. how do I know whether recovery was real or only cosmetic

---

### 5. Cross-layer routing surface

This hub itself is part of the operational routing layer.

1. [📘 Docs Hub](./README.md)

Use this when the question is:

1. what Docs page should I open next
2. where should I go after startup
3. when should I jump from Docs into Research or Eval

---

## 🪜 Suggested docs paths

### Path A: complete newcomer path

Use this if you are starting from zero.

1. [⚡ Quickstart](./quickstart.md)
2. [⌨️ Boot Commands](./boot-commands.md)
3. [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)

This path gives you:

1. first entry
2. command clarity
3. lawful reading order

---

### Path B: startup plus recovery path

Use this if you can already start Avatar but want to recover it when it thins.

1. [⌨️ Boot Commands](./boot-commands.md)
2. [🔧 Persona Recovery Operations](./persona-recovery-operations.md)
3. [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)

This path gives you:

1. valid boot and recovery grammar
2. boundary between boot and recovery
3. reading discipline after drift

---

### Path C: tuning path

Use this if the system is working but you want to steer it more precisely.

1. [🍳 Parameter Tuning Cookbook](./parameter-tuning-cookbook.md)
2. [🛠️ Avatar Tuning Workflow](./avatar-tuning-workflow.md)
3. [🔧 Persona Recovery Operations](./persona-recovery-operations.md)

This path gives you:

1. symptom-first tuning
2. profile comparison discipline
3. recovery-aware tuning

---

### Path D: docs to research path

Use this if Docs answered the operational layer and you now want deeper understanding.

1. [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)
2. [🔬 Research Hub](../research/README.md)
3. [🗺️ Packed Master Structure Map](../research/packed-master-structure-map.md)
4. [🔁 Dual Closed-Loop Execution Chain](../research/dual-closed-loop-execution-chain.md)

This path is best when you want to move from usage to structure.

---

### Path E: docs to eval path

Use this if Docs helped you operate the branch, but now you want to inspect whether it actually held under pressure.

1. [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)
2. [🧪 Eval Hub](../eval/README.md)
3. [🧨 Blackfan Testing](../eval/blackfan-testing.md)
4. [🧭 Persona Behavior Checks](../eval/persona-behavior-checks.md)

This path is best when you want to move from operation to inspection.

---

## 🔍 Why docs and research are different

This distinction matters.

The **Docs** layer answers:

1. how to start
2. how to read
3. how to tune
4. how to recover

The **Research** layer answers:

1. what the packed master is
2. what counts as execution
3. what the selector actually selects
4. what runtime posture actually controls
5. why structured imperfection is a retention law
6. how matrix accountability and blackfan audit work

So:

1. Docs tell you how to operate
2. Research tells you how to understand

Both matter.  
They are not the same thing.

---

## 🔍 Why docs and eval are different

This distinction matters too.

The **Docs** layer helps you do things.

The **Eval** layer helps you judge whether the current branch held up under pressure.

For example:

1. Docs explain how to recover
2. Eval checks whether recovery actually deserves credit

1. Docs explain how to tune
2. Eval checks whether tuning made the branch stronger or only prettier

1. Docs explain how to start
2. Eval checks whether startup clarity survives real branch use

So:

1. Docs are operational
2. Eval is inspectable pressure

That separation keeps the branch honest.

---

## 🌱 What this layer should become over time

As Avatar grows, Docs will likely need to keep getting clearer, not just longer.

A good Docs layer should continue to do three things well:

1. reduce startup friction
2. reduce misreading
3. reduce bad tuning and bad recovery habits

That means future Docs growth should stay disciplined.

New Docs pages should exist because they solve a real operational problem, not because more pages feel more complete.

This is important.

A branch can become unreadable through documentation sprawl just as easily as it can through theory sprawl.

So Docs growth should remain task-driven.

---

## ⚠️ What this hub does not claim

This hub does **not** claim:

1. that all future Docs pages already exist
2. that Docs alone are enough to understand the whole project
3. that current Docs already replace the packed master
4. that current Docs already cover every future branch workflow
5. that current branch ergonomics are universally final
6. that Docs pages remove the need for Research or Eval

This hub is a bounded operational center.

That is exactly what it should be.

---

## 🚀 Where to go next

### If you want public entry
Go to [✨ Avatar Home](../README.md)

### If you want startup
Go to [⚡ Quickstart](./quickstart.md)

### If you want command syntax
Go to [⌨️ Boot Commands](./boot-commands.md)

### If you want lawful reading order
Go to [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)

### If you want tuning
Go to [🍳 Parameter Tuning Cookbook](./parameter-tuning-cookbook.md)

### If you want recovery
Go to [🔧 Persona Recovery Operations](./persona-recovery-operations.md)

### If you want deeper structure
Go to [🔬 Research Hub](../research/README.md)

### If you want pressure and inspection
Go to [🧪 Eval Hub](../eval/README.md)

---

## 🔗 Quick Links

### Docs core
- [⚡ Quickstart](./quickstart.md)
- [⌨️ Boot Commands](./boot-commands.md)
- [📖 How to Read the Avatar Master File](./how-to-read-the-avatar-master-file.md)
- [🍳 Parameter Tuning Cookbook](./parameter-tuning-cookbook.md)
- [🔧 Persona Recovery Operations](./persona-recovery-operations.md)
- [🛠️ Avatar Tuning Workflow](./avatar-tuning-workflow.md)

### Product and layer hubs
- [✨ Avatar Home](../README.md)
- [🔬 Research Hub](../research/README.md)
- [🧪 Eval Hub](../eval/README.md)

### Research
- [🗺️ Packed Master Structure Map](../research/packed-master-structure-map.md)
- [🚪 Launchpad, Front Door, and Command Grammar](../research/launchpad-front-door-and-command-grammar.md)
- [🔁 Dual Closed-Loop Execution Chain](../research/dual-closed-loop-execution-chain.md)
- [🎛️ Runtime Posture Intensity Map](../research/runtime-posture-intensity-map.md)
- [🧩 Shell-to-Runtime Mapping](../research/shell-to-runtime-mapping.md)
- [🧭 Selector Execution Domain](../research/selector-execution-domain.md)
- [🔄 Activation, Attenuation, and Reentry](../research/activation-attenuation-and-reentry.md)
- [🧬 Structured Imperfection Theory](../research/structured-imperfection-theory.md)
- [🚦 Pre-Emission Floor and Hard Control](../research/pre-emission-floor-and-hard-control.md)
- [🧮 Matrix Accountability and Numeric Binding](../research/matrix-accountability-and-numeric-binding.md)
- [🧪 Blackfan Audit Baseline](../research/blackfan-audit-baseline.md)
- [✂️ Compression and Non-Duplication Law](../research/compression-and-non-duplication-law.md)

### Eval
- [🧨 Blackfan Testing](../eval/blackfan-testing.md)
- [🧭 Persona Behavior Checks](../eval/persona-behavior-checks.md)
- [🌍 Multilingual Status](../eval/multilingual-status.md)

### Up
- [⬆️ Back to Avatar Home](../README.md)
- [⬆️ Back to WFGY Root](../../README.md)