@bannynet/core-v6 0.0.22 → 0.0.24

package/ADMINISTRATION.md

@@ -1,136 +1,87 @@
 # Administration
 
-Admin privileges and their scope in banny-retail-v6. The contract (`Banny721TokenUriResolver`) is a single-file system with one admin role (Ownable) and per-token owner privileges.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| Scope | Resolver-level metadata, SVG asset commitments/uploads, and body-level outfit management for Banny NFTs. |
-| Operators | The resolver owner for global metadata and asset commitments, body owners for decoration actions, and anyone for permissionless SVG uploads that match committed hashes. |
-| Highest-risk actions | Committing the wrong SVG hash, changing global metadata unexpectedly, or locking outfit changes while assets are held custodially in the resolver. |
-| Recovery posture | Write-once SVG commitments cannot be corrected in place. If resolver behavior is wrong, recovery usually means deploying a replacement resolver rather than editing stored content. |
-
-## Routine Operations
+| --- | --- |
+| Scope | `Banny721TokenUriResolver` metadata, SVG commitments, and outfit-state control |
+| Control posture | Global `Ownable` metadata control plus per-body owner control |
+| Highest-risk actions | Wrong SVG hash commitments, incorrect metadata updates, and long outfit locks |
+| Recovery posture | Metadata is editable, but committed hashes, uploaded SVGs, and active locks are not reversible |
 
-- Commit SVG hashes only after verifying the exact UPC-to-content pairing, since the commitment is permanent.
-- Treat metadata and product-name changes as ecosystem-wide display changes that affect every token rendered through the resolver.
-- Remind users that equipped assets are held by the resolver contract until they are unequipped through the supported flow.
-- Use outfit locks deliberately, because they freeze body-level changes for the fixed lock window.
+## Purpose
 
-## One-Way Or High-Risk Actions
+`banny-retail-v6` has a small but real control plane. The resolver owner controls collection-wide metadata and SVG commitments. Body owners control decoration and outfit locks. No admin can rescue equipped NFTs if resolver logic fails.
 
-- `setSvgHashesOf` is write-once per UPC.
-- `setSvgContentsOf` is also write-once once valid content is uploaded.
-- `lockOutfitChangesFor` can only extend the active lock, never shorten it.
-- There is no admin rescue path for custodially held outfit NFTs.
+## Control Model
 
-## Recovery Notes
-
-- If committed artwork is wrong, the practical recovery path is a new resolver or a new UPC strategy, not overwriting the existing entry.
-- If outfits become stuck because of a resolver bug, this contract exposes no owner rescue flow; recovery would require replacement infrastructure rather than an admin intervention.
+- `Banny721TokenUriResolver` is `Ownable`.
+- Global admin power is limited to metadata, product naming, and SVG hash commitments.
+- Actual SVG upload is permissionless once the hash is committed.
+- Body owners control decoration and locking for their own bodies.
+- Equipped accessories are held by the resolver while attached.
 
 ## Roles
 
-| Role | How Assigned | Scope |
-|------|-------------|-------|
-| **Contract Owner** | Set via constructor `Ownable(owner)`. Transferable via OpenZeppelin `transferOwnership()`. | Global: SVG asset management, metadata, product naming |
-| **NFT Body Owner** | Whoever holds the banny body token on the JB721TiersHook contract. Checked via `IERC721(hook).ownerOf(bannyBodyId)`. | Per-token: decoration, locking |
-| **NFT Outfit/Background Owner** | Whoever holds the outfit or background token on the hook contract. | Per-token: authorize equipping to a body they own |
-| **Anyone (Permissionless)** | No restriction. | Upload SVG content (if matching hash exists) |
-| **Trusted Forwarder** | Set at construction via `ERC2771Context(trustedForwarder)`. Immutable after deploy. | Meta-transaction relay: `_msgSender()` resolves to the relayed sender |
-
-## Privileged Functions
-
-### Banny721TokenUriResolver -- Owner-Only Functions
-
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `setMetadata(description, url, baseUri)` | `onlyOwner` | Overwrites the token metadata description, external URL, and SVG base URI. All three fields are always written (pass current value to keep, empty string to clear). |
-| `setProductNames(upcs, names)` | `onlyOwner` | Sets custom display names for products identified by UPC. Names are stored in `_customProductNameOf` mapping. Can overwrite previously set names. |
-| `setSvgHashesOf(upcs, svgHashes)` | `onlyOwner` | Commits keccak256 hashes for SVG content keyed by UPC. Each hash can only be set once -- reverts with `HashAlreadyStored` if the UPC already has a hash. This is the gating step that controls which SVG content can later be uploaded permissionlessly. |
-
-### Banny721TokenUriResolver -- Permissionless Functions
-
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `setSvgContentsOf(upcs, svgContents)` | None (anyone) | Stores SVG content for a UPC, but only if: (1) a hash was previously committed by the owner via `setSvgHashesOf`, (2) `keccak256(content) == storedHash`, and (3) content has not already been stored (`ContentsAlreadyStored`). This is the permissionless "lazy upload" mechanism. |
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Resolver owner | `Ownable(owner)` at construction | Global | Can transfer ownership with `transferOwnership()` |
+| Body owner | `IERC721(hook).ownerOf(bannyBodyId)` | Per body | Can decorate and lock that body |
+| Anyone | No assignment | Global | Can upload SVG bytes only if they match a committed hash |
 
-### Banny721TokenUriResolver -- NFT-Owner Functions
+## Privileged Surfaces
 
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `decorateBannyWith(hook, bannyBodyId, backgroundId, outfitIds)` | `_checkIfSenderIsOwner` + `nonReentrant` | Equips/unequips outfits and background on a banny body. Caller must own the body token. For each outfit/background: caller must own the asset directly, OR own the banny body that currently wears/uses it. Transfers outfit NFTs into the resolver contract (custodial). |
-| `lockOutfitChangesFor(hook, bannyBodyId)` | `_checkIfSenderIsOwner` | Locks a banny body's outfit for 7 days (`_LOCK_DURATION`). Lock can only be extended, never shortened (`CantAccelerateTheLock`). Prevents `decorateBannyWith` during the lock period. |
+| Contract | Function | Who Can Call | Effect |
+| --- | --- | --- | --- |
+| `Banny721TokenUriResolver` | `setMetadata(...)` | Resolver owner | Changes global description, URL, and base URI |
+| `Banny721TokenUriResolver` | `setProductNames(...)` | Resolver owner | Changes display names for products |
+| `Banny721TokenUriResolver` | `setSvgHashesOf(...)` | Resolver owner | Commits write-once SVG hashes for UPCs |
+| `Banny721TokenUriResolver` | `setSvgContentsOf(...)` | Anyone with matching bytes | Uploads write-once SVG payloads for committed hashes |
+| `Banny721TokenUriResolver` | `decorateBannyWith(...)` | Current body owner | Equips or unequips accessories and updates custody |
+| `Banny721TokenUriResolver` | `lockOutfitChangesFor(...)` | Current body owner | Extends the outfit lock window for that body |
 
-### Banny721TokenUriResolver -- Restricted Receiver
+## Immutable And One-Way
 
-| Function | Guard | What It Does |
-|----------|-------|-------------|
-| `onERC721Received(operator, from, tokenId, data)` | `operator == address(this)` | Only accepts incoming NFT transfers when the resolver itself initiated the transfer. Rejects all direct user transfers to the resolver contract with `UnauthorizedTransfer`. |
+- SVG hash commitments are write-once.
+- SVG contents are write-once once uploaded.
+- `lockOutfitChangesFor(...)` only extends the active lock.
+- The lock duration is fixed by `_LOCK_DURATION`.
+- Default art fragments, category semantics, and the trusted forwarder are constructor or code immutables.
 
-## Asset Management
+## Operational Notes
 
-**Who can add SVG assets:**
+- Treat `setSvgHashesOf(...)` like a release gate. A wrong hash usually means a new resolver or new UPC strategy, not a small edit.
+- Treat `setMetadata(...)` and `setProductNames(...)` as collection-wide display changes.
+- Remind users that equipped assets are in resolver custody while attached.
+- Only lock outfits when temporary non-editability is the intended experience.
+- Use safe ERC-721 transfer flows when assets enter the resolver path. Plain `transferFrom` can strand NFTs without a recovery path.
 
