# Hermetic Foundry Schema Addendum v0.3.19

This ZIP contains the Hermetic Foundry XML schema set using the current `xml-schemas/` root and `xml-schemas/entities/` directory structure.

Version 0.3.19 is a documentation-only schema set. It adds developer-facing `xs:annotation` / `xs:documentation` coverage for root schemas, shared types, entity roots, domain payloads, and important enums without changing validation semantics, element names, order, occurrence rules, namespaces, or package content. Version 0.3.18 extends the existing `hf:mediaAssetType` picture metadata pattern to Creatures, Covenants, Laboratories, and Items. Version 0.3.17 adds shared Quick Item profile overlays for mundane, magical, relic, supernatural, and laboratory-linked item records while preserving first-class Item, Equipment, Weapon, Armor, and Book schemas. Version 0.3.16 adds optional structured Quick Laboratory alpha data for owner links, signed characteristics, refinement support, personality traits, specializations, selected Laboratory Virtues and Flaws, enchanted item placeholders, and notes. Version 0.3.15 adds optional structured Quick Covenant alpha data for identity, selected Boons and Hooks, members, governance, resources, library, lab texts, casting tablets, vis, laboratories, finances, and notes. Version 0.3.14 adds optional structured Quick Creature Combat data for rich-text Soak, Fatigue, Wound Penalties, and repeated Attack, Armor, and Weapon rows. Version 0.3.13 corrects Quick Creature selected Creature Powers with source-facing Might Cost and Initiative text, Art requisites, optional Level, and expanded R/D/T values required by package-backed Creature Powers. Version 0.3.12 added structured creature-side selected power rows for Quick Creature Powers. Version 0.3.11 formalizes the Familiar reconciliation schema set after v0.3.10 added structured magus-owned familiar bond powers/enchantments. Version 0.3.9 added an optional NPC/free-build flag for characters. Version 0.3.8 added first-pass Spell Mastery schema support. Version 0.3.6 adds future-proof parameter-aware references for rules requirements/prohibitions. Version 0.3.5 expanded the character model to support printable Ars Magica character-sheet data, including fields visible on the standard Ars Magica character sheet.

## Schema documentation in v0.3.19

Version 0.3.19 adds annotations intended for developers, future Codex passes, XML Carousel, and generated schema documentation.

The annotations focus on:

- global document roots and schema-specific entity roots
- shared identity, canonical ID, reference, snapshot, provenance, validation, change-history, Quick Sheet, and media metadata types
- Quick Item composition profiles and their boundaries
- Character, Creature, Covenant, Laboratory, Item, Equipment, Book, Ability, Virtue/Flaw, rules-impact, and package-support payload types
- enum intent and data-model ownership notes where a raw value list is not self-explanatory

This version does not add UI help text, gameplay rules automation, XML Carousel screens, schema constraints, new elements, new attributes, or new package content. Version 0.3.18 and older supported schema versions remain loadable by the app.

## Picture metadata support in v0.3.18

Version 0.3.18 reuses `hf:mediaAssetType` for:

- `creatureData/creatureArt`
- `covenantData/covenantArt`
- `laboratoryData/laboratoryArt`
- `itemData/itemArt`

These fields store metadata and local/package-relative references such as `relativePath`, `fileName`, `mimeType`, `displayName`, `altText`, and `description`. They do not embed binary media, base64 content, or copied Ars Magica visual assets.

## Namespace and schema locations

The namespace URI remains:

```xml
http://hf.wolfshafenpress.com/xml-schemas
```

Namespaced entity XML should continue to use standard two-part `xsi:schemaLocation` values. The namespace URI remains HTTP; Hermetic Foundry app-generated XML and project regression fixtures use HTTPS schema document locations:

```xml
xsi:schemaLocation="http://hf.wolfshafenpress.com/xml-schemas https://hf.wolfshafenpress.com/xml-schemas/foundry-entity.xsd"
```

Schema-specific fixtures use the corresponding HTTPS entity schema document locations under `entities/`.

## Quick Item schema groundwork in v0.3.17

Version 0.3.17 extends `entities/items.xsd` with an optional `itemCategory` enum for:

- Mundane Item
- Arcane Connection
- Casting Tool / Casting Item
- Enchanted Device
- Talisman
- Relic
- Other Supernatural Item
- Laboratory Magic Item / Feature

The schema intentionally does not add Quick Item categories for Siege Engine / Large War Gear, Laboratory Text, Casting Tablet, or Raw Vis Stock. Laboratory Text and Casting Tablet remain future/system-specific work outside this Quick Item pass.

