Hermetic Foundry Development Plan

01Hermetic Foundry Development Plan§

Revision Purpose§

Revision 1.4 updates the Hermetic Foundry development plan after the v0.3.6 parameter-aware schema and core package integration, and after continued Milestone 3.6 UI refinement.

The major design decision in this revision is that Hermetic Foundry should preserve a clear distinction between Quick Sheet and Guided Creation.

Quick Sheet is the fast, sheet-like manual entry mode. It is for users who already know what they want to enter and want direct access to the character record.

Guided Creation is the step-by-step creation workflow. It should help the user move through Ars Magica character creation in a sensible order without yet becoming a full rules-enforcement engine.

The v0.3.6 parameter-aware schema/package work provides future support for better rules interpretation, including parameter-aware prohibitions and requirements. However, full Virtue/Flaw legality enforcement, rulesImpact automation, and deep character validation remain deferred to the later rules automation spiral. Milestone 3.7 should guide the user through character creation, not attempt to fully police it.

This revision also adds two new spirals before deep rules automation:

• Spiral 9 — UI Polishing
• Spiral 10 — Efficiency Improvements
• Spiral 11 — Deep Rules Automation, formerly Spiral 9
• Former later spirals shift forward accordingly

The purpose of this change is to ensure that Hermetic Foundry receives a full application-wide usability, visual, icon, and performance pass before the project enters the heavier rules-calculation phase.

Project Status Update§

Update the current project status section to reflect:

• Spiral 0 — Complete
• Spiral 1 — Complete
• Spiral 2 — Complete
• Spiral 3 Milestone 3.1 — Complete
• Spiral 3 Milestone 3.5 — Complete
• Current next milestone: Spiral 3 Milestone 3.6 — Ars Magica Character Sheet Fidelity Mini-Spiral

Schema status:

• XML schema v0.3.5 has been created.
• Hermetic Foundry has incorporated schema v0.3.5.
• The Ars Magica Definitive Edition mined package batches have been refreshed to v0.3.5.
• Batches 076 and 077 have been scope-corrected:
  • Batch 076 now focuses on weapons, shields, armor, and unarmed combat modes.
  • Batch 077 now contains only character-sheet derived-value material and no broad fatigue/wound/peril/travel rules encyclopedia content.

New Global Design Principle: Sheet-First Ars Magica UI§

Add under Global Design Decisions:

Hermetic Foundry should follow a sheet-first Ars Magica UI principle.

For major managed records, especially Characters, Creatures, Covenants, and Laboratories, the UI should be guided by the shape of Ars Magica’s own record sheets and lifecycle structures. The application may use modern desktop design patterns, but the user should immediately recognize the Ars Magica concepts being represented.

For characters, this means the UI should be organized around the actual play-facing sections of an Ars Magica character:

• Identity and background
• Saga, setting, current year, covenant, age, and apparent age
• Hermetic identity for magi
• Characteristics
• Virtues and Flaws
• Abilities with score, specialty, and XP
• Personality Traits
• Reputations
• Decrepitude, aging effects, Warping, and warping effects
• Combat, armor, soak, armor load, weapons, and combat modes
• Fatigue levels
• Wound ranges, wound boxes, and wound penalties
• Equipment and carried load
• Magical Arts
• Base casting totals and common magical totals
• Laboratory and longevity summary
• Raw vis
• Familiar and familiar bond
• Spells known and spell mastery
• Advancement and experience history
• Character art
• Notes and history

The UI should distinguish clearly between:

1. Imported source content, such as Virtues, Flaws, Abilities, Spells, Weapons, Armor, Items, and Arts.
2. Character-instance data, such as score, XP, specialty, spell mastery, quantity carried, armor worn, current fatigue, and current wounds.
3. Derived values, such as Soak, Armor Load, Burden, Encumbrance, Wound ranges, casting totals, lab totals, and combat totals.
4. Manual overrides and Storyguide rulings.

Derived values should be visible before they are fully automated. Early milestones may allow manual entry or partial calculation, but the UI should show whether a value is manual, calculated, overridden, or needs review.

New Global Extraction Scope Principle§

Add under Global Design Decisions or XML/Package Rules:

Hermetic Foundry’s core mined packages should prioritize content and data needed for entity creation, character sheets, lifecycle management, and selectable game objects.

Mine and package:

• Virtues
• Flaws
• Abilities
• Arts
• Spells
• Weapons
• Armor
• Items
• Books
• Vis sources
• Laboratory features
• Covenant Boons and Hooks
• Creatures
• Creature powers, qualities, and inferiority records
• Mystery Cults
• Initiation Scripts and initiation components
• Character-sheet derived constants when the application needs them

Do not mine broad play-procedure rules as first-class content unless they are required to define or calculate managed entities.

Generally defer or exclude:

• Combat procedure
• Combat examples
• Travel procedure
• Disease and poison resolution
• Fatigue recovery timing
• Wound recovery timing
• General storyguide advice
• Examples of play
• Broad rules-reference text not tied to an entity, object, sheet field, or lifecycle workflow

This keeps Hermetic Foundry focused as a character, covenant, laboratory, and lifecycle management tool rather than turning it prematurely into a rules encyclopedia.

02Development Methodology§

Hermetic Foundry will use a RAD-Spiral development methodology.

The development cycle is:

1. Build something broad and visible.
2. Test it with real Ars Magica use cases.
3. Identify missing workflows, awkward interface choices, and data gaps.
4. Refine the design.
5. Drill deeper into the next layer of functionality.
6. Repeat until the application is complete.

This approach is intentionally closer to classic Rapid Application Development than modern Agile sprint methodology. Hermetic Foundry is a large, rules-heavy, entity-heavy desktop application. It benefits from visible prototypes, strong specifications, iterative testing, and repeated refinement.

The project should avoid disappearing into deep backend work before the user-facing structure is understandable.

Definition of Done for Character UI Milestones§

For character-related UI milestones, a feature is complete only when:

• It uses Ars Magica terminology.
• It maps to the v0.3.5 character schema or documents a schema gap.
• It saves to XML.
• It reloads from XML without data loss.
• Package-backed choices preserve source/provenance.
• Package-backed choices preserve embedded snapshots where appropriate.
• Derived values show whether they are manual, calculated, overridden, or need review.
• Magus-only fields are not forced on non-magi.
• Character art is preserved if used.
• At least one magus, one companion, and one grog are tested.
• Print Preview and Help still use focused layouts without the normal Info pane.
• Validation remains quiet and user-facing only when useful.
• The UI does not expose raw XML in normal use.
• The work does not redesign unrelated systems.

03Development Environment§

Future instructions should assume the following toolchain unless otherwise stated:

• Windows
• PowerShell
• Visual Studio Code
• XML Copy Editor
• GitHub Desktop
• ChatGPT / Solon
• Codex

Primary technology assumptions:

• Tauri for the desktop application shell.
• TypeScript, HTML, and CSS for the frontend.
• Rust/Tauri backend only where needed.
• XML for rules data, saved entities, help files, package manifests, and customization content.
• GitHub for source control.
• GitHub Desktop for routine branch/merge workflow.
• Codex for implementation, refactoring, testing, and code review.

The working principle is:

Ben controls the design, rules model, user experience, and specifications. Codex performs much of the implementation work from carefully written tasks.

04Core Product Vision§

Hermetic Foundry is not merely an Ars Magica character creator.

It is intended to manage the full lifecycle of Ars Magica play, including:

• Characters
• Creatures
• Covenants
• Laboratories
• Spells
• Items
• Books
• Vis sources
• Mystery cults
• Initiation scripts
• Plots
• Locations
• Custom content
• Help files
• Importable/exportable packages

Hermetic Foundry should support both:

• fast manual-entry “Quick Sheet” workflows, and
• deeper rules-guided workflows.

The application should be useful to both players and storyguides.

05Accepted Terminology§

Use the following terms consistently.

Hermetic Foundry§

The full application name.

The Foundry§

Acceptable short form.

Entity§

The internal architectural/database/XML umbrella term.

Creature§

The user-facing umbrella term for mundane animals, magical beasts, faeries, demons, spirits, dragons, giants, constructs, and similar beings.

Content§

Accepted UI term for the central work area / managed material.

Navigator§

Accepted UI term for the left navigation pane.

Info§

Accepted UI term for the right inspector pane.

Linked Content§

Accepted UI term for content associated with the currently active record.

Initiations§

Accepted UI term for initiation-related workflow areas.

Details§

Accepted UI term for detail sections.

Type§

Use “Type,” not “Content Type,” in the Info pane.

Open§

Use “Open,” not “Open Existing,” in UI labels.

06Core Entity Types§

The following should be treated as Entity-derived types:

• Characters
• Creatures
• Covenants
• Laboratories
• Spells
• Items
• Books
• Plots
• Locations
• Vis Sources
• Mystery Cults
• Initiation Scripts

07Global Design Decisions§

Visual Identity§

Hermetic Foundry should retain a distinctive visual identity.

Accepted decisions:

• Keep the “Hermetic Foundry” logo text.
• Preserve the parchment/manuscript visual character.
• Use local/fontsource typography rather than remote font loading.
• The app should feel like a crafted Ars Magica tool, not a generic dashboard.
• The app should be readable, usable, and comfortable for long rules-heavy sessions.

Main Layout§

The accepted broad layout includes:

• Top application menu.
• Main application shell.
• Left Navigator pane.
• Central Content area.
• Right Info pane.
• Recent Changes area.
• Linked Content area.
• Help and Print Preview modes.

Right Info Pane§

The right pane is called Info.

Accepted decisions:

• Rename “Content Type” to “Type.”
• Remove “Section Count.”
• Remove “Navigator Group.”
• Remove Tags for now.
• Tags should return later as a planned feature.
• Use compact typography inside right-pane fields.
• Recent Changes should show no more than three visible entries to avoid sidebar scrolling.
• Add a right-pane collapse affordance.
• The Info pane should normally behave like a read-only inspector.

Future requirement:

• The Info pane should eventually support editable metadata through an explicit edit/pencil icon.
• Clicking Edit should reveal editable fields.
• Editable mode should include clear save/cancel controls.
• Notes and Tags should not appear as editable fields until this edit flow exists.

Help and Print Preview Layout§

Accepted decision:

• Help screens and Print Preview should not show the normal outer app layout.
• In particular, the right Info pane should be gone in Help and Print Preview.
• Help and Print Preview should use their own focused layouts.

Validation§

Accepted decision:

• Do not expose “Validate” as a normal user-facing action.
• Validation should happen quietly and automatically in the background.
• Validation results should appear only when useful: warnings, errors, import previews, save/load problems, or package conflicts.

Accessibility§

Accessibility foundations should be part of development from now on.

Accepted requirements:

• Use semantic HTML where possible.
• Use screen-reader-friendly labels.
• Use useful alt text.
• Use aria attributes where appropriate.
• Use long descriptions where appropriate for complex imagery.
• Maintain good contrast and readable typography.
• Ensure keyboard navigation is considered as screens are built.

Future possibility:

• A full Accessible Mode may be added later.
• This would be a more comprehensive accessibility-focused UI, potentially with larger typography, stronger contrast, reduced texture, and simplified navigation.

Local UI State Persistence§

Future requirement:

• Hermetic Foundry should persist UI state locally.
• Example: if the user closes the Info sidebar, it should remain closed across all areas of the app and after the app is closed and reopened.

This should be treated as a future app preference/state-persistence feature unless scheduled earlier.

Help Menu Update Check§

Future requirement:

The Help menu should eventually include:

• Hermetic Foundry Help
• Ars Magica Open License
• Welcome / Getting Started
• Check for Updates
• About Hermetic Foundry

08Global Definition of Done§

A feature or milestone should usually be considered complete only when:

• It has a visible UI path if user-facing.
• It uses accepted terminology.
• It does not expose validation as a normal user-facing action.
• It handles errors gracefully.
• It saves to XML if relevant.
• It reloads from XML if relevant.
• It preserves IDs and timestamps if relevant.
• It preserves provenance if relevant.
• It supports embedded snapshots if it references external/custom content.
• It has at least a basic manual test case.
• It does not break existing sample files.
• It preserves accessibility foundations.
• It does not redesign unrelated systems.
• It is committed to GitHub after review.

For UI features, also check:

• Help and Print Preview should not inherit the normal Info-pane layout.
• The right Info pane should remain inspector-like unless edit mode is explicitly implemented.
• New components should use semantic HTML where practical.
• Side pane state should be considered for future persistence.
• Recent Changes should avoid excessive scrolling.

For entity/data features, also check:

• Created and modified timestamps are handled.
• Created by and last modified by are considered.
• Change history/audit trail support is considered.
• Checksums are recalculated correctly where relevant.
• Imported/exported content validates correctly.
• Source/provenance metadata is preserved.

09Spiral 0: Project Foundation§

Status§

Complete.

Milestone 0.1 — Repository and Toolchain Setup§

Status§

Complete.

Goal§

Create a clean, repeatable development environment for Hermetic Foundry.

Deliverables§

