@bananapus/core-v6 0.0.35 → 0.0.36

package/ADMINISTRATION.md

@@ -7,30 +7,30 @@
 | Scope | Core Juicebox V6 control plane: directory, controller, terminals, permissions, prices, and global protocol switches |
 | Control posture | Mixed protocol-owner, project-owner, delegated-operator, controller, and terminal control |
 | Highest-risk actions | Controller migration, terminal migration, token binding, price-feed installation, and broad permission grants |
-| Recovery posture | Project-local mistakes may be fixable if rulesets permit; immutable infra mistakes usually require replacement layers and migration |
+| Recovery posture | Project-local mistakes may be fixable if rulesets allow it; immutable infra mistakes usually require replacement and migration |
 
 ## Purpose
 
-`nana-core-v6` is the largest control plane in the stack. It combines protocol-owned contracts, project-local ownership, delegated operators through `JBPermissions`, and ruleset flags that selectively permit or forbid changes. This file is about who can still change project behavior once the core is live.
+`nana-core-v6` is the main control plane in the stack. It mixes protocol-owned contracts, project-local ownership, delegated operators through `JBPermissions`, and ruleset flags that allow or block changes. This file explains who can still change project behavior after core is live.
 
 ## Control Model
 
 - Protocol-wide `Ownable` surfaces exist on `JBDirectory`, `JBProjects`, `JBPrices`, and `JBFeelessAddresses`.
-- Project-local control runs through the project NFT owner in `JBProjects`.
-- Fine-grained operator delegation runs through `JBPermissions`.
-- Controllers and terminals are privileged system callers once the directory points to them.
-- Current ruleset flags can further allow or deny certain owner or operator actions.
+- Project-local control comes from the project NFT owner in `JBProjects`.
+- Fine-grained operator delegation comes from `JBPermissions`.
+- Controllers and terminals become privileged system callers once the directory points to them.
+- The current ruleset can further allow or deny owner or operator actions.
 
 ## Roles
 
 | Role | How Assigned | Scope | Notes |
 | --- | --- | --- | --- |
-| Project owner | `JBProjects.ownerOf(projectId)` | Per project | Root human control surface for a project |
+| Project owner | `JBProjects.ownerOf(projectId)` | Per project | Main human control surface |
 | Project operator | `JBPermissions` grant | Per project or wildcard | Can be narrow or dangerously broad |
 | Controller | `JBDirectory.controllerOf(projectId)` | Per project | Manages rulesets, token setup, splits, and fund-access config |
-| Terminal | `JBDirectory` terminal set | Per project | Can move funds through `JBTerminalStore` and terminal entrypoints |
-| Protocol owner | `Ownable(owner)` on protocol-wide contracts | Global | Different contracts have different owners |
-| Omnichain ruleset operator | `JBController` constructor immutable | Global or broad | Bypasses some ordinary owner paths for synchronized ruleset flows |
+| Terminal | `JBDirectory` terminal set | Per project | Moves funds through `JBTerminalStore` and terminal entrypoints |
+| Protocol owner | `Ownable(owner)` on protocol-wide contracts | Global | Different contracts can have different owners |
+| Omnichain ruleset operator | `JBController` constructor immutable | Global or broad | Bypasses some owner checks for synchronized ruleset flows |
 
 ## Privileged Surfaces
 
@@ -44,48 +44,48 @@ High-value admin functions include:
 - `JBFeelessAddresses.setFeelessAddress(...)`
 - `JBProjects.setTokenUriResolver(...)`
 
-The most important practical distinction is:
+The practical split is simple:
 
 - protocol owners change global infrastructure or defaults
-- project owners and their operators change project configuration
-- controllers and terminals are trusted system actors once the directory points to them
+- project owners and operators change project configuration
+- controllers and terminals act with the authority core gives them
 
-## Immutable And One-Way
+## Immutable And One-Way Decisions
 
 - Default or project-specific price feeds are write-once for a given pair.
-- ERC-20 token binding decisions for a project are effectively one-time.
+- ERC-20 token binding for a project is effectively one-time.
 - The fee beneficiary project ID inside `JBMultiTerminal` is hardcoded.
