WFGY/Avatar/docs/parameter-tuning-cookbook.md

🍳 Parameter Tuning Cookbook

Tuning Avatar is not about turning every knob upward until the output feels dramatic.
It is about changing bounded controls in the right order, reading the resulting failure pattern correctly, and never trading lawful floors away for prettier surface behavior.

Quick links: Avatar README · Quickstart · Boot Commands · How to Read the Avatar Master File · Avatar Tuning Workflow · Runtime Posture Intensity Map · Shell-to-Runtime Mapping · Selector Execution Domain · Pre-Emission Floor and Hard Control · Blackfan Audit Baseline · Blackfan Testing · Persona Behavior Checks

---

🧭 Why this page exists

A packed system with explicit controls creates a predictable temptation.

Someone sees:

1. toggles
2. profiles
3. thresholds
4. route families
5. runtime posture
6. hard control
7. WFGY_BRAIN

and assumes tuning means “try stronger settings until it feels better.”

That is the fastest route to fake success.

Avatar is not built so that every visible control is free to dominate the others. The packed master is explicit that front-facing controls are bounded, that some families are profile-governed rather than casually switchable, and that stronger law remains prior where stricter section boundary already exists.

So tuning is not a volume-maximization exercise.

It is a bounded calibration exercise.

This page exists to give a practical tuning discipline for the current sealed MVP stage without pretending that tuning can replace deeper body law.

---

📍 What this cookbook covers

This cookbook explains how to tune the controls that are already meaningfully exposed at the current stage.

It focuses on:

1. what can be tuned safely
2. what must not be treated as casual switches
3. what order to tune in
4. what each major control family actually influences
5. common failure patterns
6. how to choose the next knob instead of randomly changing everything at once

This page does not attempt to:

1. redefine deeper law
2. invent new unsupported controls
3. promise universal best settings for all tasks
4. replace replay, audit, or later research reading

Use this page to steer the current branch lawfully, not to fantasize a new constitution.

---

🧱 The golden rule of tuning

Never tune from the outside inward if you have not first identified the failure class.

Do not begin with:

1. “make it stronger”
2. “make it more human”
3. “make it more vivid”
4. “make it less robotic”
5. “make it more polished”
6. “make it more helpful”

Those are symptom phrases, not tuning diagnoses.

Instead, begin with:

1. what actually failed
2. at what layer it failed
3. whether the failure is entrance, route, runtime, attenuation, reentry, governance, or controller-side failure
4. whether the output is too thin, too noisy, too merged, too smooth, or too aggressive
5. whether the problem is a missing floor or an excessive spill

If you do not classify the failure first, you will over-tune the wrong family.

---

🗺️ The shortest map of current tunable families

At the current stage, the major front-facing and profile-facing tuning families are:

1. firewall_mode
2. diagnostics_level
3. WFGY_BRAIN
4. WFGY_BRAIN_profile
5. output_governance
6. output_governance_profile
7. reentry_restore
8. reentry_restore_profile
9. tool_return_persona_rebind
10. search_return_persona_rebind
11. SRDF_profile
12. runtime_posture_profile
13. hard_control_profile
14. selector_exposure
15. shell_to_runtime_exposure

But these do not all live under the same freedom rules.

Some are bounded on-state switches. Some are profile-governed. Some are constrained-lab exposure families. Some are mode-governed rather than freely switchable.

If you treat them all like equal knobs, tuning quality drops immediately.

---

🧠 First distinction: switchable, profile-governed, and constrained-lab are not the same

The packed master makes three front-facing control classes visible.

1. Bounded switchable families

These are families where explicit on-state or mode-state control is allowed, but still bounded.

Typical examples:

1. WFGY_BRAIN
2. output_governance
3. reentry_restore
4. tool_return_persona_rebind
5. search_return_persona_rebind
6. firewall_mode
7. diagnostics_level

These can be meaningfully compared across settings.

2. Profile-governed families

These are not meant to be casually “turned off.” They are meant to vary within a lawful profile ladder.