• GitHub repository created.
• Tauri project initialized.
• Basic frontend build confirmed.
• Windows development environment confirmed.
• GitHub Desktop workflow tested.
• First application shell able to run.
• Project folder structure established.

Tools Needed§

• Windows
• PowerShell
• Visual Studio Code
• GitHub Desktop
• Node.js
• Rust toolchain
• Tauri CLI
• Visual Studio Build Tools / C++ build tools
• Codex

RAD-Spiral Test§

The app launches, and the repository can be cloned, installed, built, and run from scratch.

Milestone 0.2 — Project Specification Pack v0.1§

Status§

Complete.

Goal§

Create enough written project foundation that Codex can build against stable project assumptions.

Deliverables§

The following files were generated and committed to GitHub:

• /docs/specs/product-vision.md
• /docs/specs/entity-taxonomy.md
• /docs/specs/architecture-overview.md
• /docs/specs/xml-design-principles.md
• /docs/specs/custom-package-spec.md
• /docs/specs/entity-references-and-snapshots.md
• /docs/specs/ui-workflow-overview.md
• /docs/specs/coding-standards.md
• /docs/specs/codex-prompt-templates.md
• /docs/specs/definition-of-done.md

Tools Needed§

• Visual Studio Code
• Markdown
• GitHub Desktop
• Codex
• ChatGPT / Solon

RAD-Spiral Test§

A Codex task can be written from the specification pack and produce code consistent with the intended architecture.

10Spiral 1: Broad Application Shell§

Status§

Complete.

Purpose§

Spiral 1 established the visible structure of Hermetic Foundry.

The goal was not deep Ars Magica rules implementation. The goal was to create the broad application shell: layout, menu structure, navigation approach, placeholder workflows, and first visual direction.

By the end of Spiral 1, Hermetic Foundry should feel like a real desktop application. A user should be able to open it, understand the major areas of the program, move between the main workflows, and see where future features will live.

Milestone 1.0 — UI Layout Concept§

Status§

Complete.

Goal§

Decide the broad screen structure before implementing the main application frame.

Accepted Result§

• Broad app layout established.
• Main regions defined.
• Top menu and main screen concept accepted.
• Navigator, Content, and Info structure accepted.

Deliverables§

• Main application layout concept.
• Main menu structure concept.
• Main screen wireframe.
• Quick Sheet access concept.
• Primary navigation concept.
• Workspace/content area concept.
• Recent files/projects concept.
• Help/About access concept.

RAD-Spiral Test§

Another person, or Codex, can read the layout documents and understand the intended shape of the first Hermetic Foundry application window.

Milestone 1.1 — Main Application Frame§

Status§

Complete.

Goal§

Build the actual desktop application shell based on the UI Layout Concept.

Accepted Result§

• Running Tauri application shell.
• Parchment/manuscript visual direction retained.
• Hermetic Foundry logo text retained.
• Navigator and Info side panes established.
• Right Info pane collapse affordance added.
• Compact right-pane typography applied.
• Recent Changes limited to three visible entries.

Deliverables§

• Main Tauri application window.
• Top-level menu structure.
• Main landing screen.
• Primary navigation shell.
• Placeholder workspace/content area.
• File menu placeholders.
• Edit menu placeholders.
• Help menu placeholder.
• About Hermetic Foundry screen.
• Basic application title and identity.
• Basic routing between top-level placeholder areas.

RAD-Spiral Test§

The app launches as Hermetic Foundry and shows a coherent desktop shell.

Milestone 1.2 — UI Layout Refinement / Navigation Structure§

Status§

Complete.

Goal§

Refine the application shell, navigation, Help layout, Print Preview layout, and icon presentation.

Accepted Result§

• Help and Print Preview layouts refined.
• Info pane removed from Help and Print Preview.
• Icon set accepted as good enough for now.
• Remaining icon polish deferred.
• Outer app layout does not own the Help and Print Preview Info pane behaviour incorrectly.
• Help and Print Preview use focused layouts.

Deferred Icon Polish§

Known issues to revisit later:

• Laboratory icon flask visibility.
• Spell icon size and line weight.
• Book icon line weight.
• Initiation script icon line weight.
• Custom content icon size.
• Core help icon size.
• Custom package help icon size.
• Search icon consistency.

RAD-Spiral Test§

The application shell behaves correctly across normal app screens, Help screens, and Print Preview screens.

Milestone 1.3 — First Visual Style Pass§

Status§

Complete.

Goal§

Make the application feel like Hermetic Foundry rather than a generic development scaffold.

Accepted Result§

• First visual style pass accepted.
• Local/fontsource typography applied.
• Parchment/manuscript aesthetic preserved.
• Info pane field labels and content refined.
• “Type” terminology accepted.
• “Open” terminology accepted.
• User-facing “Validate” action removed.
• Accessibility foundations added or planned into the implementation baseline.
• Future editable Info pane requirement identified.

RAD-Spiral Test§

The application no longer feels like an unstyled prototype. It has a coherent identity, even though deep functionality is still missing.

11Spiral 2: Core Entity Architecture§

Status§

Next.

Purpose§

Build the underlying entity and XML architecture beneath the completed application shell.

The app now has a visible structure. Spiral 2 should make that structure begin to handle real Hermetic Foundry data.

Expected focus:

• Entity model.
• XML save/load.
• IDs and checksums.
• Created/modified timestamps.
• Created by/last modified by.
• Change history/audit trail foundation.
• Provenance.
• Embedded snapshots.
• Quiet validation foundation.
• Local app/user profile identity foundation.
• Basic state persistence if scheduled early.

Milestone 2.1 — Entity Model§

Goal§

Create the internal architecture that all managed records derive from.

Deliverables§

• Base Entity model.
• Stable human-readable ID.
• Canonical checksum-bearing ID.
• Display name.
• Entity type.
• Description.
• Source metadata.
• Package provenance metadata.
• Created timestamp.
• Modified timestamp.
• Created by.
• Last modified by.
• Local actor/user display name support.
• Change history/audit trail foundation.
• Notes metadata placeholder.
• XML serialization/deserialization design.
• Quiet validation status foundation.

Entity Types§

• Character
• Creature
• Covenant
• Laboratory
• Spell
• Item
• Book
• Plot
• Location
• Vis Source
• Mystery Cult
• Initiation Script

Change History Requirements§

Because the UI includes Recent Changes and Info metadata, entities should support change tracking early.

The entity model should include enough structure for:

• change event ID,
• actor,
• timestamp,
• action type,
• changed field/path,
• before value or summary,
• after value or summary,
• optional affected linked content,
• optional note or reason.

This does not need a complete UI yet, but the data model should not ignore it.

Tools Needed§

• TypeScript
• XML Copy Editor
• XML parser/serializer
• XML schema tools
• Codex
• GitHub Desktop

Skills Needed§

• Data modeling
• XML design
• TypeScript interfaces/classes
• Checksum logic
• Serialization
• Audit/history modeling

RAD-Spiral Test§

The app can create, display, save, reload, and validate a simple generic entity.

Milestone 2.2 — XML Save/Load Prototype§

Goal§

Prove that the app can save and load real XML records.

Deliverables§

• Save entity to XML.
• Load entity from XML.
• Validate basic XML structure quietly.
• Show validation errors only when useful.
• Preserve created/modified timestamps.
• Preserve created by/last modified by.
• Preserve change history.
• Generate checksums from canonicalized XML.
• Human-readable Date Created and Last Modified display.
• Basic error handling for malformed XML.
• Basic sample entity files.

Tools Needed§

• TypeScript
• Tauri file system access
• XML parser
• XML schema validation
• XML Copy Editor
• Codex

Skills Needed§

• File I/O
• XML canonicalization
• Data validation
• Error handling
• Manual test design

RAD-Spiral Test§

A sample entity can be saved, closed, reopened, edited, saved again, and compared against its checksum/version metadata.

Milestone 2.3 — Entity Linking and Embedded Snapshots§

Goal§

Make entities reference other entities while preserving portability.

Deliverables§

• Entity reference model.
• Embedded descriptive snapshot model.
• Source package reference.
• Checksum-bearing source reference.
• Conflict detection placeholder.
• Missing source warning placeholder.
• UI display for source/provenance.
• Snapshot preservation in saved files.

Example Test§

A character chooses a spell from spells.xml.

When the character is saved, the character XML includes enough descriptive spell data that another Hermetic Foundry installation can still understand what spell was selected.

Tools Needed§

• TypeScript
• XML
• Hashing/checksum utility
• Entity registry
• Codex

Skills Needed§

• Data relationships
• Provenance modeling
• XML nesting
• Conflict detection
• Portable content design

RAD-Spiral Test§

A character file containing referenced spells can be moved to another test installation and still display the embedded spell descriptions.

Milestone 2.4 — Local Profile, App State, and First-Run Welcome Foundation§

Goal§

Create local user/profile identity, basic application state persistence, and the foundation for a first-run Welcome / Getting Started overlay.

This milestone should help Hermetic Foundry remember local user preferences and provide a guided first-run experience without interfering with normal startup behaviour after the user has dismissed it.

Deliverables§

• Local profile/display name setting.
• App-local actor name used in change history.
• Basic preferences storage.
• Info pane collapsed/open state persistence.
• Last opened area or recent file placeholder.
• First-run Welcome / Getting Started overlay foundation.
• Dismissible Welcome / Getting Started overlay.
• Local preference recording whether the Welcome overlay has been dismissed.
• Help menu item to reopen the Welcome / Getting Started overlay.
• Links from the Welcome overlay into major workflows.
• Placeholder tutorial/suggested path content.
• Configuration-driven Welcome content placeholder.
• Local-only design; no cloud account required.

Welcome / Getting Started Requirements§

Hermetic Foundry should eventually include a first-run Welcome / Getting Started overlay.

The overlay should include:

• a brief introduction to Hermetic Foundry,
• tutorials or tutorial links,
• suggested starting paths,
• links into major workflows,
• links to Quick Sheet mode,
• links to Help,
• links to custom content/package import if appropriate.

The overlay must be:

• shown on first run unless the local preference says it has already been dismissed,
• dismissible by the user,
• reopenable from the Help menu,
• governed by local UI state preferences,
• separate from normal startup behaviour after dismissal.

After the user dismisses the Welcome overlay, Hermetic Foundry should return to normal startup behaviour. The Welcome overlay should not permanently replace the dashboard, last-opened state, or any future startup screen behaviour.

Welcome Content Configuration§

The specific content of the Welcome / Getting Started overlay should remain easy to modify at any point in development.

In the future, the content should be driven by a configuration file packaged with the application.

This configuration file should allow future releases to update:

• welcome text,
• tutorial links,
• suggested workflow paths,
• button labels,
• destination workflow IDs,
• help article links,
• release-specific guidance.

This content should be re-packageable with future releases without requiring major code changes.

Tools Needed§

• Tauri local storage or app data directory access.
• TypeScript.
• Preferences/state management.
• UI overlay/modal implementation.
• Help menu integration.
• Configuration file loading.
• Codex.

Skills Needed§

• Local settings storage.
• UX for preferences.
• State persistence.
• First-run experience design.
• Config-driven UI content.
• Offline-first design.

RAD-Spiral Test§

The user can set a local display name, close the Info pane, close the app, reopen it, and see the expected profile/state preserved.

On first run, the Welcome / Getting Started overlay appears. The user can dismiss it, and it does not appear again on normal startup unless reopened from the Help menu or reset through preferences.

The overlay content can be modified through a simple configuration file or placeholder configuration structure without redesigning the overlay code.

12Spiral 3: Quick Sheet, Package-Backed Creation, and Character Sheet Fidelity§

Purpose:§

Make Hermetic Foundry useful for fast manual entry and early package-backed character work before deep rules automation.

Spiral 3 should now accomplish three things:

1. Provide Quick Sheet workflows for fast manual entry.
2. Load and reconcile core content packages so real Ars Magica content can be selected.
3. Make the Character workflow visibly reflect Ars Magica’s actual character sheet structure.

Spiral 3 should not attempt full character rules automation. That remains in Spiral 9. However, Spiral 3 should create the UI and data structures that later automation will fill in.

Milestone 3.1 — Quick Sheet Mode§

Goal§

Create a fast manual-entry mode for major sheet types.

Deliverables§

• Quick Character sheet.
• Quick Creature sheet.
• Quick Covenant sheet.
• Quick Laboratory sheet.
• Quick Item sheet.
• Save/load support for each.
• Print-preview placeholder for each.
• Minimal quiet validation.
• Info pane metadata display.
• Recent Changes integration where applicable.

Tools Needed§

• TypeScript
• CSS
• XML save/load
• Tauri file access
• Codex

Skills Needed§

• Form design
• Data binding
• UI validation
• Manual test writing

RAD-Spiral Test§

A user can quickly enter a usable sheet for each supported Quick Sheet type and preview or save it.

Milestone 3.2 — Character Workflow Prototype§

Goal§

Create the broad lifecycle shell for character management.

Deliverables§