-- Constructor immutables on controller, directory, terminal, store, prices, and tokens are not patchable.
+- Constructor immutables on controller, directory, terminal, store, prices, and tokens cannot be patched.
 
 ## Operational Notes
 
-- Use narrow project-scoped permissions instead of wildcard or ROOT permissions whenever possible.
-- Validate whether the active ruleset allows the change before assuming the owner or operator can perform it.
-- Treat controller migration, terminal migration, token deployment, and price-feed installation as control-plane changes with large blast radius.
+- Use narrow project-scoped permissions instead of wildcard or ROOT permissions when possible.
+- Check whether the active ruleset allows the change before assuming the owner or operator can make it.
+- Treat controller migration, terminal migration, token deployment, and price-feed installation as high-blast-radius control-plane changes.
 - Read both the permission check and the current ruleset flags before concluding an action is allowed.
-- Keep an eye on fee-route and payout-path failure semantics: some failures are intentionally caught so funds stay recoverable instead of being permanently trapped.
+- Keep fee-route and payout-path failure semantics in mind. Some failures restore project balance instead of trapping funds.
 
 ## Machine Notes
 
-- Do not infer authority from project ownership alone; many paths also depend on the active ruleset and permission bitmap.
-- Treat `JBDirectory`, `JBController`, `JBMultiTerminal`, `JBPermissions`, `JBPrices`, `JBFeelessAddresses`, and `JBProjects` as the minimum source-of-truth set for control-plane crawling.
+- Do not infer authority from project ownership alone. Many paths also depend on the active ruleset and permission bitmap.
+- Treat `JBDirectory`, `JBController`, `JBMultiTerminal`, `JBPermissions`, `JBPrices`, `JBFeelessAddresses`, and `JBProjects` as the minimum control-plane source set.
 - If a controller, terminal, or price-feed action is not backed by the exact current directory entry, stop and resolve the mismatch first.
 - If a permission is not named explicitly in the call path, inspect the contract check before assuming delegated authority exists.
-- If a fee route or split payout failed, inspect whether the core intentionally restored project balance or left a retry path before calling it a permanent loss.
+- If a fee route or split payout failed, check whether core restored balance or left a retry path before calling it a permanent loss.
 
 ## Recovery
 
-- Wrong immutable infra usually means a new controller, terminal, store, or price layer and then migration.
-- Wrong project-local config can often be corrected if the current ruleset still permits the change.
-- Wrong wildcard permissions are fixable only by updating the permission bitmap; they are dangerous mainly because of what can happen before revocation.
-- Some fee-route and payout-route failures are recoverable in place because the core prefers restoring balance and preserving retry paths over trapping funds.
+- Wrong immutable infrastructure usually means deploying a new controller, terminal, store, or price layer and then migrating.
+- Wrong project-local config can often be corrected if the current ruleset still allows it.
+- Wrong wildcard permissions are fixed by updating the permission bitmap, but they are dangerous because of what can happen before revocation.
+- Some fee-route and payout-route failures are recoverable in place because core prefers liveness over trapped funds.
 
 ## Admin Boundaries
 
 - Protocol owners cannot directly rewrite project economics without going through the contracts and ruleset constraints that enforce those changes.
 - Project owners cannot bypass immutable constructor references or rewrite existing price-feed entries.
-- Controllers and terminals only have the authority the directory and core contracts give them; they do not get arbitrary global power.
-- Nobody can change the hardcoded fee beneficiary or retroactively patch immutable deployment mistakes in place.
+- Controllers and terminals only have the authority given by the directory and core contracts.
+- Nobody can change the hardcoded fee beneficiary or patch immutable deployment mistakes in place.
 
 ## Source Map
 

package/ARCHITECTURE.md

@@ -2,40 +2,42 @@
 
 ## Purpose
 
-`nana-core-v6` is the protocol root for the V6 stack. It owns project identity, rulesets, permissions, treasury balances, token issuance, fee behavior, payout limits, and the hook interfaces every extension repo composes with.
+`nana-core-v6` is the root of the V6 stack. It owns project identity, rulesets, permissions, treasury balances, token issuance, fee behavior, payout limits, and the hook interfaces that extension repos use.
 
