chore: ignore feature worktrees

.gitignore

@@ -44,4 +44,5 @@ __pycache__/
 *.py[cod]
 
 .pi
-.mesh
+.mesh
+.worktrees/

AGENTS.md

@@ -69,11 +69,27 @@ The `.agents/skills/` directory contains repo-specific skill files. Key skills:
 
 Use `skill` tool to load one when the task matches.
 
+## Agent skills
+
+### Issue tracker
+
+Track issues in this repository's Gitea Issues using `tea`. See
+`docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Use the five canonical triage labels without overrides. See
+`docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Use the single-context domain documentation layout. See `docs/agents/domain.md`.
+
 ## Verify commands
 
 Run in order after source changes:
 
-```
+```bash
 npm run check        # svelte-kit sync + svelte-check (typecheck)
 npm run build        # secretless Vite production build
 ```

CONTEXT.md

@@ -0,0 +1,271 @@
+# SHD.build Domain
+
+SHD.build is an independent community intelligence platform for _The Division
+Resurgence_. This glossary defines the language used for player planning, shared
+content, Game Data, governance, equipment, progression, and modeled mechanics.
+
+## Product and people
+
+**SHD.build**: The community platform described by this glossary. Always
+capitalize `SHD` and write the product name as `SHD.build`. _Avoid_: SHD Build,
+SHD Builder
+
+**Agent**: Any person using SHD.build, whether anonymous or authenticated.
+_Avoid_: User, visitor, player when referring to product access
+
+**Anonymous Agent**: An Agent who is not signed in to SHD.build. _Avoid_:
+Visitor, guest
+
+**Registered Agent**: An Agent with an SHD.build account. _Avoid_: Registered
+user, member
+
+**Modeling Session**: An interactive agentic work session that prepares one
+Mechanic Program at a time for a Registered Agent to confirm in chat before the
+session submits it through an existing ISAC action. _Avoid_: Agent, Modeling
+Client, bulk job
+
+**Contributor**: A Registered Agent who has accepted the contributor guidelines
+and may submit proposed Game Data changes for review. _Avoid_: Editor when the
+Agent cannot change Canonical Game Data directly
+
+**Operator**: A Registered Agent performing an authorized task in ISAC.
+Contributor, reviewer, moderator, and administrator authority remain distinct
+from this situational term. _Avoid_: Admin as a generic name for anyone using
+ISAC
+
+**Oversight**: The human review function for proposed Game Data, moderated
+Community Content, and identity assets. Use the qualified names Data Oversight,
+Community Oversight, Guide Oversight, and Avatar Oversight when the review area
+matters. _Avoid_: Moderation as a name for every review function
+
+## Planning and shared content
+
+**Builder**: The planning tool an Agent uses to configure a Loadout and inspect
+supported calculations. _Avoid_: Build when referring to the tool
+
+**Loadout**: A complete planned character configuration, including selected
+Equipment, progression choices, and combat assumptions. A Loadout may exist
+without becoming a saved Build. _Avoid_: Build when persistence, ownership, or
+sharing matters
+
+**Loadout Draft**: An editable Loadout that has not become a saved Build.
+Anonymous and Registered Agents may both work with drafts. _Avoid_: Build draft
+
+**Build**: A saved, owned, and shareable planning artifact whose central content
+is a Loadout. A Build may be Private, Unlisted, or Public and may derive from
+another Build. _Avoid_: Loadout when persistence, ownership, or sharing matters
+
+**Guide**: A revisioned long-form community article that may include snapshots
+of one or more Builds. A Guide is prose-led content rather than a Loadout
+container. _Avoid_: Build guide when referring to every Guide
+
+**News Article**: A revisioned editorial or syndicated article published through
+the News channel. _Avoid_: Guide, post
+
+**Article Revision**: An immutable edition of a Guide or News Article. Editors
+select one revision for publication while later revisions may await review.
+_Avoid_: Version when referring to published article history
+
+**Community Content**: Agent-authored comments, profile biographies, custom
+avatars, and Guides governed by the shared moderation lifecycle. _Avoid_:
+User-generated content, UGC
+
+**Community Note**: A visible comment that Community Oversight pins to a Public
+Database discussion. It remains Community Content and follows the same removal
+rules as other comments. _Avoid_: Official correction, staff note
+
+**Content Report**: An Agent's request for Oversight to review visible Community
+Content, with no immediate change to the content's visibility. _Avoid_: Takedown
+request
+
+**Public Database**: The Agent-facing reference view of Canonical Game Data.
+_Avoid_: Database when the term could mean application storage
+
+## Game Data and governance
+
+**Game Data**: Community-maintained structured facts about _The Division
+Resurgence_ used by the Public Database, Builder, Builds, and contribution
+workflow. _Avoid_: Source data, builder data, reference data
+
+**Canonical Game Data**: The authoritative, approved body of Game Data. _Avoid_:
+Live data, production data
+
+**Canonical Record**: One authoritative record within Canonical Game Data.
+_Avoid_: Approved proposal
+
+**Contribution Proposal**: A pending request from a Contributor to create or
+change Canonical Game Data. Approval still requires the proposed change to
+satisfy the canonical rules for its record family. _Avoid_: Draft record,
+pending record
+
+**ISAC**: The operational console for Game Data, contribution review, community
+governance, identity and access management, audit history, and system
+operations. _Avoid_: Admin panel, calculation engine
+
+**Registry**: An ISAC workspace containing one family of related records and its
+management controls. _Avoid_: Table, list page
+
+**Audit Event**: An immutable account of a consequential operation or review
+decision, including the actor, target, and change evidence. _Avoid_: Audit-log
+row, activity log
+
+**Compensating Reversion**: A new operation that restores an earlier state while
+preserving the original Audit Event and recording the reversal. _Avoid_:
+Rollback, undo when either implies rewriting history
+
+## Equipment and progression
+
+**Equipment**: The items and enhancements selected for a Loadout, including
+Weapons, Gear, Weapon Mods, Gear Mods, Skill Chips, and an OS Protocol. _Avoid_:
+Item when the equipment relationship matters
+
+**Gear**: Equippable protective equipment assigned to a character slot. Gear may
+provide core values, Attributes, a Brand Set, a Talent, and augmentation
+capacity. _Avoid_: Armor as a collective name for all Gear
+
+**Body Armor**: The canonical name for the equippable torso Gear slot. _Avoid_:
+Vest
+
+**Weapon**: An equippable firearm with a Weapon Category, damage and handling
+properties, progression values, and applicable Talents and Mods. _Avoid_: Gun
+when referring to the modeled record
+
+**Weapon Category**: The classification that groups Weapons as Shotgun, Rifle,
+MMR, AR, LMG, or SMG. _Avoid_: Weapon type, weapon family
+
+**Weapon Mod**: An enhancement fitted to a compatible Weapon slot. Regular and
+Exotic Weapon Mods follow different selection rules. _Avoid_: Attachment
+
+**Gear Mod**: An enhancement fitted to Gear according to the Gear's available
+mod capacity. _Avoid_: Tactical Augment
+
+**Tactical Augment**: A numbered augmentation position recorded on selected Gear
+in a Loadout. _Avoid_: Gear Mod
+
+**Attribute**: A named measurable game property with defined units and
+calculation meaning. _Avoid_: Stat when referring to the canonical Attribute
+catalog
+
+**Core Attribute**: One of the three primary character alignments: Firepower,
+Toughness, or Engineering. _Avoid_: Main stat, primary stat
+
+**Brand Set**: A Gear identity whose bonuses depend on how many pieces from that
+set the Loadout equips. _Avoid_: Gear set
+
+**Quality**: The item classification Standard, Specialized, Superior, or
+High-end. Quality governs available or scaled properties for applicable
+Equipment. _Avoid_: Rarity
+
+**Exotic**: A special scope used by certain Weapons, Talents, and Weapon Mods.
+Exotic is not a fifth Quality. _Avoid_: Exotic quality
+
+**Item Level**: An Equipment progression coordinate used to resolve
+level-dependent values. _Avoid_: Tier, Quality
+
+**Equipment Tier**: The T0, T1, or T2 progression band that controls Equipment
+capabilities and values. _Avoid_: Talent Tier, Item Level
+
+**Talent Tier**: The Tier I or Tier II value variant of a Talent. _Avoid_:
+Equipment Tier, T1, T2 when the distinction could be unclear
+
+**Reference Level**: The Item Level at which an observed value or range applies.
+_Avoid_: Base level
+
+**Hidden Base**: A level-independent value inferred from observed Equipment
+values and the game's progression rules. _Avoid_: Displayed Value, Raw Value
+
+**Raw Value**: A calculated value before the presentation rules that reproduce
+the game's displayed number. _Avoid_: Hidden Base, Displayed Value
+
+**Displayed Value**: The player-visible number produced after applying the
+game's presentation rules to a Raw Value. _Avoid_: Raw Value
+
+**OS Protocol**: A single equipped progression item with a Quality, Core
+Attribute alignment, primary effect, inherited secondary profile, and
+upgradeable Talent. _Avoid_: Protocol when the operating-system meaning could be
+inferred
+
+**Skill**: A selectable combat capability associated with a Specialization.
+Skills may own Skill Chip Sets and may have explicit compatibility relationships
+with another Skill. _Avoid_: Ability or Specialization Ability for the
+selectable game concept
+
+**Signature Skill**: A Specialization's defining Skill, distinguished from its
+other selectable Skills. _Avoid_: Signature ability
+
+**Skill Chip**: An Equipment selection that modifies the Skill occupying its
+Loadout position. Skill Chips belong to a Skill Chip Set and may provide
+primary, secondary, and set effects. _Avoid_: Chip when the equipment family is
+unclear
+
+**Skill Chip Set**: A reusable Skill Chip definition associated with a Skill,
+including its set bonus and optional Talent. An explicit compatibility
+relationship may let another Skill equip the set. _Avoid_: Skill set
+
+**Specialization**: A character progression identity containing Focuses, Skills,
+and progression choices. _Avoid_: Class
+
+**Focus**: A path within a Specialization aligned to one Core Attribute and
+defining a selection of Skills and progression choices. _Avoid_: Subclass,
+specialization path
+
+**Talent**: A named conditional behavior owned by its source, such as a Weapon,
+Gear item, OS Protocol, or Skill Chip Set. Different Talent sources may use
+different progression variants. _Avoid_: Perk, passive
+
+## Modeled mechanics
+
+**Mechanic Program**: The structured, source-owned description of a Talent or
+other conditional behavior. It captures the conditions, state changes, and
+outcomes needed to evaluate that behavior. _Avoid_: Script, Trigger record
+
+**Event**: An observed occurrence on a combat timeline that a Mechanic Program
+may inspect. _Avoid_: Trigger when referring to the occurrence itself
+
+**Trigger Condition**: The criteria that an Event must satisfy before a mechanic
+can proceed toward Activation. A Trigger Condition is part of a Mechanic
+Program, not a standalone Game Data record. _Avoid_: Trigger as an entity
+
+**Activation**: A successful mechanic occurrence after its Event, conditions,
+chance, and Cooldown requirements resolve. _Avoid_: Proc when precision matters
+
+**Cooldown**: The period after a successful Activation during which the same
+mechanic cannot activate again. A failed chance does not begin the Cooldown.
+_Avoid_: Delay
+
+**Mechanic State**: A value retained across Events for one mechanic, such as a
+flag, count, stack, duration, mark, or resource. _Avoid_: Runtime state when
+discussing game behavior
+
+**Outcome**: The effect emitted by an activated mechanic, such as an Attribute
+change, damage, restoration, resource change, or marker. _Avoid_: Effect when
+the source Talent and emitted result could be confused
+
+**Combat Profile**: The encounter assumptions and observed rates used to project
+a Loadout's combat performance. _Avoid_: Simulation when no event simulation
+occurs
+
+**Scenario Input**: An explicit encounter assumption required to evaluate a
+mechanic whose result cannot be determined from the Loadout alone. _Avoid_:
+Guess, default assumption
+
+**Ready**: The mechanic readiness state indicating that typed Game Data can
+evaluate the mechanic without additional Scenario Inputs. _Avoid_: Complete
+
+**Requires Assumptions**: The mechanic readiness state indicating that
+evaluation needs one or more explicit Scenario Inputs. _Avoid_: Ready,
+unsupported
+
+**Captured Only**: The mechanic readiness state indicating that SHD.build
+preserves the authored behavior but cannot calculate it. _Avoid_: Unsupported
+when the behavior has still been recorded
+
+**Extra Health**: Temporary Health granted in addition to an Agent's normal
+Health. Each grant remains distinct from later changes to the current Extra
+Health total. _Avoid_: Health, healing, bonus armor
+
+**Hit Taken**: A hit received by an Agent, including one absorbed by Extra
+Health. A Hit Taken does not require normal Health loss. _Avoid_: Taking Damage
+
+**Taking Damage**: A loss of an Agent's normal Health. A hit absorbed by Extra
+Health does not count as Taking Damage. _Avoid_: Hit Taken

docs/agents/domain.md

@@ -0,0 +1,60 @@
+# Domain docs
+
+Engineering skills must consult this repository's domain documentation before
+exploring code.
+
+## Read before exploring
+
+- Read `CONTEXT.md` at the repository root.
+- If `CONTEXT-MAP.md` exists, use it to find the `CONTEXT.md` files relevant to
+  the task.
+- Read ADRs under `docs/adr/` that affect the area you will change. In a
+  multi-context repository, also check `src/<context>/docs/adr/`.
+
+If these files do not exist, proceed without comment. Do not suggest creating
+them before the project resolves domain terms or architectural decisions. The
+`/domain-modeling` skill, reached through `/grill-with-docs` and
+`/improve-codebase-architecture`, creates them when needed.
+
+## File structure
+
+This repository uses the single-context layout:
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+A repository with multiple bounded contexts can use this layout:
+
+```text
+/
+├── CONTEXT-MAP.md
+├── docs/adr/
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use glossary terms
+
+Use the terms defined in `CONTEXT.md` in issue titles, refactor proposals,
+hypotheses, and test names. Do not substitute synonyms that the glossary
+rejects.
+
+If a needed concept is absent, reconsider whether the project uses that concept.
+If it represents a real gap, record it for `/domain-modeling`.
+
+## Flag ADR conflicts
+
+Call out any proposal that conflicts with an ADR:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

