@croptop/core-v6 0.0.33 → 0.0.34

package/ADMINISTRATION.md

@@ -1,174 +1,94 @@
 # Administration
 
-Admin privileges and their scope in croptop-core-v6.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| Scope | Croptop project deployment, posting-criteria management, publisher permissions, and project burn-lock ownership flows. |
-| Operators | Project owners, hook owners and delegates, the `CTDeployer`, `CTPublisher`, optional `CTProjectOwner`, and the configured sucker registry. |
-| Highest-risk actions | Sending a project NFT to `CTProjectOwner`, misconfiguring posting criteria, or relying on the write-once `dataHookOf` mapping without validating the hook first. |
-| Recovery posture | Ownership burn-lock mistakes are not recoverable in place. Operational fixes usually mean updating criteria if the project is still controlled, or deploying a new project/hook if it is not. |
-
-## Routine Operations
-
-- Configure posting criteria before broad publisher access, because `mintFrom()` enforces those rules for every post.
-- Use `claimCollectionOwnershipOf()` when the project should own its hook directly instead of leaving hook control with the deployer path.
-- Treat sucker deployment as a project extension that still depends on the Croptop data-hook proxy remaining correct for the project.
-- Avoid transferring project NFTs to `CTProjectOwner` unless the intention is to burn human control permanently.
+| --- | --- |
+| Scope | Croptop deployment flow, publish-policy administration, and irreversible project owner sink behavior |
+| Control posture | Mixed deployer-managed and project-local control |
+| Highest-risk actions | Burn-locking a project into `CTProjectOwner`, misconfiguring posting criteria, and deploying suckers with the wrong authority assumptions |
+| Recovery posture | Posting policy can often be changed, but burn-lock and some deployer wiring choices require replacement flows |
 
-## One-Way Or High-Risk Actions
+## Purpose
 
-- `CTProjectOwner` permanently locks any JBProjects NFT it receives.
-- `dataHookOf[projectId]` is set during deployment and has no later setter.
-- Constructor-time wildcard permissions granted by `CTDeployer` are structural and cannot be revoked from within the deployer.
+`croptop-core-v6` has two distinct control planes: project-local publishing control and deployer-level structural wiring. The high-risk surfaces are posting criteria, hook ownership, publisher permissions, and the irreversible `CTProjectOwner` burn-lock path.
 
-## Recovery Notes
+## Control Model
 
-- If posting rules are wrong but the project still controls the hook, fix them through the hook-owner surface.
-- If ownership was accidentally burned into `CTProjectOwner` or the wrong hook path was deployed, recovery generally means abandoning that control path and redeploying the project or hook composition.
+- `CTPublisher` enforces publish policy but does not own the project.
+- `CTDeployer` is both a deployment helper and a live ruleset data-hook wrapper.
+- The initial project owner receives direct hook-management permissions from `CTDeployer` at deployment time.
+- Project owners or delegates administer publishing through the hook owner and `JBPermissions`.
+- `CTProjectOwner` is an irreversible ownership sink for projects that want Croptop-mediated control.
+- `SUCKER_REGISTRY` and `PUBLISHER` receive structural permissions from `CTDeployer`.
 
 ## Roles
 