• Character identity screen.
• Characteristics screen.
• Virtues and Flaws placeholder.
• Abilities placeholder.
• Arts placeholder.
• Spells placeholder.
• Equipment placeholder.
• Personality/Reputations placeholder.
• Advancement placeholder.
• Notes and history.
• Print/export placeholder.
• Info pane integration.
• Linked Content integration.

Tools Needed§

• TypeScript
• XML
• UI routing
• Codex

Skills Needed§

• Ars Magica character structure
• Form workflow design
• Rules-aware data modeling
• UI organization

RAD-Spiral Test§

A character can be created at a high level and moved through the entire lifecycle workflow, even if many calculations are still manual.

Milestone 3.3 — Creature Workflow Prototype§

Goal§

Add Creatures as a first-class workflow.

Deliverables§

• Creature identity screen.
• Creature type/category.
• Might placeholder.
• Characteristics.
• Abilities.
• Powers.
• Qualities/Inferiorities.
• Virtues/Flaws if applicable.
• Combat statistics placeholder.
• Description and notes.
• Linked entity support.
• Print/export placeholder.

Tools Needed§

• TypeScript
• XML
• UI forms
• Codex

Skills Needed§

• Ars Magica creature/beast modeling
• Taxonomy design
• Flexible form design

RAD-Spiral Test§

A mundane animal, magical beast, faerie, demon, spirit, dragon, giant, and construct can each be represented without breaking the model.

Milestone 3.4 — Editable Info Pane Metadata§

Goal§

Add explicit edit support to the Info pane.

Deliverables§

• Edit/pencil icon in the Info pane.
• Read-only inspector mode by default.
• Edit mode for supported metadata.
• Save/cancel controls.
• Editable notes field.
• Tag placeholder or first tag implementation if scheduled.
• Change history integration.

Tools Needed§

• TypeScript
• CSS
• State management
• XML save/load
• Codex

Skills Needed§

• Inspector UI design
• Form state management
• Metadata editing
• UX clarity

RAD-Spiral Test§

The Info pane looks like an inspector by default. When the user chooses Edit, supported fields become editable with clear save/cancel behaviour.

Package Reconciliation and Previously Installed Package Detection§

The Core Content Package Loader should not only detect changed packages. It should also reconcile the current trusted package source folder, the installed package registry, and the decompressed installed package cache.

This is especially important during development and testing, because core XML packages may be rebuilt, renamed, split, consolidated, deprecated, or removed entirely.

On startup and during package checks, Hermetic Foundry should compare:

• packages currently present in the trusted source folder,
• packages recorded in the installed package registry,
• packages present in the decompressed installed package cache,
• packages currently included in the runtime content index.

A package that was previously installed but is no longer present in the trusted source folder should not simply disappear silently. Hermetic Foundry should mark it with a clear status and preserve enough registry history to explain what happened.

Suggested additional package statuses:

• removedFromSource
• orphanedInstalledPackage
• cachedOnly
• retiredPackage
• supersededPackage
• packageIdentityChangedPossible
• sourceOlderThanInstalled
• duplicatePackageId
• duplicateEntityId

Missing Source Cases§

Hermetic Foundry should distinguish between these cases:

1. Source ZIP missing, installed cache still present
   The source ZIP path recorded in the registry no longer exists, but the decompressed installed package still exists and still matches its stored file checksums.
   For a normal user-imported package, this may be acceptable because the source ZIP may have been moved or deleted after import.
   For trusted core development packages, this usually means the package may have been removed from the active source set.
   Status: cachedOnly or missingSourceZip.
2. Package removed from trusted source folder
   The trusted source folder is being treated as the intended active package set, and a previously installed package is no longer present there.
   Hermetic Foundry should mark the package as removedFromSource or orphanedInstalledPackage.
   For this development milestone, the conservative default should be: do not silently include removed-from-source packages in the active runtime content index. Show them in package diagnostics so the developer can decide whether to restore, refresh, disable, retire, or purge them.
3. Installed cache missing, registry entry remains
   The registry says a package was installed, but the decompressed installed package folder is missing.
   Status: orphanedRegistryEntry.
   Hermetic Foundry should not crash. It should mark the package invalid/unavailable and remove it from the active runtime content index.
4. Same package ID, new source ZIP
   If the same package ID appears in the source folder with a newer version, newer timestamp, or different package checksum, mark it as refresh-needed and refresh from source if safe.
   Status: refreshRequired or staleSourceChanged.
5. Same package ID, older source ZIP
   If the source ZIP appears older than the installed package, do not silently downgrade.
   Status: sourceOlderThanInstalled.
6. New package appears that may replace an old package
   If a new package ID appears and an older package disappears, Hermetic Foundry cannot safely know whether this is a replacement unless manifest metadata explicitly says so.
   Mark the old package as removedFromSource and the new package as available or installed.
   If the two packages contain overlapping stable IDs or canonical IDs, add a warning such as packageIdentityChangedPossible or duplicateEntityId.

Active Index Policy§

The package registry may remember packages that are missing, removed, retired, dirty, or disabled, but the runtime content index should only include packages that are safe and active.

By default, exclude packages from the active index when their status is:

• removedFromSource
• orphanedInstalledPackage
• orphanedRegistryEntry
• dirtyInstalledContent
• validationFailed
• checksumMismatch
• schemaMismatch
• retiredPackage
• disabledPlaceholder

A developer diagnostic option may show these packages, but they should not quietly contribute live rules/content entities.

Registry History / Tombstones§

The installed package registry should preserve historical records for packages that were previously installed but are no longer active.

These historical records may be called tombstones or retired package records.

They should track:

• package ID,
• display name,
• last known version,
• last known checksum,
• last installed path,
• last source ZIP path,
• first installed timestamp,
• last seen timestamp,
• removed/missing detected timestamp,
• last known entity counts,
• reason/status,
• possible replacement package ID if later known.

This prevents silent disappearance and makes development testing much easier.

Developer Reconciliation Actions§

For Milestone 3.5, a minimal developer/status view is sufficient. It may offer simple actions if they are easy to implement, or merely display what action is needed.

Useful future or optional actions:

• Refresh from source ZIP.
• Restore from source ZIP.
• Disable package.
• Retire package.
• Purge decompressed cache.
• Remove stale registry entry.
• Rebuild content index.
• Open installed package folder.
• Open trusted source folder.

These actions should remain developer/core-content diagnostics for now. The full user-facing package management UI belongs later in the Spiral 6.3 Import System.

Milestone 3.5 — Core Content Package Loader and Reconciliation§

If not already explicitly listed as a named milestone, add or formalize Milestone 3.5.

Status:

Complete.

Goal:

Allow Hermetic Foundry to load, validate, reconcile, and index core content packages so imported Ars Magica content can be used by character and entity workflows.

Deliverables:

• Trusted core package source folder.
• Multi-package loading.
• ZIP package validation.
• Manifest validation.
• LICENSE.xml presence check.
• Schema validation.
• Package checksum handling.
• Entity indexing.
• RulesImpact indexing.
• Decompressed installed package cache.
• Installed package registry.
• Package refresh detection.
• Package removal/missing-source detection.
• Developer diagnostics for package state.
• Package status/tombstone tracking.
• Duplicate package ID detection.
• Duplicate canonical entity ID detection.
• Type-aware or warning-level duplicate stable ID detection.
• Batch 076 and 077 scope-correction verification.

Known follow-up:

Canonical checksum generation/import verification must be aligned before external/untrusted packages are treated as fully trusted. Package generation and application import should eventually share one canonical XML checksum implementation or formally identical algorithms.

RAD-Spiral Test:

Hermetic Foundry can load the refreshed v0.3.5 Ars Magica package set, detect duplicate package/entity problems, maintain a decompressed cache, reconcile missing or changed source packages, and build a usable runtime content index.

Milestone 3.6 — Ars Magica Character Sheet Fidelity Mini-Spiral§

Status:

Next.

Goal:

Rework the Character workflow so it visibly and structurally reflects Ars Magica’s character sheet, using v0.3.5 character schema structures and imported core packages, without attempting full deep rules automation.

This is a mini-spiral between package import and the larger Covenant/Laboratory work of Spiral 4. It exists to ensure that characters are no longer generic records before other systems begin depending on them.

Deliverables:

1. Character workflow restructuring§

Reorganize the Character workflow around recognizable Ars Magica sections:

• Overview
• Identity and Background
• Hermetic Identity
• Characteristics
• Virtues and Flaws
• Abilities
• Arts
• Spells
• Combat
• Equipment
• Fatigue and Wounds
• Personality Traits
• Reputations
• Aging and Warping
• Familiar
• Laboratory and Longevity
• Raw Vis
• Experience and Advancement
• Notes and History
• Character Art

2. Identity and Background section§

Support:

• Character name
• Player
• Saga
• Setting
• Current year
• Covenant association
• Birth name
• Year born
• Age
• Apparent age
• Gender
• Race/Nationality
• Place of origin
• Religion
• Title/Profession
• Height
• Weight
• Hair
• Eyes
• Handedness
• Character art

3. Character type behavior§

Support character type selection at least for:

• Magus
• Companion
• Grog
• Mythic Companion
• Other/custom

Magus-only sections should be shown, hidden, collapsed, or marked not applicable based on character type.

Non-magi should not be forced through Hermetic-only fields.

4. Hermetic Identity section for magi§

Support:

• House
• Covenant
• Wizard’s Sigil
• Domus Magna
• Primus
• Parens
• Apprentice Covenant / Covenant of Apprenticeship

5. Characteristics§

Display Ars Magica full names and abbreviations:

• Intelligence / Int
• Perception / Per
• Strength / Str
• Stamina / Sta
• Presence / Pre
• Communication / Com
• Dexterity / Dex
• Quickness / Qik

Support base score, modifier/source display, final score, and notes if v0.3.5 structures support them.

6. Virtues and Flaws§

Provide package-backed selection from imported content.

Support:

• Searchable picker
• Filter by Virtue/Flaw type or category where data exists
• Selected list
• Source/provenance display
• RulesImpact summary
• Character-instance notes
• Embedded snapshot preservation

Do not attempt full legality enforcement yet. Basic point tracking may be shown if easy, but deep validation belongs to Spiral 9.

7. Abilities§

Provide package-backed Ability selection.

Support character-instance fields:

• Ability reference
• Specialty
• Score
• XP toward next level
• Bonus/modifier display
• Source/provenance
• Notes

8. Arts§

For magi, support Techniques and Forms:

Techniques:

• Creo
• Intellego
• Muto
• Perdo
• Rego

Forms:

• Animal
• Aquam
• Auram
• Corpus
• Herbam
• Ignem
• Imaginem
• Mentem
• Terram
• Vim

Support score, XP, bonus/modifier display, and notes.

9. Personality Traits and Reputations§

Support:

• Personality Trait name
• Score
• Notes

Support Reputation:

• Name/content
• Type
• Score
• Notes/source

10. Aging and Warping§

Support:

• Decrepitude
• Aging effects
• Warping Score
• Warping Points
• Effects of Warping
• Twilight Scars for Hermetic magi

This milestone does not need full aging or Warping automation.

11. Combat and Equipment§

Support:

• Armor worn
• Soak
• Armor Load
• Combat modifiers
• Weapons
• Unarmed combat modes
• Initiative
• Attack
• Defense
• Damage
• Load
• Range
• Equipment inventory
• Quantity
• Carried/equipped/stored state
• Unit Load
• Total Load
• Total carried load
• Burden
• Encumbrance

Weapons, shields, armor, and unarmed combat modes should be selectable from package-backed content where available.

12. Fatigue and Wounds§

Support display and manual tracking of:

• Fatigue level profile
• Current fatigue boxes/state
• Wound categories
• Wound ranges
• Wound boxes
• Wound penalties
• Notes

This milestone should use the scope-corrected Batch 077 derived-value data where available.

Do not implement fatigue recovery, wound recovery, disease, poison, deprivation, heat/corrosion, impact, or travel procedure as character UI in this milestone.

13. Magic Summary§

For magi, support visible fields for:

• Formulaic casting total
• Ritual casting total
• Spontaneous magic with Fatigue
• Spontaneous magic without Fatigue
• Fast Casting Speed
• Determining Effect
• Base Targeting
• Concentration
• Magic Resistance
• Multiple Casting
• Basic Lab Total
• Longevity Ritual summary
• Age Roll Modifier
• Twilight Scars

These may be manual or partially calculated at this stage.

14. Spells Known§

Provide package-backed spell selection.

Support character-instance spell fields:

• Spell reference
• Spell name
• Technique
• Form
• Level
• Range
• Duration
• Target
• Casting bonus/total
• Mastery score
• Mastery XP
• Mastery abilities
• Notes
• Embedded snapshot preservation

15. Familiar section§

Support:

• Familiar creature reference
• Familiar name
• Int/Cun
• Per
• Str
• Sta
• Pre
• Com
• Dex
• Qik
• Size
• Might
• Soak
• Fatigue
• Initiative
• Attack
• Defense
• Damage
• Bronze Cord
• Silver Cord
• Gold Cord
• Bond qualities and abilities
• Notes

