ravenous_roll20/FEATURES.md

612 lines
30 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Ravenous Roll20 feature catalogue
## How to use this document
This is the portable product specification for the repository. Use it when an
equivalent feature must be implemented in another project, even if that project
uses a different language, framework, or directory layout. Each feature states
observable behavior, invariants, source-of-truth inputs, the implementation in
this repository, and acceptance criteria.
This document deliberately does not duplicate every attribute or function.
Those integration details live in [ARCHITECTURE.md](ARCHITECTURE.md). The pinned
`ravenous_typst` submodule is authoritative for game rules and source data. If
this document and the book disagree, verify the pinned book and update this
document rather than preserving an accidental implementation detail.
Feature status terms:
- **Implemented** means the code and local automated checks exist.
- **Roll20-verified** means the interaction has also been exercised in Roll20.
- **Manual by design** means the sheet presents or calculates information but
intentionally does not mutate the corresponding resource.
- **Pending smoke test** means local mocks cover the logic but the remaining
real-platform scenarios are tracked in [TASKS.md](TASKS.md).
## Product boundary
The product is a French Ravenous character-management suite with four parts:
1. a generated Roll20 Custom Sheet Enhancement (CSE) character sheet;
2. optional Roll20 Mod scripts for validated JSON exchange and cross-character
actions;
3. deterministic converters and example-payload generators;
4. two dependency-free static companion sites for crafting and reusable
effects.
The suite assists play; it is not an autonomous rules engine. HP, armor
integrity, technique costs, consumable quantities, and mechanical consequences
of effects remain manual unless a future feature explicitly changes that
decision.
## F01 — Book-driven deterministic sheet build
**Status:** Implemented.
**Outcome.** Generate a deployable Roll20 bundle from hand-maintained templates
and the pinned Ravenous rulebook data. A rebuild with identical inputs produces
byte-identical output, and a check mode detects stale artifacts.
**Required behavior and invariants:**
- Read skills, nested specializations, school techniques, origins, powers,
glossary labels, build limits, trigrams, and themes from the pinned book.
- Import only school tiers strictly below `build.max_tier_exclusive`.
- Exclude resistance definitions from the generated skill list because the
sheet models them as dedicated resistance fields.
- Translate only the supported Typst subset. Resolve known references and
macros; do not silently invent semantics for unsupported game markup.
- Escape generated HTML and JavaScript safely, prevent literal `</script>`
termination, and keep generated JavaScript data split over bounded lines for
the Roll20 editor.
- Fail if an uppercase template marker remains unresolved.
- Emit the HTML, CSS, translations, manifest, and a build manifest containing
source counts, selected limits/theme, a theme list, and a content hash.
- `--check` compares expected generated content without rewriting it.
**This repository:** `tools/build.py`, `src/ravenous.html`, `src/ravenous.css`,
`src/translation.json`, `src/sheet.json`, and `scripts/build.sh`. Generated
artifacts belong in `build/` and are never edited directly.
**Acceptance:** build twice and compare bytes; run `./scripts/build.sh --check`;
verify the expected source counts and absence of unresolved markers/raw known
Typst constructs with `tests/test_build.py`.
## F02 — Responsive, persistent, themed character sheet shell
**Status:** Implemented; themes are Roll20-verified.
**Outcome.** Present the character through eight compact pages: Chasseur,
Compétences, Combat, Santé & résistances, Cuisine & alchimie, Écoles, Pouvoirs,
and Effets & tours. Navigation and user choices persist as Roll20 attributes.
**Required behavior and invariants:**
- Use Roll20 CSE mode with Legacy Sanitization disabled.
- Keep tabs in one sheet document and switch them through a persisted hidden
`tab` attribute and action buttons; do not rely on page reloads.
- Adapt grids for narrower screens without dropping fields.
- Generate all palettes from the book theme file. Persist the per-character
theme and apply it to both the sheet and chat cards.
- Permit a build-time initial/fallback UI theme without removing other themes.
- Retain readable system font fallbacks when the optional Google font cannot
load.
- Include public/GM-only roll selection and compact JSON exchange shortcuts in
the header.
**This repository:** page markup and sheet workers are in `src/ravenous.html`;
responsive styles and CSS custom properties are in `src/ravenous.css`; palette
parsing and generated selectors/rules are in `tools/build.py`.
**Acceptance:** switch every page, reopen the sheet, select at least two themes,
and inspect both sheet and chat output at desktop and narrow widths. Confirm all
book palettes occur in the generated selector and CSS.
## F03 — Character characteristics, resources, and derived values
**Status:** Implemented; core calculations are Roll20-verified.
**Outcome.** Track eight characteristics, temporary modifiers, resources, and
derived movement/health statistics with immediate worker recalculation.
**Required behavior and invariants:**
- Track Force, Agilité, Perception, Intelligence, Volonté, Psy, Chance, and
Charisme as permanent values plus temporary modifiers and displayed totals.
- Calculate derived statistics from permanent characteristics and explicit
derived-value modifiers. Temporary characteristic modifiers affect final
characteristics and skill totals, but not derived base formulas.
- Track current and maximum Jauge, Fatigue, Toxicité, Satiété, Sang, and Actions
as appropriate; maximum formulas can have explicit modifiers.
- Recalculate on sheet open and every governing input change using silent
writes where cascading events would otherwise loop.
- Preserve stable attribute names because existing Roll20 characters store
state under those names.
**This repository:** fixed fields and the `recalculate` worker in
`src/ravenous.html`; formula assertions in `tests/test_build.py` and behavior
checks in `tests/test_worker.mjs`.
**Acceptance:** test base and temporary changes independently, all max-value
modifiers, stage boundaries, and sheet reopen. Compare formulas with the pinned
rulebook before porting them.
## F04 — Generated and custom skills with roll outcomes
**Status:** Implemented; critical-failure boundary awaits Roll20 retest.
**Outcome.** Expose every sheet-visible book skill in category subtabs, support
nested specializations and custom skills, and resolve single-die threshold
checks into an outcome and margin.
**Required behavior and invariants:**
- Generate stable skill IDs and distinct stored attributes. Nested entries
inherit their parent characteristic, include ancestry in their ID/full name,
and appear indented under the parent.
- Allow the characteristic association, rank, and temporary modifier to
contribute to a skill total. The generated internal `effect` slot is
currently reserved and remains zero; do not claim active-effect automation.
- Custom repeating skills choose a characteristic and use the same total and
roll semantics.
- Let users select the die size. A roll is a critical success on natural 1, a
critical failure on the maximum face, a normal success below the threshold,
and otherwise a failure. Margin is `threshold - rolled`.
- Respect the character's public/secret-roll choice.
**This repository:** skill normalization and HTML generation in
`tools/build.py`; totals and `performSkillRoll` in `src/ravenous.html`.
**Acceptance:** verify unique IDs, category membership, nested indentation,
custom-row persistence, and rolls at natural 1, just below threshold, exactly
at threshold, and the maximum die face for both public and secret settings.
## F05 — Attack, defense, damage, and mitigation workflow
**Status:** Implemented locally; targeted-token edge cases remain a pending
Roll20 smoke test.
**Outcome.** Model arbitrary attacks as repeating rows, roll successes, offer
chat follow-ups for defense and damage, and show damage/armor-break results
after a targeted defender's selected mitigations.
**Required behavior and invariants:**
- An attack stores name, default pool, threshold, temporary threshold modifier,
optional automatic successes, whether dice are rolled, base damage, damage
per extra success, armor break, maximum counted successes, three defense
thresholds, and notes.
- Attack dice count successes against the attack threshold and add automatic
successes. Follow-up context is cached by the original roll ID when available.
- Defense prompts for a defender token and a defense type. Dodge and parry add
only the targeted defender's corresponding skill and temporary skill value
to the attack's defense threshold; reposition uses its fixed threshold.
- After defense, remaining successes are clamped to zero and capped by RMax.
Zero final successes deal zero damage. Otherwise:
`damage = base + (final successes - 1) * damage per success`.
- Manual **Dégâts** accepts remaining successes when cached context is absent.
- **Subir** prompts for remaining successes and a defender token, reads that
defender's selected resistance and protection/location query, and displays
the breakdown. Each selected resistance point removes 2 DMG and 1 AB.
Protection mitigation and the first protection used for AB follow the rules
described in F06.
- Results never subtract HP or armor integrity; that remains manual by design.
- Cache loss after worker restart must degrade to prompted/manual input rather
than corrupting a character.
**This repository:** attack repeating rows, `attackRolls`, `attackDamage`, and
four attack action handlers in `src/ravenous.html`; roll-template branches in
the same file.
**Acceptance:** test zero/one/many successes, automatic-only attacks, RMax,
defense greater than attack, all three defense types, public/secret defender
rolls, absent cached context, and hand-calculated DMG/AB with a targeted second
character.
## F06 — Health locations, resistances, and protection selection
**Status:** Implemented locally; complete combat matrix remains a pending
Roll20 smoke test.
**Outcome.** Track health and armor per body location, accumulate selected
damage resistances, and make active armor or a chosen location available to the
damage workflow.
**Required behavior and invariants:**
- Provide fixed head, torso, left/right arm, and left/right leg rows plus custom
repeating locations. Each row keeps HP, HP maximum, protection, current armor
integrity, and maximum integrity.
- Track the full sheet resistance set, while only damage-applicable physical and
elemental types participate in the current attack reduction selector.
- Multiple checked resistances accumulate. A clear action resets all checks.
- An active repeating protection contributes only while current integrity is
greater than zero. Sum protection for DMG, count active valid rows, and retain
the first valid protection in repeating-row order for AB.
- Current-selection DMG mitigation is total active protection plus final Force
if at least one valid protection exists. For a fixed/custom location, use its
protection plus Force only when its armor integrity is above zero.
- AB reduction uses selected resistance points and the first protection value,
never Force. Clamp displayed final values at zero.
- Encode both DMG mitigation and AB protection into one Roll20 query value so a
single location prompt can transport both integers through the dice parser.
**This repository:** health fields, `DAMAGE_RESISTANCES`, `FIXED_LOCATIONS`,
`PACK_FACTOR`, and recalculation workers in `src/ravenous.html`.
**Acceptance:** cover no armor, depleted armor, one and multiple active
protections, row reorder, each fixed location, a custom location with macro
punctuation in its name, multiple resistance checks, and zero clamping.
## F07 — Consumables and structured turn-effect tracker
**Status:** Implemented.
**Outcome.** Store free-form consumables and temporary effects, publish them to
chat, copy consumable/technique/power effects into a tracker, and guide manual
turn processing with reminders and expiration.
**Required behavior and invariants:**
- Consumables store kind, name, quantity, display duration, description, and
optional structured timing/reminders. Publishing does not consume quantity.
- Active effects store an active flag, name, display duration, description,
duration type, remaining count, countdown phase, and start/end/application/
removal reminders.
- Supported duration types are manual, N turns, until next start, until next
end, combat, and a reserved actions mode. Unknown or legacy timing defaults to
manual behavior.
- Start/end actions publish reminders for that phase, decrement only matching
turn counters, mark expired effects inactive, and announce removals. They do
not apply prose mechanics or change HP/resources.
- Cleanup removes only inactive effect rows and reports how many were removed.
- Copying from a consumable preserves configured timing. Copying from a
technique or power copies text and any inferred timing, without interpreting
arbitrary prose at runtime.
- Build-time reminder inference is conservative: recognize explicit French
start/end phrases, next-start/next-end, finite turn counts, and combat end;
leave uncertain duration manual.
**This repository:** effect markup and worker handlers in `src/ravenous.html`;
`effect_reminder_metadata` in `tools/build.py`.
**Acceptance:** test every duration type at both phases, inactive rows, a
multi-turn countdown to zero, no-reminder phases, cleanup, and each copy source.
Confirm no resource is automatically changed.
## F08 — School technique catalogue and acquisition
**Status:** Implemented; Roll20-verified.
**Outcome.** Import eligible school techniques from book TSVs, let users add
them individually to an editable repeating list, prevent duplicates, and show
their cards/effects in chat.
**Required behavior and invariants:**
- Group selector choices by school and label them with configured trigrams,
tier, name, and level.
- Carry school, tier, type, costs, other requirements, translated effect text,
and inferred reminder metadata into the acquired row.
- Use a stable source key to prevent adding the same generated technique twice;
do not block user-created rows without that key.
- On sheet open, backfill updated generated content/reminder metadata into rows
with recognized source keys while preserving ownership and user linkage data.
- Activation creates a themed chat card and optionally offers linked reusable
effects. Tracking copies the technique into the temporary-effect tracker.
- Do not automatically spend Sang/Jauge or execute the mechanical effect.
**This repository:** school ingestion and selector generation in
`tools/build.py`; repeating rows and worker handlers in `src/ravenous.html`.
**Acceptance:** add one technique, reject its duplicate, add a custom row,
reopen, activate, track as effect, and inspect text for unresolved Typst syntax.
## F09 — Origin selection and staged powers
**Status:** Implemented; Roll20-verified.
**Outcome.** Select an origin, import its powers in stage batches, preserve
existing/custom powers across origin changes, and activate or track powers.
**Required behavior and invariants:**
- Generate origins and powers from YAML, translating supported book markup.
- Persist both the origin key and human-readable origin name.
- Selecting an origin alone adds nothing. The user chooses a stage and requests
the batch for the currently selected origin.
- Stable keys include origin, stage, and source position. Skip existing keys to
prevent duplicates while leaving unrelated/custom rows untouched.
- On sheet open, refresh recognized imported rows from current generated data.
- Activation produces a themed chat card with optional linked reusable effects;
tracking creates a temporary effect. No prose mechanics are automated.
**This repository:** origin parsing in `tools/build.py`; UI and workers in
`src/ravenous.html`.
**Acceptance:** import the same stage twice, add another stage and a custom
power, switch origin, reopen, activate, and track. Existing rows must survive
and generated duplicates must not appear.
## F10 — Reusable effect library and cross-character offers
**Status:** Implemented.
**Outcome.** Maintain reusable effect definitions separately from active
effects, attach their IDs to technique/power chat cards, and let an authorized
player copy an offered effect to a controlled target character.
**Required behavior and invariants:**
- Library rows have a stable effect ID, enabled flag, constrained type, name,
duration, description, structured timing, and four reminders.
- Techniques/powers link by comma/space/semicolon-separated IDs. Only enabled,
exactly matching IDs appear on a chat card.
- Offer buttons carry a URI-encoded JSON payload and explicitly target a
character through Roll20's target prompt.
- The separate Mod action validates payload fields and bounds, verifies the
clicking player controls the target, and creates an active temporary-effect
row. It must not trust chat payloads or allow writes to another player's
character.
- Library JSON import/export targets reusable rows, not active effect rows.
**This repository:** library/link handling in `src/ravenous.html`;
cross-character application in `roll20_mod/ravenous_shared_effects.js`;
versioned exchange in `roll20_mod/ravenous_effects_import.js` and
`effects_web/schemas/ravenous-effects-v1.schema.json`.
**Acceptance:** offer zero, one, and multiple effects; ignore disabled or
unknown IDs; apply to a controlled target; reject an uncontrolled target and
malformed/oversized payloads; round-trip a library through a handout.
## F11 — Versioned character backup, restore, and creation
**Status:** Implemented; core workflow is Roll20-verified.
**Outcome.** Serialize a Roll20 character into a versioned JSON document and
either create a new character or replace the sheet data of an existing one.
**Required behavior and invariants:**
- Format identifier is `ravenous-roll20-character`, version 1.
- Preserve name, sheet attributes, abilities, bio, GM notes, journal access,
and control lists in exports, subject to caller visibility.
- GM creation makes a new character. Replacement retains the destination
object/ID, linked tokens, avatar, ownership, and GM-only notes while replacing
name, bio, attributes, and abilities.
- Validate the complete incoming document before deleting any destination
attributes or abilities. Reject unknown fields, invalid types, unsafe sizes,
duplicates where prohibited, and inaccessible inputs.
- Players may export/replace only characters they control and read only shared
handouts. GM handouts use GM Notes; player exports use visible Notes and grant
that player access.
- Support direct JSON for small payloads and decoded HTML handout content for
larger payloads. Sheet header commands target the current character ID.
- Reopening the sheet after import allows workers to recompute derived values.
**This repository:** `roll20_mod/ravenous_character_io.js`, header actions in
`src/ravenous.html`, and `tests/test_character_io.mjs`.
**Acceptance:** round-trip all scalar/repeating attributes, abilities, Unicode,
HTML-sensitive text, bio/notes, and permissions; test GM creation, GM replace,
player replace, inaccessible handout, uncontrolled target, malformed JSON, and
validation failure without partial deletion.
## F12 — Monster database conversion
**Status:** Implemented.
**Outcome.** Convert a monster from the book's pinned SQLite database into the
character JSON contract while retaining information that has no faithful sheet
equivalent.
**Required behavior and invariants:**
- Read the nested `monsters.db` submodule and select one/all master-visible
creatures deterministically.
- Map compatible characteristics, locations, attacks, and powers to stable
character/repeating attributes.
- Treat capabilities with damage as attacks and others as powers. Preserve
source descriptions and damage notation in row notes.
- Leave unknown dice pools/thresholds/mechanical values neutral for GM review;
never fabricate a rule conversion.
- Embed all raw database rows, including phases and unmapped fields, in GM notes
as JSON so conversion is loss-aware.
**This repository:** `tools/export_monsters.py` and
`tests/test_monster_export.py`.
**Acceptance:** convert every master-visible database entry, validate each
against the character importer, verify representative locations/attacks/powers,
and ensure raw source rows remain recoverable.
## F13 — Craft JSON exchange
**Status:** Implemented locally; real Roll20 import smoke test remains pending.
**Outcome.** Exchange finalized crafted attacks, protections, consumables, and
temporary effects through a strict versioned JSON envelope without coupling a
crafting calculator to Roll20 internals.
**Required behavior and invariants:**
- Format identifier is `ravenous-roll20-craft`, version 1. The normative schema
is `docs/ravenous-craft-v1.schema.json`; semantics are documented in
`docs/craft-json-v1.md`.
- Accept 1–100 typed items with only the fields allowed for their destination.
Reject unknown fields, invalid kinds, non-finite numbers, and oversized text.
- Import creates new repeating rows; it never overwrites existing rows, equips
protection, consumes ingredients, changes resources, or recalculates recipes.
- Imported protection is inactive by omission and must be selected manually.
- Export reads compatible repeating rows into a private/shared handout according
to caller permissions.
- Players can operate only on controlled characters and readable handouts; GMs
can use explicit IDs or token selection.
**This repository:** `roll20_mod/ravenous_craft_import.js`, schema/docs under
`docs/`, and deterministic examples from `tools/generate_crafts.py`.
**Acceptance:** import/export every item type, mixed item collections, inline
and handout payloads, player/GM paths, every validation failure class, and
reopen the destination sheet to confirm persistence.
## F14 — Deterministic interoperability fixtures
**Status:** Implemented.
**Outcome.** Produce stable, adversarial example documents that exercise import
contracts in local tests and CI.
**Required behavior and invariants:**
- A seeded character generator covers fixed and repeating sheet sections,
attributes, abilities, permissions, Unicode, and markup-sensitive strings.
- Identical seeds produce byte-identical UTF-8 JSON; different seeds vary.
- Craft generators deterministically cover forge (attack/protection) and
alchemy (consumable/modifier) destinations.
- Fixture generation is part of the normal build wrapper and check mode compares
regenerated fixtures with output.
- Fixtures are examples and test vectors, never authoritative game data.
**This repository:** `tools/generate_character.py`,
`tools/generate_crafts.py`, `scripts/build.sh`, and their Python tests.
**Acceptance:** reproducibility tests, contract validation, coverage assertions,
and successful import through the Mod API mock.
## F15 — Static craft workshop companion
**Status:** Functional prototype; full five-discipline rule parity, finalized
Roll20 mapping, QR sharing, and complete browser accessibility checks are not
implemented. The exact roadmap is in `craft_web/TASKS.md`.
**Outcome.** Provide an account-free static application for browsing
authoritative craft components, assembling single-discipline recipes, warning
about basic limits, keeping personal data locally, and exchanging provisional
recipe/output files.
**Required behavior and invariants:**
- Production output is static HTML/CSS/JavaScript/catalog data with no backend,
tracking, runtime CDN, or mandatory Node build.
- Normalize all current craft TSV and Forge equipment entries with stable IDs,
typed searchable/filterable values, source provenance, and a catalogue
fingerprint.
- Provide accent-insensitive search, discipline/stage and numeric filters,
stable sorting, one-discipline composition, basic live totals/warnings,
personal ingredients, undo/redo, local recipe/backup storage, editable recipe
exchange, print output, and provisional Roll20 download/clipboard output.
- Keep editable workshop recipes distinct from finalized Roll20 craft exports.
Recalculate rather than trusting stored totals.
- Treat imports and URL/local-storage state as untrusted. Use text DOM APIs,
validate bounds, and keep recipes private unless the user explicitly exports.
- Clearly label Forge compatibility/statistics, trap adjudication,
repeated-effect cases, and any unported discipline calculation as manual/GM
review. A provisional export must not be presented as rules-validated.
- Preserve accessibility, responsive, print, offline-static, and theme goals,
but consult `craft_web/TASKS.md` before claiming a goal is complete.
- Rule/calculation scope and current limitations are authoritative in
`craft_web/AGENTS.md`; do not claim roadmap items as implemented.
**This repository:** `craft_web/` with its own sources, generator, schema,
tests, README, task list, and nested agent guide.
**Acceptance:** deterministic static build/check, no external runtime
dependencies, complete normalized-source catalogue, persistence/import/export
round trips for implemented functions, and visible manual-review warnings.
Discipline parity and browser-quality checks become required as their backlog
items are implemented.
## F16 — Static reusable-effects companion
**Status:** Implemented static catalogue/export foundation.
**Outcome.** Browse book alterations, assemble private reusable-effect sets,
add custom entries, and export F10-compatible JSON without an account or server.
**Required behavior and invariants:**
- Source book alterations from the pinned glossary and reuse sheet translation,
theme, and conservative timing inference.
- Generate a dependency-free static application and versioned catalogue.
- Persist private sets/custom effects only in browser local storage and render
untrusted text without HTML injection.
- Export `ravenous-roll20-effects` v1 targeting the reusable library, not the
active tracker. Unknown durations remain manual.
**This repository:** `effects_web/`, especially `tools/build.py`, static sources,
the JSON schema, tests, and nested `AGENTS.md`.
**Acceptance:** deterministic build/check, catalogue translation and schema
tests, local set round trips, hostile-text rendering checks, and import into
`repeating_sharedeffects` through the Mod simulator.
## F17 — CI build, archive, and guarded publication
**Status:** Implemented.
**Outcome.** Rebuild and validate all three static deliverables and fixtures,
archive them with fingerprints, and publish only named branches to allow-listed
directories.
**Required behavior and invariants:**
- Initialize recursive submodules, use Python 3.11+ through pinned `uv`
dependencies, and ensure SQLite support for monster tests.
- Build/test/check the sheet, craft site, and effects site independently.
- Run Mod simulator tests when Node is available; lack of Node is currently an
explicitly reported optional skip in CI.
- Archive all generated bundles and examples.
- Measure Python generator line coverage with the pinned coverage tool and
reject results below 85%. Generate version, test, and coverage SVGs for every
build, archive exactly those badges, and publish them only from `main` below
`/mnt/assets/coverage/Ravenous/ravenous_roll20/main`.
- Finalize badges during Jenkins cleanup so failed `main` builds replace stale
passing status and incomplete measurements with a neutral coverage badge.
- Deploy production, development, and review branches to distinct allow-listed
paths below `/mnt/assets/ravenous_roll20`. Create the resolved product
directory when absent. Use deletion only inside that product subdirectory;
never at the shared project asset root.
- Other branches build and archive without deployment.
**This repository:** `Jenkinsfile`, `.coveragerc`, the badge/coverage scripts,
and the three build entry points.
**Acceptance:** test an ordinary branch (no deployment), each mapped publication
branch, a stale artifact, a test or coverage-floor failure, badge renderer and
publisher rejection cases, and rejection of an unexpected product target path.
## Cross-feature non-goals and compatibility rules
- Generated files are outputs, not editable sources.
- The sheet is French-first; stable machine identifiers remain ASCII where the
current contracts require it.
- Existing Roll20 attribute names, repeating section names, generated source
keys, and versioned format fields are compatibility APIs. Rename them only
with an explicit migration.
- Browser/sheet workers cannot call privileged Roll20 APIs. Cross-character
writes, handouts, permissions, and character creation belong in Mod scripts.
- Chat cards communicate and calculate; they do not grant authority to mutate a
target. Every Mod command independently validates payload and permissions.
- String-presence tests prove generation shape, not Roll20 parser/rendering
behavior. Interactive changes require a real Roll20 smoke test record.
- Counts from the current pinned book are diagnostics, not permanent product
requirements. Derive expectations from source inputs where possible.
## Adding or porting a feature
For a new feature in this repository, update this catalogue in the same change:
1. add or amend the feature's observable outcome, invariants, manual boundaries,
implementation map, and acceptance criteria;
2. update [ARCHITECTURE.md](ARCHITECTURE.md) if a boundary, data flow, persistent
name, contract, build artifact, or deployment component changes;
3. add focused automated checks and record real Roll20/browser validation or
the precise untested scenario in [TASKS.md](TASKS.md);
4. update the relevant public README and nested component guide when user
instructions or component-local constraints change.
For a port to another repository, implement the **Outcome**, **Required behavior
and invariants**, and **Acceptance** sections. The **This repository** paragraph
is a navigation aid, not a mandated target architecture.