docs/agents/issue-tracker.md

@@ -0,0 +1,106 @@
+# Issue tracker: Gitea
+
+Issues and specs for this repo live as Gitea issues. Use the
+[`tea`](https://gitea.com/gitea/tea) CLI for all operations.
+
+## Repository context
+
+Run commands inside the clone so `tea` can infer the repository and login from
+its Git remote. If the clone has multiple Gitea remotes or logins, pass
+`--remote <name>` or `--login <name>`. Use `--repo <owner>/<repo>` only outside
+the clone.
+
+Before the first operation, verify the instance with
+`tea logins list --output json`. If it is missing, ask the user to run
+`tea login add`; never ask for or handle their access token.
+
+## Conventions
+
+- **Create an issue**: `tea issues create --title "..." --description "..."`.
+  For a multi-line body, use shell command substitution around a quoted heredoc:
+
+  ```bash
+  tea issues create --title "..." --description "$(cat <<'EOF'
+  Multi-line issue body.
+  EOF
+  )"
+  ```
+
+- **Read an issue with comments**:
+  `tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.
+- **List issues**:
+  `tea issues list --state open --fields index,state,author,url,title,body,assignees,labels,comments --output json`,
+  adding `--labels "label-one,label-two"`, `--assignee <user>`, or another
+  supported filter as needed. Paginate with `--page` and `--limit`; do not
+  assume the default first 30 results are complete.
+- **Comment on an issue**: `tea comments add <number> --description "..."`.
+- **Apply or remove labels**: `tea issues edit <number> --add-labels "..."` or
+  `--remove-labels "..."`. Separate multiple labels with commas.
+- **Assign or unassign**: `tea issues edit <number> --add-assignees "..."` or
+  `--remove-assignees "..."`.
+- **Close**: post the closing explanation with
+  `tea comments add <number> --description "..."`, then run
+  `tea issues close <number>`.
+- **Reopen**: `tea issues reopen <number>`.
+- **Raw API fallback**: use `tea api '<endpoint>'` only for a Gitea feature
+  without a first-class `tea` command. Prefer `{owner}` and `{repo}`
+  placeholders so repository context remains explicit.
+
+Use `--output json` for machine-readable reads. Do not scrape table output.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set this to `yes` if this repo treats
+external pull requests as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs use the same labels and states as issues:
+
+- **Read a PR with comments and diff**:
+  `tea pulls <number> --comments --fields index,state,author,url,title,body,diff,assignees,labels,comments --output json`.
+- **List open PRs**:
+  `tea pulls list --state open --fields index,state,author,author-id,url,title,body,assignees,labels,comments --output json`.
+  Determine whether an author is external from the repository's Gitea membership
+  data; the PR listing does not classify author membership.
+- **Comment**: `tea comments add <number> --description "..."`.
+- **Apply or remove labels**: `tea pulls edit <number> --add-labels "..."` or
+  `--remove-labels "..."`.
+- **Close**: `tea pulls close <number>`.
+
+Gitea pull requests use the repository's issue index space, so `#42` may refer
+to either surface. If the context is unclear, inspect it with
+`tea pulls 42 --output json`; if that command reports no PR, read it with
+`tea issues 42 --output json`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue with `tea issues create`.
+
+## When a skill says "fetch the relevant ticket"
+
+Run
+`tea issues <number> --comments --fields index,state,author,url,title,body,assignees,labels,comments --output json`.
+
+## Wayfinding operations
+
+`/wayfinder` uses one **map** issue with linked **child** issues. These
+conventions store relationships in issue bodies, so they work across Gitea
+versions.
+
+- **Map**: create one issue labelled `wayfinder:map` containing the Notes,
+  Decisions-so-far, and Fog sections. Use
+  `tea issues create --labels "wayfinder:map"` with its title and description.
+- **Child ticket**: start the body with `Part of #<map>` and apply a
+  `wayfinder:<type>` label: `research`, `prototype`, `grilling`, or `task`. Add
+  each child as a task-list item in the map body to preserve frontier order.
+- **Blocking**: put `Blocked by: #<n>, #<n>` near the top of the child body. A
+  ticket becomes unblocked after every referenced blocker closes.
+- **Frontier query**: list all open children, order them by the map's task list,
+  and discard tickets with an open blocker or an assignee. Select the first
+  remaining ticket. Fetch each referenced blocker; do not infer its state from
+  map text.
+- **Claim**: resolve the active username with `tea whoami`, then run
+  `tea issues edit <n> --add-assignees "<username>"` as the session's first
+  write. Do not assume `@me` works.
+- **Resolve**: run `tea comments add <n> --description "<answer>"`, close the
+  child with `tea issues close <n>`, then append a context pointer and link to
+  the map's Decisions-so-far section.

docs/agents/triage-labels.md

@@ -0,0 +1,14 @@
+# Triage labels
+
+Engineering skills use five canonical triage roles. This table maps each role to
+the label string in this repository's issue tracker.
+
+| Canonical role    | Tracker label     | Meaning                                |
+| ----------------- | ----------------- | -------------------------------------- |
+| `needs-triage`    | `needs-triage`    | A maintainer must evaluate the issue   |
+| `needs-info`      | `needs-info`      | Waiting for more information           |
+| `ready-for-agent` | `ready-for-agent` | Fully specified and ready for an agent |
+| `ready-for-human` | `ready-for-human` | Requires human implementation          |
+| `wontfix`         | `wontfix`         | Maintainers will not act on the issue  |
+
+When a skill names a canonical role, use the corresponding tracker label.