-1. The contract **owner** commits SVG hashes via `setSvgHashesOf()`. This is the only gatekeeping step -- only the owner decides which UPCs get artwork.
-2. **Anyone** can then upload the actual SVG content via `setSvgContentsOf()`, provided the content's keccak256 hash matches the owner-committed hash. This is intentional: the owner sets the commitment, and anyone can fulfill it (useful for gas-efficient lazy uploading).
+## Machine Notes
 
-**Immutability of stored content:**
-- Once a hash is set for a UPC, it cannot be changed (`HashAlreadyStored`).
-- Once content is uploaded for a UPC, it cannot be replaced (`ContentsAlreadyStored`).
-- There is no function to delete or modify stored SVG hashes or content.
+- Do not assume there is a rescue path for equipped assets. There is none.
+- Treat `src/Banny721TokenUriResolver.sol` as the source of truth for lock extension and write-once SVG behavior.
+- If a committed hash and intended asset bytes differ, stop. The contract does not support overwrite repair.
+- If an asset arrived through non-safe ERC-721 transfer semantics, do not assume the resolver can detect or recover it.
 
-**Product names:**
-- Can be overwritten by the owner at any time via `setProductNames()`. There is no immutability guard on names -- the owner can rename products freely. The built-in names for UPCs 1-4 (Alien, Pink, Orange, Original) are hardcoded in `_productNameOf()` and cannot be overridden.
+## Recovery
 
-**Metadata:**
-- `svgDescription`, `svgExternalUrl`, and `svgBaseUri` can be changed by the owner at any time via `setMetadata()`. All three are always overwritten in a single call.
-
-## Custodial Model
-
-When a user equips an outfit or background on a banny body via `decorateBannyWith()`, the outfit/background NFT is transferred from the user's wallet into the `Banny721TokenUriResolver` contract. The resolver holds these NFTs in custody until the user unequips them (by calling `decorateBannyWith()` again with different outfits).
-
-**Trust assumptions:**
-- Users must trust that the resolver contract's `decorateBannyWith()` function correctly returns NFTs when outfits are changed. There is no separate `withdraw()` or `rescue()` function.
-- The `onERC721Received` guard (`operator == address(this)`) prevents anyone from sending arbitrary NFTs to the resolver. Only self-initiated transfers during `decorateBannyWith()` are accepted.
-- If the banny body NFT is transferred to a new owner while outfits are equipped, the new body owner can unequip and claim the outfit NFTs (the ownership check in `_checkIfSenderIsOwner` is against the current body owner).
-- The `lockOutfitChangesFor()` function can lock outfits for up to 7 days per call (extendable). During a lock, neither the body owner nor anyone else can change the equipped outfits.
-- There is no admin override to rescue stuck outfit NFTs. If a bug in `decorateBannyWith()` prevents unequipping, the outfits remain locked in the resolver permanently.
-
-## Immutable Configuration
-
-The following are set at construction and cannot be changed:
-
-| Property | Set At | Value |
-|----------|--------|-------|
-| `BANNY_BODY` | Constructor | Base SVG path for all banny body rendering |
-| `DEFAULT_NECKLACE` | Constructor | Default necklace SVG injected when no custom necklace equipped |
-| `DEFAULT_MOUTH` | Constructor | Default mouth SVG injected when no custom mouth equipped |
-| `DEFAULT_STANDARD_EYES` | Constructor | Default eyes SVG for non-alien bodies |
-| `DEFAULT_ALIEN_EYES` | Constructor | Default eyes SVG for alien bodies |
-| `trustedForwarder` | Constructor | ERC-2771 forwarder address for meta-transactions |
-| `_LOCK_DURATION` | Constant | 7 days -- hardcoded, not configurable |
-| Body color fills | Hardcoded in `_fillsFor()` | Color palettes for Alien, Pink, Orange, Original body types |
-| Category IDs | Constants | 18 category slots (0-17), hardcoded |
+- Bad metadata can be changed by the owner.
+- Bad SVG commitments or uploaded content cannot be corrected in place.
+- If equipped assets become stuck because of resolver logic, there is no owner rescue path.
+- If NFTs are stranded through non-safe transfer semantics, this contract does not provide recovery.
 
 ## Admin Boundaries
 
-**What the owner CANNOT do:**
-
-- **Cannot move or steal user NFTs.** The resolver only holds custody of outfit/background NFTs that users voluntarily equip. The `onERC721Received` guard ensures only self-initiated transfers are accepted.
-- **Cannot modify stored SVG content.** Once hash + content are committed, they are permanent. No delete or update function exists.
-- **Cannot modify stored SVG hashes.** Each UPC's hash is write-once.
-- **Cannot change the lock duration.** The 7-day lock is a compile-time constant.
-- **Cannot force-equip or force-unequip outfits.** Only the body NFT's owner can call `decorateBannyWith` and `lockOutfitChangesFor`.
-- **Cannot override hardcoded body names.** UPCs 1-4 always resolve to Alien, Pink, Orange, Original regardless of `_customProductNameOf`.
-- **Cannot change the trusted forwarder.** It is immutable after construction.
-- **Cannot pause the contract.** There is no pause mechanism.
-- **Cannot upgrade the contract.** It is not upgradeable.
+- The owner cannot arbitrarily withdraw equipped user NFTs.
+- The owner cannot overwrite committed hashes or uploaded SVG contents.
+- The owner cannot bypass body-owner checks on decoration or locking.
+- Nobody can shorten an active outfit lock.
+- There is no pause, upgrade, or rescue mechanism.
 
-**What the owner CAN do that affects users:**
+## Source Map
 
-- **Change metadata** (`svgDescription`, `svgExternalUrl`, `svgBaseUri`). This affects how all tokens render in wallets/marketplaces. Clearing `svgBaseUri` would break IPFS-based fallback rendering for products without on-chain SVG content.
-- **Rename products.** Custom product names (UPC > 4) can be changed at any time, altering how NFTs display.
-- **Commit new SVG hashes.** This controls which new artwork can be uploaded, but cannot affect already-stored content.
-- **Transfer ownership.** Via OpenZeppelin `transferOwnership()`, the owner can hand off all admin privileges to a new address (including a multisig, DAO, or malicious actor).
+- `src/Banny721TokenUriResolver.sol`
+- `src/interfaces/IBanny721TokenUriResolver.sol`
+- `script/Deploy.s.sol`
+- `test/TestAuditGaps.sol`
+- `test/TestQALastMile.t.sol`

package/ARCHITECTURE.md

@@ -2,75 +2,100 @@
 
 ## Purpose
 
-`banny-retail-v6` provides the metadata layer for Banny collections. The repo does not mint or own the NFTs itself. Instead, a Juicebox 721 hook points at `Banny721TokenUriResolver`, and the resolver composes body, background, and outfit NFTs into a single on-chain representation.
+`banny-retail-v6` is the Banny-specific metadata and attachment layer for Juicebox 721 collections. It does not mint NFTs or own treasury logic. It owns attachment custody, outfit-lock rules, and final token rendering.
 
-## Boundaries
+## System Overview
 
-- The repo owns Banny-specific composition logic, asset registration, and outfit locking.
-- `nana-721-hook-v6` still owns token minting, transfers, and collection-level ERC-721 behavior.
-- The resolver is intentionally application-specific. Generic 721 hook behavior should stay in `nana-721-hook-v6`.
+The repo centers on `Banny721TokenUriResolver`. A 721 hook from `nana-721-hook-v6` points to this resolver for `tokenURI(...)`. Bodies, outfits, and backgrounds remain separate NFTs at the collection layer. The resolver escrows equipped accessories, records which assets are attached to each body, and composes the final SVG and JSON metadata on demand.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `Banny721TokenUriResolver` | Stores SVG content references, tracks equipped assets per body, enforces outfit-lock windows, and returns composed token metadata |
-| `IBanny721TokenUriResolver` | Integration surface for the 721 hook or external tooling |
+- A body can only reference accessories that are currently escrowed by the resolver.
+- Replacing an equipped item must atomically return the old item and escrow the new item.
+- Outfit locks must block both explicit removal and implicit replacement until the lock expires.
+- Equipped assets move with the body NFT on transfer until the new owner unequips them.
+- Registered SVG payloads must match their committed content hash before they can render.
+- Rendering must stay deterministic for the same stored body state.
 
