aetherbound-guild/docs/reference/TRANSFERABLE_STRUCTURE_LESSONS.md

# Transferable Structure Lessons

## Use And Originality Boundary

This document converts the authorized census into independently authored
planning guidance for Aetherbound Guild. It transfers system roles, decision
timing, information needs and production implications only. It does not
transfer reference names, prose, formulas, prices, layouts, progression trees,
visual composition, art, animation, music, sound effects or source code.

Reference counts remain evidence about a captured build, not targets for this
project. Aetherbound Guild's scope comes exclusively from the [frozen product
specification][PRODUCT] and [current game contract][GAME], while factual support
comes from the [runtime census][CENSUS].

## Evidence-To-Lesson Trace

| Census evidence | What it supports | What it does not authorize |
|---|---|---|
| C-02 through C-06 | Recruits, professions and persistent branches can create overlapping build axes | Copying labels, branch themes, node topology, unlock order or values |
| C-08 and C-09 | Enemy readability benefits from role-level telegraphing before commitment | Copying enemy identities, silhouettes, attacks or encounter compositions |
| C-10 through C-13 | Equipment and milestone rewards can change party behavior and contingency planning | Copying item or artifact identities, effects, rarity rules, prices or tooltip prose |
| C-14 and C-15 | Party order is a meaningful preparation decision | Copying a formation layout, slot count or exact battlefield mapping |
| C-16 through C-19 | Environment production and run progression need separate accounting | Treating asset families, victories, progress markers and waves as interchangeable units |
| C-20 through C-23 | Collection, achievement and mode scope must be authored explicitly because the reference totals are unknown | Filling gaps with guesses from menu labels, scripts or assets |
| A-01 through A-08 | Layered presentation has a large and multi-category production footprint | Treating files, frames, types or component instances as gameplay content |

## Original Core-Loop Structure

Aetherbound Guild should use the following independently authored loop:

`contract forecast -> provisional Recruit selection or Market planning -> equip and order the Party line -> battle-offer commitment -> readable automatic battle -> causal result -> recovery or reward -> next Market or Guild progression`

The transferable lesson is the separation of player questions, not the
reference screen sequence:

| Boundary | Player question | Required state change | Required handoff |
|---|---|---|---|
| Contract forecast | What pressure is approaching, and what can I prepare for? | Enemy families, boss rules, difficulty and reward breadth become actionable | Opens provisional Recruit selection or the stable Market without hiding constraints |
| Recruit and Market plan | Which generated offers add the needed capability under current Coin, capacity and recovery pressure? | Selection or hire commits a generated Recruit with a fixed Profession, one Trait and visible tradeoffs | Equipment and Party-line previews expose consequences |
| Equipment and Party line | What behavior, timing and order will each choice change? | Loadout and front-to-rear order create a testable battle plan | Battle-offer commitment summarizes known strengths, risks and failure exposure |
| Battle-offer commitment | Which disclosed risk is worth accepting now? | One seeded offer and its resources are committed | Battle starts from a reviewable snapshot |
| Battle | Is the prepared plan working, and why? | The deterministic simulation resolves without manual skill activation or in-battle reordering | Result view preserves the causal record |
| Result | What succeeded, where did the first failure begin, and what changed? | Rewards, Fallen Recruits, returned equipment and discoveries are explained | Recovery and progression actions are offered in context |
| Recovery or reward | How should the Company adapt rather than merely restore numbers? | The next plan gains a new option, constraint or tradeoff | Returns to the next Market or Guild with a meaningfully changed decision space |

This loop preserves anticipation, observation and diagnosis while giving the
original game its own Company-management framing, Market economy and fully
automatic battle rules.

## Decision Timing

### Opening

The first interactive state should ask the player to select two of four
provisional generated Recruits before Run creation. Selection remains revisable
until commit, and the comparison must expose Profession responsibility, Trait
benefit and cost, rolled attributes, and Party-line implications. Onboarding
may stage information, but it must not make the opening plan for the player.