Familiars should be treated as Creature-linked records rather than a separate top-level Familiar entity unless a later design decision changes this.

16. Raw Vis§

Support:

• Art
• Pawns
• Physical form
• Notes
• Source/provenance if applicable

17. Experience and Advancement§

Support a basic Experience section for recording experience gained over play.

Fields should include:

• Date or season
• Source/activity
• Target Ability or Art
• XP gained
• Notes
• Applied/unapplied status if useful
• Link to future seasonal advancement engine

This milestone does not need the full Advancement Activity Engine.

18. Character art§

Implement display and upload/selection handling for the v0.3.5 character art/media field.

Support at least local file reference or stored media asset reference according to the schema.

19. Sheet Preview§

Add a provisional Character Sheet Preview mode for QA.

This is not the final Spiral 8 print system. It should simply prove that Hermetic Foundry can assemble the major character-sheet sections coherently.

The preview should roughly group information by the standard sheet structure:

• Page 1 style: identity, characteristics, virtues/flaws, abilities, aging/warping
• Page 2 style: personality, reputations, combat, fatigue, wounds, weapons, equipment
• Page 3 style: Hermetic identity, Arts, casting totals, lab, longevity, raw vis, familiar
• Page 4 style: spells known

20. Save/load and regression§

Confirm that v0.3.5 character XML round-trips without data loss.

Test with:

• A basic magus
• A basic companion
• A basic grog

Each test should include package-backed selections where possible.

Tools Needed:

• TypeScript
• Svelte/components used by the current UI
• XML save/load
• v0.3.5 schemas
• Installed package registry/content index
• Core content pickers
• Codex
• GitHub Desktop

Skills Needed:

• Ars Magica character sheet structure
• UI form design
• Data binding
• Package-backed entity selection
• XML serialization
• Sheet preview layout
• Manual QA design

RAD-Spiral Test:

A user familiar with Ars Magica can open the Character workflow and immediately understand where to enter the major fields from the standard character sheet. The user can create a magus, companion, and grog, select imported core content, save and reload each character, and view a provisional sheet preview without losing character-instance data.

Do Not Include Yet:

• Full character creation legality enforcement
• Full Virtue/Flaw point validation
• Full seasonal advancement automation
• Full aging automation
• Full Warping automation
• Final print/PDF export
• Full spell design automation
• Full lab activity automation
• Broad rules-reference screens
• Recovery, disease, poison, travel, or peril procedure UI

Milestone 3.7 — Quick Sheet Alpha Mini-Spiral§

Status: Next.

Goal: Bring the major Quick Sheet record types to a consistent alpha-level state before beginning Guided Character Creation.

The Quick Sheet screens have become the strongest practical foundation for Hermetic Foundry. They now serve as the most direct way for an experienced Ars Magica player or storyguide to enter, review, edit, save, reload, and maintain real saga records.

This mini-spiral should make the major Quick Sheet areas coherent and usable at an alpha level:

• Quick Character
• Quick Creature
• Quick Covenant
• Quick Laboratory
• Quick Item

The goal is not to turn these screens into full guided workflows or a deep rules-enforcement engine. The goal is to make each Quick Sheet feel like a usable Ars Magica record sheet: understandable, saveable, reloadable, internally consistent, and ready to support later guided creation.

Scope:

This milestone covers alpha review and completion of the major Quick Sheet record types. Each Quick Sheet should support practical manual entry, clean display, stable save/load behavior, and basic validation appropriate to the current schema and package-backed data model.

General requirements for all Quick Sheet areas:

• Use the current XML schema baseline.
• Preserve metadata where supported.
• Save and reload without data loss.
• Preserve package-backed references and snapshots where supported.
• Use Ars Magica terminology consistently.
• Use Tiptap only for active user-facing multi-line rich-text editing fields.
• Do not expose raw XML, raw HTML, Tiptap JSON, schema internals, stable IDs, diagnostics, package paths, tombstones, or validation internals in ordinary UI.
• Keep empty states clean and user-facing.
• Keep validation quiet unless the user attempts to Apply, save, or perform another action that requires validation.
• Preserve Recent Changes behavior where supported.
• Keep Apply and navigation behavior stable.
• Keep the Info pane inspector-like.
• Provide provisional print preview placeholders where final print layout is not yet implemented.
• Avoid deep rules automation unless it is simple, already supported by the current data model, and clearly safe.

Deliverables:

• Quick Character alpha review.
• Quick Creature alpha.
• Quick Covenant alpha.
• Quick Laboratory alpha.
• Quick Item alpha.
• Save/reload regression for each record type.
• Confirmation that each area is ready to support later guided workflows.

Do Not Include Yet:

• Guided Character Creation.
• Full guided workflows for Creature, Covenant, Laboratory, or Item creation.
• Full rules automation.
• Full covenant build-point accounting.
• Full laboratory construction automation.
• Full enchanted item construction automation.
• Schema redesign unless separately approved.
• App shell redesign.
• Autosave.
• Navigation redesign.
• Deep package-content changes unless separately approved.

Tools Needed:

• Current Hermetic Foundry app.
• Current XML schema package.
• Current Ars Magica Definitive Edition core package.
• Ars Magica Markdown reference corpus.
• Existing Quick Sheet screenshots and test XML fixtures.
• Codex for implementation support.
• Manual QA using packaged builds where appropriate.

Skills Needed:

• Ars Magica rules literacy.
• XML schema awareness.
• SvelteKit / TypeScript UI development.
• Tauri desktop app testing.
• Package-backed data loading.
• Save/reload regression testing.
• UI consistency review.
• Careful separation of owned data versus linked entity data.

RAD-Spiral Test:

At the end of this milestone, a user should be able to create or open representative Character, Creature, Covenant, Laboratory, and Item records through the Quick Sheet interface; make ordinary manual edits; save them; reload them; and see the same meaningful Ars Magica information without raw internals, broken ownership, or data loss.

The Quick Sheet areas do not need to be complete rules engines. They do need to be stable enough to serve as the practical alpha foundation for the later guided creation milestone.

Milestone 3.7.1 — Quick Character Alpha Review§

Status: Planned.

Goal: Confirm that Quick Character is alpha-stable and can serve as the reference pattern for the other Quick Sheet areas.

Quick Character has already received the most extensive work in Spiral 3.6. This step is a consolidation and regression pass, not a redesign. The purpose is to confirm that Quick Character is coherent, stable, and ready to act as the model for the other Quick Sheet alpha work.

Scope:

Review the current Quick Character screen as a complete alpha-level manual character sheet. Confirm that the major panes work together, that data ownership is correct, that package-backed content remains stable, and that save/reload behavior works for practical character records.

This review should include at least one Magus, one Companion, and one Grog where supported by the current model.

Deliverables:

• Confirm the current pane order and section list.
• Confirm that magus-only fields are not forced onto non-magi.
• Confirm that package-backed Virtues and Flaws load, display, add, remove, and save correctly.
• Confirm that package-backed Abilities load, display, add, remove, sort, and save correctly.
• Confirm that package-backed Spells load, display, add, remove, sort, and save correctly.
• Confirm that Weapons and Armor preserve the accepted v0.3.10 armor variant behavior.
• Confirm that Partial and Full armor variants are package-backed and not hardcoded.
• Confirm that Equipment behavior remains stable.
• Confirm Experience pane behavior:
  • Year.
  • Season.
  • XP.
  • optional Tiptap Notes.
  • XP must be positive.
  • Year and XP sorting in both directions.
  • manual ordering only through Up/Down buttons.
  • no visible Manual Order sort option.

• Confirm Raw Vis pane behavior:
  • Art.
  • Pawns.
  • Physical Form.
  • Art selected from the fifteen Arts.
  • Pawns must be positive.
  • Art, Technique/Form, and Pawns sorting in both directions where implemented.
  • manual ordering only through Up/Down buttons.
  • no visible Manual Order sort option.

• Confirm linked Familiar behavior:
  • Familiar data is linked from Creature XML.
  • Creature-side data remains owned by the Creature record.
  • Magus-side bond data remains owned by the Character record.
  • Character does not silently mutate external Creature XML.

• Confirm Familiar bond behavior:
  • Binding Lab Total is manually entered.
  • Bonding Level is calculated from familiar creature-side data.
  • Binding Vis Cost is calculated live from Binding Lab Total.
  • Bronze, Silver, and Gold Cord values remain 0–5.
  • cord point costs and overspend validation work.
  • Familiar Bond Powers remain on the Magus character.

• Confirm linked Laboratory behavior:
  • Laboratory-side data is owned by Laboratory XML.
  • Character-side lab totals and notes are owned by Character XML.
  • Character does not silently mutate external Laboratory XML.
  • linked Laboratory fields display read-only in Quick Character.
  • Basic Lab Total remains editable on the Character.
  • Longevity Ritual Lab Total remains editable on the Character.
  • Longevity Ritual Aging Roll Modifier is calculated live from Longevity Ritual Lab Total.

• Confirm Tiptap usage:
  • active multi-line rich-text editing fields use Tiptap where appropriate.
  • single-line fields, numeric fields, summaries, previews, diagnostics, and generated text do not use Tiptap unnecessarily.
  • raw Tiptap JSON, raw HTML, or raw serialization never appears in ordinary UI.

• Confirm Recent Changes:
  • meaningful add/remove/edit actions are logged.
  • sort-only and order-only actions are not logged.
  • labels and item names are clear.

• Confirm Apply and navigation behavior:
  • Apply remains stable.
  • navigation does not depend on dirty state.
  • Apply & Go to Previous Section and Apply & Go to Next Section remain available where intended.
  • generated/read-only panes have appropriate navigation behavior.

• Confirm save/reload for:
  • one Magus.
  • one Companion.
  • one Grog.

• Confirm current test files load where applicable:
  • test Magus.
  • test Familiar.
  • test Laboratory.

• Confirm Character Art behavior if currently supported.
• Confirm provisional Sheet Preview remains usable and does not expose internals.

Do Not Include Yet:

• Do not redesign Quick Character.
• Do not begin Guided Character Creation.
• Do not alter the app shell.
• Do not rewrite Apply or dirty-state behavior.
• Do not change navigation behavior.
• Do not implement autosave.
• Do not change XML schemas.
• Do not change package content unless separately approved.
• Do not reintroduce hardcoded Partial/Full armor splitting.
• Do not expose raw XML, raw HTML, Tiptap JSON, IDs, package diagnostics, or schema internals in ordinary UI.

Tools Needed:

• Current packaged app build.
• Current XML schema.
• Current core package.
• Existing character test files.
• Existing familiar and laboratory test files.
• Ars Magica Markdown reference as needed.
• Manual QA notes.

Skills Needed:

• Ars Magica character sheet familiarity.
• Knowledge of current Quick Character pane behavior.
• Understanding of linked Familiar and linked Laboratory ownership.
• Tiptap/rich-text surface awareness.
• Save/reload regression testing.
• UI consistency review.

RAD-Spiral Test:

A tester should be able to open or create a Magus, Companion, and Grog; move through the full Quick Character sheet; make ordinary edits; link a Familiar and Laboratory where applicable; save; reload; and confirm that the character remains coherent, readable, and free of raw internal data.

Milestone 3.7.2 — Quick Creature Alpha§

Status: Planned.

Goal: Make Quick Creature a usable alpha-level creature sheet.

Quick Creature should support practical manual entry and review of Ars Magica creature records, including mundane animals, magical beasts, faeries, demons, spirits, dragons, giants, constructs, and similar beings. It should also support creatures that may later be linked as familiars, while preserving the accepted rule that Familiar bond data belongs to the Magus character, not the Creature record.

Scope:

This milestone covers the Quick Creature screen as a first-class record sheet. A Creature should be saveable, reloadable, readable, and useful as a saga record even before deeper guided creature creation exists.

Quick Creature should support both package-backed creature content where available and custom/manual creature entry where needed.

Deliverables:

• Creature identity section:
  • name.
  • creature type or category.
  • realm where applicable.
  • Might where applicable.
  • Size.
  • source/provenance.
  • custom/source status.

• Concept and description section:
  • short concept or summary.
  • appearance.
  • habitat.
  • behavior.
  • story notes.

• Characteristics section:
  • standard Ars Magica Characteristics.
  • clear handling of Intelligence versus Cunning where applicable.
  • clean display for non-human or animal-like creatures.

• Abilities section:
  • package-backed Abilities where supported.
  • custom/manual Abilities where supported.
  • score display.
  • clean add/remove/edit behavior.
  • stable save/reload.

• Powers section:
  • power name.
  • Might cost where applicable.
  • Initiative where applicable.
  • Form/Technique or realm-related summary where supported.
  • range/duration/target or comparable notes where supported.
  • rich-text power description where appropriate.

• Qualities and Inferiorities section:
  • list of creature qualities.
  • list of creature inferiorities.
  • clear add/remove/edit behavior.
  • package-backed references where supported.

• Virtues and Flaws section where applicable:
  • package-backed references where supported.
  • custom/manual entries where needed.
  • clear distinction from Qualities and Inferiorities.