-## Runtime Model
+## Modules
 
-### Decoration
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `Banny721TokenUriResolver` | Escrow, attachment state, lock windows, and metadata rendering | Main contract |
+| `IBanny721TokenUriResolver` | External integration surface | Used by hooks and offchain tooling |
+
+## Trust Boundaries
+
+- Minting, ownership transfer, and collection-level ERC-721 semantics live in `nana-721-hook-v6`.
+- This repo is trusted for rendering correctness and custody of equipped assets.
+- Asset-content upload is controlled by the registered content owner, but the contract verifies uploaded bytes against the stored hash.
+
+## Critical Flows
+
+### Decorate
 
 ```text
 body owner
   -> calls decorateBannyWith(...)
-  -> resolver verifies ownership of the body token
-  -> resolver pulls the chosen background and outfit NFTs into escrow
-  -> resolver records which assets are attached to the body
-  -> resolver returns any replaced assets to the owner
+  -> resolver verifies body ownership and lock status
+  -> resolver pulls new accessories into escrow
+  -> resolver updates equipped slots
+  -> resolver returns replaced accessories to the owner
 ```
 
-### Rendering
+### Render
 
 ```text
 tokenURI(bodyId)
-  -> resolve body, background, and equipped outfit slots
-  -> fetch registered SVG fragments
-  -> compose layered SVG
-  -> return base64 JSON metadata
+  -> resolver loads body, background, and equipped slot state
+  -> fetches registered SVG fragments
+  -> composes layered SVG in Banny-specific order
+  -> returns base64 JSON metadata
 ```
 
-### Locking
+### Lock Outfit
 
 ```text
-owner
-  -> lockOutfitChangesFor(...)
-  -> body enters a temporary no-change window
-  -> decoration and removal paths must respect the lock
+body owner
+  -> calls lockOutfitChangesFor(...)
+  -> resolver stores a no-change window
+  -> later decoration and removal paths must respect it
 ```
 
-## Critical Invariants
+## Accounting Model
 
-- A body can only point at assets currently escrowed by the resolver.
-- Slot replacement must be one-for-one. Replacing an equipped item returns the old item instead of orphaning it.
-- Outfit locks must block both direct edits and indirect attempts to reclaim an equipped item through another decoration call.
-- Asset registration is split between hash registration and content upload so content can be trustlessly verified before it is stored on-chain.
+This repo does not own treasury accounting. Its critical state is custody accounting: which NFTs are escrowed, which body they belong to, and when a body is locked against changes.
 
-## Where Complexity Lives
+That custody model uses lazy reconciliation for some stale attachment records. Read paths filter against current ownership and attachment state instead of rewriting storage on every outside transfer.
 
-- Escrow bookkeeping and slot replacement must stay synchronized.
-- Lock enforcement has to cover both explicit removal and implicit replacement paths.
-- SVG composition order is application logic, not a cosmetic detail.
+## Security Model
 
-## Dependencies
-
-- `nana-721-hook-v6` for collection ownership and transfer semantics
-- Juicebox metadata resolver patterns for token URI integration
+- The main failure mode is custody drift between slot state and actual escrowed NFTs.
+- Rendering order is part of app semantics, not cosmetic output.
+- Lazy reconciliation is intentional. Changes that assume storage is always perfectly clean can strand assets or mis-render bodies.
+- Any new asset category adds both a rendering concern and a custody concern.
 
 ## Safe Change Guide
 
