@bananapus/core-v6 0.0.34 → 0.0.36

package/ARCHITECTURE.md

@@ -2,49 +2,75 @@
 
 ## Purpose
 
-`nana-core-v6` is the protocol root. It owns project identity, permissions, rulesets, token supply, treasury balances, payout limits, fee logic, and the hook interfaces that 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 behavior, terminal routing, or permission semantics, this is the repo that defines the source of truth.
+If a change affects accounting, token supply, fees, terminal routing, or permission semantics, this repo is the source of truth.
 
-## Boundaries
+## System Overview
 
-- The core owns balance and supply transitions.
-- Extensions may adjust economics through hooks, but they should not invent competing ledgers.
-- The core deliberately avoids app-specific behaviors like NFT composition, DEX routing strategy, or bridge-specific message transport.
+`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.
 
-## Main Components
+`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.
 
-| Component | Responsibility |
-| --- | --- |
-| `JBMultiTerminal` | Entry point for payments, cash outs, payouts, balance additions, and fee handling |
-| `JBTerminalStore` | Bookkeeping and preview math for payment, payout, allowance, and cash-out paths |
-| `JBController` | Project launch, ruleset queueing, token minting and burning, split-group updates |
-| `JBDirectory` | Maps projects to controllers and terminals |
-| `JBRulesets` | Time-ordered ruleset lifecycle and approval-hook integration |
-| `JBTokens`, `JBERC20`, `JBProjects` | Token and project identity surfaces |
-| `JBSplits`, `JBFundAccessLimits`, `JBPrices`, `JBPermissions` | Shared state for distribution, limits, price conversion, and authorization |
+## Core Invariants
 
-## Runtime Model
+- 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 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 entrypoints | Execution surface |
+| `JBTerminalStore` | Shared accounting and preview math | Economic source of truth |
+| `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 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
 
 ### Payment
 
 ```text
 terminal receives funds
-  -> terminal store reads the current ruleset and optional data hooks
-  -> store computes weight-based minting results
+  -> terminal store reads the active ruleset and optional data hooks
+  -> 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 execute only after settlement
+  -> pay hooks run after settlement
 ```
 
 ### Cash Out
 
 ```text
 holder requests redemption
-  -> terminal store computes reclaim amount from surplus, supply, and tax settings
-  -> optional data hooks can adjust the calculation inputs
+  -> 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 the reclaim amount and routes protocol fees
-  -> cash-out hooks execute only after settlement
+  -> terminal pays reclaim value and routes protocol fees
+  -> cash-out hooks run after settlement
+```
+
+### Launch And Queue Rulesets
+
+```text
+owner, operator, or omnichain ruleset operator
+  -> controller launches or queues rulesets
+  -> 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
@@ -53,32 +79,55 @@ holder requests redemption
 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 and may add fee-free surplus
 ```
 
-## Critical Invariants
+## 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 they should not duplicate them.
 
-- Preview functions must remain behaviorally aligned with state-changing functions.
-- Data hooks run before settlement and may alter the economics; pay and cash-out hooks run after settlement. That phase boundary is intentional.
-- Reserved tokens and pending reserves affect supply-sensitive math even before distribution.
-- Terminal balances, fee accounting, and surplus calculations must agree. Any drift here contaminates every product repo.
-- Rulesets are time-ordered and approval-aware; deployment wrappers depend on predictable ID progression and activation semantics.
-- Permission checks are not a UI concern. They are part of protocol state transition validity.
+`JBTerminalStore` keeps terminal balances, payout-limit usage, and surplus-allowance usage. Those reset boundaries are not the same:
 
-## Where Complexity Lives
+- payout-limit usage is tracked by ruleset cycle number
+- surplus-allowance usage is tracked by `ruleset.id`
 
-- `JBMultiTerminal`, `JBTerminalStore`, and `JBController` form one accounting pipeline and are easiest to misunderstand when read separately.
-- Preview paths deliberately mirror state-changing paths; keeping them aligned is a permanent maintenance burden.
-- Fee-free surplus, held fees, and payout/allowance interactions create edge cases that are small in code size but large in blast radius.
+If a duration-based ruleset auto-cycles without a new ruleset ID, payout-limit usage resets but allowance usage does not.
 
-## Dependencies
+## Security Model
 
-- `nana-permission-ids-v6` for the shared permission namespace
-- OpenZeppelin, PRBMath, Chainlink, and Permit2 for standards and math utilities
+- 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.
+- `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
 