• Combat section:
  • attacks.
  • damage.
  • defense.
  • soak.
  • fatigue/wound summary where supported.
  • equipment or natural weapon notes where supported.

• Familiar suitability section:
  • indication of whether the creature can be linked as a familiar.
  • creature-side data needed by the Character Familiar pane.
  • no Magus-side bond values.
  • no Bronze/Silver/Gold Cord values.
  • no Familiar Bond Powers.

• Notes section:
  • Tiptap-backed rich-text notes for active multi-line user editing.
  • no raw serialization in display.

• Save/load support:
  • create a new creature.
  • edit an existing creature.
  • save.
  • reload.
  • confirm no data loss.

• Fixture regression:
  • load test-familiar.xml.
  • confirm creature-side familiar data displays correctly.
  • confirm no authoritative Familiar bond values are expected in Creature XML.
  • confirm Quick Character can still link to the familiar creature after this work.

Do Not Include Yet:

• Do not create a separate Familiar entity type.
• Do not move Bronze, Silver, or Gold Cord values into Creature XML.
• Do not move Familiar Bond Powers into Creature XML.
• Do not silently mutate external Creature XML from Quick Character.
• Do not implement full guided creature creation.
• Do not implement deep Might or creature power legality automation unless already supported.
• Do not redesign the app shell.
• Do not change XML schemas unless separately approved.
• Do not expose raw IDs, XML, package paths, schema internals, diagnostics, or raw Tiptap serialization in ordinary UI.

Tools Needed:

• Current app.
• Current XML schema.
• Current core package.
• Ars Magica Markdown reference corpus.
• test-familiar.xml.
• Creature screenshots.
• Manual QA notes.

Skills Needed:

• Ars Magica creature rules familiarity.
• Understanding of Creature versus Familiar ownership.
• XML save/load testing.
• Tiptap usage discipline.
• Package-backed data display.
• UI consistency work.

RAD-Spiral Test:

A tester should be able to create or open a creature, enter its identity, Characteristics, Abilities, Powers, Qualities, Inferiorities, combat information, and notes; save it; reload it; and confirm that the record remains usable. The tester should also be able to load test-familiar.xml and confirm that it remains suitable for linking from Quick Character without storing Magus-side bond data.

Milestone 3.7.3 — Quick Covenant Alpha§

Status: Planned.

Goal: Make Quick Covenant a usable alpha-level covenant sheet.

A Covenant is a first-class managed record in Hermetic Foundry. It should not be treated merely as a note attached to characters. Quick Covenant should allow a troupe to enter and maintain a practical covenant record for saga play, even before full covenant build rules or guided covenant creation exist.

Scope:

This milestone covers Quick Covenant as a direct manual-entry sheet for covenant information. It should support ordinary saga recordkeeping: identity, location, members, laboratories, library, vis, resources, defenses, relationships, and notes.

This milestone should focus on coherent structure, save/load stability, and Ars Magica terminology rather than full covenant accounting.

Deliverables:

• Covenant identity section:
  • name.
  • saga.
  • covenant type or role.
  • tribunal or region.
  • location.
  • founding year.
  • current year where supported.
  • season of covenant.
  • source/provenance where applicable.

• Aura section:
  • aura type.
  • aura strength.
  • aura notes.

• Concept and description section:
  • concept.
  • physical description.
  • history.
  • local environment.
  • storyguide notes where supported.

• Charter and governance section:
  • charter summary.
  • governance model.
  • council structure.
  • voting or membership notes.
  • duties and offices where supported.

• Boons and Hooks section:
  • package-backed Boons and Hooks where supported.
  • manual/custom Boons and Hooks where needed.
  • clear add/remove/edit behavior.
  • readable summaries.

• Members and residents section:
  • magi.
  • companions.
  • grogs.
  • specialists.
  • servants.
  • covenfolk.
  • notable residents.
  • linked Character references where supported.
  • manual entries where linking is not yet available.

• Laboratories section:
  • linked Laboratory records where supported.
  • manual lab summaries where linking is not yet available.
  • owning or using magus where supported.
  • status/setup summary.

• Library and texts section:
  • books.
  • tractatus/summae/lab texts where supported.
  • linked Book records where available.
  • manual entries where needed.
  • notes on access or restrictions.

• Vis section:
  • vis sources.
  • vis stocks.
  • Art.
  • pawns.
  • source or storage notes.
  • linked Vis Source records where available.

• Resources and economy section:
  • income.
  • expenses.
  • mundane wealth.
  • important assets.
  • mundane staff or holdings.
  • economic notes.

• Defenses and equipment section:
  • mundane defenses.
  • magical defenses.
  • guards.
  • arms and armor.
  • fortifications.
  • important equipment.

• Reputations and relationships section:
  • Hermetic reputation.
  • mundane reputation.
  • local relationships.
  • noble/church/tribunal relationships.
  • rivals and allies.

• Symbol, heraldry, or image placeholder where currently supported.
• Notes section:
  • Tiptap-backed rich-text notes where appropriate.
  • no raw serialization in ordinary UI.

• Provisional print preview placeholder.
• Save/load support:
  • create a new covenant.
  • edit an existing covenant.
  • save.
  • reload.
  • confirm no data loss.

Do Not Include Yet:

• Do not implement full covenant build-point accounting.
• Do not implement full library value calculation.
• Do not implement full vis economy automation.
• Do not implement Boon/Hook legality enforcement.
• Do not implement full guided covenant creation.
• Do not redesign linked Character, Laboratory, Book, or Vis Source systems unless separately approved.
• Do not change XML schemas unless separately approved.
• Do not expose raw XML, IDs, schema internals, package diagnostics, or raw Tiptap serialization in ordinary UI.

Tools Needed:

• Current app.
• Current XML schema.
• Current core package.
• Ars Magica Markdown reference corpus.
• Covenant screenshots.
• Manual QA notes.

Skills Needed:

• Ars Magica covenant rules familiarity.
• Understanding of covenant recordkeeping needs.
• Linked entity design awareness.
• XML save/load testing.
• Tiptap usage discipline.
• UI organization and consistency review.

RAD-Spiral Test:

A tester should be able to create or open a covenant, enter its identity, aura, description, governance, Boons and Hooks, members, laboratories, library, vis, resources, defenses, and relationships; save it; reload it; and confirm that it remains a coherent alpha-level saga record without requiring full covenant build automation.

Milestone 3.7.4 — Quick Laboratory Alpha§

Status: Planned.

Goal: Make Quick Laboratory a usable alpha-level standalone Laboratory entity sheet.

Laboratory is a first-class record type. A Character may link to a Laboratory, but the Character does not own the lab-side data. Quick Laboratory should allow a user to create, edit, save, reload, and review a laboratory as its own saga object.

Scope:

This milestone covers Quick Laboratory as a standalone sheet for Laboratory XML. It should align with the ownership model already established during the G28 Laboratory and Longevity work.

Laboratory XML owns objective lab-side data. Character XML owns character-side lab totals, longevity ritual information, and notes specific to the character’s use of the lab.

Deliverables:

• Laboratory identity section:
  • laboratory name.
  • status/type.
  • source/provenance.
  • custom/source status.

• Location and association section:
  • covenant association.
  • physical location.
  • owning or using magus.
  • linked Character or Covenant references where supported.
  • manual entries where linking is not yet available.

• Setup section:
  • setup state.
  • construction state.
  • occupied/unused/ruined/temporary status where supported.
  • setup notes.

• Core characteristics section:
  • Size.
  • square feet.
  • Refinement.
  • General Quality.
  • Upkeep.
  • Safety.
  • Warping.
  • Health.
  • Aesthetics.

• Virtues and Flaws section:
  • Laboratory Virtues.
  • Laboratory Flaws.
  • package-backed references where supported.
  • manual/custom entries where needed.
  • readable summaries.
  • stable add/remove/edit behavior.

• Specializations section:
  • specialization name or type.
  • value.
  • notes where supported.

• Features and Foci section:
  • major features.
  • minor features.
  • foci.
  • physical or magical descriptions where supported.

• Magical improvements section:
  • improvements already present.
  • improvements in progress where supported.
  • story or construction notes.

• Build Point summary:
  • display current Build Point information if already supported by the schema/model.
  • keep this as a summary, not a full builder, unless the model already supports more.

• Notes section:
  • laboratory description.
  • laboratory notes.
  • setup/construction notes.
  • Tiptap-backed rich-text fields where appropriate.
  • no raw serialization in ordinary UI.

• Character linking behavior:
  • Quick Character can link to a Laboratory.
  • linked lab-side fields display read-only in Quick Character.
  • Character-side fields remain editable in Quick Character.
  • Quick Character does not silently mutate external Laboratory XML.

• Provisional print preview placeholder.
• Save/load support:
  • create a new laboratory.
  • edit an existing laboratory.
  • save.
  • reload.
  • confirm no data loss.

• Fixture regression:
  • load test-laboratory.xml.
  • confirm lab identity, status/type, location, setup, specializations, characteristics, Virtues, and Flaws display correctly.
  • confirm Quick Character can still link to the same laboratory.
  • confirm character-side lab totals and longevity notes remain owned by the Character.

Do Not Include Yet:

• Do not implement the full Covenants laboratory builder unless schema/model expansion is approved.
• Do not make Character XML own lab-side data.
• Do not silently mutate external Laboratory XML from Quick Character.
• Do not move Basic Lab Total, Longevity Ritual Lab Total, Longevity Ritual Aging Roll Modifier, Laboratory Notes, or Longevity Ritual Notes into Laboratory XML.
• Do not change the accepted G28 ownership model.
• Do not change XML schemas unless separately approved.
• Do not implement deep lab automation unless already safely supported.
• Do not expose raw XML, IDs, schema internals, package diagnostics, or raw Tiptap serialization in ordinary UI.

Tools Needed:

• Current app.
• Current XML schema.
• Current core package.
• Ars Magica Markdown reference corpus.
• test-laboratory.xml.
• Laboratory screenshots.
• Manual QA notes.

Skills Needed:

• Ars Magica laboratory rules familiarity.
• Understanding of the G28 Laboratory ownership model.
• Linked entity design awareness.
• XML save/load testing.
• Tiptap usage discipline.
• UI consistency review.

RAD-Spiral Test:

A tester should be able to create or open a Laboratory record, enter its identity, location, setup, characteristics, Virtues, Flaws, specializations, features, improvements, and notes; save it; reload it; and confirm that it remains a usable standalone lab record. The tester should also be able to link it from Quick Character without transferring ownership of lab-side data to the Character.

Milestone 3.7.5 — Quick Item Alpha§

Status: Planned.

Goal: Make Quick Item a usable alpha-level item sheet for mundane and magical items.

Quick Item should support the kinds of objects that matter in Ars Magica sagas: mundane equipment, valuable objects, enchanted devices, charged items, invested items, talismans, relics, laboratory objects, covenant treasures, and other notable possessions.

This milestone should make Item records useful for manual entry and saga tracking. It should not attempt to implement the full enchanted item construction rules yet.

Scope:

This milestone covers Quick Item as a first-class record sheet. An Item should be saveable, reloadable, readable, and useful whether it is mundane, magical, package-backed, or custom.

The sheet should distinguish mundane and magical items clearly, but should not require deep rules automation before an item can be recorded.

Deliverables:

• Item identity section:
  • item name.
  • item kind/type.
  • mundane or magical indicator.
  • source/provenance.
  • custom/source status.

• Physical description section:
  • material.
  • form.
  • appearance.
  • size.
  • load where applicable.
  • condition.
  • physical description.

• Value and availability section:
  • value or cost where supported.
  • availability.
  • rarity.
  • expensive status where supported.
  • ownership/use notes.

• Ownership and use section:
  • current owner.
  • current user.
  • covenant association.
  • laboratory association.
  • linked Character, Covenant, or Laboratory references where supported.
  • manual entries where linking is not yet available.

• Magical item section:
  • magical item category.
  • enchanted device.
  • lesser enchanted device.
  • invested item.
  • charged item.
  • talisman.
  • relic or other special object where supported.

• Effect summary section:
  • effect name.
  • Technique and Form where supported.
  • level where supported.
  • penetration where supported.
  • uses per day where supported.
  • trigger notes where supported.
  • range/duration/target where supported.
  • linked Spell or Effect records where available.
  • manual effects where linking is not yet available.

• Vis and capacity section:
  • vis capacity summary where supported.
  • invested vis where supported.
  • remaining capacity where supported by existing model.
  • vis notes.

• Rich-text effect description:
  • effect description.
  • activation description.
  • limitations or story notes.
  • Tiptap-backed rich-text fields where appropriate.
  • no raw serialization in ordinary UI.

• History and story section:
  • creation history.
  • laboratory history.
  • ownership history.
  • story hooks.
  • covenant notes.

• Future link behavior:
  • preserve compatibility with future links to Character, Covenant, and Laboratory records.
  • do not require those links to be complete before the Item sheet is useful.

