notes on governance/decentralization transition and roadmap

docs/btcli/btcli-permissions.md

@@ -2,6 +2,10 @@
 title: "Bittensor CLI: Permissions Guide"
 ---
 
+import { GovernanceTransitionalState } from "../governance/_governance-transitional-state.mdx";
+
+<GovernanceTransitionalState />
+
 The Bittensor CLI, `btcli` provides a wide range of functionality, and has a range of different requirements for various commands: some require a coldkey private key to authenticate, some require a hotkey private key, and some require neither. Additionally, different functions require different levels of permissions. Some require the user to have special status like being registered with a node, have a validator permit, or be an active member of the senate.
 
 This page details the requirements for all of the `btcli` commands.

docs/btcli/btcli.md

@@ -2,8 +2,12 @@
 title: "Bittensor CLI: btcli Reference Document"
 ---
 
+import { GovernanceTransitionalState } from "../governance/_governance-transitional-state.mdx";
+
 # Bittensor CLI: `btcli` Reference Document
 
+<GovernanceTransitionalState />
+
 Command line interface (CLI) for Bittensor. Uses the values in the configuration file. These values can be overriden by passing them explicitly in the command line.
 
 See [Getting Started](../getting-started/install-btcli.md) to install `btcli`.

docs/governance/_governance-transitional-state.mdx

@@ -0,0 +1,13 @@
+/*
+Governance Transitional State Notice Partial
+*/
+
+import Admonition from '@theme/Admonition';
+
+export const GovernanceTransitionalState = () => (
+  <Admonition type="info" title="Governance in Transition">
+    <p>
+      Bittensor governance is currently in a <strong>transitional state</strong> as the network moves toward full decentralization. For details on planned governance changes, see the <a href="../learn/roadmap">Bittensor Roadmap</a>.
+    </p>
+  </Admonition>
+);

docs/governance/governance.md

@@ -1,66 +1,11 @@
 ---
-title: "Governance Overview"
+title: "Governance"
 ---
 
 import { SdkVersion } from "../sdk/_sdk-version.mdx";
+import { GovernanceTransitionalState } from "./_governance-transitional-state.mdx";
 
-# Governance Overview
+# Governance
 
-Bittensor's governance protocol transitions the management of the network from centralization within the foundation to community ownership over time.
+<GovernanceTransitionalState />
 
-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.
-
-Triumvirate members are Opentensor Foundation employees, while the Senate is formed from the top K delegate hotkeys.
-
-## Proposals
-
-Proposals are encapsulations of other extrinsics and will be executed only after meeting both of the two conditions:
-
-1. The proposal has obtained (50% + 1) approvals from the Senate, and
-2. A member of the Triumvirate has closed the proposal.
-
-The above guarantees that the Senate must reach a majority consensus to execute a proposal.
-
-:::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.
-:::
-
-## Security
-
-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.
-
-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.
-
-## Example
-
-Consider the following:
-
-- The Triumvirate contains three seats, with members `Alice`, `Bob`, and `Charlie`.
-- The Senate has three members elected to participate: `Dave`, `Eve`, and `Ferdie`.
-
-**Triumvirate**
-
-`Bob` has a novel concept for a subnet and wishes to deploy it on the Bittensor network. `Bob` creates a proposal with the calldata:
-
-<SdkVersion />
-
-```python
-SubtensorModule.SudoAddNetwork(netuid, tempo, modality)
-```
-
-and sends the transaction to the network in order to broadcast the proposal.
-
-**Senate**
-
-- `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.
-
-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.
-
-**Closing**
-
-`Alice` sees Senate has passed the proposal and executes the `close` extrinsic to execute the calldata within the proposal.
-
-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.

docs/governance/senate.md

@@ -2,47 +2,8 @@
 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
+import { GovernanceTransitionalState } from "./_governance-transitional-state.mdx";
 
+# 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
-```
+<GovernanceTransitionalState />

docs/governance/senators-btcli-guide.md

@@ -2,8 +2,12 @@
 title: "Senator's Guide to `BTCLI`"
 ---
 
+import { GovernanceTransitionalState } from "./_governance-transitional-state.mdx";
+
 # Senator's Guide to `BTCLI`
 
+<GovernanceTransitionalState />
+
 Governance participants (senate members, sudo-level accounts) can propose changes, cast votes, or execute privileged commands that affect the entire network. They must have a **coldkey** with the relevant governance role (senate membership or sudo privileges).
 
 See [Requirements for Senate participation](./senate)