-### 1. Project Owner
-
-**How assigned:** Receives the JBProjects ERC-721 NFT for the project. Initially set by the `owner` parameter in `CTDeployer.deployProjectFor()`. Can be transferred via standard ERC-721 transfer.
-
-**Scope:** Per-project. Controls posting rules and hook ownership for a single project.
-
-### 2. Hook Owner
-
-**How assigned:** Determined by `JBOwnable(hook).owner()`. For CTDeployer-launched projects, the deployer initially owns the hook (via `DEPLOYER.deployHookFor()`). The project owner can later claim hook ownership via `claimCollectionOwnershipOf()`.
-
-**Scope:** Per-hook. The hook owner (or anyone with `ADJUST_721_TIERS` permission for that hook's project) can configure posting criteria.
-
-### 3. CTDeployer (Contract)
-
-**How assigned:** Immutable singleton deployed at construction. Acts as the `IJBRulesetDataHook` for all CTDeployer-launched projects (set in `deployProjectFor()`).
-
-**Scope:** All Croptop-deployed projects. Proxies pay/cashout data hook calls, grants fee-free cashouts to suckers, and holds broad permissions on behalf of launched projects.
-
-### 4. CTPublisher (Contract)
-
-**How assigned:** Immutable singleton deployed at construction. Receives `ADJUST_721_TIERS` permission from CTDeployer at construction.
-
-**Scope:** All hooks for which it has `ADJUST_721_TIERS` permission. Creates NFT tiers and mints first copies.
-
-### 5. CTProjectOwner (Contract)
-
-**How assigned:** Optional burn-lock proxy. Receives project ownership when a project NFT is `safeTransferFrom`'d to it.
-
-**Scope:** Per-project. Grants `CTPublisher` permanent `ADJUST_721_TIERS` permission for the received project. Once the project is transferred here, human ownership is effectively burned.
-
-- **Important:** `onERC721Received()` accepts project NFTs from any transfer, not only mints. If a project owner accidentally transfers their project NFT to `CTProjectOwner`, it is permanently locked -- there is no recovery function. The only check is that `msg.sender` is the `PROJECTS` contract (ensuring it is a JBProjects NFT, not an arbitrary ERC-721).
-
-### 6. Sucker Registry
-
-**How assigned:** Immutable dependency set at CTDeployer construction. Receives `MAP_SUCKER_TOKEN` permission at construction.
-
-**Scope:** All projects deployed via CTDeployer. Can map tokens for cross-chain bridging. Determines which addresses get fee-free cashouts.
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Project owner | `JBProjects.ownerOf(projectId)` | Per project | May grant delegates through `JBPermissions` |
+| Hook owner | `JBOwnable(hook).owner()` | Per hook | Often resolves to the project owner after claim |
+| `CTDeployer` | Immutable singleton | Global | Launch helper and runtime wrapper |
+| `CTPublisher` | Immutable singleton | Global runtime surface | Needs `ADJUST_721_TIERS` authority on relevant hooks |
+| `CTProjectOwner` | Receives project NFT transfer | Per project | Burn-lock path; no return function |
+| `SUCKER_REGISTRY` | Immutable dependency | Global | Holds wildcard `MAP_SUCKER_TOKEN` from the deployer |
 
-### 7. Publishers (Poster Addresses)
+## Privileged Surfaces
 
-**How assigned:** Either any address (when allowlist is empty) or explicitly added to a per-hook per-category allowlist via `configurePostingCriteriaFor()`.
+| Contract | Function | Who Can Call | Effect |
+| --- | --- | --- | --- |
+| `CTDeployer` | `deployProjectFor(...)` | Anyone | Launches a Croptop-shaped project and configures initial permissions |
+| `CTDeployer` | `claimCollectionOwnershipOf(...)` | Current project owner | Transfers hook ownership from the deployer path to the project |
+| `CTDeployer` | `deploySuckersFor(...)` | Project owner or `DEPLOY_SUCKERS` delegate | Extends a project with suckers |
+| `CTPublisher` | `configurePostingCriteriaFor(...)` | Hook owner or `ADJUST_721_TIERS` delegate | Changes posting policy for a hook and category |
+| `CTPublisher` | `mintFrom(...)` | Anyone subject to policy | Publishes posts, mints first copies, and routes the Croptop fee |
+| `CTProjectOwner` | `onERC721Received(...)` | Any project NFT transfer into it | Locks the project into the Croptop owner helper and grants `CTPublisher` tier-adjust authority |
 
-**Scope:** Per-hook, per-category. Can create NFT tiers (posts) and mint first copies, subject to posting criteria.
+The important nuance is:
 
-## Privileged Functions
+- after `deployProjectFor(...)`, the initial project owner can directly manage tiers, metadata, minting, and discount percent through permissions granted from `CTDeployer`
+- this means the owner can bypass the publisher path until ownership is claimed away from `CTDeployer`
 
-### CTDeployer
+## Immutable And One-Way
 
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|-------------|
-| `deployProjectFor()` | Anyone | None | Global | Deploys a new Juicebox project with 721 hook, configures posting rules, optionally deploys suckers, transfers ownership to `owner`. No access restriction -- anyone can deploy a project. |
-| `claimCollectionOwnershipOf()` | Project owner | None (direct `ownerOf` check) | Per-project | Transfers hook ownership to the project via `JBOwnable.transferOwnershipToProject()`. Caller must be `PROJECTS.ownerOf(projectId)`. |
-| `deploySuckersFor()` | Project owner or delegate | `JBPermissionIds.DEPLOY_SUCKERS` | Per-project | Deploys new cross-chain suckers for an existing project. Uses `_requirePermissionFrom()` against the project owner. |
+- `CTDeployer`'s wildcard permission grants to `SUCKER_REGISTRY` and `CTPublisher` are structural.
+- `dataHookOf[projectId]` is write-once through deployment flow.
+- Sending a project NFT into `CTProjectOwner` is effectively irreversible.
+- `FEE_PROJECT_ID` in `CTPublisher` is constructor-immutable.
 
-### CTPublisher
+## Operational Notes
 
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|-------------|
-| `configurePostingCriteriaFor()` | Hook owner or delegate | `JBPermissionIds.ADJUST_721_TIERS` | Per-hook, per-category | Sets posting rules: minimum price, min/max supply, max split percent, address allowlist. Uses `_requirePermissionFrom()` against `JBOwnable(hook).owner()`. |
-| `mintFrom()` | Anyone (subject to allowlist) | None (enforced by allowlist in `_setupPosts`) | Per-hook | Publishes posts as 721 tiers, mints first copies, routes 5% fee to `FEE_PROJECT_ID`. Validates all posts against configured criteria. |
+- Validate posting criteria before broad publisher access; the publisher enforces those rules on every post.
+- Decide intentionally whether the project should keep the initial direct-management path or move to project-owned hook control with `claimCollectionOwnershipOf(...)`.
+- Use `claimCollectionOwnershipOf(...)` when the project should own the hook directly instead of relying on the deployer as the ownership bridge.
+- Treat the burn-lock path as governance finality, not convenience.
+- Review Croptop deployer changes as both launch-time and runtime changes.
 
-### CTProjectOwner
+## Machine Notes
 
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|-------------|
-| `onERC721Received()` | Anyone who transfers a JBProjects NFT | None | Per-project | On receiving a project NFT from `PROJECTS`, grants `CTPublisher` the `ADJUST_721_TIERS` permission for that project. The contract does not restrict this to mint receipts; any transferred JBProjects NFT will be accepted and effectively burn human ownership. |
+- Do not treat `CTDeployer` as a passive script helper; it is also part of the live runtime path.
+- Treat `src/CTPublisher.sol`, `src/CTDeployer.sol`, and `src/CTProjectOwner.sol` as the minimum source set for control-plane crawling.
+- If a project NFT has already been sent to `CTProjectOwner`, stop assuming the original owner can recover it.
 
-### Permissions Granted at CTDeployer Construction
+## Recovery
 
-These permissions are set in the CTDeployer constructor and apply to all projects it will ever deploy (wildcard `projectId: 0`):
-
-| Permission | Granted To | Purpose |
-|-----------|-----------|---------|
-| `MAP_SUCKER_TOKEN` | `SUCKER_REGISTRY` | Allows the sucker registry to map tokens for cross-chain bridging on any project owned by CTDeployer. |
-| `ADJUST_721_TIERS` | `PUBLISHER` (CTPublisher) | Allows CTPublisher to add tiers to any hook on any project owned by CTDeployer. |
-
-### Permissions Granted During `deployProjectFor()`
-
-These permissions are set per-project during deployment:
-
-| Permission | Granted To | Purpose |
-|-----------|-----------|---------|
-| `ADJUST_721_TIERS` | `owner` | Allows the project owner to adjust 721 tiers. |
-| `SET_721_METADATA` | `owner` | Allows the project owner to update 721 metadata. |
-| `MINT_721` | `owner` | Allows the project owner to mint 721 tokens directly. |
-| `SET_721_DISCOUNT_PERCENT` | `owner` | Allows the project owner to set tier discount percentages. |
-
-## Data Hook Proxy
-
-When deploying a project, `CTDeployer` sets itself as the project's `dataHook` in the ruleset metadata. It then proxies data hook calls to the project's actual 721 tiers hook:
-
-- **`beforePayRecordedWith`**: Calls `IJBRulesetDataHook(hook).beforePayRecordedWith(context)` where `hook = dataHookOf[context.projectId]`, then returns the 721 hook's specifications.
-- **`beforeCashOutRecordedWith`**: Checks if the caller is a registered sucker via `SUCKER_REGISTRY.isSuckerOf()`. If so, returns 0% cash-out tax (fee-free bridging). Otherwise, delegates to the 721 hook.
-- **`hasMintPermissionFor`**: Returns `true` for registered suckers, `false` for all other addresses. Does not delegate to the 721 hook.
-
-This proxy pattern exists so that CTDeployer can intercept cash-out calls to grant fee-free bridging to suckers while still supporting the 721 hook's NFT minting logic.
-
-The `dataHookOf[projectId]` mapping is write-once (set during `deployProjectFor`, no setter function). The proxy target cannot be changed after deployment.
-
-## Immutable Configuration
-
-These values are set at deploy time and cannot be changed after deployment:
-
-| Value | Contract | Set At | Description |
-|-------|----------|--------|-------------|
-| `FEE_DIVISOR` | CTPublisher | Compile time (constant = 20) | Fee percentage: 5% (1/20). Hardcoded, not configurable. |
-| `FEE_PROJECT_ID` | CTPublisher | Constructor (immutable) | Project ID that receives all fees. Cannot be changed. |
-| `DIRECTORY` | CTPublisher | Constructor (immutable) | JBDirectory for project/terminal lookups. |
-| `PROJECTS` | CTDeployer | Constructor (immutable) | JBProjects NFT contract. |
-| `DEPLOYER` | CTDeployer | Constructor (immutable) | JB721TiersHookDeployer for hook creation. |
-| `PUBLISHER` | CTDeployer | Constructor (immutable) | CTPublisher contract reference. |
-| `SUCKER_REGISTRY` | CTDeployer | Constructor (immutable) | Sucker registry for cross-chain bridging. |
-| `PERMISSIONS` | CTDeployer, CTProjectOwner | Constructor (immutable) | JBPermissions contract for access control. |
-| `trustedForwarder` | CTDeployer, CTPublisher | Constructor (immutable via ERC2771Context) | Meta-transaction trusted forwarder address. |
-| `dataHookOf[projectId]` | CTDeployer | `deployProjectFor()` | Once set during deployment, the data hook for a project can never be changed. Write-once storage. |
-| Project weight | CTDeployer | `deployProjectFor()` | Hardcoded at `1_000_000 * 10^18` with ETH base currency and max cashout tax rate. |
-| Hook deploy salt | CTDeployer | `deployProjectFor()` | `keccak256(abi.encode(salt, msg.sender))` -- deterministic but caller-specific. |
+- If posting policy is wrong but the project still controls the hook, fix it through `configurePostingCriteriaFor(...)`.
+- If the wrong hook path or burn-lock path was chosen, recovery usually means a new project or new hook arrangement.
+- `CTProjectOwner` is not a reversible safety valve.
 
 ## Admin Boundaries
 
-What admins CANNOT do:
-
-1. **Project owners cannot change the fee rate.** `FEE_DIVISOR = 20` (5%) is a compile-time constant. No function exists to modify it.
-
-2. **Project owners cannot change the fee recipient.** `FEE_PROJECT_ID` is immutable. Fees always route to the same project.
-
-3. **Project owners cannot change the data hook.** `dataHookOf[projectId]` is write-once (set during `deployProjectFor`, no setter function). The data hook proxy pattern is permanent.
-
-4. **Project owners cannot disable Croptop posting entirely for a category.** `configurePostingCriteriaFor()` requires `minimumTotalSupply > 0`. The workaround is to set an astronomically high `minimumPrice` with `minimumTotalSupply = maximumTotalSupply = 1`. See finding NM-006.
-
-5. **Project owners cannot bypass posting criteria through `CTPublisher`, but they may still bypass the publisher surface entirely.** `mintFrom()` enforces all configured rules. Separately, the initial owner/operator can hold direct hook-management permissions from `CTDeployer`, which lets them adjust tiers or mint without going through `CTPublisher` until ownership is claimed away or permissions are narrowed.
-
-6. **CTPublisher cannot mint without paying.** `mintFrom()` requires `msg.value >= totalPrice + fee`. There is no free-mint path through CTPublisher.
-
-7. **CTProjectOwner cannot return project ownership.** Once a project NFT is transferred to CTProjectOwner, there is no function to transfer it back. Ownership is effectively burned.
-
-8. **No admin can modify existing tier prices.** Once a tier is created via `_setupPosts()`, the price is set in the `JB721TiersHookStore`. CTPublisher uses the stored price for fee calculation on subsequent mints (not `post.price`). See H-19 fix.
+- Neither project owners nor Croptop can change the fixed Croptop fee divisor in `CTPublisher`.
+- `CTPublisher` cannot trap fee ETH intentionally; failed fee-terminal payments refund `_msgSender()` or revert.
+- `CTProjectOwner` cannot return project ownership once it receives the NFT.
+- `CTDeployer` cannot later rewrite `dataHookOf[projectId]` through a setter.
+- `CTDeployer` does not stop the initial project owner from using the directly granted hook permissions before ownership is claimed away.
 
-9. **No admin can drain CTPublisher funds.** CTPublisher has no `withdraw()` function and no `receive()` / `fallback()`. The only ETH that enters the contract is during `mintFrom()` and it is fully routed to the project terminal and fee terminal (or refunded to the caller if the fee terminal reverts) within the same transaction. If that refund also fails, the mint reverts rather than trapping ETH in the publisher.
+## Source Map
 
-10. **Sucker registry trust is irrevocable.** The `MAP_SUCKER_TOKEN` permission is granted at CTDeployer construction with `projectId: 0` (wildcard). There is no function to revoke this permission from within CTDeployer.
+- `src/CTPublisher.sol`
+- `src/CTDeployer.sol`
+- `src/CTProjectOwner.sol`
+- `script/Deploy.s.sol`
+- `script/helpers/CroptopDeploymentLib.sol`
+- `test/TestAuditGaps.sol`

package/ARCHITECTURE.md

@@ -2,70 +2,95 @@
 
 ## Purpose
 
-`croptop-core-v6` turns a Juicebox project with a 721 tiers hook into a permissioned publishing surface. Project owners define what kinds of posts are allowed, and third parties can mint new content tiers only if their post matches those rules. A fixed fee is routed to a designated fee project on every publish.
+`croptop-core-v6` turns a Juicebox project with a 721 tiers hook into a permissioned publishing market. Project owners define what posts are valid, third parties publish content by minting or reusing tiers, and Croptop routes a fixed publish fee to the canonical fee project.
 
-## Boundaries
+## System Overview
 
-- `CTPublisher` owns publishing policy and fee routing.
-- `CTDeployer` owns one-shot project creation and optional sucker setup.
-- The underlying 721 tier implementation remains in `nana-721-hook-v6`.
-- The repo does not reimplement terminal accounting; payments still settle through Juicebox terminals.
+`CTPublisher` is the runtime policy and fee-routing surface. `CTDeployer` is the launch-time wrapper that can package a project, its 721 hook configuration, posting rules, and optional omnichain setup in one transaction. `CTProjectOwner` is the irreversible ownership helper for projects that want Croptop-mediated administration instead of a plain owner EOA.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `CTPublisher` | Validates posts, creates or reuses tiers, mints the first copy, and routes publish fees |
-| `CTDeployer` | Launches a Juicebox project plus hook configuration in one transaction and can proxy hook callbacks |
-| `CTProjectOwner` | Burn-lock helper that permanently delegates tier adjustment authority to Croptop |
-| `CTAllowedPost`, `CTPost`, related structs | Encode project-level publishing policy and publish requests |
+- A post can only be published if it satisfies the configured category, pricing, supply, split, and allowlist rules.
+- Publish fees must be computed from the call value, not from ambient contract balance.
+- `CTPublisher` must not trap fee funds. If the fee-project payment fails, the fee is refunded to `_msgSender()`, and if that refund fails the publish reverts.
+- Tier creation and minting must continue to respect `nana-721-hook-v6` invariants.
+- `CTDeployer` intentionally creates a temporary owner-bypass period before collection ownership is claimed away from the deployer.
+- `CTProjectOwner` is a burn-lock primitive, not a flexible admin panel.
 
-## Runtime Model
+## Modules
 
-### Publishing
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `CTPublisher` | Post validation, tier reuse or creation, first-copy minting, fee routing | Main runtime contract |
+| `CTDeployer` | Project launch, hook wiring, optional sucker setup, wrapper behavior | Launch-time and runtime wrapper |
+| `CTProjectOwner` | Irreversible ownership helper | Governance-sensitive |
+| `CTAllowedPost`, `CTPost`, related structs | Publishing policy and request encoding | Shared config surface |
+
+## Trust Boundaries
+
+- Tier storage and minting semantics live in `nana-721-hook-v6`.
+- Terminal accounting and project ownership live in `nana-core-v6`.
+- When omnichain setup is enabled, this repo composes deployer patterns from `nana-suckers-v6` and `nana-omnichain-deployers-v6` instead of reimplementing them.
+
+## Critical Flows
+
+### Publish
 
 ```text
 poster
-  -> mintFrom(hook, posts, ...)
-  -> publisher validates each post against project-defined criteria
-  -> publisher calls the 721 hook to create or reuse tiers
+  -> calls mintFrom(...)
+  -> publisher validates each post against project policy
+  -> publisher creates or reuses 721 tiers
   -> project terminal receives the publish payment
-  -> fee project receives the fixed fee slice, or `_msgSender()` is refunded that fee if the fee terminal rejects it
-  -> first copy of each created tier is minted to the poster
+  -> fee project receives the fixed fee slice, or `_msgSender()` is refunded if that fee payment fails
+  -> first copy of each post tier is minted to the poster
 ```
 
-### Project Launch
+### Launch
 
 ```text
 creator
-  -> CTDeployer launches the project, hook, posting criteria, and optional suckers
-  -> deployer can also stand in as a ruleset data-hook wrapper when needed
+  -> CTDeployer launches the project and 721-hook shape
+  -> configures Croptop posting rules
+  -> optionally wires omnichain sucker deployment
+  -> may remain in the flow as a runtime wrapper when hook composition is enabled
 ```
 
-## Critical Invariants
-
-- A post is valid only if it satisfies the configured category, price, supply, split, and allowlist constraints.
-- Fee routing must be computed from the payment value, not transient contract balance, so forced ETH cannot distort the fee.
-- Fee routing must not strand ETH in `CTPublisher`. If the fee terminal rejects payment, the fee is refunded to `_msgSender()`; if that refund fails, the mint reverts.
-- `CTProjectOwner` only makes sense as a lock, not a flexible admin layer. Once a project is burn-locked, Croptop becomes the only intended tier-adjustment path.
-- Publishing should not bypass the 721 hook's own invariants around tier creation and minting.
+## Accounting Model
 
-## Where Complexity Lives
+This repo does not define treasury accounting. Its critical economic logic is publish-fee routing and the mapping from valid post data to 721 tier creation or reuse.
 
-- Post validation is spread across category rules, split limits, supply bounds, and optional allowlists.
-- `CTDeployer` is subtle because it is both a launch helper and, in some flows, a runtime hook proxy.
-- Fee routing is intentionally liveness-first: it prefers refunding `_msgSender()` over blocking the mint when the fee terminal is down, but still reverts if the refund itself cannot be delivered.
+`CTPublisher` also relies on duplicate-content and pricing checks to stop fee evasion through batch composition or tier reuse. Those checks are part of economic correctness, not just content hygiene.
 
-## Dependencies
+## Security Model
 
-- `nana-721-hook-v6` for tier storage and minting
-- `nana-suckers-v6` and `nana-omnichain-deployers-v6` patterns when omnichain deployment is enabled
-- `nana-core-v6` terminals, permissions, and project ownership
+- Fee routing is liveness-first but still value-sensitive; fallback refunds must stay correct.
+- `CTDeployer` has a larger review surface than a normal deployer because it can also participate at runtime.
+- Croptop's product boundary is partly social: until collection ownership is claimed away from `CTDeployer`, the project owner can interact through the granted permissions rather than only through the publisher surface.
+- Posting policy bugs are product-level authorization bugs, not just metadata bugs.
 
 ## Safe Change Guide
 
-- Keep publishing policy separate from 721 implementation details. If a change is generally useful for all tiered collections, it belongs downstream.
-- When modifying fee logic, reason through terminal payment ordering and failure fallback paths together.
-- Any change to `CTDeployer` should be reviewed as both a deployer and a live hook wrapper, because it participates in runtime flows after launch.
-- Changes to burn-lock semantics should be treated as governance changes, not UI conveniences.
-- Be wary of adding product-specific tier semantics here that really belong in the generic 721 hook.
+- Put generic tier logic in `nana-721-hook-v6`, not here.
+- If fee behavior changes, review payment ordering, fee-project fallback, and refund failure handling together.
+- If deployer ownership or permission grants change, re-check the temporary bypass window and post-claim ownership behavior together.
+- If `CTDeployer` changes, test both project launch and any wrapped hook flow it participates in.
+- Treat `CTProjectOwner` changes as governance changes.
+
+## Canonical Checks
+
+- publish-path fee routing and policy enforcement:
+  `test/CTPublisher.t.sol`
+- fee fallback and refund safety:
+  `test/audit/FeeFallbackBlackhole.t.sol`
+- duplicate-content and batch-fee-evasion resistance:
+  `test/regression/DuplicateUriFeeEvasion.t.sol`
+
+## Source Map
+
+- `src/CTPublisher.sol`
+- `src/CTDeployer.sol`
+- `src/CTProjectOwner.sol`
+- `test/CTPublisher.t.sol`
+- `test/audit/FeeFallbackBlackhole.t.sol`
+- `test/regression/DuplicateUriFeeEvasion.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,15 +1,15 @@
 # Audit Instructions
 
-Croptop is a publishing layer on top of Juicebox projects and the 721 hook stack. Audit it as a permissions and fee-routing system, not just a content app.
+Croptop is a publishing layer on top of Juicebox projects and the tiered 721 stack. Audit it as a permissions, fee-routing, and project-launch system.
 
-## Objective
+## Audit Objective
 
 Find issues that:
 - let publishers create or mint posts outside configured criteria
 - let users evade Croptop fees or route them incorrectly
 - grant fee-free or privileged cash-outs to the wrong actors
-- create stale, duplicate, or abusive tier reuse across posts
-- break ownership handoff or permanently lock a project in an unintended admin state
+- make tier reuse bypass stale-content, fee, or policy checks
+- leave a project in an unintended ownership or admin state
 
 ## Scope
 
@@ -17,76 +17,68 @@ In scope:
 - `src/CTPublisher.sol`
 - `src/CTDeployer.sol`
 - `src/CTProjectOwner.sol`
-- `src/interfaces/`
-- `src/structs/`
-- deployment scripts in `script/`
-
-External integrations that matter:
-- `nana-core-v6`
-- `nana-721-hook-v6`
-- `nana-ownable-v6`
-- `nana-suckers-v6`
-
-## System Model
-
-Croptop has three roles:
-- `CTPublisher`: validates post configuration, creates or adjusts tiers, mints the first copy, and routes fees
-- `CTDeployer`: launches a project, wires hook ownership and post criteria, and acts as a data-hook proxy where required
-- `CTProjectOwner`: ownership helper for projects that want Croptop-controlled administration
-
-The system relies on project-specific posting criteria such as:
-- minimum price
-- supply bounds
-- category restrictions
-- split limits
-- optional address allowlists
+- all interfaces in `src/interfaces/`
+- all structs in `src/structs/`
+- deployment helpers in `script/`
 
-## Critical Invariants
+## Start Here
+
+1. `src/CTPublisher.sol`
+2. `src/CTDeployer.sol`
+3. `src/CTProjectOwner.sol`
+
+## Security Model
 
-1. Post criteria are binding
-No publish path should bypass configured minimum price, total supply bounds, split caps, or allowlist restrictions.
+Croptop composes several subsystems:
+- `CTPublisher` enforces posting criteria, creates or adjusts tiers, and routes fees
+- `CTDeployer` launches projects and wires hooks, criteria, and ownership helpers
+- `CTProjectOwner` lets a project follow Croptop-specific admin rules instead of a fixed EOA
 
-2. Fee collection is complete
-Each Croptop mint should either pay the configured fee or take the documented fallback path. Users must not be able to mint while underpaying Croptop.
+Trust boundaries that matter:
+- project owners choose policy, but should not be able to bypass the policy they configured
+- fee recipients and external hooks may revert or reenter
+- sucker-based privileges must be limited to genuine omnichain components
 
-3. Tier reuse is safe
-Existing tiers must not be reusable in a way that evades fees, stale criteria, or duplicate-content protections.
+## Roles And Privileges
 
-4. Sucker privileges stay narrow
-Any cash-out tax exemptions or mint permissions intended for legitimate suckers must not be reachable by arbitrary callers or spoofed registry state.
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Project owner | Choose policy and ownership mode | Must not bypass the active policy through helper paths |
+| `CTPublisher` | Create or reuse tiers and route fees | Must stay within configured criteria |
+| `CTDeployer` | Launch projects and wire helpers | Must not retain unexpected post-launch authority |
+| Sucker integration | Access narrow omnichain-only paths | Must be backed by authentic registry state |
 
-5. Ownership transitions are intentional
-Burn-lock or project-owner helper flows must not grant broader privileges than intended or accidentally strand project administration.
+## Integration Assumptions
 
-## Threat Model
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `nana-721-hook-v6` | Tier state and tier adjustments match Croptop policy checks | Posting criteria and tier reuse safety break |
+| `nana-core-v6` | Terminal and project routing are authentic | Fee routing and publish settlement drift |
+| `nana-ownable-v6` | Ownership helper resolves the intended admin | Projects can end up misowned or stranded |
+| `nana-suckers-v6` | Registry identifies genuine omnichain actors | Fee-free or privileged paths widen incorrectly |
+
+## Critical Invariants
 
-Prioritize:
-- malicious publishers choosing edge-case prices, split structures, or reused metadata
-- malicious project owners misconfiguring rules and then trying to escape them
-- fake or stale sucker registrations
-- fee-recipient failures that alter control flow
-- reentrancy through fee routing or tier-adjustment side effects
+1. Minimum price, supply bounds, split limits, category restrictions, and allowlists stay binding on every publish path.
+2. Every Croptop mint either pays the configured fee or takes the documented fallback path without underpaying Croptop.
+3. Existing tiers cannot be reused in a way that revives stale criteria or dodges fee collection.
+4. Sucker-only or fee-exempt paths cannot be reached through spoofed registry state or stale deployment wiring.
+5. Ownership handoff and burn-lock flows do not accidentally widen privileges or strand administration.
 
-## Hotspots
+## Attack Surfaces
 
-- `CTPublisher.mintFrom` and its validation pipeline
-- any code path that computes fees from user-provided versus on-chain values
-- tier creation or adjustment against prior post state
-- `CTDeployer` data-hook behavior for pay and cash-out flows
-- permission grants made during deployment or project-owner handoff
-- any one-way lock or burn-based ownership design
+- publish and mint entrypoints
+- fee computation from user input versus on-chain state
+- tier creation, adjustment, and reuse logic
+- deployer-mediated pay or cash-out data-hook behavior
+- permission grants during deployment and ownership transfer
 
-## Build And Verification
+## Accepted Risks Or Behaviors
+
+- Fee routing may degrade to a fallback path rather than block publishing entirely.
+
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-Current tests emphasize:
-- fee evasion
-- stale tier mappings
-- reentrancy and attacker-controlled publish flows
-- fork and omnichain composition
-
-Strong findings usually show either fee loss, unauthorized publishing power, or a project entering a control configuration it cannot safely escape.

package/README.md

@@ -4,7 +4,12 @@ Croptop turns a Juicebox project with a 721 hook into a permissioned publishing
 
 Docs: <https://docs.juicebox.money>  
 Site: <https://croptop.eth.limo>
-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
 
@@ -28,7 +33,7 @@ If a bug looks like ordinary tier issuance or terminal accounting, start in the
 | --- | --- |
 | `CTPublisher` | Validates posts, adjusts 721 tiers, mints the first copy, and routes protocol and project payments. |
 | `CTDeployer` | Launches a project, configures Croptop posting rules, and can wire in omnichain sucker deployments. |
-| `CTProjectOwner` | Burn-lock ownership helper that can permanently route project administration through Croptop's publishing surface. |
+| `CTProjectOwner` | Ownership sink that can permanently hold a project NFT while still delegating the posting permissions Croptop needs. |
 
 ## Mental Model
 
@@ -39,6 +44,36 @@ There are two separate concerns here:
 
 That distinction matters because many "Croptop bugs" are deployment-shape bugs rather than publishing-rule bugs.
 
+## Read These Files First
+
+1. `src/CTPublisher.sol`
+2. `src/CTDeployer.sol`
+3. `src/CTProjectOwner.sol`
+4. `test/CTPublisher.t.sol`
+5. `test/ClaimCollectionOwnership.t.sol`
+
+## High-Signal Tests
+
+1. `test/CTPublisher.t.sol`
+2. `test/CTDeployer.t.sol`
+3. `test/ClaimCollectionOwnership.t.sol`
+4. `test/audit/FeeFallbackBlackhole.t.sol`
+5. `test/regression/DuplicateUriFeeEvasion.t.sol`
+
+## Integration Traps
+
+- Croptop publishing policy is separate from ordinary 721 tier issuance, so readers often stop in the wrong repo
+- fee routing is part of the publish path and has fallback behavior that affects who must be able to receive ETH
+- `CTProjectOwner` intentionally changes the project's ownership shape and should be reviewed as part of the trust model
+- duplicate-content, stale-tier, and fee-evasion edge cases are first-class surfaces, not only UI concerns
+
+## Where State Lives
+
+- posting criteria and publish-side enforcement live in `CTPublisher`
+- deployment-time project wiring lives in `CTDeployer`
+- ownership-sink behavior lives in `CTProjectOwner`
+- actual tier issuance and treasury accounting still live in sibling Juicebox repos
+
 ## Install
 
 ```bash
@@ -62,9 +97,9 @@ Useful scripts:
 
 ## Deployment Notes
 
-Deployments are handled through Sphinx using the environments configured in the repo scripts. `CTDeployer` can also compose cross-chain sucker deployments when the target publishing project needs omnichain support.
+Deployments are handled through Sphinx using the environments configured in the repo scripts. `CTDeployer` can also compose cross-chain sucker deployments when a nonzero sucker configuration is supplied for the target publishing project.
 
-The deploy script now expects an explicit nonzero `FEE_PROJECT_ID` for canonical deployments. It does not safely
+The deploy script now expects an explicit nonzero `FEE_PROJECT_ID` for production-style deployments. It does not safely
 autodiscover a fee project by scanning existing project IDs.
 
 ## Repository Layout
@@ -89,7 +124,13 @@ script/
 - posting criteria are only as safe as the project owner configures them
 - fee routing depends on the designated fee project remaining correctly configured; if its terminal rejects payments,
   Croptop refunds the fee to `_msgSender()` instead of trapping ETH in `CTPublisher`
-- burn-lock ownership is intentionally irreversible and should only be used when immutability is desired
-- after burn-locking into `CTProjectOwner`, the previous owner no longer holds the project NFT directly; control is
+- parking a project in `CTProjectOwner` is intentionally irreversible in practice and should only be used when immutability is desired
+- after routing ownership into `CTProjectOwner`, the previous owner no longer holds the project NFT directly; control is
   intentionally mediated through Croptop's owner helper and hook-admin surface instead of remaining a plain owner EOA
 - duplicate-content and stale-tier edge cases are guarded by tests, but integrations should still treat metadata reuse carefully
+
+## For AI Agents
+
+- Do not describe Croptop as a generic 721 marketplace; it is a rules-driven publishing layer on top of Juicebox.
+- Read `CTPublisher` before `CTDeployer` when the question is about publish eligibility or fee behavior.
+- If the issue is basic tier minting or accounting, move to `nana-721-hook-v6` or `nana-core-v6`.

package/RISKS.md

@@ -22,6 +22,7 @@ This file focuses on the publishing, fee-routing, and hook-composition risks tha
 - **Trusted forwarder.** ERC-2771 `_msgSender()` is trusted in both CTPublisher and CTDeployer for permission checks, allowlist validation, and payment routing. A compromised forwarder can post as any allowed address, deploy projects as any owner, and redirect payments.
 - **CTDeployer as permanent data hook proxy.** `CTDeployer` sets itself as the data hook for projects it deploys. `dataHookOf[projectId]` is set once during `deployProjectFor` and has no setter to update it. If the underlying data hook needs to change, there is no mechanism to do so without redeploying.
 - **Sucker registry.** `CTDeployer.beforeCashOutRecordedWith` trusts `SUCKER_REGISTRY.isSuckerOf()` for 0% tax cashouts, same risk as the omnichain deployer.
+- **Sucker deployment is intended to be fail-open at launch time.** `deployProjectFor` calls `SUCKER_REGISTRY.deploySuckersFor` only when a non-zero deployment salt is configured, and the current deployment path is documented as allowing launch to continue on chains where the configured sucker deployer cascade cannot complete. Operators should not assume a successful Croptop launch implies omnichain support is live.
 - **CTProjectOwner as burn target.** Projects transferred to `CTProjectOwner` grant `ADJUST_721_TIERS` to `PUBLISHER`. The project NFT cannot be recovered -- this is intentional but irreversible.
 - **JBDirectory / Terminal resolution.** `CTPublisher.mintFrom` resolves terminals via `DIRECTORY.primaryTerminalOf()`. A compromised directory could redirect payment and fee flows.
 - **721 hook store.** `_setupPosts` calls `hook.STORE().tierOf()` and `hook.STORE().isTierRemoved()`. The store is trusted to return accurate tier data. A malicious hook returning a fake store can report manipulated prices, supply limits, and removal status, causing `_setupPosts` to miscalculate `totalPrice` or skip duplicate detection.
@@ -59,6 +60,7 @@ This file focuses on the publishing, fee-routing, and hook-composition risks tha
 
 - **CTDeployer forwards pay/cashout calls to `dataHookOf` with null check.** `beforePayRecordedWith` and `beforeCashOutRecordedWith` check for a null `dataHookOf` and return defaults (context weight, empty specs) instead of reverting. If a non-null data hook reverts, payments/cashouts for the project are still blocked.
 - **No mechanism for hook migration.** `dataHookOf` is written once in `deployProjectFor` and never updated. If the data hook becomes compromised, there is no governance path to replace it without deploying a new project.
+- **Sucker support can be absent even when deployment requested it.** Launch does not treat successful sucker setup as part of the Croptop app's core publish flow. A project can come online with the publisher, hook, and main terminal flow active while no suckers were actually deployed yet. Monitoring and deployment tooling should verify the returned sucker set explicitly instead of inferring success from project launch.
 - **Tier ID prediction.** `_setupPosts` predicts new tier IDs as `maxTierIdOf(hook) + 1 + i`. If another transaction adds tiers between `maxTierIdOf` read and `adjustTiers` execution, tier IDs shift and the wrong tiers are minted. This is a race condition in concurrent posting.
 - **CTProjectOwner accepts any project NFT.** `onERC721Received` grants `ADJUST_721_TIERS` to `PUBLISHER` for whatever tokenId is received. If a non-Croptop project is accidentally transferred to `CTProjectOwner`, the publisher gains tier adjustment permission for it.
 - **Fee payment destination.** Fees are routed to `FEE_PROJECT_ID` via its primary terminal. If the fee project changes its terminal or token acceptance incompatibly, `mintFrom` attempts to refund the fee to `_msgSender()`. If the caller cannot receive ETH, the mint reverts.

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## Use This File For
 
 - Use this file when the task touches Croptop publishing, project deployment, data-hook forwarding, fee routing, or burn-locked ownership behavior.
-- Start here, then jump into the publisher, deployer, or owner contract depending on which path the user is actually asking about.
+- Start here, then decide whether the issue is posting-policy validation, tier reuse/content identity, deployer-packaged project shape, or burn-locked ownership. Those concerns interact, but they are not the same subsystem.
 
 ## Read This Next
 
@@ -13,7 +13,9 @@
 | Publishing and metadata behavior | [`src/CTPublisher.sol`](./src/CTPublisher.sol) |
 | Deployment and fee-project wiring | [`src/CTDeployer.sol`](./src/CTDeployer.sol), [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/ConfigureFeeProject.s.sol`](./script/ConfigureFeeProject.s.sol) |
 | Ownership burn-lock behavior | [`src/CTProjectOwner.sol`](./src/CTProjectOwner.sol) |
-| Regression, attack, or fork coverage | [`test/regression/`](./test/regression/), [`test/fork/`](./test/fork/), [`test/`](./test/) |
+| Runtime and operational invariants | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
+| Publishing, metadata, and attack coverage | [`test/CTPublisher.t.sol`](./test/CTPublisher.t.sol), [`test/Test_MetadataGeneration.t.sol`](./test/Test_MetadataGeneration.t.sol), [`test/CroptopAttacks.t.sol`](./test/CroptopAttacks.t.sol) |
+| Deployment, ownership, and fork coverage | [`test/CTDeployer.t.sol`](./test/CTDeployer.t.sol), [`test/CTProjectOwner.t.sol`](./test/CTProjectOwner.t.sol), [`test/ClaimCollectionOwnership.t.sol`](./test/ClaimCollectionOwnership.t.sol), [`test/Fork.t.sol`](./test/Fork.t.sol), [`test/TestAuditGaps.sol`](./test/TestAuditGaps.sol) |
 
 ## Repo Map
 
@@ -37,5 +39,8 @@ Permissioned publishing layer for Juicebox 721 projects. Project owners define p
 
 - Start in [`src/CTPublisher.sol`](./src/CTPublisher.sol) for posting-rule and fee behavior, but check [`src/CTDeployer.sol`](./src/CTDeployer.sol) when the bug might come from project shape or hook forwarding.
 - Treat posting criteria, fee routing, and duplicate-content handling as treasury-sensitive and product-sensitive at the same time.
+- Category policy is part of the product surface. Changes to allowed addresses, supply bounds, or split caps alter what can be published, not just how it is paid for.
 - If the task mentions project immutability or admin recovery, inspect [`src/CTProjectOwner.sol`](./src/CTProjectOwner.sol) before changing deployer or publisher code.
+- Metadata bugs can be publishing bugs, resolver-shape bugs, or duplicate-content bugs. Check all three before assuming a string-formatting issue.
+- Duplicate-post and tier-reuse behavior are first-class runtime semantics. Do not treat them like cacheable convenience logic.
 - When a bug looks like generic 721 issuance, confirm it is not actually in `nana-721-hook-v6`.

package/USER_JOURNEYS.md

@@ -1,56 +1,118 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
 
-- project owners turning a Juicebox 721 project into a publishing marketplace
-- publishers creating or reusing NFT tiers as posts
-- operators locking project administration into Croptop-specific ownership patterns
+This repo turns a Juicebox 721 project into a permissioned publishing system.
+It owns post validation, Croptop fee routing, and the deployment packaging that turns a project into a Croptop-managed
+publisher. It does not own the base terminal accounting or the underlying 721 tier mechanics it wraps.
+
+## Primary Actors
+
+- project owners creating a Croptop publishing surface
+- publishers minting posts into an existing Croptop project
+- auditors reviewing fee routing, posting policy, and owner-lock semantics
+
+## Key Surfaces
+
+- `CTPublisher`: validates posts, adjusts tiers, mints the first copy, and routes Croptop fees
+- `CTDeployer`: launches a Croptop-shaped project and can compose omnichain deployment
+- `CTProjectOwner`: owner helper that can burn-lock administration into Croptop
+- `mintFrom(...)`: main publishing entrypoint for new content
 
 ## Journey 1: Turn A Project Into A Croptop Publisher
 
-**Starting state:** a project already exists or is about to launch, and the owner wants category-level posting rules.
+**Actor:** project owner.
+
+**Intent:** install Croptop publishing policy on a project.
 
-**Success:** Croptop posting criteria are installed and future posts must satisfy them.
+**Preconditions**
+- the project already exists or will be launched through `CTDeployer`
+- the owner has chosen category rules and the expected 721 hook shape
 
-**Flow**
-1. Configure category-level posting constraints such as price floor, supply bounds, split limits, and optional allowlists.
-2. Install or verify the 721 hook shape the project expects.
-3. Route the project through Croptop's publisher logic so future post creation is policy-checked instead of free-form tier editing.
+**Main Flow**
+1. Configure category-level constraints such as price floor, supply, splits, and allowlists.
+2. Install or verify the expected 721 hook setup.
+3. Route publishing through Croptop so future posts are policy-checked instead of free-form tier edits.
+
+**Failure Modes**
+- category rules do not match the intended publishing product
+- teams assume Croptop replaces the need to audit the underlying 721 hook
+
+**Postconditions**
+- the project now routes publishing through Croptop policy rather than direct free-form tier creation
 
 ## Journey 2: Publish Content Into An Existing Croptop Project
 
-**Starting state:** a publisher has a post that satisfies the target project's posting rules.
+**Actor:** publisher.
+
+**Intent:** publish one post into a Croptop project and mint the first copy.
+
+**Preconditions**
+- the post satisfies the target project's category policy
+- the caller can receive ETH if the fee refund fallback is needed
+- duplicate-content and stale-tier implications are understood
 
-**Success:** the post becomes a valid 721 tier and the first mint settles correctly.
+**Main Flow**
+1. Call `mintFrom(...)` with the content URI and pricing data.
+2. `CTPublisher` validates the post against category and fee policy.
+3. It creates or reuses the underlying tier, mints the first copy, and routes project revenue plus the Croptop fee.
 
-**Flow**
-1. The publisher calls `mintFrom(...)` or the equivalent publishing surface with the content URI and pricing data.
-2. `CTPublisher` checks the post against category rules and fee policy.
-3. It creates or reuses the underlying 721 tier, mints the first copy, and routes both project revenue and the Croptop fee. If the fee terminal is unavailable, the fee is refunded to `_msgSender()` instead.
+**Failure Modes**
+- duplicate URIs or stale tier mappings
+- publisher inputs satisfy the base 721 hook but violate Croptop's stricter rules
+- the fee terminal rejects the fee payment and `_msgSender()` cannot receive the refund
 
-**Failure cases that matter:** duplicate URIs, split configurations that evade fees, stale tier mappings, publisher inputs that satisfy the 721 hook but violate Croptop's stricter publishing rules, and callers that cannot receive ETH when a fee refund fallback is needed.
+**Postconditions**
+- the post is minted or reused as a tier under Croptop policy and the fee path is accounted for
 
 ## Journey 3: Launch A New Croptop Project End To End
 
-**Starting state:** the product wants a fresh project that already has Croptop deployment choices baked in.
+**Actor:** product team or deployer.
 
-**Success:** one deployment flow launches the project, wires the 721 hook, and installs the initial posting rules.
+**Intent:** launch a project already wired for Croptop publishing.
 
-**Flow**
-1. Use `CTDeployer` with project config, posting rules, and any omnichain deployment config.
-2. The deployer launches the Juicebox project, configures the Croptop-specific owner model, and wires in publisher behavior.
-3. The project is ready for publishers without a manual post-launch setup phase.
+**Preconditions**
+- the team has project config, posting rules, and any omnichain requirements ready
+- the correct `FEE_PROJECT_ID` is known for deployment
+
+**Main Flow**
+1. Use `CTDeployer` with project config, posting rules, and optional omnichain config.
+2. The deployer launches the project, configures Croptop ownership assumptions, and wires publisher behavior.
+3. The resulting project is ready for publishers without a manual post-launch setup gap.
+
+**Failure Modes**
+- the fee project is misconfigured or omitted
+- teams treat `CTDeployer` as packaging only and miss its policy implications
+
+**Postconditions**
+- the resulting project is ready for Croptop publishers without a post-launch wiring gap
 
 ## Journey 4: Lock Administration Into Croptop's Owner Surface
 
-**Starting state:** the project should continue operating through Croptop's policy surface instead of ordinary project-owner discretion.
+**Actor:** project owner.
+
+**Intent:** keep governance inside Croptop's constrained owner surface.
 
-**Success:** the project's admin path is burn-locked or otherwise routed through `CTProjectOwner`.
+**Preconditions**
+- the owner wants irreversible product-shaping constraints, not ordinary owner flexibility
 
-**Flow**
-1. Transfer or configure ownership so Croptop's owner helper controls the relevant admin surface.
+**Main Flow**
+1. Transfer or configure ownership so `CTProjectOwner` controls the relevant admin surface.
 2. Restrict future edits to the paths Croptop intentionally exposes.
-3. Accept that this is a product-shaping choice, not a cosmetic deployment detail.
+3. Accept that this is an ownership-model decision, not cosmetic packaging.
+
+**Failure Modes**
+- teams burn-lock before validating the publishing policy in production-like conditions
+- reviewers miss that prior owner discretion no longer exists directly
+
+**Postconditions**
+- future administration is constrained to the Croptop owner surface instead of ordinary owner discretion
+
+## Trust Boundaries
+
+- this repo is trusted for publishing policy and fee routing
+- the underlying 721 hook remains trusted for tier issuance and lower-level NFT accounting
+- Croptop fee behavior depends on the fee project and its terminal remaining correctly configured
 
 ## Hand-Offs
 

package/foundry.toml

@@ -16,6 +16,8 @@ fail_on_revert = false
 [rpc_endpoints]
 ethereum = "${RPC_ETHEREUM_MAINNET}"
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,33 +1,33 @@
 {
-    "name": "@croptop/core-v6",
-    "version": "0.0.33",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/mejango/croptop-core-v6"
-    },
-    "scripts": {
-        "test": "forge test",
-        "coverage:integration": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
-        "deploy:mainnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
-        "deploy:mainnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks mainnets",
-        "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
-        "deploy:testnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks testnets",
-        "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'croptop-core-v5'"
-    },
-    "dependencies": {
-        "@bananapus/721-hook-v6": "^0.0.33",
-        "@bananapus/buyback-hook-v6": "^0.0.27",
-        "@bananapus/core-v6": "^0.0.34",
-        "@bananapus/ownable-v6": "^0.0.17",
-        "@bananapus/permission-ids-v6": "^0.0.17",
-        "@bananapus/router-terminal-v6": "^0.0.26",
-        "@bananapus/suckers-v6": "^0.0.25",
-        "@openzeppelin/contracts": "^5.6.1"
-    },
-    "devDependencies": {
-        "@bananapus/address-registry-v6": "^0.0.17",
-        "@rev-net/core-v6": "^0.0.31",
-        "@sphinx-labs/plugins": "^0.33.3"
-    }
+  "name": "@croptop/core-v6",
+  "version": "0.0.34",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mejango/croptop-core-v6"
+  },
+  "scripts": {
+    "test": "forge test",
+    "coverage:integration": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary",
+    "deploy:mainnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks mainnets",
+    "deploy:mainnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks mainnets",
+    "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets",
+    "deploy:testnets:project": "source ./.env && export START_TIME=$(date +%s) && npx sphinx propose ./script/ConfigureFeeProject.s.sol --networks testnets",
+    "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'croptop-core-v5'"
+  },
+  "dependencies": {
+    "@bananapus/721-hook-v6": "^0.0.35",
+    "@bananapus/buyback-hook-v6": "^0.0.27",
+    "@bananapus/core-v6": "^0.0.34",
+    "@bananapus/ownable-v6": "^0.0.17",
+    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@bananapus/router-terminal-v6": "^0.0.26",
+    "@bananapus/suckers-v6": "^0.0.25",
+    "@openzeppelin/contracts": "^5.6.1"
+  },
+  "devDependencies": {
+    "@bananapus/address-registry-v6": "^0.0.17",
+    "@rev-net/core-v6": "^0.0.32",
+    "@sphinx-labs/plugins": "^0.33.3"
+  }
 }

package/references/operations.md

@@ -21,5 +21,5 @@
 
 ## Useful Proof Points
 
-- [`test/fork/`](../test/fork/) when deployment shape matters.
-- [`script/helpers/`](../script/helpers/) if the issue is really script/config assembly.
+- [`test/Fork.t.sol`](../test/Fork.t.sol) when deployment shape matters.
+- [`script/ConfigureFeeProject.s.sol`](../script/ConfigureFeeProject.s.sol) if the issue is really script/config assembly.

package/references/runtime.md

@@ -22,6 +22,6 @@
 
 ## Tests To Trust First
 
-- [`test/regression/`](../test/regression/) for pinned content and tier edge cases.
-- [`test/fork/`](../test/fork/) for live integration assumptions.
-- [`test/`](../test/) broadly when the issue could be in publisher or deployer behavior rather than one isolated function.
+- [`test/CTPublisher.t.sol`](../test/CTPublisher.t.sol) and [`test/Test_MetadataGeneration.t.sol`](../test/Test_MetadataGeneration.t.sol) for content and metadata behavior.
+- [`test/CTDeployer.t.sol`](../test/CTDeployer.t.sol) and [`test/Fork.t.sol`](../test/Fork.t.sol) for live deployment assumptions.
+- [`test/CroptopAttacks.t.sol`](../test/CroptopAttacks.t.sol) and [`test/TestAuditGaps.sol`](../test/TestAuditGaps.sol) when the issue could be in publisher or deployer behavior rather than one isolated function.

package/src/CTPublisher.sol

@@ -27,7 +27,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    // forge-lint: disable-next-line(mixed-case-variable)
     error CTPublisher_DuplicatePost(bytes32 encodedIPFSUri);
     error CTPublisher_EmptyEncodedIPFSUri();
     error CTPublisher_InsufficientEthSent(uint256 expected, uint256 sent);
@@ -66,7 +65,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     /// @notice The ID of the tier that an IPFS metadata has been saved to.
     /// @custom:param hook The hook for which the tier ID applies.
     /// @custom:param encodedIPFSUri The IPFS URI.
-    // forge-lint: disable-next-line(mixed-case-variable)
     mapping(address hook => mapping(bytes32 encodedIPFSUri => uint256)) public override tierIdForEncodedIPFSUriOf;
 
     //*********************************************************************//
@@ -324,7 +322,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
     /// is returned.
     function tiersFor(
         address hook,
-        // forge-lint: disable-next-line(mixed-case-variable)
         bytes32[] memory encodedIPFSUris
     )
         external
@@ -332,7 +329,6 @@ contract CTPublisher is JBPermissioned, ERC2771Context, ICTPublisher {
         override
         returns (JB721Tier[] memory tiers)
     {
-        // forge-lint: disable-next-line(mixed-case-variable)
         uint256 numberOfEncodedIPFSUris = encodedIPFSUris.length;
 
         // Initialize the tier array being returned.

package/src/interfaces/ICTPublisher.sol

@@ -73,7 +73,7 @@ interface ICTPublisher {
     /// @param hook The hook for which the tier ID applies.
     /// @param encodedIPFSUri The encoded IPFS URI to look up.
     /// @return The tier ID, or 0 if the URI has not been published.
-    // forge-lint: disable-next-line(mixed-case-function, mixed-case-variable)
+    // forge-lint: disable-next-line(mixed-case-function)
     function tierIdForEncodedIPFSUriOf(address hook, bytes32 encodedIPFSUri) external view returns (uint256);
 
     /// @notice Get the tiers for the provided encoded IPFS URIs.
@@ -81,7 +81,6 @@ interface ICTPublisher {
     /// @param encodedIPFSUris The URIs to get tiers of.
     /// @return tiers The tiers that correspond to the provided encoded IPFS URIs. Empty tiers are returned for URIs
     /// without a tier.
-    // forge-lint: disable-next-line(mixed-case-variable)
     function tiersFor(address hook, bytes32[] memory encodedIPFSUris) external view returns (JB721Tier[] memory tiers);
 
     /// @notice Configure the allowed criteria for publishing new NFTs to a hook.

package/src/structs/CTAllowedPost.sol

@@ -11,7 +11,6 @@ pragma solidity ^0.8.0;
 /// @custom:member maximumSplitPercent The maximum split percent (out of JBConstants.SPLITS_TOTAL_PERCENT) that a
 /// poster can set. 0 means splits are not allowed.
 /// @custom:member allowedAddresses A list of addresses that are allowed to post on the category through Croptop.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct CTAllowedPost {
     address hook;
     uint24 category;

package/src/structs/CTDeployerAllowedPost.sol

@@ -10,7 +10,6 @@ pragma solidity ^0.8.0;
 /// @custom:member maximumSplitPercent The maximum split percent (out of JBConstants.SPLITS_TOTAL_PERCENT) that a
 /// poster can set. 0 means splits are not allowed.
 /// @custom:member allowedAddresses A list of addresses that are allowed to post on the category through Croptop.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct CTDeployerAllowedPost {
     uint24 category;
     uint104 minimumPrice;

package/src/structs/CTPost.sol

@@ -12,9 +12,7 @@ import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 /// @custom:member splitPercent The percent of the tier's price to route to the splits (out of
 /// JBConstants.SPLITS_TOTAL_PERCENT).
 /// @custom:member splits The splits to route funds to when this tier is minted.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct CTPost {
-    // forge-lint: disable-next-line(mixed-case-variable)
     bytes32 encodedIPFSUri;
     uint32 totalSupply;
     uint104 price;

package/src/structs/CTProjectConfig.sol

@@ -11,7 +11,6 @@ import {CTDeployerAllowedPost} from "../structs/CTDeployerAllowedPost.sol";
 /// @param name The name of the collection where posts will go.
 /// @param symbol The symbol of the collection where posts will go.
 /// @param salt A salt to use for the deterministic deployment.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct CTProjectConfig {
     JBTerminalConfig[] terminalConfigurations;
     string projectUri;

package/src/structs/CTSuckerDeploymentConfig.sol

@@ -5,7 +5,6 @@ import {JBSuckerDeployerConfig} from "@bananapus/suckers-v6/src/structs/JBSucker
 
 /// @custom:member deployerConfigurations The information for how to suck tokens to other chains.
 /// @custom:member salt The salt to use for creating suckers so that they use the same address across chains.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct CTSuckerDeploymentConfig {
     JBSuckerDeployerConfig[] deployerConfigurations;
     bytes32 salt;