-- Put new generic 721 behavior in `nana-721-hook-v6`, not here.
-- Treat slot accounting and escrow transfers as coupled logic. Changing one without the other is how equipment duplication bugs appear.
-- Changes to `tokenURI` should preserve deterministic output for the same body state.
-- If adding new asset categories, verify render order and replacement semantics together.
-- If a change touches both metadata composition and escrow state, test transfer lifecycle behavior, not just rendered output.
+- Keep generic ERC-721 behavior in `nana-721-hook-v6`, not here.
+- Review escrow writes and transfer behavior together whenever changing attachment logic.
+- If transfer or cleanup behavior changes, re-check lazy reconciliation alongside body-transfer inheritance.
+- If `tokenURI(...)` changes, test stable output for unchanged state and replacement behavior for changed state.
+- If adding slots or asset classes, update rendering order, slot replacement, and lock enforcement in one change.
+
+## Canonical Checks
+
+- accessory escrow, replacement, and decoration flow:
+  `test/DecorateFlow.t.sol`
+- burned-body custody edge cases:
+  `test/audit/BurnedBodyStrandsAssets.t.sol`
+- transfer-path protection against stranded attachments:
+  `test/audit/TryTransferFromStrandsAssets.t.sol`
+
+## Source Map
+
+- `src/Banny721TokenUriResolver.sol`
+- `test/DecorateFlow.t.sol`
+- `test/audit/BurnedBodyStrandsAssets.t.sol`
+- `test/audit/TryTransferFromStrandsAssets.t.sol`
+- `script/Deploy.s.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,87 +1,78 @@
 # Audit Instructions
 
-This repo is the Banny avatar composition layer. Its runtime surface is small, but it directly custodizes NFTs and decides what a Banny body can wear.
+This repo is the Banny avatar composition layer. It does not mint the base NFTs, but it does hold equipped accessories and define the metadata users see.
 
-## Objective
+## Audit Objective
 
 Find issues that:
-- strand body, outfit, or background NFTs in the resolver
-- let the wrong actor equip, unequip, steal, or overwrite accessories
-- bypass outfit-lock timing or freeze users longer than intended
-- return incorrect metadata for bodies, outfits, or backgrounds
-- break category exclusivity or layering assumptions
+
+- strand outfits or backgrounds in resolver custody
+- let the wrong actor equip, unequip, overwrite, or recover accessories
+- break outfit-lock timing or freeze a body longer than intended
+- return metadata that does not match stored attachment state
+- bypass category or layering constraints
 
 ## Scope
 
 In scope:
+
 - `src/Banny721TokenUriResolver.sol`
 - `src/interfaces/IBanny721TokenUriResolver.sol`
-- deployment scripts in `script/`
-
-Primary integration assumptions to verify:
-- the resolver is used as a token URI resolver for a `JB721TiersHook`
-- the underlying 721 hook remains the token contract and tier source
-- the resolver temporarily holds accessory NFTs while they are equipped
+- deployment helpers in `script/`
 
-## System Model
+## Start Here
 
-The resolver does not mint project NFTs. It:
-- reads tier and token metadata from the attached 721 hook
-- receives outfit and background NFTs through safe transfers
-- records which body currently has which attachments
-- enforces category and conflict rules
-- renders composed metadata and SVG output
+1. `src/Banny721TokenUriResolver.sol`
+2. accessory receipt and release paths
+3. deployment wiring in `script/`
 
-The critical custody model is:
-- body owner controls decoration
-- resolver holds equipped accessories
-- on unequip or invalidation, assets must become recoverable by the rightful owner
+## Security Model
 
-## Critical Invariants
+The resolver is an attachment and rendering layer around a `JB721TiersHook` collection.
 
-1. No asset loss in custody
-Every outfit or background transferred into the resolver must remain attributable to exactly one body or be withdrawable back to the rightful owner.
+- the underlying 721 hook remains the token contract and source of body ownership
+- the resolver temporarily holds accessory NFTs while they are equipped
+- body ownership should be the only authority that changes equipped state
+- accessory contracts may be hostile or malformed, so receipt and release ordering matters
 
-2. Body ownership gates decoration
-Only an authorized actor for the body may change its equipped state.
+## Roles And Privileges
 
-3. Category exclusivity
-Conflicting categories must not be equipped together, and categories that are forbidden as accessories must never become equipped through edge paths.
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Body owner | Equip, unequip, and lock accessories | Must be derived from the current hook-reported owner |
+| Resolver owner | Update metadata and SVG-related admin state | Must not control equipped-state authorization |
+| Accessory NFT contract | Execute callbacks during custody changes | Must not corrupt bookkeeping or steal custody |
 
-4. Lock correctness
-`lockOutfitChangesFor` must only prevent changes for the intended body and duration. It must not be bypassable, extendable by unauthorized actors, or accidentally permanent.
+## Integration Assumptions
 
-5. Metadata coherence
-`tokenURI` and related rendering helpers must reflect actual equipped state and should not expose stale or impossible compositions.
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `JB721TiersHook` | Reports authentic body ownership and tier metadata | Unauthorized decoration or incorrect rendering |
+| Accessory ERC-721s | Behave like standard transferable NFTs | Custody or release flows fail unexpectedly |
 
-## Threat Model
+## Critical Invariants
 
-Prioritize adversaries that:
-- transfer unexpected NFTs into the resolver
-- try to decorate using burned, removed, or mismatched token IDs
-- exploit reentrancy on NFT receipt or withdrawal
-- use invalid category order or duplicate categories to desync state
-- attempt to steal accessories by redecorating around lock windows
+1. Every accessory transferred into the resolver remains attributable to one body or is recoverable by the rightful owner.
+2. Only the current body owner or an intended delegate can change that body's equipped state.
+3. Conflicting categories cannot be equipped together, including through replacement or invalidation edge paths.
+4. Outfit-lock state only affects the intended body for the intended duration.
+5. Metadata and SVG generation reflect current state and do not show impossible combinations.
 
-## Hotspots
+## Attack Surfaces
 
-- `decorateBannyWith`: ownership checks, state replacement, and asset movement ordering
-- any path that accepts NFT transfers into resolver custody
-- outfit/background release paths after redecorating, burning, or invalid token states
+- decoration entrypoints that replace one accessory with another
+- ERC-721 receipt hooks and any path that accepts custody
+- release paths after redecorating, burning, or invalid token state
 - category validation and conflict checks
-- lock timestamp handling
-- token URI generation that assumes on-chain SVG data exists or remains consistent
+- metadata assembly that assumes onchain assets or tier data remain available
+
+## Accepted Risks Or Behaviors
+
+- Equipped accessories intentionally follow the body unless they are unequipped first.
+- Preserving attribution on failed transfer-out is safer than dropping custody state.
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-The current test tree emphasizes:
-- attack and regression coverage around stranding and exclusivity
-- decoration lifecycle flows
-- fork and QA scenarios
-
-Prefer proofs that show a body or accessory becoming inaccessible, transferable by the wrong party, or rendered inconsistently with stored state.

package/README.md

@@ -1,40 +1,72 @@
 # Banny Retail
 
-Banny Retail is an on-chain avatar system for Juicebox 721 collections. A body NFT can wear outfit NFTs, sit on a background NFT, and render the full composition as an on-chain SVG and base64 metadata payload.
+Banny Retail is an onchain avatar system for Juicebox 721 collections. A body NFT can wear outfit NFTs, use a background NFT, and resolve to a base64 JSON token URI whose image is an onchain SVG.
 
 Docs: <https://docs.juicebox.money>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-This is a resolver-centric application built on top of [`@bananapus/721-hook-v6`](https://www.npmjs.com/package/@bananapus/721-hook-v6). The resolver owns attached outfit and background NFTs while a body is decorated, then composes the active layers into a single token URI response.
+This is a resolver-centric app built on top of [`@bananapus/721-hook-v6`](https://www.npmjs.com/package/@bananapus/721-hook-v6). The resolver holds attached outfit and background NFTs while a body is decorated, then composes the active layers into a single token URI response.
 
 The main user flows are:
 
 - mint body, outfit, and background NFTs through a Juicebox 721 hook
 - attach accessories to a body with `decorateBannyWith`
-- optionally freeze the current look for seven days with `lockOutfitChangesFor`
-- upload SVG payloads lazily after an owner registers their content hashes
+- optionally freeze the look for seven days with `lockOutfitChangesFor`
+- upload SVG payloads after an owner registers the content hashes
 
-Use this repo when you need collection-specific, fully on-chain metadata composition on top of Juicebox NFTs. Do not use it as a generic 721 hook; it is an application-layer resolver, not a protocol NFT primitive.
-
-If a bug changes tier pricing, mint eligibility, or treasury flow, it is probably not here first. Start in the 721 hook repo and only come here once the issue is clearly in attachment, custody, or rendering behavior.
+Use this repo when you need collection-specific, fully onchain metadata composition on top of Juicebox NFTs. Do not use it as a generic 721 hook. It is an app-layer resolver, not a protocol NFT primitive.
 
 ## Key Contract
 
 | Contract | Role |
 | --- | --- |
-| `Banny721TokenUriResolver` | Resolves token metadata, stores equipped accessories, enforces outfit locks, and renders layered SVG output for Banny collections. |
+| `Banny721TokenUriResolver` | Resolves metadata, stores equipped accessories, enforces outfit locks, and renders layered SVG output for Banny collections. |
 
 ## Mental Model
 
 This repo owns three things:
 
-1. custody of attached outfit and background NFTs while equipped
-2. rules around what a body can wear and when that can change
-3. rendering of the final token metadata payload
+1. custody of outfit and background NFTs while they are equipped
+2. rules for what a body can wear and when that can change
+3. rendering of the final metadata payload
+
+It does not own mint pricing, tier issuance, or treasury accounting.
+
+## Read These Files First
+
+1. `src/Banny721TokenUriResolver.sol`
+2. `test/DecorateFlow.t.sol`
+3. `test/OutfitTransferLifecycle.t.sol`
+4. `nana-721-hook-v6/src/JB721TiersHook.sol` for upstream mint and tier behavior
+
+## High-Signal Tests
+
+1. `test/DecorateFlow.t.sol`
+2. `test/OutfitTransferLifecycle.t.sol`
+3. `test/audit/BurnedBodyStrandsAssets.t.sol`
+4. `test/audit/TryTransferFromStrandsAssets.t.sol`
+5. `test/TestQALastMile.t.sol`
 
-It does not own mint pricing, tier issuance, or project accounting.
+## Integration Traps
+
+- the resolver holds equipped assets, so transfer edge cases matter as much as rendering output
+- transferred bodies carry their equipped assets, so a new body holder can inherit control of them
+- burned bodies and non-safe transfer patterns can strand expectations around resolver-held assets
+- outfit locks survive body transfers until expiry
+- metadata quality depends on lazily uploaded asset payloads, not only token state
+
+## Where State Lives
+
+- equipped outfit and background state live in `Banny721TokenUriResolver`
+- layer rendering and token URI generation live in the same resolver
+- mint pricing, tier inventory, and treasury behavior live upstream in `nana-721-hook-v6`
 
 ## Install
 
@@ -61,7 +93,7 @@ Useful scripts:
 
 ## Deployment Notes
 
-Deployments are handled through Sphinx using the environments configured in `script/Deploy.s.sol`. The resolver is intended to be plugged into a Juicebox 721 hook as that hook's token URI resolver.
+Deployments are handled through Sphinx using the environments configured in `script/Deploy.s.sol`. The resolver is meant to be plugged into a Juicebox 721 hook as that hook's token URI resolver.
 
 ## Repository Layout
 
@@ -80,7 +112,14 @@ script/
 
 ## Risks And Notes
 
-- attached outfits and backgrounds are custodied by the resolver while equipped
+- attached outfits and backgrounds are held by the resolver while equipped
 - outfit locks are fixed-duration and cannot be shortened once set
-- on-chain SVG content is immutable once uploaded for a given registered hash
-- rendering quality and metadata correctness depend on the integrity of uploaded SVG assets
+- onchain SVG content is immutable once uploaded for a committed hash
+- plain `transferFrom` can still create asset-tracking surprises around resolver custody
+- rendering quality depends on the integrity of uploaded SVG assets
+
+## For AI Agents
+
+- Treat this repo as an app-layer resolver, not as the NFT issuance primitive.
+- Start with `Banny721TokenUriResolver` and the lifecycle tests before summarizing attachment behavior.
+- If the question is about mint economics or tier availability, inspect `nana-721-hook-v6` instead.

package/RISKS.md

@@ -1,89 +1,80 @@
 # Banny Retail Risk Register
 
-This file focuses on failure modes that can break NFT custody, let untrusted hook integrations bypass assumptions, or leave a rendered Banny in a state that does not match the assets users think they own.
+This file focuses on the failure modes that can break NFT custody, bypass hook assumptions, or leave a rendered Banny in a state that does not match the assets users think they own.
 
 ## How to use this file
 
-- Read `Priority risks` first; those are the highest-signal failure modes for operators, auditors, and integrators.
-- Use `Accepted Behaviors` to separate intentional tradeoffs from genuine bugs.
+- Read `Priority risks` first.
+- Use `Accepted Behaviors` to separate intentional tradeoffs from bugs.
 - Treat `Invariants to Verify` as required test and audit targets.
 
 ## Priority risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
-| P0 | Untrusted `hook` or store integration | The caller chooses the hook, and the resolver trusts it for ownership checks, tier metadata, and transfers. A bad hook can fake authority or trap assets. | Operationally restrict supported hooks, scrutinize sections 1, 3, and 5, and test with hostile hook behavior. |
-| P1 | Silent transfer failure retention | Failed returns intentionally keep attachment records to avoid stranding NFTs, but this can leave phantom render state if the underlying asset is gone forever. | Explicit accepted-behavior rules, retained-item handling, and invariants around custody/state correspondence. |
-| P1 | Sale-time outfit lock griefing | A seller can transfer a locked body and force the buyer to wait up to 7 days before changing outfits. | Fixed-duration lock, marketplace disclosure, and user education before secondary sales. |
-
+| P0 | Untrusted `hook` or store integration | The resolver trusts the supplied hook for ownership checks, tier metadata, and transfers. A bad hook can fake authority or trap assets. | Restrict supported hooks, scrutinize the hook boundary, and test hostile hook behavior. |
+| P1 | Silent transfer-failure retention | Failed returns intentionally keep attachment records to avoid stranding NFTs, but this can leave phantom render state if the asset is gone forever. | Explicit accepted-behavior rules, retained-item handling, and custody/state invariants. |
+| P1 | Sale-time outfit-lock griefing | A seller can transfer a locked body and force the buyer to wait up to 7 days before changing outfits. | Fixed-duration lock, marketplace disclosure, and user education. |
 
 ## 1. Trust Assumptions
 
-- **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted for all ownership checks in `decorateBannyWith`, `lockOutfitChangesFor`, and admin functions. A compromised forwarder can dress/undress any banny and steal equipped outfits.
-- **Hook contract.** The `hook` parameter is caller-supplied and not validated against any registry. A malicious hook contract could return arbitrary tier data, manipulate ownership checks, or trap NFTs.
-- **Owner (Ownable).** The contract owner controls SVG hashes, product names, and metadata URIs. A compromised owner can set malicious SVG content hashes, enabling XSS via on-chain SVG injection after the matching content is uploaded.
-- **721 hook store.** `_storeOf(hook)` calls `IJB721TiersHook(hook).STORE()` -- trusts the hook to return a legitimate store. A malicious hook can return a fake store with manipulated tier data.
+- **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted for ownership checks and admin functions.
+- **Hook contract.** The `hook` parameter is caller-supplied and not validated against a registry.
+- **Owner.** The contract owner controls SVG hashes, product names, and metadata URIs.
+- **721 hook store.** `_storeOf(hook)` trusts the hook to return a legitimate store.
 
-## 2. Economic / Manipulation Risks
+## 2. Economic And Manipulation Risks
 
-- **Outfit theft via banny body transfer.** Equipped outfits and backgrounds travel with the banny body NFT on transfer. If a banny body is sold with valuable outfits equipped, the buyer gains control of all equipped items. Sellers must unequip before selling. Marketplaces may not surface this risk.
-- **try-catch silent failures with retention.** `_tryTransferFrom` silently catches all transfer failures and returns `false`. When a transfer fails, the resolver preserves the attachment record instead of clearing state. For backgrounds, the entire background change is aborted. For outfits, failed-to-return items are retained in the attached list via `_storeOutfitsWithRetained`. This prevents NFT stranding — assets remain tracked and recoverable once the transfer issue is resolved (e.g., the owner contract becomes receivable). However, if an outfit NFT is burned or its tier removed, the retained record refers to a non-existent asset, creating a phantom entry in the SVG rendering.
-- **Lock griefing.** `lockOutfitChangesFor` extends the lock to `block.timestamp + 7 days`. Locking just before selling prevents the buyer from changing outfits for up to 7 days. The lock now also freezes reassignment of currently equipped outfits/backgrounds away from that body during the lock window.
+- **Outfit theft via body transfer.** Equipped outfits and backgrounds move with the body NFT. If a body is sold while wearing valuable items, the buyer gains control of them.
+- **Try-catch silent failures with retention.** Failed transfer-outs preserve attachment records instead of clearing state. This avoids stranding but can create phantom render entries for burned or removed assets.
+- **Lock griefing.** `lockOutfitChangesFor` extends the lock to `block.timestamp + 7 days`. Locking just before a sale can block the buyer from changing the look for up to 7 days.
 
 ## 3. Access Control
 
-- **No hook validation (HIGH impact).** Any address can be passed as `hook`. A malicious hook can return `_msgSender()` from `ownerOf()` to pass authorization checks, execute arbitrary code during `safeTransferFrom`, or return manipulated tier data from `STORE().tierOfTokenId()`.
-- **SVG content upload is permissionless (with hash).** `setSvgContentsOf` only requires the content to match a pre-committed hash. Safe if hashes are correctly committed.
-- **onERC721Received restriction.** Only accepts NFTs when `operator == address(this)`. `transferFrom` (non-safe) bypasses this -- NFTs sent via `transferFrom` are permanently locked with no rescue function.
+- **No hook validation.** Any address can be passed as `hook`. A malicious hook can fake `ownerOf`, execute arbitrary code during transfers, or return manipulated tier data.
+- **SVG content upload is permissionless once the hash is committed.** This is safe only if the committed hash is correct.
+- **`onERC721Received` restriction.** The contract only accepts NFTs when `operator == address(this)`. Plain `transferFrom` bypasses that and can permanently lock NFTs.
 
 ## 4. DoS Vectors
 
-- **External call iteration scales with outfit count.** `_attachedOutfitIdsOf[hook][bannyBodyId]` is replaced wholesale on each `decorateBannyWith` call (not appended to), so the array is bounded by the number of currently equipped outfits, not cumulative history. However, `decorateBannyWith` iterates over both the previous and new outfit arrays to diff them (transferring removed outfits back and new outfits in), so gas cost scales with the number of outfits being equipped/unequipped in a single call.
-- **External hook calls in view functions.** `tokenUriOf` and `svgOf` call into the hook's store multiple times per outfit. A malicious hook that consumes excessive gas or reverts can make token metadata unretrievable. Measured: `tokenUriOf` with a well-behaved hook and 9 equipped outfits costs ~609k gas (see `test_tokenUri_gasSnapshot_9outfits`). The practical ceiling for a malicious hook is bounded only by the caller's gas limit — RPC nodes typically cap `eth_call` at 30M+ gas, so even expensive hooks won't fail for off-chain reads, but on-chain consumers (e.g., other contracts calling `tokenURI`) could revert.
+- **External call iteration scales with outfit count.** `decorateBannyWith` iterates both old and new outfit arrays, so gas cost scales with the number of outfits changed in one call.
+- **External hook calls in view functions.** `tokenUriOf` and `svgOf` call into the hook's store multiple times. A malicious or gas-heavy hook can make metadata unreadable.
 
 ## 5. Integration Risks
 
-- **Cross-contract NFT custody.** Outfits are held by `Banny721TokenUriResolver` via `safeTransferFrom`. If approval is revoked on the hook contract, equipping fails.
-- **Tier removal desync.** If a tier is removed from the 721 hook while an outfit from that tier is equipped, `_productOfTokenId` returns a product with `id == 0`. The outfit remains equipped but renders as empty. `_tryTransferFrom` may fail silently when trying to return it.
-- **Non-safe transfer loss.** Outfits sent directly to this contract via `transferFrom` (not `safeTransferFrom`) are permanently stuck since there is no rescue function.
-- **ReentrancyGuard.** `decorateBannyWith` uses `nonReentrant`, but `lockOutfitChangesFor` and view functions do not. Reentrancy through hook callbacks is possible but state updates follow CEI pattern.
+- **Cross-contract NFT custody.** Outfits are held by the resolver via `safeTransferFrom`. If approval is revoked on the hook contract, equipping fails.
+- **Tier removal desync.** If a tier is removed while an outfit from that tier is equipped, the outfit may remain attached but render empty.
+- **Non-safe transfer loss.** Outfits sent directly via `transferFrom` can be permanently stuck because there is no rescue function.
+- **Reentrancy assumptions.** `decorateBannyWith` uses `nonReentrant`, but other functions rely on ordering and limited state impact instead.
 
 ## 6. Invariants to Verify
 
-- Every outfit held by this contract has a corresponding `_wearerOf[hook][outfitId]` pointing to a valid banny body.
-- Every background held by this contract has a corresponding `_userOf[hook][backgroundId]` pointing to a valid banny body.
-- `outfitLockedUntil[hook][bannyBodyId]` is monotonically non-decreasing per banny body (lock can only be extended, never shortened).
-- After `decorateBannyWith`, all previously equipped outfits not in the new set are either transferred back to `_msgSender()` or retained in the attached list if the transfer failed.
-- `_attachedOutfitIdsOf[hook][bannyBodyId]` contains the outfitIds passed to the most recent `decorateBannyWith` call, plus any retained outfits whose return transfer failed. Category exclusivity is enforced on the merged set (retained + new outfits), not just the new outfit set alone. Additionally, duplicate categories in the merged set are rejected with `Banny721TokenUriResolver_DuplicateCategory()` to prevent retained outfits from silently duplicating a category supplied in the new set.
-- SVG content integrity: `keccak256(_svgContentOf[upc]) == svgHashOf[upc]` for all populated entries.
-- NFT custody balance: the number of outfit NFTs held by this contract (`IERC721(hook).balanceOf(address(this))`) equals the total number of outfits currently equipped across all banny bodies for that hook. Violations indicate phantom outfits (equipped in state but NFT lost via try-catch silent failure) or orphaned NFTs (held by contract but not tracked in `_wearerOf`).
+- Every outfit held by the contract has a corresponding wearer mapping to a valid body.
+- Every background held by the contract has a corresponding user mapping to a valid body.
+- `outfitLockedUntil` is monotonically non-decreasing per body.
+- After `decorateBannyWith`, old outfits not in the new set are either returned or explicitly retained because transfer-out failed.
+- Category exclusivity holds on the merged set of retained and newly supplied outfits.
+- SVG content integrity holds for all populated entries.
+- The number of held outfit NFTs should match the number of outfits still tracked as equipped for that hook.
 
 ## 7. Accepted Behaviors
 
-### 7.1 Failed transfers retain attachment records (anti-stranding)
-
-`_tryTransferFrom` catches all transfer failures and returns `false`. When returning a previously equipped item fails, the resolver preserves the attachment record rather than clearing state:
-
-- **Backgrounds**: If returning the old background fails, the entire background change is aborted (`return` in `_decorateBannyWithBackground`). The old background stays attached and the new one is not equipped.
-- **Background removal**: If returning the background fails during removal (backgroundId=0), `_attachedBackgroundIdOf` is not cleared. The background stays attached.
-- **Outfits**: Failed-to-return outfits remain non-zero in the `previousOutfitIds` array. `_storeOutfitsWithRetained` appends them to the new outfit list, preserving their attachment record. After merging, the resolver verifies no two outfits share the same category (reverts with `DuplicateCategory` if a retained outfit conflicts with a newly supplied one).
-
-This prevents NFT stranding — assets held by the resolver stay tracked and recoverable. Once the transfer issue is resolved (e.g., the owner contract implements `IERC721Receiver`), a subsequent `decorateBannyWith` call will successfully return the retained items.
+### 7.1 Failed transfers retain attachment records
 
-For permanently unrecoverable assets (burned NFTs, removed tiers), the retained record creates a phantom entry in the SVG rendering and attached list. This is cosmetically incorrect but not economically exploitable — phantom entries cannot be transferred or sold. The alternative — reverting on any failed transfer — would make `decorateBannyWith` fragile: a single burned outfit would prevent the banny owner from changing ANY outfits.
+If returning a previously equipped item fails, the resolver keeps the attachment record instead of dropping it. This avoids stranding NFTs held by the resolver, but it can leave cosmetic phantom state for permanently unrecoverable assets.
 
-### 7.2 Lock griefing window is bounded at 7 days
+### 7.2 Lock griefing is bounded at 7 days
 
-`lockOutfitChangesFor` extends the lock to `block.timestamp + 7 days`. A seller who locks just before transferring the banny forces the buyer to wait up to 7 days. This is accepted because: (1) marketplaces can check `outfitLockedUntil` before displaying the item, (2) the lock duration is fixed (not owner-configurable), and (3) the lock prevents a more severe attack where a buyer immediately strips valuable outfits — the lock gives the previous owner time to arrange the sale intentionally.
+`lockOutfitChangesFor` can force a buyer to wait, but the window is fixed and cannot be extended arbitrarily beyond the current maximum.
 
-### 7.3 On-chain SVG rendering gas is well within limits
+### 7.3 Onchain SVG rendering gas is acceptable
 
-`tokenUriOf` constructs full SVGs on-chain with string concatenation. Measured gas ceiling: ~609K gas for the worst case (9 non-conflicting outfits + background with on-chain SVG content), well within typical RPC node limits (30M+). Regression test: `test_tokenUri_gasSnapshot_9outfits` in `test/TestQALastMile.t.sol`.
+Full `tokenUriOf` rendering is expensive but still within practical RPC limits for the supported outfit counts.
 
 ### 7.4 Outfits burn alongside the body
 
-When a banny body NFT is burned (e.g. via cash-out), any equipped outfits and backgrounds held by the resolver are permanently unrecoverable. The resolver has no recovery function and this is intentional — outfits are part of the body's identity and share its fate. Users who want to preserve outfits must unequip them before burning the body.
+If a body NFT is burned while outfits are equipped, those outfits are intentionally unrecoverable. Users who want to keep them must unequip first.
 
-### 7.5 Reentrancy in non-guarded functions is harmless
+### 7.5 Reentrancy in non-guarded functions is treated as harmless under the current model
 
-`lockOutfitChangesFor` and all view functions (`tokenUriOf`, `svgOf`) are not protected by `nonReentrant`. A malicious hook's `STORE().tierOfTokenId()` could re-enter `lockOutfitChangesFor` during a `tokenUriOf` call, but this is harmless -- `lockOutfitChangesFor` only extends the lock timestamp (monotonically non-decreasing) and has no state that could be corrupted by reentrancy. The view functions themselves are read-only at the contract level (no storage writes), so reentrancy through them cannot extract value.
+`lockOutfitChangesFor` only extends a timestamp, and view functions do not write storage. That keeps the remaining reentrancy surface narrow.

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## Use This File For
 
 - Use this file when the task involves Banny outfit attachment, layered SVG rendering, token URI composition, or asset custody and lock behavior.
-- Start here, then open the resolver, scripts, or tests that match the exact rendering or attachment path in question.
+- Start here, then decide whether the issue is custody state, lock timing, stored SVG content, or final token-URI composition.
 
 ## Read This Next
 
@@ -11,9 +11,10 @@
 |---|---|
 | Repo overview and user-facing behavior | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | Resolver implementation | [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) |
+| Runtime and content-management invariants | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
 | Deployment or scripted drops | [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/Drop1.s.sol`](./script/Drop1.s.sol), [`script/Add.Denver.s.sol`](./script/Add.Denver.s.sol) |
