@croptop/core-v6 0.0.32 → 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`.