add governance and switch to balancer amms

docs/btcli/btcli-permissions.md

@@ -438,7 +438,7 @@ The `btcli crowd` commands are used to create and manage crowdloans on the netwo
 
 ### `liquidity`
 
-The `btcli liquidity` commands are used to provide and manage trading liquidity for specific subnets. For more information, see [Liquidity positions](../liquidity-positions/liquidity-positions.md).
+The `btcli liquidity` commands were used to manage user liquidity positions. User LP positions are currently disabled on-chain. Subnet pools now use protocol-owned liquidity managed by the [Balancer weighted pool AMM](../learn/balancer-amm.md).
 
 - **`liquidity add`**: Add liquidity to the swap (as a combination of TAO + Alpha).
 - **`liquidity list`**: Shows a wallet's liquidity positions in given subnet.

docs/governance/governance.md

@@ -1,66 +1,151 @@
 ---
-title: "Governance Overview"
+title: "Governance"
 ---
 
-import { SdkVersion } from "../sdk/_sdk-version.mdx";
+# Governance
 
-# Governance Overview
+Bittensor on-chain governance, live as of June 24th, 2026, replaces sudo-based operational control with a two-stage referendum system. All root calls — protocol changes, runtime upgrades, and other privileged operations — reach the chain only after passing through both stages.
 
-Bittensor's governance protocol transitions the management of the network from centralization within the foundation to community ownership over time.
+## Collectives
 