-| Decoration lifecycle and regressions | [`test/DecorateFlow.t.sol`](./test/DecorateFlow.t.sol), [`test/OutfitTransferLifecycle.t.sol`](./test/OutfitTransferLifecycle.t.sol), [`test/regression/`](./test/regression/) |
-| Adversarial or QA coverage | [`test/BannyAttacks.t.sol`](./test/BannyAttacks.t.sol), [`test/TestQALastMile.t.sol`](./test/TestQALastMile.t.sol), [`test/audit/`](./test/audit/) |
+| Decoration lifecycle and custody invariants | [`test/DecorateFlow.t.sol`](./test/DecorateFlow.t.sol), [`test/OutfitTransferLifecycle.t.sol`](./test/OutfitTransferLifecycle.t.sol) |
+| Adversarial, fork, or final QA coverage | [`test/BannyAttacks.t.sol`](./test/BannyAttacks.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol), [`test/TestQALastMile.t.sol`](./test/TestQALastMile.t.sol) |
 
 ## Repo Map
 
@@ -25,16 +26,17 @@
 
 ## Purpose
 
-Application-layer token URI resolver for Juicebox 721 collections that lets Banny body NFTs equip outfit and background NFTs, custody them while equipped, and render fully on-chain layered SVG metadata.
+App-layer token URI resolver for Juicebox 721 collections. It lets Banny body NFTs equip outfit and background NFTs, holds them while equipped, and renders fully onchain layered SVG metadata.
 
 ## Reference Files
 
