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
contract][PRODUCT], 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, chapters 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:

`guild forecast -> roster and job plan -> equipment and formation -> route commitment -> readable auto-battle with bounded intervention -> causal result -> recovery or reward -> guild progression`

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

| Boundary | Player question | Required state change | Required handoff |
|---|---|---|---|
| Guild forecast | What pressure is approaching, and what can I prepare for? | Threat and opportunity information becomes actionable | Opens roster, job, equipment and route planning without hiding constraints |
| Roster and job plan | Which people and capabilities form the expedition thesis? | Recruits receive explicit jobs and responsibilities | Formation and equipment previews expose consequences |
| Equipment and formation | What behavior, timing and position will each choice change? | Loadout and order create a testable battle plan | Route commitment summarizes the plan's known strengths and risks |
| Route commitment | Which uncertainty is worth accepting now? | Resources and risk are committed | Battle starts from a reviewable snapshot |
| Battle | Is the prepared plan working, and why? | The simulation resolves with sparse, legible intervention windows | Result view preserves the causal record |
| Result | What succeeded, where did the first failure begin, and what changed? | Rewards, injuries, losses and discoveries are explained | Recovery and progression actions are offered in context |
| Recovery or reward | How should the guild adapt rather than merely restore numbers? | The next plan gains a new option, constraint or tradeoff | Returns to forecast with a meaningfully changed decision space |

This loop preserves anticipation, observation and diagnosis while giving the
original game its own guild-management framing, route logic and intervention
rules.

## Decision Timing

### Opening

The first interactive state should ask for a real build commitment using a
small, understandable option set. Onboarding may stage information, but it
should not make the opening plan on the player's behalf. The choice must expose
what changes in role, resource pressure or formation behavior.

### Before Battle

Route, equipment, job and formation choices should converge in a plan review.
The review must show projected responsibilities and known threats without
pretending to predict the exact simulation. Reversible edits stay reversible
until commitment; destructive or costly changes require explicit confirmation.

### During Battle

Automatic execution is valuable only when cause remains inspectable. Each
bounded intervention should answer a distinct tactical question and preserve
the value of preparation. Slow playback, pause where platform rules allow, and
event inspection are diagnostic controls; they are not separate game modes.

### 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. Replacement
availability, injury handling, debt, route retreat and guild support should be
authored as economy rules. A platform-funded revival cannot be the balancing
assumption.

### Persistent Progression

Persistent rewards should open new planning grammar: information, formation
options, profession transformations, route tools, recovery policies or
resource conversions. Flat universal bonuses may support progression, but
cannot carry it alone because they do not create a new decision.

## Content Grammar

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

| Content family | Required differentiators | Filler rejection test |
|---|---|---|
| Recruit | Personal constraint, decision preference, formation responsibility, profession affinities, recovery consequence and relationship hook | Reject when swapping the name and portrait leaves every decision unchanged |
| 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 |
| Advanced profession | A transformation of targeting, timing, position, resource flow or risk ownership | Reject when it is only a stronger version of the base profession |
| Enemy identity | 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 |
| Equipment or item | Eligible users, changed verb, trigger, tradeoff, positioning consequence, comparison rule and visible feedback | Reject when only a scalar value or rarity changes |
| Milestone relic | Build-level contingency, route-valuation change, conflict with other plans and a visible trigger | Reject when it is merely a larger generic bonus |
| Chapter | New route pressure, enemy grammar, economy stress, environmental rule, recovery question, boss synthesis and lasting guild consequence | Reject when it is only a visual reskin with larger numbers |
| Achievement | Explicit behavior worth recognizing, progress visibility, completion condition and non-distorting reward | Reject when it rewards passive repetition without teaching or celebrating mastery |
| Collection entry | Discoverability rule, readable unknown state, provenance, completion semantics and accessibility text | Reject when it exposes spoilers or exists only to inflate completion time |

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 |
|---|---|---|---|
| Forecast | Route pressure, known threat, opportunity and deadline | Guild capacity and recovery exposure | Full historical statistics |
| Recruit or job choice | Responsibility gained, constraint accepted and team interaction | Growth path and equipment eligibility | Complete progression tree |
| Equipment | Changed behavior, eligible target, replacement result and resource cost | Synergies and comparison detail | Collection lore |
| Formation | Order, targeting exposure, protection relationship and movement implication | Alternate saved plans | Cosmetic presentation |
| Route commitment | Expected risk, reward class, uncertainty and irreversible cost | Relevant counters and recovery reserve | Unrelated collection progress |
| Battle | Current objective, dangerous cause, intervention availability and speed state | Aggregate team state | Long-form build explanation |
| Result | First collapse, decisive interaction, injuries/losses and earned choices | Contribution detail and event log | Meta collection celebration |
| Progression | New decisions unlocked and prerequisites | Long-term path preview and reset consequence | Unrelated branch 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, exact product-specification commitments, not observed or
inferred reference totals. Their authority is the [frozen product contract][PRODUCT].

| Original content family | Approved count | Evidence class and exactness | Planning consequence |
|---|---:|---|---|
| Named recruitable characters | 30 | Direct specification; exact | Each row needs a distinct personal constraint and build role. Shared rigs may support production, but identities cannot be palette variants. |
| Base professions | 12 | Direct specification; exact | The base set must cover genuinely different responsibilities and resource verbs. |
| Advanced professions | 24 | Direct specification; exact | Each base profession receives authored transformations whose decision impact survives comparison. |
| Enemy combat identities | 100 | Direct specification; exact | Encounter design must compose rule interactions, not multiply visual variants. |
| Chapters | 8 | Direct specification; exact | Each chapter adds a decision grammar and culminates in a synthesis encounter. |
| Equipment and items | 320 | Direct specification; exact | Production should use coherent families while keeping each gameplay record traceable. |
| Behavior-changing equipment and items | At least 120 | Direct specification; lower-bound acceptance threshold | Validators must flag rows that change behavior, targeting, timing, positioning, resources or job identity and reject unsupported claims. |

The reference census neither proves nor justifies these targets. It demonstrates
why gameplay rows and presentation assets need separate budgets. The original
contract remains the sole authority for scope.

## 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, impact readability, misses and mitigation, status changes, death or
withdrawal, intervention readiness, 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 | Build an original graph, prerequisites, branch meanings and reset policy |
| Adapt | Combine related preparation questions where it reduces navigation | Use an original information architecture; do not reproduce the reference arrangement |
| Adapt | Use milestone 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, intervention
  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 job, 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