-If a change affects accounting, supply, fee logic, terminal routing, or permission semantics, this repo is the source of truth.
+If a change affects accounting, token supply, fees, terminal routing, or permission semantics, this repo is the source of truth.
 
 ## System Overview
 
-`JBController`, `JBMultiTerminal`, and `JBTerminalStore` form the main execution and accounting pipeline. `JBDirectory`, `JBRulesets`, `JBProjects`, `JBTokens`, `JBPermissions`, `JBSplits`, and related contracts provide the routing, identity, and shared state that all downstream repos depend on. `JBTerminalStore` is terminal-scoped through `msg.sender`, so each terminal records its own balances and usage against the shared ruleset and price surfaces. Extensions may influence economics through hook interfaces, but they should not create competing ledgers.
+`JBController`, `JBMultiTerminal`, and `JBTerminalStore` form the main execution and accounting path. `JBDirectory`, `JBRulesets`, `JBProjects`, `JBTokens`, `JBPermissions`, `JBSplits`, and related contracts provide routing, identity, and shared state for downstream repos.
+
+`JBTerminalStore` is terminal-scoped through `msg.sender`, so each terminal tracks its own balances and usage while sharing the same ruleset and price surfaces. Hooks can change economics or add side effects, but they should not create a second ledger.
 
 ## Core Invariants
 
-- Preview functions must remain behaviorally aligned with state-changing functions.
-- Data hooks run before settlement and may alter economics; pay and cash-out hooks run after settlement.
+- Preview functions should stay aligned with the state-changing functions they mirror.
+- Data hooks run before settlement and may change economics. Pay and cash-out hooks run after settlement.
 - Reserved tokens and other pending supply affect supply-sensitive math before distribution.
 - Terminal balances, fee accounting, reclaim math, and surplus calculations must agree.
-- Fee logic taxes fund egress, not every internal rebalance. Same-terminal project routing is a special case and must stay coherent with fee-free surplus tracking.
-- Rulesets are time-ordered and approval-aware, and many deployer repos depend on predictable ID progression.
-- Permission checks are protocol validity checks, not UI affordances.
+- Fee logic taxes value leaving the system, not every internal rebalance.
+- Rulesets are time-ordered and approval-aware, and downstream deployers depend on predictable ID progression.
+- Permission checks are protocol safety checks, not just UI hints.
 
 ## Modules
 
 | Module | Responsibility | Notes |
 | --- | --- | --- |
-| `JBMultiTerminal` | Payment, cash-out, payout, allowance, and fee entrypoint | Execution surface |
+| `JBMultiTerminal` | Payment, cash-out, payout, allowance, and fee entrypoints | Execution surface |
 | `JBTerminalStore` | Shared accounting and preview math | Economic source of truth |
-| `JBController` | Launch, queue rulesets, mint, burn, and split-group updates | Supply and configuration |
+| `JBController` | Launch, queue rulesets, mint, burn, and update split groups | Supply and configuration |
 | `JBDirectory`, `JBRulesets` | Project routing and time-based ruleset lifecycle | Coordination layer |
 | `JBProjects`, `JBTokens`, `JBERC20` | Identity and token surfaces | Ownership and tokenization |
 | `JBPermissions`, `JBSplits`, `JBFundAccessLimits`, `JBPrices` | Shared authorization and configuration state | Cross-repo dependencies |
 
 ## Trust Boundaries
 
-- This repo owns canonical balance and supply transitions.
-- Hook repos may adjust inputs and post-settlement side effects, but they should not replace the ledger defined here.
-- External price feeds, Permit2, and ERC-20 behavior are dependencies, but accounting truth stays in core.
+- This repo owns the canonical balance and supply transitions.
+- Hook repos may change inputs and post-settlement behavior, but they should not replace the core ledger.
+- External price feeds, Permit2, and ERC-20 behavior matter, but accounting truth still lives here.
 
 ## Critical Flows
 