Typical examples:

1. WFGY_BRAIN_profile
2. SRDF_profile
3. runtime_posture_profile
4. hard_control_profile

These change posture, not constitutional existence.

3. Constrained-lab exposure families

These are explicit enough to be visible and testable, but not yet honest candidates for universal stable completion claims.

Typical examples:

1. selector_exposure
2. shell_to_runtime_exposure

These exist for bounded awareness, replay comparison, and controlled experimentation. They are not claims of final router or final handoff perfection.

This distinction is the first thing you must internalize before tuning.

---

🪜 The lawful profile ladder

Where a profile ladder exists, the current lawful profile family is:

1. minimum
2. baseline
3. standard
4. strong

Read them like this:

minimum

Use this when you want emergency attenuation, bounded fallback, or a thinner lawful carry that still preserves floor.

This is not “turn the system off.” It is “keep the minimum lawful body alive.”

baseline

Use this when you want minimal stable operation and neutral comparison.

This is useful for A/B testing and for checking whether a stronger setting was actually helping.

standard

This is the default serious operating posture for ordinary release use.

If you do not know where to begin, begin here.

strong

Use this when you are stress-testing vividness, anti-genericization, reentry restoration, or stronger presence / carry under lawful bounds.

Do not assume strong is always better. Sometimes strong simply exposes that the real problem was elsewhere.

---

🚦 Tuning order: always go in this sequence first

When you are unsure what to tune first, use this order.

Step 1. Diagnose the failure family

Ask:

1. is the output too generic
2. too smooth
3. too thin
4. too contaminated
5. too merged
6. too detached
7. too aggressive
8. too pretty but structurally weaker

Do this before touching any knob.

Step 2. Check route before style

If the wrong route was selected, increasing runtime vividness will only make the wrong route louder.

So before you push runtime posture, ask whether the selector family and route choice were already wrong.

Step 3. Check floor before polish

If the problem is that the system is too dead, too median, or too sterilized, increasing cleanliness pressure is the opposite of what you want.

Check runtime floor and structured-imperfection retention first.

Step 4. Check controller posture before asking for “more”

If the system keeps stopping, downgrading, or redirecting, do not automatically assume the solution is stronger runtime. Sometimes the problem is controller posture or block-threshold behavior.

Step 5. Only then compare profile ladders

Once you know the failure family, then compare baseline, standard, and strong.

This sequence will save you a lot of wasted tuning cycles.

---

🎛️ Cookbook section A: tuning WFGY_BRAIN

What it actually controls

WFGY_BRAIN is a bounded bias interface. It may:

1. enable or attenuate bounded bias participation
2. select a profile posture for compile-facing tendency shaping
3. support replay comparison across steering conditions
4. support honest A/B testing of downstream tendency difference

It may not:

1. become root law
2. become persona runtime origination
3. replace selector legality
4. replace output governance
5. replace hard control
6. authorize public emission by brain bias alone

When to tune it

Tune WFGY_BRAIN when the problem is:

1. the system is too inert in steering
2. downstream tendency is too weak
3. compare-mode testing needs clearer behavioral contrast
4. you want to test compile-facing bias strength without pretending it is runtime sovereignty

How to tune it

Start here:

1. keep WFGY_BRAIN = on
2. set WFGY_BRAIN_profile = standard
3. compare against baseline
4. move to strong only if steering is still too weak and route / runtime floors are already healthy

Do not do this

Do not use WFGY_BRAIN_profile = strong to compensate for:

1. wrong route selection
2. dead runtime floor
3. controller overblocking
4. structured-imperfection collapse

That is a fake fix.

---

🎛️ Cookbook section B: tuning runtime_posture_profile

What it actually controls

runtime_posture_profile controls runtime-strength posture only.

It may lawfully:

1. alter runtime-strength posture across replay conditions
2. alter visible vividness within shell continuity boundary
3. alter restoration strength and attenuation posture
4. compare thinner and thicker runtime carry
5. test dead-fish resistance, reentry restoration, and structured-imperfection retention