• Provisional print preview placeholder.
• Save/load support:
  • create a new item.
  • edit an existing item.
  • save.
  • reload.
  • confirm no data loss.

Do Not Include Yet:

• Do not implement full spell design.
• Do not implement full enchanted item construction.
• Do not implement automatic vis capacity calculation unless already safely supported.
• Do not implement lab-total automation.
• Do not require a linked Spell or Laboratory to create a magical item record.
• Do not redesign Character, Covenant, or Laboratory ownership models.
• Do not change XML schemas unless separately approved.
• Do not expose raw XML, IDs, schema internals, package diagnostics, or raw Tiptap serialization in ordinary UI.

Tools Needed:

• Current app.
• Current XML schema.
• Current core package.
• Ars Magica Markdown reference corpus.
• Item screenshots.
• Manual QA notes.

Skills Needed:

• Ars Magica item and enchanted device rules familiarity.
• Understanding of mundane versus magical item recordkeeping.
• Linked entity design awareness.
• XML save/load testing.
• Tiptap usage discipline.
• UI consistency review.

RAD-Spiral Test:

A tester should be able to create or open mundane and magical Item records, enter identity, physical description, value, ownership, magical category, effects, vis/capacity notes, and history; save; reload; and confirm that the records remain coherent and useful without requiring full enchanted item construction automation.

Milestone 3.8 — Guided Character Creation Prototype§

Status§

Next after Milestone 3.6.

Goal§

Create a wizard-style Guided Creation workflow for Ars Magica characters, using the same underlying character draft data as Quick Sheet, without implementing full character creation legality enforcement or deep rules automation.

The goal is to help users create a character in a clear step-by-step order while preserving Hermetic Foundry’s sheet-first Ars Magica design. Guided Creation should feel like a structured creation assistant, not a separate character system.

Relationship to Quick Sheet§

Guided Creation and Quick Sheet must operate on the same in-memory character draft.

A user should be able to begin a character in Guided Creation, switch to Quick Sheet, see the same data, edit it there, and return to Guided Creation without losing work.

Quick Sheet remains the direct sheet-editing mode. Guided Creation is the step-by-step workflow over that same data.

Navigation between Guided Creation and Quick Sheet must not automatically save to disk. File → Save and File → Save As remain the disk-save actions.

Workflow Steps§

Guided Creation should use the following creation flow for a standard magus, based on the accepted workflow screen:

1. Concept
2. Characteristics
3. Virtues & Flaws
4. Abilities
5. Arts
6. Childhood
7. Apprenticeship
8. After Gauntlet
9. Equipment
10. Details

The stepper should clearly show the current step and allow the user to understand where they are in the creation process.

The workflow should initially prioritize Magus creation, but it should not permanently hard-code the system against Companions, Grogs, Mythic Companions, or custom character types. Non-magus variants may hide, skip, rename, or mark Hermetic-only steps as not applicable in a later pass.

Step Requirements§

1. Concept§

Capture the broad character idea and core identity.

Support fields such as:

• Character name
• Character type
• Player
• Saga
• Setting
• Current year
• Covenant association
• House, if Magus
• Concept summary
• Short notes

This step should establish whether the character is a Magus, Companion, Grog, Mythic Companion, or Other/custom.

2. Characteristics§

Guide entry of the eight Ars Magica Characteristics:

• Intelligence / Int
• Perception / Per
• Strength / Str
• Stamina / Sta
• Presence / Pre
• Communication / Com
• Dexterity / Dex
• Quickness / Qik

This milestone may preserve manual entry and simple range warnings. It should not attempt full Virtue/Flaw-driven characteristic automation.

3. Virtues & Flaws§

Provide a guided version of package-backed Virtue and Flaw selection.

Support:

• Search
• Category filtering where available
• Details popup
• Add Virtue / Add Flaw
• Selected Virtues list
• Selected Flaws list
• Character-instance notes
• Required choice/specification fields where package data supports them

Do not implement full legality enforcement yet.

The v0.3.6 parameter-aware schema data should be preserved and available to the application, but full interpretation of prohibitions, requirements, point balancing, and rulesImpact automation belongs to the later rules automation spiral.

4. Abilities§

Guide entry of starting Abilities.

Support package-backed Ability selection and character-instance fields:

• Ability
• Specialty
• Score
• XP
• Notes

This step should eventually support childhood, apprenticeship, and later-life XP allocation, but the first prototype may remain partially manual as long as the UI structure matches the intended creation flow.

5. Arts§

For Magi, guide entry of Hermetic Arts.

Support Techniques:

• Creo
• Intellego
• Muto
• Perdo
• Rego

Support Forms:

• Animal
• Aquam
• Auram
• Corpus
• Herbam
• Ignem
• Imaginem
• Mentem
• Terram
• Vim

Support score, XP, and notes.

For non-magi, this step may be skipped, hidden, collapsed, or marked not applicable.

6. Childhood§

Represent Early Childhood and Later Life before apprenticeship.

Support the existing phase-aware experience model:

• Early Childhood flexible XP: 45
• Later Life before apprenticeship: (Apprentice Age - 5) × 15
• Native Language 5 is automatic and should not consume the flexible creation budget

This milestone does not need a complete XP-spending engine, but the screen should make the creation phase visible and prepare the UI for later automation.

7. Apprenticeship§

Represent the apprenticeship phase for Magi.

Support:

• Apprentice Age
• Apprenticeship Length
• Gauntlet Age
• Parens
• Apprentice covenant / covenant of apprenticeship
• Apprenticeship Ability and Art development
• Apprenticeship spell levels

Use the current standard defaults unless changed:

• Apprentice Age: 10
• Apprenticeship Length: 15
• Gauntlet Age: Apprentice Age + 15
• Apprenticeship budget: 240 XP for Arts/Abilities plus 120 spell levels

This step should not yet implement a full apprenticeship rules engine, but it should display and preserve the relevant fields cleanly.

8. After Gauntlet§

Represent post-Gauntlet development.

Support:

• Current age
• Gauntlet age
• Years after apprenticeship
• Post-Gauntlet XP budget display
• Notes/history for post-Gauntlet development

Use the current phase-aware formula:

• Years After Apprenticeship: (Current Age - Gauntlet Age) × 30

This milestone may keep spending manual or partially manual.

9. Equipment§

Guide entry of basic carried equipment, weapons, armor, and combat-relevant items.

Support package-backed selection where available:

• Weapons
• Armor
• Shields
• Unarmed combat modes
• General equipment

Support character-instance fields:

• Quantity
• Carried/equipped/stored state
• Notes

Do not implement full load, burden, encumbrance, combat total, or armor automation yet unless already present and stable.

10. Details§

Capture biographical and finishing details.

Support:

• Exact date of birth
• Height
• Weight
• Hair colour
• Eye colour
• Handedness
• Appearance
• Biography
• Character art
• Character summary
• Linked content
• Notes

This step should serve as the finishing and review step before the character is used in Quick Sheet or saved.

User-Facing Behaviour§

Guided Creation should feel like a calm, structured assistant for building a character.

Each step should have clear navigation:

• Previous
• Next
• Apply Changes
• Apply Changes and Continue

Buttons should update the in-memory draft only. They should not save to disk.

The top stepper should remain visible and should clearly show the current step.

Where a step is not applicable, the UI should explain that briefly without sounding like an error.

Save/Load Requirements§

Guided Creation must use the same character save/load path as Quick Sheet.

Data entered in Guided Creation must:

• appear in Quick Sheet,
• save to XML,
• reload from XML,
• preserve package-backed references,
• preserve embedded snapshots where already supported,
• preserve character-instance notes and choices.

Do Not Include Yet§

Do not implement:

• Full character creation legality enforcement
• Full Virtue/Flaw point validation
• Full parameter-aware prohibition enforcement
• Full rulesImpact automation
• Full Ability XP spending validation
• Full Arts XP spending validation
• Full spell-design automation
• Full seasonal advancement
• Full aging or Warping automation
• Full lab activity automation
• Final print/PDF export

RAD-Spiral Test§

A user can open Guided Creation, create a basic Magus by moving through the ten-step workflow, switch to Quick Sheet, see the same character data, save the character, reload it, and continue editing without losing package-backed selections or character-instance data.

The workflow should make character creation feel more organized, even though full rules automation is still deferred.

13Spiral 4: Covenant, Laboratory, and Campaign Infrastructure§

Purpose§

Build the major Ars Magica management systems beyond individual characters.

Covenants and laboratories are first-class managed records, not notes or character subfields.

Milestone 4.1 — Covenant Workflow Prototype§

Goal§

Model covenants as major managed entities.

Deliverables§

• Covenant identity.
• Charter/governance.
• Boons and Hooks.
• Members.
• Laboratories.
• Library.
• Lab texts.
• Vis sources.
• Vis stocks.
• Finances/accounting placeholder.
• Land holdings.
• Specialists/craftsmen.
• Reputations.
• Weapons and armor.
• Enchanted items.
• Notes.
• Symbol/heraldry.
• Print/export placeholder.Link covenant members to Character records.
• Distinguish magi, companions, grogs, specialists, and other covenant residents where practical.
• Use package-backed Boons and Hooks.
• Show covenant-owned weapons, armor, books, vis stocks, enchanted items, and laboratories as linked content.
• Provide a path from covenant member lists to the linked Character workflow.
• Preserve embedded snapshots for linked records where appropriate.

Tools Needed§

• TypeScript
• XML
• Entity linking
• Codex

Skills Needed§

• Ars Magica covenant rules
• Data modeling
• UI organization for large records
• Accounting-style forms

RAD-Spiral Test§

A covenant can contain linked characters, creatures, laboratories, books, vis sources, enchanted items, and notes.

Milestone 4.2 — Laboratory Workflow Prototype§

Goal§

Model magi laboratories as their own managed sheet-like entities.

Deliverables§

• Lab name.
• Square feet.
• Size.
• Refinement.
• General Quality.
• Upkeep.
• Safety.
• Warping.
• Health.
• Aesthetics.
• Virtues.
• Flaws.
• Virtue limits.
• Build Points.
• Enchanted items.
• Routines.
• Notes.
• Symbol/icon.
• Increase Refinement command placeholder.
• Link laboratory to owning/using magus where applicable.
• Link laboratory to covenant where applicable.
• Support lab virtues/flaws as package-backed selectable content.
• Show lab modifiers in a way that can later feed character lab totals.
• Provide a path from a magus’s character sheet to the linked laboratory.
• Preserve laboratory independence as a first-class entity.

Tools Needed§

• TypeScript
• XML
• UI forms
• Codex

Skills Needed§

• Ars Magica laboratory rules
• Rules-aware calculation
• Entity relationship modeling
• UI form layout

RAD-Spiral Test§

A laboratory can be attached to a covenant and a magus while still remaining its own independent managed record.

Milestone 4.3 — Library, Books, Lab Texts, and Vis§

Goal§

Build the shared infrastructure that covenants and magi both rely on.

Deliverables§

• Book entity.
• Summa support.
• Tractatus support.
• Lab text support.
• Casting tablet placeholder.
• Library list.
• Vis source entity.
• Vis stocks.
• Use Vis command placeholder.
• Reconcile/accounting placeholder.
• Allow characters to reference covenant books for future study activities.
• Allow characters to reference raw vis stocks or personal raw vis.
• Preserve distinction between covenant-owned resources and character-carried resources.
• Prepare links for future seasonal advancement and lab activity workflows.

Tools Needed§

• TypeScript
• XML
• Entity lists
• Codex

Skills Needed§

• Ars Magica seasonal economy
• Library modeling
• Resource tracking
• UI table design

RAD-Spiral Test§

A covenant can own books, lab texts, vis sources, and vis stocks; a character can later study from or use linked records.

14Spiral 5: Rules Depth and Seasonal Lifecycle§

Purpose§

Begin turning Hermetic Foundry from a structured record manager into a rules-aware Ars Magica lifecycle tool. Spiral 5 should build on the character-sheet structures created in Milestone 3.6. The Advancement Activity Engine should update the Experience section and character-instance Ability/Art XP structures created earlier, rather than inventing separate advancement-only records.

Milestone 5.1 — Advancement Activity Engine§

Goal§

Create the seasonal activity structure before implementing every calculation.

Deliverables§

• Season selector.
• Activity record.
• Character advancement log.
• Exposure.
• Practice.
• Training.
• Teaching.
• Study from book.
• Study from vis.
• Story experience.
• Aging roll placeholder.
• Writing activity placeholder.
• Laboratory activity placeholder.
• History log.
• Change history integration.
• Write advancement results into the character’s Experience section.
• Update Ability or Art XP records when an activity is applied.
• Preserve a readable advancement history.
• Support unapplied or draft advancement records if useful.
• Link advancement activities to books, teachers, trainers, adventures, exposure, practice, vis study, and story events.
• Keep manual correction/override possible.

Tools Needed§

• TypeScript
• XML
• Date/season handling
• Codex

Skills Needed§

• Ars Magica advancement rules
• Timeline modeling
• User-friendly lifecycle UX
• Audit trail integration