-- Open [`references/runtime.md`](./references/runtime.md) when you need attachment and custody behavior, rendering order, or the main invariants that protect equipped assets.
-- Open [`references/operations.md`](./references/operations.md) when you need upload and metadata-management behavior, deployment breadcrumbs, or the common stale-data traps around SVG content and scripts.
+- Open [`references/runtime.md`](./references/runtime.md) for attachment and custody behavior, rendering order, and the main invariants that protect equipped assets.
+- Open [`references/operations.md`](./references/operations.md) for upload and metadata-management behavior, deployment breadcrumbs, and common stale-data traps around SVG content.
 
 ## Working Rules
 
-- Start in [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) for both rendering and attachment behavior. This repo is mostly one contract with several tightly coupled responsibilities.
+- Start in [`src/Banny721TokenUriResolver.sol`](./src/Banny721TokenUriResolver.sol) for both rendering and attachment behavior.
 - Treat custody, stale attachment cleanup, and lock timing as high-risk. Rendering bugs are visible, but custody bugs are worse.
+- Equipped outfits and backgrounds travel with the body NFT. Treat that inheritance as intentional before calling it a bug.
 - When a task mentions minting, pricing, or terminal accounting, verify that the problem is not actually in the upstream 721 hook repo.
 - If you touch SVG or metadata behavior, check whether the issue is in stored content, rendering composition, or the hook-to-resolver integration point before patching.