### Before Battle

Market, equipment, Profession, Party-line and battle-offer choices should
converge in a plan review. The review must show projected responsibilities,
known threats and exact failure exposure without pretending to predict every
simulation event. Reversible edits stay reversible until commitment;
destructive or costly changes require explicit confirmation.

### During Battle

Automatic execution is valuable only when cause remains inspectable. Battle
provides start, pause, speed, inspect and retreat controls, but no repeated
manual skill activation and no in-battle equipment or Party-line editing.
Playback and event inspection are diagnostic controls; presentation speed must
not change the deterministic result.

### After Battle

The first post-battle view should identify the earliest meaningful collapse,
the interaction that caused it and the downstream cost. Contribution totals
are secondary to a causal timeline. Reward selection follows diagnosis so that
the next choice responds to what the player just learned.

### After Failure

Recovery must create a new viable plan without erasing consequence. Fallen
Recruits remain removed for the Run, their equipment returns, death creates
Replacement Credit, and the next Market protects an affordable base-Profession
offer under the current product rules. Recovery must remain an authored economy
contract; platform-funded revival cannot be its balancing assumption.

### Persistent Progression

Persistent rewards should open breadth: information, Profession sidegrades,
previews, challenges, catalog access and optional rule changes. They must not
grant permanent universal damage, health, Coin income or starting-capacity
advantages that replace Run decisions.

## Content Grammar

Every content row should declare its player-facing function before art production.
The following schemas are original planning requirements, not reconstructions
of reference data.

| Content family | Required differentiators | Filler rejection test |
|---|---|---|
| Generated Recruit | Generated identity seed, modular appearance, fixed Profession, equal-budget rolled attribute distribution, exactly one Trait, equipment, level, price and offer provenance, survival history and recovery consequence | Reject any rule that treats a name or appearance combination as another gameplay identity or requires authored personal or social content |
| Base profession | Battlefield responsibility, resource verb, preferred position, readable cadence, failure mode and counterplay | Reject when it is only a stat package or element label |
| Regular advanced or hidden hybrid Profession | A transformation of targeting, timing, position, resource flow or risk ownership with declared prerequisites | Reject when it is only a stronger version of an existing Profession |
| Trait | One visible mechanical benefit and one cost that change offer, equipment or Party-line valuation | Reject when it is biography, flavor-only text or an unbounded extra rules bundle |
| Equipment | Eligible users, changed verb, trigger, tradeoff, order consequence, comparison rule and visible feedback | Reject when only a scalar value, rarity or presentation variant changes |
| Artifact | Run-wide contingency, Market or battle-offer valuation change, conflict with other plans and a visible trigger | Reject when it attaches as ordinary unit equipment or is merely a larger generic bonus |
| Ordinary or elite enemy | Pre-commitment signal, threat rule, target pressure, counter, ally interaction, escalation state and result explanation | Reject when color or health is the only meaningful difference |
| Boss | Contract-rule synthesis, phase and timeout logic, summon or displacement pressure, previewed counters and causal result needs | Reject when it is an ordinary enemy with only larger numbers |
| Region | New composition or Market pressure, formation-order valuation, environmental rule, recovery question and two-Contract escalation | Reject when it is only a visual reskin with larger numbers |

The matrices should distinguish an **identity** from its **presentation
variants**. Rarity, level, portrait expression, equipment overlay, animation
frame, VFX layer and localization string belong to production tables, not to
the gameplay-identity count.

## Information Hierarchy

Information should be organized around the current decision rather than around
the underlying data model.