Shared profile overlays in `foundry-common.xsd` allow Item, Equipment, Weapon, and Armor records to compose physical details with arcane connection, casting tool, enchantment, talisman, relic, supernatural, laboratory item, shape/material bonus, effect/power, and stat data. A magic sword can remain a `Weapon`; an enchanted suit of armor can remain `Armor`; and a talisman can also carry physical or enchantment data.

Book/Text remains the existing separate `Book` entity. Version 0.3.17 does not fold books into generic items and does not redesign Quick Book.

## Quick Laboratory alpha data in v0.3.16

Version 0.3.16 extends `entities/laboratories.xsd` additively around the existing Laboratory payload. The older repeated `virtue` and `flaw` references remain valid for existing Laboratory XML and package references.

New optional Laboratory data stores local Quick Laboratory rows: `name`, manual/linked `owner`, manual/linked `associatedCovenant`, positive whole `squareFeet`, signed Size/Refinement/General Quality/Upkeep/Safety/Warping/Health/Aesthetics scores, refinement derivation notes, `personalityTrait`, `specialization`, `selectedVirtue`, `selectedFlaw`, `enchantedItem`, and rich `notes`.

Selected Laboratory Virtues and Flaws may preserve package references while storing local display names, magnitude/category/source fields, custom flags, selected parameters, selected modifiers, notes, and sort order. Custom rows can be stored directly on the Laboratory without creating separate package content.

Shared additions include `hf:positiveWholeNumberType`, `hf:dualFieldType`, Laboratory specialization enums for Arts and Activities, active/dropped specialization status, and Laboratory enchanted-item mode values. Version 0.3.16 also extends `entities/laboratory-features.xsd` with optional package-side `parameter` and `specializationGrant` metadata while preserving existing `modifier` rows.


## Quick Covenant alpha data in v0.3.15

Version 0.3.15 extends `entities/covenants.xsd` additively. Existing Covenant elements remain valid, including `charter`, `boon`, `hook`, `member`, `laboratory`, `visSource`, `situation`, `resourceProfile`, `ruleSection`, `procedure`, `organizationModel`, `financeModel`, and `loyaltyModel`.

New optional `covenantData` children support local Quick Covenant rows: `identityProfile`, `boonSelection`, `hookSelection`, `memberEntry`, `governance`, `resources`, `library`, `labTexts`, `castingTablets`, `vis`, `laboratories`, `finances`, and general `notes`. Package-backed rows can retain `hf:referenceType` links while storing local selected values such as display names, point values, quantities, source notes, and rich-text notes.

Structured Vis Source and Vis Stock rows store user-facing display names alongside Art, pawn, Build Point, and notes fields so Quick Covenant entries can round-trip without relying on package examples or flat summaries.

The new `hf:covenantAccessiblePowerLevelEnum` stores covenant creation accessible power levels (`Low`, `Medium`, `High`, `Legendary`, `Variable`, `Other`) separately from the existing `hf:covenantPowerLevelEnum` (`Weak`, `Medium`, `Powerful`, `Variable`, `Other`) used by base resource profiles.

Flat `quickSheet` fields may still be present for preview/search compatibility, but structured `covenantData` is the durable Quick Covenant alpha storage.


## Creature combat in v0.3.14

Version 0.3.14 adds optional `creatureData/combat` support to `entities/creatures.xsd`. The combat block stores rich-text `soak`, `fatigue`, and `woundPenalties` fields, plus repeated structured `attack`, `armor`, and `weapon` rows.

Attack and weapon stat fields remain flexible strings so ordinary Ars Magica notation such as `+8`, `-4`, `0`, `n/a`, and prose notes can round-trip without over-constraining source material. Older creature XML without `creatureData/combat` remains valid.

## Creature selected powers in v0.3.13

Version 0.3.13 expands selected Creature Power rows so package-backed powers can be selected without losing Ars Magica notation details. A selected power stores `technique` plus repeated `techniqueRequisite`, `form` plus repeated `formRequisite`, optional `level`, source-facing `mightCost`, source-facing `initiative`, `range`, `duration`, `target`, and rich-text `effect`.

This supports powers such as `Cr(Re)Ig 30` and `ReMe(An) 45`, including formulaic initiatives like `Qik-2`, negative initiatives, Target `Spectacle`, Target `Sight`, and Range `Special`.

## Creature selected powers in v0.3.12