package/USER_JOURNEYS.md

@@ -1,80 +1,190 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
 
-- Banny collection operators publishing body, outfit, and background tiers
-- collectors minting avatars and equipping accessories
-- teams managing on-chain art payloads and metadata composition
+This repo is the Banny-specific composition and metadata layer on top of a Juicebox 721 collection. It owns attachment custody, compatibility rules, outfit locks, and rendered token metadata. It does not own tier pricing, treasury accounting, or mint eligibility outside resolver-specific checks.
+
+## Primary Actors
+
+- collection operators publishing bodies, outfits, backgrounds, and metadata
+- collectors equipping and unequipping avatar pieces
+- auditors reviewing custody, lock, and rendering behavior
+
+## Key Surfaces
+
+- `Banny721TokenUriResolver`: custody, compatibility, locks, and rendered SVG metadata
+- `decorateBannyWith(...)`: equips outfits and a background to a body and returns old items when possible
+- `lockOutfitChangesFor(...)`: freezes appearance changes for the fixed lock window
+- `setSvgHashesOf(...)` / `setSvgContentsOf(...)`: publish or repair art payloads
+- `setMetadata(...)` / `setProductNames(...)`: update collection metadata and UPC naming
 
 ## Journey 1: Mint A Body, Outfit, And Background Set
 
-**Starting state:** the Banny collection is live through the 721 hook and the relevant tiers exist.
+**Actor:** collector.
+
+**Intent:** acquire the pieces needed to build a composed Banny.
+
+**Preconditions**
 
-**Success:** the collector owns the pieces needed to build a composed avatar.
+- the Banny collection is live through the 721 hook
+- the required body, outfit, and background tiers exist
 
-**Flow**
-1. Mint the body, outfit, and background NFTs through the underlying Juicebox 721 project.
-2. Keep pricing, issuance, and treasury assumptions anchored in the 721 hook rather than this resolver.
-3. Treat this repo as the composition layer that activates once the user owns the right pieces.
+**Main Flow**
+
+1. Mint the body, outfit, and background NFTs through the underlying 721 project.
+2. Keep mint pricing and issuance assumptions anchored in the 721 hook, not this repo.
+3. Move to this resolver only once the user owns compatible pieces.
+
+**Failure Modes**
+
+- the wrong tiers are minted or the pieces are incompatible
+- teams misread this repo as the minting or accounting surface
+
+**Postconditions**
+
+- the user holds the components needed for later composition
 
 ## Journey 2: Dress A Banny And Put Accessories Into Resolver Custody
 
-**Starting state:** the collector owns a body plus compatible accessories.
+**Actor:** body owner.
+
+**Intent:** equip a body with a background and outfits so the resolver serves the composed avatar.
 
-**Success:** the chosen outfit and background are attached to the body and the resolver renders the combined look.
+**Preconditions**
+
+- the caller controls the body and the accessories being equipped
+- no active outfit lock blocks the change
+- the selected pieces are compatible by category and collection rules
+
+**Main Flow**
 
-**Flow**
 1. Call `decorateBannyWith(...)` for the target body.
-2. `Banny721TokenUriResolver` checks compatibility rules and takes custody of the attached accessory NFTs while they are equipped.
-3. The body's token URI now resolves to a layered SVG and metadata payload reflecting the active composition.
+2. The resolver checks compatibility and diffs old versus new attachments.
+3. Equipped accessories move into resolver custody while attached.
+4. The token URI for the body now reflects the combined SVG and metadata.
+
+**Failure Modes**
+
+- duplicate outfit categories or incompatible combinations are provided
+- transfer-back of previously attached items fails, leaving retained custody state for later recovery
+- reviewers forget that the resolver, not the wallet, holds equipped accessories while active
+
+**Postconditions**
+
+- the body renders with the new composition
+- attached accessories stay in resolver custody until replaced or cleared
 
 ## Journey 3: Lock A Banny's Appearance For A Period
 
-**Starting state:** the collector likes the current look and does not want it changed immediately.
+**Actor:** body owner.
+
+**Intent:** freeze the current appearance for the fixed lock window.
+
+**Preconditions**
+
+- the body already has a state worth freezing
+- the caller understands the lock is fixed-duration
+
+**Main Flow**
+
+1. Call `lockOutfitChangesFor(...)`.
+2. The resolver extends the lock for that body.
+3. Future decoration or removal attempts must wait until the lock expires.
+
+**Failure Modes**
 
-**Success:** the avatar's appearance is frozen for the lock window and later equipment changes must wait.
+- a seller locks just before transfer and the buyer cannot restyle immediately
+- integrations fail to show lock state before listing or sale
 
-**Flow**
-1. Call `lockOutfitChangesFor(...)` on the resolver.
-2. The resolver records the lock period for that body.
-3. Future decorate or removal actions respect the lock until it expires.
+**Postconditions**
 
-## Journey 4: Publish Or Repair On-Chain Art Assets
+- appearance changes are blocked until the lock expires
 
-**Starting state:** the collection's visual payloads are referenced by content hashes but the actual SVG payloads still need to be made available.
+## Journey 4: Publish Or Repair Onchain Art Assets
 
-**Success:** token URIs render complete art instead of placeholders or missing layers.
+**Actor:** collection operator or art publisher.
 
-**Flow**
-1. Register the content hashes for bodies, outfits, or backgrounds with `setSvgHashesOf(...)`.
-2. Upload or repair the corresponding SVG payloads with `setSvgContentsOf(...)`.
-3. Re-resolve token URIs to confirm the on-chain composition now renders correctly.
+**Intent:** make token URIs render complete onchain art.
 