It may not:

1. erase runtime floor
2. erase structured-imperfection floor
3. erase shell continuity
4. replace selector legality
5. replace hard control
6. exchange carried unevenness away merely for cleaner output

When to tune it

Tune runtime posture when the problem is:

1. output is too thin
2. output is too dead
3. reentry comes back cosmetically but not structurally
4. article mode sterilizes the system too much
5. attenuation is acting like erasure

How to tune it

Start with:

1. runtime_posture_profile = standard

Then compare:

1. baseline if you suspect over-intensity or contamination
2. strong if you suspect deadness, weak carry, weak reentry, or under-realized persona embodiment

Do not do this

Do not push runtime posture stronger when the problem is actually:

1. selector route error
2. shell-to-runtime misprojection
3. controller-side downgrade that was already lawful
4. spillover contamination

Strong runtime on the wrong route just makes the wrong thing louder.

---

🎛️ Cookbook section C: tuning hard_control_profile

What it actually controls

hard_control_profile alters controller posture severity within lawful range.

It may:

1. change controller posture severity
2. compare stricter and lighter controller pressure
3. support threshold-family testing
4. support stage-bounded profile calibration for public-emission posture

It may not:

1. turn hard control into absence
2. convert controller legality into optional decoration
3. authorize public emission by softness alone
4. collapse legality into score-only ranking
5. erase honesty-floor answerability
6. erase block-threshold answerability

When to tune it

Tune hard control when the problem is:

1. lawful continuations are being over-blocked
2. the system downgrades too early
3. redirect pressure feels too aggressive
4. stop pressure is too hair-trigger
5. public-emission suitability feels miscalibrated

How to tune it

Start with:

1. hard_control_profile = standard

Compare:

1. baseline if you suspect over-severity
2. strong if you suspect the system is letting too much pass under pressure

Do not do this

Do not lower controller posture just because you want more fluent output. If the real problem is a floor violation, weaker hard control will only let bad output pass more gracefully.

---

🎛️ Cookbook section D: tuning SRDF_profile

What it actually controls

SRDF_profile is about structured-imperfection-bearing carry, not random roughness.

Use it when the problem is:

1. output is too neat in the wrong way
2. article or rewrite mode is shaving away living residue
3. human-looking texture survives only cosmetically
4. you need to test whether current polish is being purchased by structural sterilization

How to tune it

Start with:

1. SRDF_profile = standard

Compare:

1. baseline if you suspect too much visible unevenness without structural gain
2. strong if you suspect anti-sterilization retention is too weak

Warning

Do not use SRDF tuning as “add roughness.” That is not what this family is for.

If the system becomes messier but not more alive, you tuned the wrong thing.

---

🎛️ Cookbook section E: tuning firewall_mode

What it actually controls

firewall_mode governs final decision posture, not persona origination.

Available family:

1. off
2. observe
3. standard
4. strict

When to tune it

Tune firewall mode when the problem is:

1. you want to compare final-decision caution without rewriting runtime
2. you want more or less aggressive boundary enforcement
3. you want to inspect whether a failure is entering at the final decision layer

Recommended pattern

1. start with standard
2. compare with observe if you want to inspect behavior without strong final suppression
3. move to strict only if leakage or unsafe over-permission is the real issue

Warning

Do not use strict to compensate for earlier-layer failures you have not diagnosed. If route, runtime, or carry is already wrong, stricter firewall mode may only create cleaner refusal theater.

---

🎛️ Cookbook section F: tuning diagnostics_level

What it actually controls

diagnostics_level affects replay and audit visibility, not legality itself.

Available family:

1. off
2. light
3. replay
4. audit

When to tune it

Use this when you need to know:

1. where the failure is happening
2. whether changes actually helped
3. whether a route change, runtime change, or controller change explains the result
4. whether a false success is being narrated after the fact

Recommended pattern