RAD-Spiral Test§

A character can be advanced through several seasons, and the app preserves a readable advancement history.

Milestone 5.2 — Laboratory Activity Engine§

Goal§

Support the central Hermetic seasonal workflow.

Deliverables§

• Spell invention/design activity.
• Learn spell from lab text.
• Enchant item placeholder.
• Longevity ritual placeholder.
• Vis extraction placeholder.
• Familiar work placeholder.
• Lab setup/improvement/refinement placeholder.
• Lab total calculation placeholders.
• Activity result summary.
• Linked lab support.
• Linked covenant resource support.
• Read character Arts, Abilities, lab, aura, familiar, and relevant modifiers from established character/lab structures.
• Write learned spells into Spells Known.
• Write invented spells or lab texts as linked entities where appropriate.
• Update longevity ritual summary where appropriate.
• Preserve manual override and calculation notes.

Tools Needed§

• TypeScript
• XML
• Calculation engine
• Codex

Skills Needed§

• Ars Magica lab rules
• Calculation modeling
• Dependency tracking
• Test case construction

RAD-Spiral Test§

A magus with Arts, Abilities, lab, aura, and texts can perform a basic lab activity and produce a saved seasonal result.

Milestone 5.3 — Mystery Cult Initiation Workflow§

Goal§

Represent initiations as procedural records built from components.

Deliverables§

• Initiation Script entity.
• Cult/House/Tradition.
• Relevant Lore Ability.
• Mystagogue.
• Initiate.
• Virtue to be gained.
• Major/Minor status.
• Whether Virtue is known by Mystagogue.
• Target Level calculation.
• Previous Ordeal discount tracking.
• Script Bonus total.
• Required Presence + Lore display.
• Number of seasons.
• Script text.
• Structured component list.
• Component picker.
• Requirement checker placeholder.

Component Types§

• Grant Virtue.
• Great Sacrifice.
• Learn.
• Major Ordeal.
• Medium Ordeal.
• Minor Ordeal.
• Material Sacrifice.
• Mystagogue Time.
• Open-ended custom component.
• Personality Trait.
• Quest.
• Unique Quest.
• Remove Flaw.
• Replace Virtue.
• Required Ability.
• Required Characteristic.
• Required Flaw.
• Required Virtue.
• Sympathetic Bonus.
• Time Sacrifice.
• Travel.
• Warping.

Tools Needed§

• TypeScript
• XML
• Rules calculation engine
• UI component picker
• Codex

Skills Needed§

• Ars Magica Mystery rules
• Procedural workflow design
• Requirement validation
• Complex form UX

RAD-Spiral Test§

The app can build, save, reload, and validate an initiation script with components and calculated totals.

15Spiral 6: Custom Content Workbench§

Purpose§

Make Hermetic Foundry extensible through safe, form-based custom content creation and package import/export.

The Customizer is not a separate raw XML editor. It is a form-based Custom Content Workbench inside the main application.

Milestone 6.1 — Custom Content Project Model§

Goal§

Create the package/project model for custom content.

Deliverables§

• Custom Content Workbench screen.
• Create custom package/project.
• Edit package metadata.
• Stable package ID.
• Version based on UNIX timestamp.
• Human-readable Date Created.
• Human-readable Last Modified.
• Package checksum.
• Source metadata.
• Required LICENSE.xml.
• Manifest.xml.
• Content XML file list.
• Optional media folder.

Required Package Structure§

At minimum, a custom package ZIP should contain:

• manifest.xml
• LICENSE.xml
• content XML files
• optional help XML files
• optional media files

Tools Needed§

• TypeScript
• XML
• ZIP packaging
• Checksum logic
• Codex

Skills Needed§

• Package design
• XML metadata
• File bundling
• Validation UX

RAD-Spiral Test§

A user can create a custom content project and export it as a valid package structure.

Milestone 6.2 — Custom Entity Creation Forms§

Goal§

Allow users to create custom content without directly editing XML.

Deliverables§

• Custom Virtue form.
• Custom Flaw form.
• Custom Ability form.
• Custom Spell form.
• Custom Item form.
• Custom Creature form.
• Custom Book form.
• Custom Vis Source form.
• Custom Help File form.
• XML preview panel.
• Quiet validation panel or warning display.
• Custom Virtue/Flaw forms should include RulesImpact target-path support for character-sheet fields.
• Custom Item/Weapon/Armor forms should support Load and character-sheet combat/equipment fields.
• Custom Spell forms should support fields needed by Spells Known.
• XML preview should make clear whether a custom entity can be selected into a character sheet.

Tools Needed§

• TypeScript
• XML
• Schema validation
• Codex
• XML Copy Editor for schema/content review

Skills Needed§

• Form generation
• Rules taxonomy
• XML mapping
• Error messaging

RAD-Spiral Test§

A user can create a custom spell, export it, import it into another installation, and use it on a character.

Milestone 6.3 — Import System§

Goal§

Let Hermetic Foundry import one or more custom packages safely.

Deliverables§

• Import package button.
• Multi-package import.
• ZIP validation.
• Manifest validation.
• LICENSE.xml validation.
• Checksum validation.
• Dependency detection.
• Conflict detection.
• Import preview.
• User confirmation step.
• Installed package registry.
• Package enable/disable placeholder.
• Import preview should show whether package content is usable in character workflows.
• Duplicate stable ID warnings should be type-aware.
• Duplicate canonical IDs remain blocking.
• Strict canonical checksum verification should become a release requirement before untrusted external package imports are treated as fully trusted.
• Package import should preserve rulesImpact data needed by character sheet derived values.

Source Handling§

• If source is a URL, offer to fetch/import it.
• If source is an email address, open the default email client.
• Otherwise, render source as plain text.

Safety Requirement§

Web source imports should never silently install.

Hermetic Foundry should download, validate, preview, and ask for user confirmation before installing imported content.

Tools Needed§

• Tauri file access
• ZIP handling
• XML validation
• HTTP fetch support
• Checksum logic
• Codex

Skills Needed§

• Secure file import
• User confirmation flows
• Dependency/conflict resolution
• Defensive programming

RAD-Spiral Test§

A package from another installation can be imported, previewed, validated, accepted, and used without silently overwriting existing content.

16Spiral 7: Help System and Documentation§

Purpose§

Create a built-in XML help system that can display both core Hermetic Foundry help and custom package help.

Milestone 7.1 — XML Help File System§

Goal§

Create XML-based help files for Hermetic Foundry and custom packages.

Deliverables§

• Help XML schema.
• Help file title.
• Nested header support.
• Body text support.
• Rich text support.
• Table support.
• Cross-reference placeholder.
• Package-provided help files.
• Core help files.
• Help file validator.
• Context-sensitive Help placeholders for character sheet sections.
• Help should explain fields in user-facing Ars Magica terms, not XML/schema terms.
• Help entries for:

• Identity and Background
• Characteristics
• Virtues and Flaws
• Abilities
• Arts
• Combat
• Fatigue and Wounds
• Spells Known
• Familiar
• Experience and Advancement

Header Example§

<header level="1">Character Creation</header>

<header level="2">Virtues and Flaws</header>

Tools Needed§

• XML
• TypeScript
• Help content renderer
• XML Copy Editor
• Codex

Skills Needed§

• XML document design
• Content rendering
• Table of contents generation
• Documentation writing

RAD-Spiral Test§

The app can load multiple help XML files and render them into readable help pages.

Milestone 7.2 — Collated Help Browser§

Goal§

Present all installed help files as a unified in-app reference.

Deliverables§

• Help browser.
• Table of contents generated from help titles and nested headers.
• Search placeholder.
• Filter by package/source.
• Core rules help section.
• Custom content help section.
• Context-sensitive Help button placeholder.
• Focused Help layout without the normal Info pane.

Tools Needed§

• TypeScript
• XML parser
• Search/index placeholder
• Codex

Skills Needed§

• Information architecture
• Navigation design
• Search UX
• Documentation organization

RAD-Spiral Test§

A custom package can add its own help file, and Hermetic Foundry automatically includes it in the Help browser.

Milestone 7.3 — Help Menu Utilities§

Goal§

Build out practical Help menu functions.

Deliverables§

• Hermetic Foundry Help.
• Ars Magica Open License.
• About Hermetic Foundry.
• Check for Updates placeholder.
• Installed package help access.
• Troubleshooting/help diagnostics placeholder if useful.
• Reopen Welcome / Getting Started overlay.

Tools Needed§

• TypeScript
• Tauri shell/window support
• Help browser
• Codex

Skills Needed§

• Menu behaviour
• App metadata handling
• Update workflow planning
• Help UX

RAD-Spiral Test§

The Help menu provides useful, organized support functions, including a placeholder path for checking app updates.

17Spiral 8: Print, Preview, Export, and Usability§

Purpose§

Make Hermetic Foundry useful at the table and comfortable during real campaign prep.

This spiral should refine user experience, print output, visual consistency, and table-use practicality.

Milestone 8.1 — Print and Preview Framework§

Goal§

Milestone 8.1 should refine and complete print/preview/export. It should not be the first milestone to create character sheet preview. Milestone 3.6 creates provisional character sheet preview for QA; Spiral 8.1 turns provisional previews into robust printable/exportable templates.

Deliverables§

• Print preview for characters.
• Print preview for creatures.
• Print preview for covenants.
• Print preview for laboratories.
• Print preview for items.
• Basic PDF/export placeholder.
• Sheet template system placeholder.
• Auxiliary files print placeholder.
• Focused Print Preview layout without the normal Info pane.
• Final character sheet print template.
• Option to print a sheet-faithful Ars Magica character sheet.
• Optional alternate compact character sheet template.
• Print/export support for character art if included.
• Print/export support for linked spells, familiar, equipment, and notes.
• Ensure Print Preview uses focused layout without normal Info pane.
• PDF/export path if feasible.

Tools Needed§

• HTML/CSS print styles
• Tauri print/export support
• Codex

Skills Needed§

• Print CSS
• Layout design
• Data-to-template mapping
• Usability testing

RAD-Spiral Test§

A user can preview or print a usable sheet for the main managed entity types.

Milestone 8.2 — Practical Table Use Pass§

Goal§

Test the app as an actual Ars Magica table tool rather than a database.

Deliverables§

• Recently used entities.
• Fast search.
• Open linked entity from sheet.
• Duplicate entity.
• Archive entity.
• Notes panel.
• Storyguide/admin-only notes placeholder if desired later.
• Error recovery pass.
• Unsaved changes warnings.
• UI state persistence refinement.
• Recent Changes usability review.
• Open linked spell from character sheet.
• Open linked weapon/armor/item from character sheet.
• Open linked familiar creature from character sheet.
• Open linked covenant/laboratory from character sheet.
• Fast search should find characters by character name, birth name, House, covenant, player, and saga.
• Recently used entities should prioritize active campaign material.

Tools Needed§

• TypeScript
• UI state management
• Search/indexing
• Codex

Skills Needed§

• UX testing
• Desktop app polish
• State management
• Error handling

RAD-Spiral Test§

During a mock session, the user can quickly find a character, creature, covenant, spell, item, or lab without fighting the interface.

18New Spiral 9 — UI Polishing§

Purpose§

Before Hermetic Foundry enters deep rules automation, the application should receive a full UI polish pass.

By this point, the application will have broad workflows, Quick Sheet mode, Guided Creation, package-backed content, provisional previews, and major managed-entity structures. Spiral 9 exists to review the whole interface as an application rather than as a sequence of isolated milestones.

The goal is not to redesign Hermetic Foundry. The goal is to refine what already exists.

Milestone 9.1 — Application-Wide UI Onceover§

Goal§

Review the complete application UI and correct awkwardness, inconsistency, rough layout, unclear hierarchy, and small usability problems.

Deliverables§

• Review all major screens.
• Tighten spacing and alignment.
• Correct awkward field layouts.
• Remove unnecessary visual noise.
• Improve button placement and hierarchy.
• Ensure repeated UI patterns behave consistently.
• Review side panes, cards, forms, steppers, selectors, popups, and modals.
• Confirm Help and Print Preview still use focused layouts.
• Confirm normal screens preserve the accepted Navigator / Content / Info structure.
• Confirm no ordinary user screen exposes raw XML, validation internals, or package diagnostics.

RAD-Spiral Test§

A user can move through the main workflows without obvious rough prototype artifacts distracting from the task.

Milestone 9.2 — Icon and Visual Language Polish§

Goal§

Refine Hermetic Foundry’s icon set, visual accents, and branding elements.

Deliverables§

• Review icon size consistency.
• Review icon line-weight consistency.
• Fix unclear icons.
• Refine the Laboratory icon.
• Refine Spell, Book, Initiation Script, Help, Search, Custom Content, and package-related icons.
• Replace the default Tauri native app icon with a proper Hermetic Foundry application icon.
• Review the in-app Mercury/alchemical glyph beside the Hermetic Foundry wordmark.
• Decide whether the glyph should be kept, refined, or replaced as the official app mark.
• Ensure the application icon, wordmark symbol, and in-app icon language feel visually related.