| Moment | Primary information | Secondary information | Deferred detail |
|---|---|---|---|
| Contract forecast | Region pressure, enemy families, boss rule, difficulty and reward breadth | Guild unlocks and recovery exposure | Full historical statistics |
| Provisional Recruit or Market offer | Profession responsibility, Trait benefit and cost, rolled attributes and Coin price | Party-line fit, equipment eligibility and offer provenance | Generated-name and appearance detail |
| Equipment | Changed behavior, eligible target, replacement result and resource cost | Synergies and comparison detail | Collection lore |
| Party line | Front-to-rear order, target exposure, protection, reach and movement implication | Reserve options and predicted first interactions | Cosmetic presentation |
| Battle-offer commitment | Enemy order, risk tier, reward, retreat result and irreversible cost | Relevant counters and recovery reserve | Unrelated collection progress |
| Battle | Current objective, dangerous cause, pause/speed/inspect/retreat state | Aggregate Company state | Long-form build explanation |
| Result | First collapse, decisive interaction, Fallen Recruits, returned equipment and earned choices | Contribution detail and event log | Meta collection celebration |
| Meta progression | New breadth, information and challenge rules | Long-term catalog and mastery prerequisites | Unrelated history detail |

Tooltips must explain changed behavior in the same vocabulary used by battle
and results. Empty, locked, unaffordable, incompatible, full-capacity and
destructive states need authored reasons and next actions. Accessibility labels
must carry meaning without relying on color, animation speed or audio alone.

## Approved Original Scope

These are direct product commitments, not observed or inferred reference
totals. Their authority is the [frozen product specification][PRODUCT] and
[current game contract][GAME]; stable identity namespaces are recorded in the
[content matrix authority][CONTENT].

| Original content family | Approved count | Evidence class and exactness | Planning consequence |
|---|---:|---|---|
| Generated Recruits | Dynamic; no preset identity total or cumulative-hire cap | Direct specification; structural | Each Recruit is a compositional Run participant. Generated name and modular appearance do not create additional gameplay identities. |
| Base professions | 12 | Direct specification; exact | The base set must cover genuinely different responsibilities and resource verbs. |
| Regular advanced Professions | 24 | Direct specification; exact | Each base Profession has exactly two regular descendants whose decision impact survives comparison. |
| Hidden hybrid Professions | 6 | Direct specification; exact | Hybrid prerequisites and behavior must be discoverable and mechanically distinct; the full Profession catalog totals 42. |
| Mechanical Traits | 36 | Direct specification; exact | Every Recruit has exactly one lightweight benefit-and-cost modifier. |
| Equipment | 320 | Direct specification; exact | Production should use coherent families while keeping each behavior record traceable. |
| Artifacts | 60 | Direct specification; exact | Each identity changes shared Run valuation and remains distinct from unit equipment. |
| Ordinary and elite enemies | 100 | Direct specification; exact | Encounter design must compose rule interactions, not multiply visual variants. |
| Bosses | 16 | Direct specification; exact | Each boss synthesizes its Contract and exposes its distinctive rules before commitment. |
| Regions | 8 | Direct specification; exact | Each Region contains two ordered Contracts and two bosses and introduces a distinct pressure or valuation question. |

The reference census neither proves nor justifies these targets. It demonstrates
why gameplay rows and presentation assets need separate budgets. The frozen
specification and current game contract remain the sole authorities for scope;
the content matrix records their stable IDs and currently requires at least 160
of the 320 equipment rows to change behavior rather than only a scalar.

## Production-Scope Implications

### Separate Ledgers

Maintain linked but independent ledgers for:

- gameplay identities and their rules;
- screen and state coverage;
- portraits, bodies, equipment layers and environment sets;
- animation states, transitions and reusable motion families;
- VFX events and readability roles;
- SFX events, variations, cooldowns, polyphony and mix states;
- music states and transitions;
- localization strings and accessibility alternatives.

One gameplay identity may need many presentation assets, and one presentation
asset may support many identities. Neither ledger may derive its total from the
other.

### Reuse With Legibility

Shared rigs, motion families, equipment layers and effect grammars are valid
scope controls when silhouettes, timing and cause remain readable. Reuse must
be planned from the original art direction. It cannot trace or imitate the
reference actor construction or asset style.