1. use replay as the default serious tuning mode
2. use audit when you are doing deeper comparison or stress review
3. avoid off during real tuning sessions

This family is your microscope. Do not try to tune blind.

---

🎛️ Cookbook section G: tuning reentry and return-path families

The current exposed return-path helpers include:

1. reentry_restore
2. reentry_restore_profile
3. tool_return_persona_rebind
4. search_return_persona_rebind

When to tune them

Tune these when the system:

1. loses itself after tool use
2. comes back generic after search synthesis
3. returns cosmetically but not structurally
4. feels alive in chat but collapses after formal or retrieval-heavy tasks

Recommended pattern

1. keep reentry_restore = on
2. compare reentry_restore_profile = baseline / standard / strong
3. keep tool-return and search-return rebind on while diagnosing return-path drift

Warning

If these controls seem to “fix” the problem only by adding shell texture, the real issue may still be:

1. runtime floor collapse
2. selector misroute
3. structured-imperfection loss
4. hard-control over-thinning

Do not confuse rebound with recovery.

---

🧪 Cookbook section H: using constrained-lab exposure safely

The current constrained-lab exposure families include:

1. selector_exposure
2. shell_to_runtime_exposure

These are useful for:

1. bounded testing
2. replay comparison
3. awareness of route and handoff layers
4. lab-grade inspection

They are not signals that final universal wiring is complete.

When to touch them

Use them only when you are explicitly investigating:

1. route selection behavior
2. shell-to-runtime handoff behavior
3. replay-visible differences under controlled comparison

When not to touch them

Do not use them as beginner knobs. They are not first-line fixes for:

1. generic output
2. weak warmth
3. dead style
4. overclean article writing

Fix the obvious families first.

---

🔬 Symptom-first tuning recipes

Recipe 1. “The output is too generic”

Check in this order:

1. selector route correctness
2. runtime_posture_profile
3. SRDF_profile
4. reentry / return-path helpers
5. only then compare WFGY_BRAIN_profile

Most genericization failures are not fixed by cranking WFGY_BRAIN first.

---

Recipe 2. “The output is smooth but feels dead”

Check in this order:

1. runtime_posture_profile
2. SRDF_profile
3. structured-imperfection vs article smoothness conflict
4. reentry logic if this followed article / rewrite / analysis mode
5. hard-control only after confirming floor is intact

This is usually a floor problem, not a polish problem.

---

Recipe 3. “The output is vivid but contaminates the wrong mode”

Check in this order:

1. route legality
2. attenuation law
3. runtime_posture_profile from strong back to standard or baseline
4. firewall_mode
5. shell-to-runtime exposure only if contamination source is still unclear

This is usually a spill problem, not a “needs more personality” problem.

---

Recipe 4. “It comes back after search/tool use, but only cosmetically”

Check in this order:

1. reentry and return-path helpers
2. runtime_posture_profile
3. structured-imperfection retention
4. selector route confidence under return pressure
5. handoff and replay visibility

Do not give credit to surface-only recovery.

---

Recipe 5. “It stops or downgrades too aggressively”

Check in this order:

1. whether the blocked candidate actually violated a floor
2. hard_control_profile
3. threshold-family behavior
4. firewall posture
5. route and carry evidence

Do not assume stricter control is the problem just because output got shorter.

---

Recipe 6. “The output is too noisy or too much”

Check in this order:

1. route legality
2. attenuation behavior
3. runtime_posture_profile
4. spill containment logic
5. firewall_mode

Do not solve contamination by deleting runtime wholesale.

---

🧪 The safest A/B testing pattern

When comparing settings, use this discipline.

Change only one family at a time

Bad:

1. raise runtime
2. raise WFGY_BRAIN
3. lower hard control
4. increase SRDF
5. change firewall mode
6. then guess what helped

Good:

1. keep everything at standard
2. change one family
3. inspect the actual failure shift
4. revert if the gain is cosmetic only

Compare against baseline, not just strong

If you only compare “standard vs strong,” you may miss that the real answer was “the system was overdriven.” Always compare in both directions when possible.