Version 0.3.12 changes `creatureData/power` from a reference-only entry into a structured selected-power row. A selected power may still carry an optional package `reference`, but it now also stores the creature-facing `name`, `mightCost`, `initiative`, `technique`, `form`, `range`, `duration`, `target`, and rich-text `effect`.

This supports Quick Creature as an actual creature sheet: a package-backed Creature Power can be selected, customized where needed, ordered by document order for manual ordering, and saved without losing its local rules values.

Shared schema types added in v0.3.12:

- `hf:techniqueArtType`
- `hf:formArtType`
- `hf:spellRangeType`
- `hf:spellDurationType`
- `hf:spellTargetType`
- `hf:nonNegativeWholeNumberType`

Existing package Creature Power entity data remains separate from selected creature-sheet power rows.

## Familiar reconciliation versioning in v0.3.11

Version 0.3.11 updates the active schema set version for the Familiar reconciliation model introduced in v0.3.10. The XML ownership model is unchanged: Creature XML stores creature-side facts, while Magus Character XML stores familiar relationship data.

## Familiar bond ownership in v0.3.10

Version 0.3.10 keeps Creature XML creature-focused and stores magus-familiar relationship state on the magus Character XML.

Key addition:

- `entities/characters.xsd` adds repeated `magicProfile/familiarBond/bondPower` entries using the existing `hf:selectedContentType` shape. Character familiar bonds now have a structured place for bond powers/enchantments alongside the familiar reference, Bronze/Silver/Gold cords, repeated bond qualities/abilities, and relationship notes.

Ownership rule:

- Creature XML owns creature facts such as Might, powers intrinsic to the creature, qualities, habitat, and creature-side descriptive fields.
- Character XML owns familiar relationship facts such as cord scores, bond qualities or abilities, bond powers or enchantments, and relationship notes.
- Existing optional snapshot/stat fields under `familiarBond` are retained for backwards compatibility and should be treated as cached display snapshots, not as the authoritative creature record.

## NPC/free-build character flag in v0.3.9

Version 0.3.9 adds optional character-level NPC support for Quick Character / character-sheet workflows.

Key addition:

- `entities/characters.xsd` adds `identityAndBackground/npc` as an optional boolean. When true, Hermetic Foundry should treat the character as a non-player/free-build character: character creation rule issues should still be reported to the user, but should not block character creation or saving. The flag does not override basic XML/data-integrity requirements.

## Spell Mastery additions in v0.3.8

Version 0.3.8 models Spell Mastery as a specialized Ability rather than a new top-level Ability category.

Key additions:

- `entities/abilities.xsd` adds `abilityKind`, with `Standard` and `SpellMastery` values.
- Spell Mastery Ability definitions can declare `masteredSpellRequired`, `specialtyAllowed`, and repeated special mastery ability definitions.
- Spell Mastery remains under the existing `Arcane` Ability category.
- `entities/characters.xsd` adds selected Ability `spellMastery` data, including an optional mastered spell reference, selected special mastery abilities, snapshots, and notes.
- The v0.3.8 regression fixtures cover both a package-backed `(Spell) Mastery` Ability and a character that has selected Spell Mastery for `Pilum of Fire`.

## Parameter-aware references in v0.3.6

Version 0.3.6 keeps existing v0.3.5 package XML valid while allowing future package content to express rules such as “this entity prohibits that entity only when a particular parameter value is selected.”

Key additions:

- `hf:RulesParameterType` now supports optional `stableId`, `canonicalId`, `ownerStableId`, and `scope` attributes.
- `hf:RulesAllowedValueType` allows `allowedValue` entries to carry optional entity identifiers, such as an Ability stable ID.
- `hf:referenceType` / `hf:entityReferenceType` now allows repeated `parameterMatch` children.
- `hf:parameterMatchType` supports fixed value matches, stable value matches, same-value comparisons, and mapped comparisons.
- Virtue/Flaw data can now include top-level `parameter` definitions for player-facing choices, instead of relying only on repeated local `rulesImpact` parameters.
- Character `selectionParameter` entries now use `hf:selectedParameterValueType`, preserving the older generic key/value shape while adding parameter and selected-value identifiers.

Example parameter-aware prohibition:

```xml
<prohibits stableId="armde.virtue.puissant-ability" entityType="Virtue">
  <displayName>Puissant Ability: Artes Liberales</displayName>
  <parameterMatch
    parameterStableId="armde.virtue.puissant-ability.parameter.ability"
    ownerStableId="armde.virtue.puissant-ability"
    operator="equals"
    valueStableId="armde.ability.artes-liberales">
    <displayName>Ability must be Artes Liberales</displayName>
  </parameterMatch>
</prohibits>
```