@@ -44,22 +46,22 @@ If a change affects accounting, supply, fee logic, terminal routing, or permissi
 ```text
 terminal receives funds
   -> terminal store reads the active ruleset and optional data hooks
-  -> before-pay data hook can modify weight and return pay-hook specs
-  -> terminal store records payment against the terminal-scoped ledger
+  -> before-pay data hook can change weight and return pay-hook specs
+  -> terminal store records the payment in the terminal-scoped ledger
   -> controller mints beneficiary tokens and accrues reserved tokens
-  -> pay hooks run only after settlement
+  -> pay hooks run after settlement
 ```
 
 ### Cash Out
 
 ```text
 holder requests redemption
-  -> terminal store reads current ruleset, balances, and supply inputs
-  -> before-cash-out data hook can modify reclaim inputs and hook specs
-  -> terminal store records the cash out against the terminal-scoped ledger
+  -> terminal store reads the current ruleset, balances, and supply inputs
+  -> before-cash-out data hook can change reclaim inputs and hook specs
+  -> terminal store records the cash out in the terminal-scoped ledger
   -> controller burns tokens
   -> terminal pays reclaim value and routes protocol fees
-  -> cash-out hooks run only after settlement
+  -> cash-out hooks run after settlement
 ```
 
 ### Launch And Queue Rulesets
@@ -67,8 +69,8 @@ holder requests redemption
 ```text
 owner, operator, or omnichain ruleset operator
   -> controller launches or queues rulesets
-  -> launch path also sets the controller in the directory and configures terminals
-  -> rulesets become the source of truth for subsequent pay, cash-out, and admin constraints
+  -> launch also sets the controller in the directory and configures terminals
+  -> rulesets become the source of truth for later pay, cash-out, and admin constraints
 ```
 
 ### Payouts And Allowances
@@ -77,31 +79,36 @@ owner, operator, or omnichain ruleset operator
 authorized caller
   -> consumes payout limits or surplus allowances
   -> funds move to splits, projects, hooks, or direct recipients