-The first stage of this transition to decentralized management is the creation of a bicameral legislature. In this stage, the [Triumvirate](../resources/glossary.md#triumvirate) creates proposals for the [Senate](./senate.md) to approve.
+Governance is organized around five named on-chain collectives managed by `pallet-multi-collective`:
 
-Triumvirate members are Opentensor Foundation employees, while the Senate is formed from the top K delegate hotkeys.
+| Collective | Size | Selection | Role |
+|---|---|---|---|
+| **Proposers** | 1–20 | Curated (root-assigned) | Submit proposals |
+| **Triumvirate** | 3 (fixed) | Curated (root-assigned) | First-stage approval |
+| **Economic** | 16 (fixed) | Rotating every 60 days | Review-stage voting |
+| **Building** | 16 (fixed) | Rotating every 60 days | Review-stage voting |
+| **EconomicEligible** | ≤64 | Auto-synced from root registrations | Candidate pool for Economic |
 
-## Proposals
+## Proposal Flow
 
-Proposals are encapsulations of other extrinsics and will be executed only after meeting both of the two conditions:
+### Stage 1: Triumvirate track
 
-1. The proposal has obtained (50% + 1) approvals from the Senate, and
-2. A member of the Triumvirate has closed the proposal.
+A member of the **Proposers** collective submits a root call. The proposal enters the Triumvirate track:
 
-The above guarantees that the Senate must reach a majority consensus to execute a proposal.
+- The three Triumvirate members have **7 days** to vote.
+- **2-of-3 aye votes**: proposal advances to the review track.
+- **2-of-3 nay votes** or timeout: proposal is rejected and cleaned up.
 
-:::tip Execution of a proposal
-When a proposal is executed, the calldata passed to it during its creation are included in the same block as the close extrinsic.
-:::
+### Stage 2: Review track
 
-## Security
+On Triumvirate approval, the proposal enters a delay period. The voter set is the **deduplicated union of the Economic and Building collectives** (at most 32 members). The voter set is snapshotted at the moment the review period opens — collective rotations during the delay do not change who may vote or shift the thresholds.
 
-Before the governance protocol existed, all administrative actions within the network (e.g., changing hyperparameters, creating new subnetworks, chain upgrades) required permission via a single privileged key, known as `sudo`. If the `sudo` private key were somehow compromised, a malicious actor could take over the network and execute any privileged extrinsics.
+The delay starts at **24 hours** and can extend to a **2-day maximum** as nay votes accumulate, following an ease-out adjustment curve. When the adjusted delay drops below the time already elapsed, execution begins.
 
-Under the governance protocol, a malicious actor would have to compromise a Triumvirate member and control a majority of Senate seats in order to approve a proposal.
+During the delay period, voters may:
 
-## Example
+- **Fast-track**: 75% or more aye votes → executes at the next block.
+- **Cancel**: 51% or more nay votes → proposal cancelled and cleaned up.
+- Otherwise the proposal executes when the delay period expires.
 
-Consider the following:
+### Execution
 
-- The Triumvirate contains three seats, with members `Alice`, `Bob`, and `Charlie`.
-- The Senate has three members elected to participate: `Dave`, `Eve`, and `Ferdie`.
+The chain dispatches the call with root privilege through an atomic enact wrapper. If the call fails it is not retried and is cleaned up. A stale scheduler entry on a terminated referendum cannot dispatch its inner call.
 
-**Triumvirate**
+![On-Chain Governance: Proposal Flow](/img/docs/proposal-flow.svg)
 
-`Bob` has a novel concept for a subnet and wishes to deploy it on the Bittensor network. `Bob` creates a proposal with the calldata:
+<!-- @startuml
+title On-Chain Governance: Proposal Flow
 
-<SdkVersion />
+skinparam shadowing false
+skinparam defaultFontName Monospace
+skinparam sequence {
+  LifeLineBorderColor #444444
+  ParticipantBorderColor #444444
+  ParticipantBackgroundColor white
+  ArrowColor #444444
+}
 
-```python
-SubtensorModule.SudoAddNetwork(netuid, tempo, modality)
-```
+actor "Proposers Collective\n(1–20 members)" as P
+actor "Triumvirate\n(3 members)" as T
+actor "Review Collective\n(Economic ∪ Building, ≤32)" as RC
+database "Chain" as C
 
-and sends the transaction to the network in order to broadcast the proposal.
+== Proposal Submission ==
+note over P
+A member of the Proposers collective submits a root call
+(protocol change, runtime upgrade, or other privileged operation).
+end note
+P -> C: submit_proposal(call)
 
-**Senate**
+note over C
+Proposal enters Triumvirate track.
+end note
 
-- `Dave`, `Eve`, and `Ferdie` all own the nominated delegate hotkeys, and they individually control more than two percent of the network's total stakes.
-- Using `btcli`, they can view the proposal and the calldata, which it will execute upon approval.
-- `Dave` and `Ferdie` decided they wanted to approve this new subnet, and they both approved the proposal.
-- `Eve` disagrees with the concept and disapproves of the proposal.
+== Triumvirate Track (7 days) ==
+group #LightSkyBlue 7-day decision window\n2-of-3 ayes advance · 2-of-3 nays reject
+  T -> C: vote(aye/nay)
 
-Even though the Senate may have twelve members at any time, it is not guaranteed that there will be twelve occupied seats. With a Senate size of three, the approval threshold will be two approvals. Since `Dave` and `Ferdie` both approved this proposal, a member of the Triumvirate can now execute it.
+  opt 2-of-3 ayes reached
+    C -> C: advance to review track
 
-**Closing**
+  else 2-of-3 nays reached OR 7-day timeout
+    C -> C: reject
+  end
+end group
 
-`Alice` sees Senate has passed the proposal and executes the `close` extrinsic to execute the calldata within the proposal.
+== Review Track ==
 
-Bittensor now has a new subnet on which `Alice`, `Bob`, or `Charlie` can create further proposals to change hyperparameters, allow or disallow registration, and control any other configuration previously controlled by the `sudo` private key.
+group #LightGreen 24h initial delay / 2-day max\nVoter set: deduplicated union of Economic and Building
+  RC -> C: vote(aye/nay)
+
+  opt Fast-track
+    C -> C: 75% or more aye votes → execute at next block
+  end
+
+  opt Cancel
+    C -> C: 51% or more nay votes → proposal cancelled
+  end
+
+  opt Delay adjustment
+    C -> C: recompute delay (ease-out curve) as nay votes accumulate
+  end
+end group
+
+note right of C
+Voter eligibility is snapshotted at review-track open.
+Collective rotations during the period do not change
+who may vote or shift the thresholds.
+When the adjusted delay drops below elapsed time,
+execution begins.
+end note
+
+== Execution ==
+note over C
+After the delay period expires (and if not cancelled),
+the chain executes the call with root privilege.
+If execution fails, it is not retried and is cleaned up.
+end note
+
+C -> C: execute(call as Root)
+alt success
+  C -> C: cleanup
+else failure
+  C -> C: cleanup (no retry)
+end
+
+@enduml
+-->
+
+## Collective Membership
+
+### Proposers and Triumvirate
+
+Both are curated: members are added, removed, or swapped by root governance. The Triumvirate is fixed at 3 seats. Previously the Triumvirate held sudo access directly; under the new system it is the first stage of the referendum process with no direct sudo.
+
+### Economic collective
+
+The Economic collective is selected from the **EconomicEligible** pool every 60 days. The top 16 EconomicEligible coldkeys by stake EMA value take the seats. If fewer than 16 eligible coldkeys are available, the rotation fails safely and the previous membership remains in place.
+
+**EconomicEligible** membership is auto-synced with root registration state. When a coldkey's root-registered hotkey count goes from 0 to 1, the coldkey is added to EconomicEligible. The EMA tracks a combined stake value per coldkey: liquid TAO plus the TAO value of alpha across all owned hotkeys, sampled incrementally each block (8 subnets and ≤256 hotkeys per tick, decay factor alpha=0.02). A 210-sample warmup of approximately 30 days is required before a coldkey becomes eligible for selection.
+
+### Building collective
+
+The Building collective is selected every 60 days. The top 16 subnet-owner coldkeys by their best subnet's moving price take the seats, subject to:
+
+- Subnets younger than 180 days are excluded.
+- At most one seat per coldkey regardless of how many qualifying subnets they own.
+
+If fewer than 16 eligible coldkeys are available, the rotation fails safely and the previous membership remains in place.

docs/governance/senate.md

@@ -3,46 +3,3 @@ title: "Senate"
 ---
 
 # Senate
-
-The Senate is a group of delegates who have elected to participate in proposals, and who control a significant portion of total network stake.
-
-All members of the network who have delegated stake to any of these Senate members are represented by the party that controls the delegate they've chosen to stake with. This allows any holder within the network to be represented, and to make their opinion known by delegating with organizations who represent their interests.
-
-## Requirements
-
-In order to participate in the Senate, a coldkey must:
-
-- Have registered with any subnetwork as a hotkey-coldkey pair.
-- Have a hotkey stake value is greater than 2% of the network's total stake amount, through delegation or self-stake.
-- Have elected to participate in the Senate.
-<!-- how ??? -->
-
-Once all four of the requirements have been fulfilled by a coldkey-hotkey pair, they can vote on any proposal created by the [Triumvirate](../resources/glossary#triumvirate).
-
-In the case that the Senate has all twelve seats filled, and a delegate wishes to join, they will replace the lowest stake member as long as they have more stake in the network.
-
-<!-- ## Joining the senate
-
-
-How ??? How do you get on the `btcli sudo senate` list?
-How do you get to `btcli sudo senate-vote` ? Under what conditions will this command succeed?
-
- -->
-
-## Viewing proposals
-
-Anyone can view proposals currently before the senate. This is an unpermissioned request.
-
-```shell
-btcli sudo proposals
-```
-
-## Voting
-
-Senators can vote using the following command. You will be prompted for the proposal hash, which can be obtained in the proposals overview using `btcli sudo proposals`.
-
-After entering a proposal hash, you will then be prompted to either cast an approval or a disapproval. Once confirmed, the vote will be included in the next block and counted in the vote.
-
-```
-btcli sudo senate-vote
-```