Example mapped-value prohibition:

```xml
<prohibits stableId="armde.virtue.puissant-ability" entityType="Virtue">
  <displayName>Puissant Ability for the same Realm Lore</displayName>
  <parameterMatch
    parameterStableId="armde.virtue.puissant-ability.parameter.ability"
    ownerStableId="armde.virtue.puissant-ability"
    operator="sameMappedValue"
    sourceParameterStableId="armde.virtue.student-of-realm.parameter.realm"
    sourceOwnerStableId="armde.virtue.student-of-realm"
    mappingStableId="armde.mapping.realm-to-lore-ability">
    <displayName>Same mapped Realm Lore</displayName>
  </parameterMatch>
</prohibits>
```

## Character sheet additions in v0.3.5

`entities/characters.xsd` now includes a richer `characterData` payload with backwards-compatible legacy Quick Sheet fields plus new structured sections:

- `identityAndBackground`
- `hermeticIdentity` for magus/Order of Hermes data
- `characterArt`
- `characteristics`
- `virtuesAndFlaws`
- `abilities`
- `arts`
- `experience`
- `decrepitude`
- `warping`
- `personalityTraits`
- `reputations`
- `combatProfile`
- `fatigueProfile`
- `woundProfile`
- `inventory`
- `magicProfile`
- `derivedValues`

The new Hermetic identity fields include House, Parens, Apprentice Covenant, Primus, Domus Magna, Wizard's Sigil, and Covenant of Apprenticeship.

`identityAndBackground` includes saga name, setting, current year, associated covenant, age, apparent age, Size, Confidence, and the biographical fields from the standard sheet.

`experience` records experience gained during play as event lines, including season, source, activity, target, XP amount, and notes.

`characterArt` uses the new reusable `hf:mediaAssetType` from `foundry-common.xsd`. It stores references/metadata for user- or package-supplied media files. It is not intended to embed Ars Magica book artwork or copied visual assets.

## Equipment/load additions in v0.3.5

- `entities/equipment.xsd` retains and documents `load` as reusable equipment data for equipment, weapons, armor, shields, and unarmed combat-mode records.
- `entities/items.xsd` now has optional `cost`, `load`, `availability`, `quantityNotes`, and `sourceRulesText` fields so non-equipment items can still carry physical/load metadata when needed.
- Character inventory entries also record quantity, unit load, total load, carried/equipped/stored state, total carried load, Burden, and Encumbrance.

## Derived values and rulesImpact target paths

The character schema now has explicit target locations for rules impacts from Virtues, Flaws, equipment, spells, and other sources. Recommended path conventions include:

- `/character/identityAndBackground/size`
- `/character/identityAndBackground/confidenceScore`
- `/character/characteristics/{abbr}/score`
- `/character/abilities/{stable-id-or-slug}/score`
- `/character/arts/{abbr}/score`
- `/character/combatProfile/soak`
- `/character/combatProfile/armorLoad`
- `/character/inventory/totalCarriedLoad`
- `/character/inventory/burden`
- `/character/inventory/encumbrance`
- `/character/fatigueProfile/level/{slug}`
- `/character/woundProfile/{severity}`

These are conventions for application logic and `rulesImpacts`; the schema stores paths as strings so the app can evolve without a schema change for every new calculated value.

## Mining convention

For mined Ars Magica content, preserve exact book text intended for end-user display in inherited `description` fields and/or schema-specific `sourceRulesText` fields. Put parsed mechanics and calculations into structured `rulesImpacts` and entity-specific mechanical fields.

For the current character-creator scope, mine first-class entities and object/entity-affecting mechanics. Do not mine broad play-procedure rules unless they directly define, calculate, modify, or print a managed entity or character-sheet field.

This is a schema package only. It contains no Ars Magica book text, graphics, logos, maps, page images, or other visual assets.

## Project validation

This bundle was locally validated with lxml schema compilation and fixture validation.

Summary:

- Schema files validated: 38
- XML fixtures validated: 39
- Passed: 77
- Failed: 0
- Skipped: 0

See `VALIDATION_REPORT.txt` and `VALIDATION_REPORT.json`.
Note: v0.3.6 fix 1 adds `schemaUpgraded` to `changeActionEnum` so schema-upgrade change history validates strictly.