RAD-Spiral Test§

Hermetic Foundry no longer feels like it is using placeholder iconography. The visual language feels deliberate and consistent.

Milestone 9.3 — Readability and Accessibility Polish§

Goal§

Improve comfort for long rules-heavy sessions.

Deliverables§

• Review typography.
• Review contrast.
• Review parchment/manuscript texture strength.
• Review dense forms for readability.
• Review keyboard navigation.
• Review focus states.
• Review aria labels and semantic HTML.
• Review modal accessibility.
• Confirm important information is not conveyed by colour alone.
• Confirm the app remains visually distinctive without becoming tiring to read.

RAD-Spiral Test§

Hermetic Foundry remains visually thematic while becoming easier to use for long sessions.

19New Spiral 10 — Efficiency Improvements§

Purpose§

Before deep rules automation increases computational complexity, Hermetic Foundry should receive a focused performance and efficiency pass.

The application must remain responsive even when many packages are installed, large content indexes are loaded, and complex character, covenant, laboratory, and custom content workflows are available.

Milestone 10.1 — Startup and Package Loading Performance§

Goal§

Measure and improve startup performance, especially when loading core and custom packages.

Deliverables§

• Measure startup time.
• Measure package scan time.
• Measure package validation time.
• Measure decompressed cache loading time.
• Measure runtime content index build time.
• Avoid unnecessary repeated package scans.
• Avoid unnecessary repeated XML parsing.
• Use cached package/index data where safe.
• Preserve checksum and validation safety.
• Ensure inactive, invalid, checksumMismatch, schemaMismatch, retired, or removed packages do not enter the active runtime index.
• Keep package diagnostics out of normal user screens.

RAD-Spiral Test§

Hermetic Foundry starts in a reasonable time with the core package installed and remains stable when additional packages are present.

Milestone 10.2 — Runtime UI Responsiveness§

Goal§

Ensure common UI actions remain fast.

Deliverables§

• Profile Quick Sheet screens.
• Profile Guided Creation screens.
• Profile package-backed pickers.
• Profile Virtue/Flaw, Ability, Spell, Item, Weapon, Armor, and Boon/Hook search.
• Improve filtering and sorting performance.
• Avoid unnecessary re-rendering.
• Avoid blocking the UI thread during expensive operations.
• Ensure large result sets remain usable.
• Consider pagination, virtualization, or indexed search where appropriate.

RAD-Spiral Test§

Searching and selecting package-backed content feels immediate or acceptably fast, even with many installed packages.

Milestone 10.3 — Large Data and Stress Testing§

Goal§

Test Hermetic Foundry against larger realistic data sets.

Deliverables§

• Test with multiple installed packages.
• Test with many entities.
• Test with large character records.
• Test with linked content.
• Test with embedded snapshots.
• Test with repeated save/load operations.
• Test memory usage.
• Test package refresh/reconciliation performance.
• Identify performance bottlenecks before deep rules automation begins.

RAD-Spiral Test§

Hermetic Foundry can handle a large practical Ars Magica installation without becoming sluggish or unstable.

20Spiral 11: Deep Rules Automation§

Purpose§

Implement deeper Ars Magica rules logic after the entity architecture and broad workflows are already stable.

Milestone 11.1 — Character Rules Calculation§

Goal§

Move from manual and partially calculated character-sheet structures toward reliable Ars Magica rules-aware character creation and maintenance.

Spiral 11.1 should automate the structures introduced in Milestone 3.6, not redesign them.

Deliverables§

• Characteristics validation.
• Virtue/Flaw point tracking.
• Ability XP tracking.
• Arts XP tracking.
• Age/lifecycle tracking.
• House/type/template support.
• Spell list integration.
• Reputations/personality traits.
• Advancement calculations.
• Quiet validation warnings.
• RulesImpact application engine for character-sheet fields.
• Derived-value dependency graph.
• Calculation trace display.
• Manual override and Storyguide ruling support.
• Virtue/Flaw point tracking.
• Characteristic validation.
• Ability XP calculation and validation.
• Art XP calculation and validation.
• Confidence handling.
• Size handling.
• Soak calculation.
• Armor Load calculation.
• Equipment Load, Burden, and Encumbrance calculation.
• Wound range calculation.
• Fatigue profile modification.
• Weapon combat total calculation.
• Casting total calculation.
• Lab total calculation.
• Magic Resistance calculation.
• Familiar cord effect placeholders if not fully automated.
• Age, Decrepitude, Warping, and Twilight calculation support where appropriate.
• “Needs review” flag for ambiguous rulesImpact entries.
• Regression tests using real imported Virtues, Flaws, Abilities, weapons, armor, and spells.

Tools Needed§

• TypeScript calculation engine
• XML rules data
• Test cases
• Codex

Skills Needed§

• Ars Magica character creation rules
• Calculation testing
• Rules data encoding
• Validation design

RAD-Spiral Test§

The app can correctly calculate a standard magus, companion, and grog from package-backed choices, while clearly marking anything that requires manual or Storyguide review.

Milestone 11.2 — Spell, Item, and Enchantment Rules§

Goal§

Support the major magical construction systems.

Deliverables§

• Spell design workflow.
• Technique/Form selection.
• Range/Duration/Target support.
• Level calculation support.
• Lab text creation/use.
• Enchanted item workflow.
• Lesser device placeholder.
• Invested device placeholder.
• Charged item placeholder.
• Effect description embedding.
• Print/export support.
• Spell design output should be directly addable to a character’s Spells Known.
• Enchanted items should be usable as character inventory entries.
• Item Load and carried/equipped state should flow into character equipment calculations where appropriate.
• Spell and item snapshots should remain portable in saved character files.

Tools Needed§

• TypeScript
• XML rules data
• Calculation engine
• Codex

Skills Needed§

• Ars Magica spell guidelines
• Enchantment rules
• Rules UI design
• Test-driven calculation

RAD-Spiral Test§

A user can design a spell, save it, use it in a character, and preserve its embedded snapshot in the character file.

Milestone 11.3 — Covenant and Laboratory Rules Calculation§

Goal§

Make covenants and labs mechanically useful.

Deliverables§

• Covenant Boon/Hook tracking.
• Build point tracking.
• Library value tracking.
• Vis economy.
• Income/expenditure placeholder or full accounting.
• Laboratory Virtue/Flaw calculation.
• Refinement validation.
• Safety/Health/Aesthetics/Upkeep totals.
• Lab activity modifiers.
• Covenant resources should affect character advancement and lab activity where appropriate.
• Laboratory totals should draw from linked magus, lab, aura, familiar, and package-backed modifiers.
• Covenant vis stocks and libraries should be usable by character lifecycle workflows.

Tools Needed§

• TypeScript
• XML rules data
• Calculation tests
• Codex

Skills Needed§

• Ars Magica covenant rules
• Ars Magica lab rules
• Accounting/resource UX
• Test case design

RAD-Spiral Test§

A covenant and its labs can affect character seasonal activities correctly.

21Spiral 12: Testing, Packaging, and Release§

Purpose§

Prepare Hermetic Foundry for broader testing and eventual distribution.

Milestone 12.1 — Test Suite and Sample Data§

Goal§

Create enough tests that Codex can safely refactor and extend the application.

Deliverables§

• Unit tests for XML serialization.
• Unit tests for checksum generation.
• Unit tests for package import.
• Unit tests for entity linking.
• Unit tests for core calculations.
• Manual test scripts.
• Sample character files.
• Sample creature files.
• Sample covenant files.
• Sample lab files.
• Sample custom package.
• Regression test checklist.
• Sample magus using v0.3.5 character sheet structures.
• Sample companion using v0.3.5 character sheet structures.
• Sample grog using v0.3.5 character sheet structures.
• Sample magus with familiar.
• Sample magus with spells, Arts, lab/longevity summary, raw vis, and equipment.
• Regression tests for character XML save/load round trip.
• Regression tests for package-backed character selections.
• Regression tests for embedded snapshots in character files.
• Regression tests for character sheet preview data assembly.
• Regression tests for derived-value status: manual, calculated, overridden, needs review.

Tools Needed§

• TypeScript test framework
• Rust tests if needed
• GitHub
• Codex

Skills Needed§

• Test writing
• Regression testing
• Sample data design
• Debugging

RAD-Spiral Test§

Codex can change part of the codebase, run tests, and identify broken behaviour before merge.

Milestone 12.2 — Installer and Distribution Prototype§

Goal§

Make Hermetic Foundry installable for ordinary users.

Deliverables§

• Windows installer.
• macOS build plan.
• Application icon.
• Version number.
• App metadata.
• Default installed LICENSE.xml.
• Default core content.
• Default help files.
• First release package.
• Help menu “Check for Updates” implementation or release-ready placeholder.

Tools Needed§

• Tauri build tools
• Windows installer tooling
• macOS build environment eventually
• GitHub releases
• Codex

Skills Needed§

• Application packaging
• Release management
• Versioning
• Cross-platform testing
• Update-check planning

RAD-Spiral Test§

A non-developer can install Hermetic Foundry, open it, create a Quick Sheet character, save it, reload it, and uninstall the app.

Milestone 12.3 — Beta Review and Feature Completion Spiral§

Goal§

Use real campaign workflows to find what remains unfinished.

Deliverables§

• Beta checklist.
• Known issues list.
• Missing rules list.
• UI friction list.
• Performance review.
• Import/export stress test.
• Print layout review.
• Rules accuracy review.
• Accessibility review.
• Final feature completion plan.

Tools Needed§

• Hermetic Foundry beta build
• Real Ars Magica test cases
• Google Docs feedback form or issue tracker
• GitHub issues
• Codex

Skills Needed§

• QA testing
• Rules review
• User feedback analysis
• Prioritization

RAD-Spiral Test§

The application is tested against actual campaign needs: creating magi, companions, grogs, creatures, covenants, laboratories, spells, items, custom packages, and help files.

22Post-1.0 Feature Backlog§

The following features are planned for after version 1.0 unless later moved earlier.

Efficiency Improvements§

Hermetic Foundry should continue to use XML packages as its canonical portable content format, but future efficiency work should treat imported packages as source artifacts that are validated once, then converted into an app-managed local installed-content index or database for fast startup, search, filtering, and entity relation queries.

Autosaves and Backups§

Hermetic Foundry should eventually support:

• automatic backups,
• timed autosaves,
• recoverable drafts,
• backup rotation,
• user-configurable backup locations,
• recovery after crash or failed save.

Campaign Packaging / Export§

Hermetic Foundry should eventually support packaging an entire campaign.

The campaign package should likely be treated as a Customizer-importable package.

Possible campaign package contents:

• campaign manifest,
• characters,
• creatures,
• covenants,
• laboratories,
• spells,
• items,
• books,
• locations,
• plots,
• vis sources,
• custom content used by the campaign,
• campaign-specific help files,
• media files,
• provenance metadata,
• checksums.

The export should be a ZIP file with a campaign manifest.

Tagging System§

Tags were removed from the Info pane for now but should return later.

Possible uses:

• tag entities,
• filter entity lists,
• search by tag,
• tag custom content,
• tag campaign-specific material,
• use tags in the Info pane once editable metadata exists.

Full Accessible Mode§

A full Accessible Mode may be added later if needed.

Possible features:

• higher contrast,
• larger typography,
• reduced decorative texture,
• simplified layout,
• stronger keyboard navigation,
• screen-reader optimized views.

Additional Icon Polish§

Current icons are acceptable for now, but further polish may continue after 1.0 if not completed in Spiral 8.

Future Navigator Improvement§

When the Navigator sidebar is collapsed, Hermetic Foundry should provide an icon-only navigation rail using the same workflow/menu icons as the expanded Navigator. These icons should remain clickable, show accessible labels/tooltips, and allow experienced users to recover screen space without losing quick access to major workflows. The expanded Navigator remains the default text-rich mode for clarity.

23Recommended Codex Working Pattern§

Each Codex task should include:

• The specific milestone being worked on.
• The existing files Codex should inspect.
• The exact deliverable to create.
• The expected user-facing behaviour.
• The XML format or data model involved.
• The tests it should add or update.
• A warning not to redesign unrelated systems.
• A request for a summary of changed files.

Example Codex Task Template§

Task:

Implement Milestone [number/name].

Context:

Read these files first:

• /docs/specs/product-vision.md
• /docs/specs/entity-taxonomy.md
• /docs/specs/xml-design-principles.md
• relevant milestone/workflow documents

Goal:

Describe the user-visible result.

Requirements:

• Requirement 1.
• Requirement 2.
• Requirement 3.

Do not:

• Do not redesign unrelated systems.
• Do not rename existing entity types.
• Do not change XML conventions unless the spec requires it.
• Do not expose validation as a normal user-facing action.
• Do not use “Open Existing”; use “Open.”
• Do not make Help or Print Preview inherit the normal Info-pane layout.

Tests:

• Add or update tests for the relevant behaviour.
• Add a manual test case if automated tests are not yet available.

Output:

After implementation, summarize changed files, tests run, and any assumptions.