-  -> same-terminal project payouts stay inside terminal accounting, may accrue fee-free surplus, and must not accidentally mint against the payer's own balance
+  -> same-terminal project payouts stay inside terminal accounting and may add fee-free surplus
 ```
 
 ## Accounting Model
 
-This repo owns the canonical ledger for balances, fees, supply-sensitive reclaim math, payout limits, allowances, reserved tokens, and preview calculations. Other repos may wrap or influence these values, but none should duplicate them.
+This repo owns the canonical ledger for balances, fees, supply-sensitive reclaim math, payout limits, allowances, reserved tokens, and preview calculations. Other repos may wrap or influence these values, but they should not duplicate them.
+
+`JBTerminalStore` keeps terminal balances, payout-limit usage, and surplus-allowance usage. Those reset boundaries are not the same:
+
+- payout-limit usage is tracked by ruleset cycle number
+- surplus-allowance usage is tracked by `ruleset.id`
 
-`JBTerminalStore` keeps terminal balances, payout-limit usage, and surplus-allowance usage. That state is terminal-scoped, but not all reset boundaries are the same: payout-limit usage is tracked by ruleset cycle number, while surplus-allowance usage is tracked by `ruleset.id`. Auto-cycling a duration-based ruleset does not reset allowance usage; queueing a new ruleset does.
+If a duration-based ruleset auto-cycles without a new ruleset ID, payout-limit usage resets but allowance usage does not.
 
 ## Security Model
 
-- `JBMultiTerminal`, `JBTerminalStore`, and `JBController` should be reviewed as one pipeline.
-- `JBTerminalStore` is shared logic but terminal-scoped state. Misunderstanding that split causes bad accounting assumptions.
+- Review `JBMultiTerminal`, `JBTerminalStore`, and `JBController` as one pipeline.
+- `JBTerminalStore` uses shared logic with terminal-scoped state. Misreading that split leads to bad accounting assumptions.
 - Small changes in fee or surplus logic can affect every downstream repo.
-- Same-terminal project payouts, fee-free surplus capping, and migration cleanup are coupled. Changing one without the others creates fee bypasses or overcharges.
-- `allowOwnerMinting` is not a universal mint kill switch. Terminals, the current data hook, and hook-authorized callers can still mint through the controller path.
-- Hook ordering and preview-execution alignment are permanent maintenance obligations.
+- Same-terminal project payouts, fee-free surplus capping, and migration cleanup are coupled.
+- `allowOwnerMinting` is not a universal mint kill switch. Other allowed paths can still mint.
+- Hook ordering and preview-execution alignment are ongoing maintenance requirements.
 
 ## Safe Change Guide
 
-- Trace both preview and state-changing paths for any nontrivial change.
+- Trace both the preview path and the state-changing path for any nontrivial change.
 - Read downstream hook repos before changing hook metadata or interface expectations.
-- Keep fee logic, balance logic, reclaim math, and surplus math synchronized.
-- If you change payouts between projects on the same terminal, re-check self-pay revert behavior, fee-free surplus accumulation, and the post-pay cap against recorded balance.
-- If you change ruleset rollover semantics, re-check which usage counters reset on cycle progression versus new ruleset IDs.
+- Keep fee logic, balance logic, reclaim math, and surplus math in sync.
+- If you change same-terminal payouts between projects, re-check self-pay reverts, fee-free surplus accumulation, and post-pay caps.
+- If you change ruleset rollover semantics, re-check which counters reset on cycle progression versus new ruleset IDs.
 - If permissions change, update shared docs and downstream assumptions at the same time.
 
 ## Canonical Checks

package/AUDIT_INSTRUCTIONS.md

@@ -1,10 +1,11 @@
 # Audit Instructions
 
-This is the core Juicebox V6 protocol. Most ecosystem invariants reduce to this repo eventually.
+This is the core Juicebox V6 protocol. Most ecosystem invariants eventually reduce to this repo.
 
 ## Audit Objective
 
 Find issues that:
+
 - break terminal solvency or internal accounting
 - let projects extract more than payout or surplus-allowance limits
 - miscompute payment minting, reserved tokens, or cash-out reclaim amounts
@@ -14,11 +15,13 @@ Find issues that:
 ## Scope
 
 In scope:
+
 - all Solidity under `src/`
 - deployment scripts in `script/`
 - price-feed setup and periphery contracts under `src/periphery/`
 
 Especially critical contracts:
+
 - `JBMultiTerminal`
 - `JBTerminalStore`
 - `JBController`
@@ -32,6 +35,7 @@ Especially critical contracts:
 ## Start Here
 
 For the fastest serious review, read in this order:
+
 - `JBTerminalStore`
 - `JBMultiTerminal`
 - `JBController`
@@ -39,40 +43,44 @@ For the fastest serious review, read in this order:
 - `JBPermissions`
 - `JBPrices`
 
-That order mirrors how most high-severity issues emerge:
+That order mirrors how most high-severity issues appear:
+
 - accounting is computed
-- funds are moved
-- tokens are minted or burned
-- permissions and price context decide whether the move was legitimate
+- funds move
+- tokens mint or burn
+- permissions and price context determine whether the move is allowed
 
 ## Security Model
 
 Core roles:
+
 - `JBMultiTerminal`: holds funds and executes pay, payout, cash-out, allowance, and fee-processing flows
-- `JBTerminalStore`: accounting and surplus logic
-- `JBController`: project lifecycle, token mint/burn, and permissions-sensitive operations
-- `JBRulesets`: current and queued economic parameters
-- `JBTokens`: ERC-20 and credit accounting
-- `JBPermissions`: access-control backbone
+- `JBTerminalStore`: owns accounting and surplus logic
+- `JBController`: owns project lifecycle, token mint and burn, and permission-sensitive operations
+- `JBRulesets`: stores current and queued economic parameters
+- `JBTokens`: handles ERC-20 and credit accounting
+- `JBPermissions`: provides the access-control backbone
+
+Extension points:
 
-The rest of the ecosystem plugs into these extension points:
 - data hooks
 - pay hooks
 - cash-out hooks
 - split hooks
 - approval hooks
 
-Core ordering to keep in mind:
-- store records accounting before terminal fulfillment finishes
-- controller mint and burn operations happen around terminal flows, not as a separate settlement layer
-- hooks can turn what looks like a simple pay or cash-out into a multi-contract composition
+Ordering to keep in mind:
+
+- the store records accounting before terminal fulfillment is finished
+- controller mint and burn operations happen inside terminal flows, not in a separate settlement layer
+- hooks can turn a simple pay or cash-out into a multi-contract flow
 
 ## Roles And Privileges
 
 | Role | Powers | How constrained |
 |------|--------|-----------------|
 | Project owner and operators | Configure rulesets, limits, routing, and permissions | Must stay inside the explicit permission model |
-| Terminal | Hold funds and execute settlement | Must remain solvent relative to internal accounting |
+| Terminal | Hold funds and execute settlement | Must stay solvent relative to internal accounting |
 | Controller | Mint, burn, and manage project lifecycle | Must not bypass project-scoped authorization |
 | Hooks and splits | Extend pay and cash-out behavior | Must not make previews and accounting irreconcilable |
 
@@ -86,29 +94,22 @@ Core ordering to keep in mind:
 
 ## Critical Invariants
 
-1. Terminal solvency
-Internal balances and held-fee obligations must reconcile with actual terminal token balances.
-
-2. No over-withdrawal
-Payouts and allowance usage must never exceed configured per-cycle limits.
-
-3. Cash-out correctness
-Surplus, total supply, tax rate, fee treatment, and hook overrides must combine into the intended reclaim amount.
-
-4. Ruleset integrity
-The active ruleset and any fallback or cycling behavior must reflect exact timing and approval-hook semantics.
-
-5. Token accounting consistency
-Credits, ERC-20 total supply, reserved token balance, and burn/mint paths must remain internally coherent.
-
-6. Privilege containment
-Permissions, wildcard grants, controller migration, and terminal routing must not allow unauthorized project control or fund movement.
-
-7. Held-fee correctness
-When fee payment is deferred, later replenishment or migration behavior must not accidentally forgive, duplicate, or cross-charge the obligation.
-
-8. Preview coherence
-`previewPayFor` and `previewCashOutFrom` should not become meaningfully inconsistent with execution in ways downstream repos can exploit.
+1. Terminal solvency  
+   Internal balances and held-fee obligations must reconcile with actual terminal token balances.
+2. No over-withdrawal  
+   Payouts and allowance usage must never exceed configured per-cycle limits.
+3. Cash-out correctness  
+   Surplus, total supply, tax rate, fee treatment, and hook overrides must combine into the intended reclaim amount.
+4. Ruleset integrity  
+   The active ruleset and any fallback or cycling behavior must match exact timing and approval-hook semantics.
+5. Token accounting consistency  
+   Credits, ERC-20 total supply, reserved token balance, and burn/mint paths must stay coherent.
+6. Privilege containment  
+   Permissions, wildcard grants, controller migration, and terminal routing must not allow unauthorized control or fund movement.
+7. Held-fee correctness  
+   Deferred fees must not be accidentally forgiven, duplicated, or charged to the wrong place.
+8. Preview coherence  
+   `previewPayFor` and `previewCashOutFrom` should not drift from execution in ways downstream repos can exploit.
 
 ## Attack Surfaces
 
@@ -117,10 +118,11 @@ When fee payment is deferred, later replenishment or migration behavior must not
 - held-fee lifecycle and `_processFee`
 - surplus aggregation across terminals
 - controller migration and terminal migration
-- `setPermissionsFor` and any wildcard semantics
+- `setPermissionsFor` and wildcard semantics
 
 Replay these sequences:
-1. `pay` with a data hook that alters weight or hook specs and then reenters through a pay hook
+
+1. `pay` with a data hook that changes weight or hook specs and then reenters through a pay hook
 2. `cashOutTokensOf` when cross-terminal surplus and `useTotalSurplusForCashOuts` matter
 3. `sendPayoutsOf` into splits that route to another project, hook, or failing beneficiary
 4. held-fee accumulation followed by migration or balance depletion
@@ -128,7 +130,7 @@ Replay these sequences:
 
 ## Accepted Risks Or Behaviors
 
-- Hooks are intentionally powerful extension points; safety depends on clear sequencing and bounded trust, not on avoiding composition.
+- Hooks are intentionally powerful. Safety comes from clear ordering and bounded trust, not from avoiding composition.
 
 ## Verification
 

package/README.md

@@ -1,6 +1,6 @@
 # Juicebox Core V6
 
-`@bananapus/core-v6` is the core protocol package for Juicebox on EVM chains. It defines projects, rulesets, terminals, permissions, token issuance, cash outs, splits, price feeds, and the accounting surfaces that the rest of the V6 ecosystem builds on.
+`@bananapus/core-v6` is the base protocol package for Juicebox on EVM chains. It defines projects, rulesets, terminals, permissions, token issuance, cash outs, splits, price feeds, and the accounting that the rest of the V6 ecosystem builds on.
 
 Docs: <https://docs.juicebox.money>
 Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
@@ -12,37 +12,37 @@ Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-If a V6 package moves value, mints tokens, checks permissions, or reasons about project configuration, it almost certainly depends on this repo.
+If a V6 package moves value, mints tokens, checks permissions, or reads project configuration, it probably depends on this repo.
 
-The core package provides:
+This package provides:
 
 - project ownership and metadata through `JBProjects`
 - ruleset lifecycle management through `JBRulesets`
-- issuance, queueing, token setup, and splits through `JBController`
+- token issuance, ruleset queueing, token setup, and splits through `JBController`
 - multi-token terminal accounting through `JBMultiTerminal` and `JBTerminalStore`
 - operator permissions through `JBPermissions`
 - on-chain price-feed routing through `JBPrices`
 
-Use this repo when you need the canonical protocol accounting and execution surfaces. Do not duplicate its logic in downstream packages unless the repo is explicitly intended to wrap or extend the core surface.
+Use this repo when you need the protocol's canonical accounting and execution logic. Do not copy that logic into downstream repos unless the repo is explicitly meant to wrap or extend core.
 
-If you only read one repo before auditing the rest of the ecosystem, read this one.
+If you only read one V6 repo before reading the rest, read this one.
 
 ## Mental Model
 
-The core protocol is easiest to reason about in four layers:
+It helps to think about core in four layers:
 
 1. identity and configuration: `JBProjects`, `JBDirectory`, `JBRulesets`
 2. execution: `JBController` and `JBMultiTerminal`
 3. accounting: `JBTerminalStore`
-4. permissions and external context: `JBPermissions`, `JBPrices`, feeless-address and deadline helpers
+4. permissions and shared context: `JBPermissions`, `JBPrices`, feeless-address and deadline helpers
 
-Many integrations touch only layer 2, while many economically important bugs are easiest to understand from layer 3.
+Many integrations mostly touch layer 2. Many high-impact bugs are easier to understand in layer 3.
 
-The shortest path through the repo is:
+The shortest reading path is:
 
 1. `JBController` for project launch and ruleset configuration
-2. `JBMultiTerminal` for execution entrypoints
-3. `JBTerminalStore` for economic truth
+2. `JBMultiTerminal` for user-facing execution entrypoints
+3. `JBTerminalStore` for the accounting model
 4. `JBDirectory` and `JBPermissions` for routing and authority
 
 ## Read These Files First
@@ -58,30 +58,30 @@ The shortest path through the repo is:
 
 | Contract | Role |
 | --- | --- |
-| `JBController` | Project launch, ruleset queueing, token configuration, and split management. |
-| `JBMultiTerminal` | Main payment, payout, allowance, and cash-out terminal surface. |
-| `JBTerminalStore` | Shared accounting store for balances, surplus, fees, and reclaim calculations. |
-| `JBDirectory` | Project-to-controller and project-to-terminal routing registry. |
+| `JBController` | Launches projects, queues rulesets, configures tokens, and manages split groups. |
+| `JBMultiTerminal` | Main payment, payout, allowance, and cash-out surface. |
+| `JBTerminalStore` | Shared accounting for balances, surplus, fees, and reclaim math. |
+| `JBDirectory` | Registry for controller and terminal routing. |
 | `JBProjects` | ERC-721 project registry and ownership surface. |
-| `JBPermissions` | Packed operator permissions registry. |
-| `JBPrices` | Price feed routing used by terminals and integrations. |
+| `JBPermissions` | Packed operator-permission registry. |
+| `JBPrices` | Price-feed routing used by terminals and integrations. |
 
 ## Integration Traps
 
-- `JBMultiTerminal` is not a single-token terminal. Integrations that assume one token, one balance, or one primary path usually misread the accounting model.
-- data hooks and cash-out hooks are not cosmetic. They can change effective issuance, reclaim value, and side effects on the path.
-- permission checks are not always against the project owner. Some flows are scoped to the token holder instead.
-- previews and execution are intentionally close, but integrators should still treat them as distinct surfaces when hooks or dynamic routing are involved.
+- `JBMultiTerminal` is multi-token and multi-terminal. Do not assume one token or one balance.
+- Data hooks and cash-out hooks can change economics and side effects. They are part of the protocol surface.
+- Permission checks are not always against the project owner. Some flows are scoped to the token holder instead.
+- Preview and execution are intentionally close, but callers should still treat them as separate surfaces when hooks or routing can change behavior.
 
 ## Where State Lives
 
-- project identity and ownership live in `JBProjects`
-- controller and terminal routing live in `JBDirectory`
-- ruleset history and activation live in `JBRulesets`
-- balances, surplus, fees, and reclaim accounting live in `JBTerminalStore`
-- operator authority lives in `JBPermissions`
+- project identity and ownership: `JBProjects`
+- controller and terminal routing: `JBDirectory`
+- ruleset history and activation: `JBRulesets`
+- balances, surplus, fees, and reclaim accounting: `JBTerminalStore`
+- operator authority: `JBPermissions`
 
-When in doubt, read the state-owning contract before the contract that merely forwards into it.
+When a flow is unclear, read the contract that owns the state before the contract that forwards into it.
 
 ## High-Signal Tests
 
@@ -115,7 +115,7 @@ Useful scripts:
 
 ## Deployment Notes
 
-This repo contains both core deployments and periphery deployment helpers. Most other V6 packages assume these contracts exist first and treat them as the stable base layer of the ecosystem.
+This repo contains the main core deployments and periphery deployment helpers. Most other V6 packages assume these contracts exist first and treat them as the stable base layer.
 
 ## Repository Layout
 
@@ -132,15 +132,15 @@ script/
 
 ## Risks And Notes
 
-- hooks can meaningfully change payment and cash-out behavior, so core integrations must treat hook composition as part of the protocol surface
-- permissions are flexible enough to be dangerous when scoped broadly or granted with wildcard project IDs
-- multi-terminal and multi-token accounting is powerful but increases the chance of integration mistakes when callers assume a single-terminal model
-- fee, surplus, and reclaim logic are economically sensitive and remain high-priority audit surfaces
+- Hooks can materially change payment and cash-out behavior.
+- Permissions are flexible, which makes broad or wildcard grants risky.
+- Multi-terminal and multi-token accounting is powerful, but it is easy to misuse if an integration assumes a single-terminal model.
+- Fee, surplus, and reclaim logic stay high-priority audit areas.
 
-The fastest way to misunderstand V6 is to treat the core contracts like a simple crowdfunding terminal. They are closer to a configurable accounting and settlement substrate.
+The easiest way to misread V6 is to treat core like a simple crowdfunding terminal. It is closer to a configurable accounting and settlement layer.
 
 ## For AI Agents
 
-- Start with `JBController`, `JBMultiTerminal`, and `JBTerminalStore`; do not summarize core behavior from helper libraries alone.
-- Distinguish controller configuration from terminal execution and from store accounting.
-- If a behavior involves hooks, inspect the hook repo too before treating the preview or execution path as canonical.
+- Start with `JBController`, `JBMultiTerminal`, and `JBTerminalStore`.
+- Keep controller configuration, terminal execution, and store accounting separate in your mental model.
+- If hooks are involved, inspect the hook repo before treating preview or execution behavior as final.