-- Start any nontrivial change by tracing both the preview path and the state-changing path.
-- Read downstream hook repos before changing hook interfaces or metadata expectations.
-- Keep fee logic, balance logic, and surplus logic in sync; "small" tweaks here are almost always ecosystem-wide changes.
-- When adding permissions or changing who is checked against a permission, update ecosystem docs and downstream assumptions immediately.
-- If a change seems local inside core, assume it is not until proven otherwise.
+- 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 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
+
+- fee-free surplus and same-terminal payout behavior:
+  `test/TestFeeFreeCashOutBypass.sol`
+- migration and terminal-accounting continuity:
+  `test/TestTerminalMigration.sol`
+- ruleset ordering and transition behavior:
+  `test/RulesetTransitions.t.sol`
+
+## Source Map
+
+- `src/JBController.sol`
+- `src/JBMultiTerminal.sol`
+- `src/JBTerminalStore.sol`
+- `src/JBDirectory.sol`
+- `src/JBRulesets.sol`
+- `src/JBPermissions.sol`
+- `test/TestFeeFreeCashOutBypass.sol`
+- `test/TestTerminalMigration.sol`
+- `test/RulesetTransitions.t.sol`

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.
 
-## Objective
+## 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,112 +43,97 @@ 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
 
-## System Model
+## 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
-
-## Critical Invariants
+Ordering to keep in mind:
 
-1. Terminal solvency
-Internal balances and held-fee obligations must reconcile with actual terminal token balances.
+- 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
 
-2. No over-withdrawal
-Payouts and allowance usage must never exceed configured per-cycle limits.
+## Roles And Privileges
 
-3. Cash-out correctness
-Surplus, total supply, tax rate, fee treatment, and hook overrides must combine into the intended reclaim amount.
+| 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 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 |
 
-4. Ruleset integrity
-The active ruleset and any fallback or cycling behavior must reflect exact timing and approval-hook semantics.
+## Integration Assumptions
 
-5. Token accounting consistency
-Credits, ERC-20 total supply, reserved token balance, and burn/mint paths must remain internally coherent.
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| Price feeds | Currency conversions are fresh and coherent | Cross-currency flows misprice |
+| Hook ecosystem | External hooks obey documented interfaces | Settlement becomes unsafe after control transfer |
+| Directory and migration surfaces | Canonical routing changes are authentic | Funds or permissions shift to the wrong place |
 
-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.
-
-## Threat Model
-
-Prioritize:
-- hook-driven reentrancy or state-ordering issues
-- price-feed failure and cross-currency conversions
-- fee-processing failure paths
-- migration and feeless-address edge cases
-- ruleset-boundary timing attacks
-- wildcard or root permission escalation
-
-The highest-yield attacker mindsets here are:
-- a malicious hook that receives control after balances move but before the full user flow is conceptually finished
-- a project owner exploiting migration, limits, or feeless settings rather than breaking access control directly
-- a cross-currency user extracting value from rounding or stale price conversions
+## Critical Invariants
 
-## Hotspots
+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
 
 - `pay`, `cashOutTokensOf`, `sendPayoutsOf`, and `useAllowanceOf`
 - `preview*` paths when downstream repos treat them as execution truth
 - held-fee lifecycle and `_processFee`
 - surplus aggregation across terminals
 - controller migration and terminal migration
-- `setPermissionsFor` and any wildcard semantics
+- `setPermissionsFor` and wildcard semantics
 
-## Sequences Worth Replaying
+Replay these sequences:
 
-1. `pay` with a data hook that returns altered weight and hook specs, then re-enter through a pay hook.
-2. `cashOutTokensOf` when `useTotalSurplusForCashOuts` or cross-terminal surplus logic matters.
-3. `sendPayoutsOf` into splits that route to another project, hook, or failing beneficiary.
-4. held-fee accumulation -> migration or balance depletion -> `processHeldFeesOf`.
-5. permission grants involving operators, wildcard project IDs, or later controller changes.
+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
+5. permission grants involving operators, wildcard project IDs, or later controller changes
 
-## Finding Bar
+## Accepted Risks Or Behaviors
 
-The best findings in this repo usually prove one of these:
-- the store records more value than the terminal can safely honor
-- a limit is consumed too late, after externally controlled code can already profit
-- a migration or held-fee edge path changes who ultimately bears an obligation
-- permissions that look project-scoped become ecosystem-relevant through wildcard or routing semantics
+- Hooks are intentionally powerful. Safety comes from clear ordering and bounded trust, not from avoiding composition.
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-The current test suite already targets:
-- flash-loan and economic exploits
-- permissions invariants
-- ruleset transitions
-- fee and migration edge cases
-- multi-token and cross-currency surplus behavior
-
-The highest-value findings in this repo are the ones that make downstream hooks or deployers unsafe even when those repos are otherwise correct.

package/README.md

@@ -1,43 +1,48 @@
 # 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)
+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
 
-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 invariant. 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
 
-Most integrations touch only layer 2. Most economically important bugs leak through 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
@@ -53,30 +58,38 @@ 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
+
+1. `test/TestPayBurnRedeemFlow.sol`
+2. `test/TestTerminalPreviewParity.sol`
+3. `test/invariants/TerminalStoreInvariant.t.sol`
+4. `test/invariants/RulesetsInvariant.t.sol`
+5. `test/audit/CrossTerminalSurplusSpoof.t.sol`
 
 ## Install
 
@@ -102,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
 
@@ -119,9 +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 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
 
-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.
+- 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.