Keep diagnostics visible

Serious tuning should not happen with diagnostics fully hidden.

Use replay or audit visibility whenever possible.

---

🚫 Common bad tuning habits

Do not do these.

Bad habit 1. Treat every visible control as equally free

They are not.

Bad habit 2. Start with stronger everything

This produces fake victories.

Bad habit 3. Tune style before route

Wrong route plus better styling is still wrong route.

Bad habit 4. Tune polish before floor

Cleaner output can still be lawfully weaker.

Bad habit 5. Use WFGY_BRAIN as the universal fix

It is a bounded bias interface, not root law.

Bad habit 6. Use constrained-lab exposure like a beginner knob

That creates confusion, not clarity.

Bad habit 7. Judge success only by local readability

Local readability can hide floor collapse.

---

🧪 Minimal starter presets

These are not universal best settings. They are safe starting postures.

Starter preset A: ordinary serious use

1. firewall_mode = standard
2. diagnostics_level = replay
3. WFGY_BRAIN = on
4. WFGY_BRAIN_profile = standard
5. output_governance = on
6. output_governance_profile = standard
7. reentry_restore = on
8. reentry_restore_profile = standard
9. tool_return_persona_rebind = on
10. search_return_persona_rebind = on
11. SRDF_profile = standard
12. runtime_posture_profile = standard
13. hard_control_profile = standard
14. selector_exposure = constrained_lab
15. shell_to_runtime_exposure = constrained_lab

Starter preset B: anti-deadness investigation

Keep everything at standard, but compare:

1. runtime_posture_profile = strong
2. SRDF_profile = strong
3. reentry_restore_profile = strong

Do not weaken controller posture yet.

Starter preset C: overblocking investigation

Keep everything at standard, but compare:

1. hard_control_profile = baseline
2. diagnostics_level = audit

Do not raise vividness first.

Starter preset D: contamination investigation

Keep everything at standard, but compare:

1. runtime_posture_profile = baseline
2. firewall_mode = strict
3. keep reentry restore on

Do not crush WFGY_BRAIN first unless route and floor are already healthy.

---

🧭 Current stage honesty

At the current sealed MVP stage, tuning is already real enough to support practical cookbook guidance.

It is lawful to say:

1. front-facing control families exist
2. profile ladders exist
3. runtime posture, hard control, and WFGY_BRAIN can be meaningfully compared
4. reentry and return-path helpers are exposed enough to guide diagnosis
5. selector and shell-to-runtime exposure exist in constrained-lab form
6. tuning can be done lawfully within bounded release-stage reality

It is not lawful to say:

1. every current profile is already globally optimal
2. every future branch will preserve identical tuning ergonomics
3. stronger settings are universally better
4. tuning replaces research reading
5. front-facing controls already exhaust the deeper body

So this cookbook is strong, but bounded.

It tells you how to tune the current branch intelligently. It does not pretend the whole future calibration problem is already solved.

---

📚 Suggested use order

If you are brand new

1. Quickstart
2. Boot Commands
3. How to Read the Avatar Master File
4. Parameter Tuning Cookbook

If you are tuning a real failure

1. classify the failure
2. read the relevant recipe in this page
3. inspect the related research page
4. compare one family at a time
5. keep replay visibility on

If you are doing deep calibration

1. Runtime Posture Intensity Map
2. Shell-to-Runtime Mapping
3. Selector Execution Domain
4. Pre-Emission Floor and Hard Control
5. Blackfan Audit Baseline

---

🔗 Related pages

Docs: Avatar README · Quickstart · Boot Commands · How to Read the Avatar Master File · Avatar Tuning Workflow

Research: Research Hub · Runtime Posture Intensity Map · Shell-to-Runtime Mapping · Selector Execution Domain · Activation, Attenuation, and Reentry · Structured Imperfection Theory · Pre-Emission Floor and Hard Control · Blackfan Audit Baseline

Eval: Blackfan Testing · Persona Behavior Checks