### Author Behavior Before Variants

Approve an identity only after its trigger, tradeoff, counterplay, interaction
and feedback are specified. Rarity and numerical tuning come later. This keeps
variant production from disguising an incomplete content matrix.

### Count States, Not Just Screens

The gallery and prototype must cover success, failure, empty, locked,
unaffordable, incompatible, full-capacity, confirmation, cancellation,
recovery, postgame and accessibility states. A screen title alone does not
prove the workflow is designed.

### Budget Diagnostic Feedback

Auto-battle production scope includes more than attacks. It needs pre-commit
telegraphs, cast and impact readability, misses and mitigation, target changes,
projectile collisions, displacement, summons, status changes, casualties,
retreat, speed-safe feedback and result causality. Animation, VFX and audio
budgets should map to these event roles before bulk asset creation.

## Adopt, Adapt, Reject

| Decision | Structural guidance | Originality guardrail |
|---|---|---|
| Adopt | Make pre-battle choices visibly affect automated outcomes and make results diagnostic | Author new rules, vocabulary and presentation for every state |
| Adopt | Use recovery to keep failure consequential but playable | Balance from the original economy, without platform-funded rescue assumptions |
| Adopt | Let persistent progression expand the planning space | Open original breadth, information and challenge rules without permanent universal power |
| Adapt | Combine related preparation questions where it reduces navigation | Use an original information architecture; do not reproduce the reference arrangement |
| Adapt | Use Artifacts and fixed rewards as build pivots | Create original identities, triggers, conflicts and visual language |
| Adapt | Use modular asset production to control scope | Define original silhouettes, rigs, layers and animation grammar |
| Reject | File counts as evidence of gameplay breadth | Validate content matrices and asset inventories separately |
| Reject | Speed settings, tutorials or UI states counted as content modes | Define mode boundaries by rules, progression and failure contract |
| Reject | Scalar-only rows presented as distinct content | Enforce the filler rejection tests before review |
| Reject | Copied names, prose, formulas, prices, layouts, topology or expressive assets | Keep all product-facing work independently authored and source-traceable |

## Downstream Design Requirements

The census should change downstream work in concrete ways:

- **Systems specifications:** define the full loop handoffs, automatic-battle
  control boundary, failure recovery, persistence and save semantics.
- **Content matrices:** assign stable original IDs and the differentiator fields
  above; maintain separate variant and asset references.
- **Screen/state map:** show decision-specific hierarchy, reversible and
  irreversible transitions, all error/empty/locked states and diagnostic
  results.
- **Art and animation plan:** budget by original actor family, equipment layer,
  event state and environment need, never by reference export counts.
- **Audio plan:** budget event roles, variants and mix behavior, never one event
  per archived clip.
- **Economy and build simulations:** test whether recovery preserves viable
  counterfactuals and whether persistent progression creates choices rather
  than only larger values.
- **Interactive prototype:** verify that players can predict a plan, identify
  the first collapse and state the next adaptation without seeing hidden
  formulas.

## Review Gate

Before any lesson enters a product-facing artifact, reviewers should be able to
answer yes to all of the following:

- Is the lesson traceable to a census row or the frozen original contract?
- Is it stated as a player decision or production requirement rather than a
  copied implementation?
- Are reference lower bounds kept separate from original targets?
- Are gameplay identities kept separate from assets, frames, layers and UI
  states?
- Are names, prose, formulas, values, layouts, trees, art and audio independently
  authored?
- Does the result add a distinct decision, counterfactual or information need rather
  than a cosmetic variant?

Failure of any answer is an originality or completeness blocker during the
design-only stage.

[CENSUS]: REFERENCE_RUNTIME_CENSUS.md
[PRODUCT]: ../../.agent-taskgraph/spec.md
[GAME]: ../product/GAME_PRODUCT_CONTRACT.md
[CONTENT]: ../content/CONTENT_INDEX.md