-**Failure cases that matter:** publishing content that does not match the registered hash, forgetting to set product names for new pieces, and assuming the 721 hook owns the art payload when this repo owns the rendered output.
+**Preconditions**
+
+- the relevant UPCs and content hashes are known
+- the operator understands that the hash is the commitment and SVG content must match it exactly
+
+**Main Flow**
+
+1. Register hashes with `setSvgHashesOf(...)`.
+2. Upload matching payloads with `setSvgContentsOf(...)`.
+3. Re-check token URI output after publication or repair.
+
+**Failure Modes**
+
+- uploaded SVG does not match the committed hash
+- product names are missing or stale
+- teams assume the 721 hook owns rendered output when this repo does
+
+**Postconditions**
+
+- token URIs can render the intended onchain art payloads
 
 ## Journey 5: Update Collection Metadata And Product Catalog Entries
 
-**Starting state:** the collection exists, but its descriptive metadata or UPC-to-name catalog needs to change.
+**Actor:** collection operator.
+
+**Intent:** change collection-level metadata and human-readable product labels.
+
+**Preconditions**
 
-**Success:** token URIs and collection-level presentation reflect the intended description, external URL, base URI, and product naming.
+- the operator has authority over the resolver metadata surface
+
+**Main Flow**
 
-**Flow**
 1. Update collection metadata with `setMetadata(...)`.
-2. Set or repair product names for the UPCs the renderer should expose with `setProductNames(...)`.
-3. Re-check token URI output so the rendered Banny and its catalog labels agree.
+2. Set or repair UPC names with `setProductNames(...)`.
+3. Re-check a representative token URI so labels and art agree.
+
+**Failure Modes**
+
+- metadata and SVG state drift apart
+- operators update catalog labels without checking already-minted assets
+
+**Postconditions**
+
+- collection-level metadata and UPC names line up with the published art set
 
 ## Journey 6: Unequip And Recover Custodied Accessories
 
-**Starting state:** a body has attached pieces held by the resolver and the owner wants to rearrange or transfer them.
+**Actor:** body owner.
+
+**Intent:** recover attached accessories from resolver custody.
+
+**Preconditions**
+
+- the current lock window, if any, has expired
+- the owner understands that old pieces may only be returned as part of a later decoration update
+
+**Main Flow**
+
+1. Replace or clear the equipped items through `decorateBannyWith(...)`.
+2. The resolver attempts to return no-longer-equipped accessories.
+3. Once returned, those NFTs can be transferred or reused independently.
+
+**Failure Modes**
+
+- previously equipped pieces remain retained because transfer-back failed
+- burned or otherwise unrecoverable pieces leave cosmetic phantom state until corrected
+
+**Postconditions**
+
+- no-longer-equipped accessories are either returned or remain explicitly retained pending recovery
 
-**Success:** the accessories leave resolver custody and can be reused or transferred independently.
+## Trust Boundaries
 
-**Flow**
-1. Remove or replace the equipped items once no lock blocks the change.
-2. The resolver releases custody of the old accessory NFTs.
-3. The owner can now transfer, burn, or re-equip those pieces elsewhere.
+- this repo is trusted for custody of equipped accessories while attached
+- the underlying 721 hook remains the source of mint pricing, tier issuance, and treasury behavior
+- metadata correctness depends on operators publishing the intended SVG hashes and contents
 
 ## Hand-Offs
 
 - Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md) for mint pricing, tier issuance, reserves, and treasury behavior.
-- Use this repo only once the question is about custody, compatibility, outfit locks, or SVG composition.
+- Use this repo once the question is about custody, compatibility, outfit locks, or SVG composition.

package/foundry.toml

@@ -14,6 +14,8 @@ runs = 1024
 depth = 100
 fail_on_revert = false
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,37 +1,37 @@
 {
-    "name": "@bannynet/core-v6",
-  "version": "0.0.22",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/mejango/banny-retail-v6"
-    },
-    "engines": {
-        "node": ">=20.0.0"
-    },
-    "scripts": {
-        "test": "forge test",
-        "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
-        "generate:migration": "node ./script/outfit_drop/generate-migration.js",
-        "deploy:mainnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
-        "deploy:testnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
-        "deploy:testnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks testnets",
-        "deploy:mainnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks mainnets",
-        "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'banny-core-v6'"
-    },
-    "dependencies": {
-        "@bananapus/721-hook-v6": "^0.0.35",
-        "@bananapus/core-v6": "^0.0.34",
-        "@bananapus/permission-ids-v6": "^0.0.17",
-        "@bananapus/router-terminal-v6": "^0.0.26",
-        "@bananapus/suckers-v6": "^0.0.25",
-        "@croptop/core-v6": "^0.0.33",
-        "@openzeppelin/contracts": "^5.6.1",
-        "@rev-net/core-v6": "^0.0.32",
-        "keccak": "^3.0.4"
-    },
-    "devDependencies": {
-        "@bananapus/address-registry-v6": "^0.0.17",
-        "@sphinx-labs/plugins": "^0.33.3"
-    }
+  "name": "@bannynet/core-v6",
+  "version": "0.0.24",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mejango/banny-retail-v6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "forge test",
+    "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
+    "generate:migration": "node ./script/outfit_drop/generate-migration.js",
+    "deploy:mainnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
+    "deploy:testnets": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
+    "deploy:testnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks testnets",
+    "deploy:mainnets:drop:1": "source ./.env && npx sphinx propose ./script/Drop1.s.sol --networks mainnets",
+    "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'banny-core-v6'"
+  },
+  "dependencies": {
+    "@bananapus/721-hook-v6": "^0.0.38",
+    "@bananapus/core-v6": "^0.0.36",
+    "@bananapus/permission-ids-v6": "^0.0.19",
+    "@bananapus/router-terminal-v6": "^0.0.30",
+    "@bananapus/suckers-v6": "^0.0.28",
+    "@croptop/core-v6": "^0.0.36",
+    "@openzeppelin/contracts": "^5.6.1",
+    "@rev-net/core-v6": "^0.0.35",
+    "keccak": "^3.0.4"
+  },
+  "devDependencies": {
+    "@bananapus/address-registry-v6": "^0.0.17",
+    "@sphinx-labs/plugins": "^0.33.3"
+  }
 }

package/references/operations.md

@@ -21,5 +21,5 @@
 
 ## Useful Proof Points
 
-- [`test/audit/`](../test/audit/) for security-sensitive assumptions.
-- [`script/helpers/`](../script/helpers/) when a deployment issue is really a script/config problem.
+- [`test/BannyAttacks.t.sol`](../test/BannyAttacks.t.sol) and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) for security-sensitive assumptions.
+- [`script/Drop1.s.sol`](../script/Drop1.s.sol) and [`script/Add.Denver.s.sol`](../script/Add.Denver.s.sol) when a deployment issue is really a script/config problem.

package/references/runtime.md

@@ -24,4 +24,4 @@
 - [`test/DecorateFlow.t.sol`](../test/DecorateFlow.t.sol) for the main equip/unequip lifecycle.
 - [`test/OutfitTransferLifecycle.t.sol`](../test/OutfitTransferLifecycle.t.sol) for custody and return behavior.
 - [`test/BannyAttacks.t.sol`](../test/BannyAttacks.t.sol) for adversarial flows.
-- [`test/TestQALastMile.t.sol`](../test/TestQALastMile.t.sol) and [`test/regression/`](../test/regression/) for pinned edge cases.
+- [`test/Fork.t.sol`](../test/Fork.t.sol), [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol), and [`test/TestQALastMile.t.sol`](../test/TestQALastMile.t.sol) for integration and pinned edge cases.

package/src/Banny721TokenUriResolver.sol

@@ -109,15 +109,10 @@ contract Banny721TokenUriResolver is
     /// @custom:param upc The universal product code that the SVG hash represent.
     mapping(uint256 upc => bytes32) public override svgHashOf;
 
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_ALIEN_EYES;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_MOUTH;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_NECKLACE;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override DEFAULT_STANDARD_EYES;
-    // forge-lint: disable-next-line(mixed-case-variable)
     string public override BANNY_BODY;
 
     //*********************************************************************//