more mech docs touches + publish client docs (#100)

* wip

* wip

* wip

* wip

Author: MichaelTrestman

docs/sdk/subtensor-api.md

@@ -74,6 +74,36 @@ print(sub.delegates.get_delegate_identities())
 sub.chain.tx_rate_limit()
 ```
 
+### Mechanism helpers (multiple incentive mechanisms)
+
+Subnets can run multiple incentive mechanisms. The API adds helpers and optional `mechid` on key calls.
+
+- New getters:
+  - `get_mechanism_count(netuid)` → int
+  - `get_mechanism_emission_split(netuid)` → list[int] or None (even split implied)
+  - `is_in_admin_freeze_window(netuid)` → bool
+- Mechanism-aware methods now accept `mechid` (default `0`):
+  - `set_weights`, `commit_weights`, `reveal_weights`, `weights`, `bonds`, `get_metagraph_info`, `get_all_metagraphs_info(all_mechanisms=False)`
+
+```python
+import bittensor as bt
+
+sub = bt.SubtensorApi()
+netuid = 14
+
+count = sub.get_mechanism_count(netuid=netuid)
+split = sub.get_mechanism_emission_split(netuid=netuid)
+
+# Set weights for mechanism 1
+ok, msg = sub.set_weights(
+    wallet=bt.Wallet("alice"),
+    netuid=netuid,
+    mechid=1,
+    uids=[0,1,2],
+    weights=[1,1,1],
+)
+```
+
 ### Asynchronous
 
 ```python

docs/subnets/managing-mechanisms-btcli.md

@@ -6,19 +6,25 @@ title: "Managing Multiple Incentive Mechanisms with BTCLI"
 
 This tutorial shows how to configure and manage multiple incentive mechanisms in a single subnet using BTCLI.
 
-For background on the concepts, see [Understanding Multiple Incentive Mechanisms](understanding-multiple-mech-subnets).
+For a discussion of the background concepts, see [Understanding Multiple Incentive Mechanisms](understanding-multiple-mech-subnets).
 
 See also: [Managing Mechanisms with SDK](managing-mechanisms-with-sdk).
 
+:::tip Hot new feature
+Multiple incentive mechanisms per subnet is a new feature that is still in development. It's initial release on mainnet is expected the week of September 22. In the meantime, it can be experimented with using a locally run chain.
+
+See [Announcements](../learn/announcements) for updates.
+:::
+
 **Prerequisites**
 - A local Subtensor chain running. See: [Run a Local Bittensor Blockchain Instance](../local-build/deploy)
 - A local subnet created (and emissions started). See: [Create a Subnet (Locally)](../local-build/create-subnet)
 - Wallets provisioned and funded for local development. See: [Provision Wallets](../local-build/provision-wallets)
 - BTCLI installed (development version required for mechanism commands)
 
-::::tip
+:::tip
 Substitute your subnet's netuid, which you can find with `btcli subnet list`.
-::::
+:::
 
 :::warning Runtime limit
 As of the current Subtensor runtime, a subnet can have a maximum of 2 mechanisms. Attempts to set a higher count will be rejected by the chain (runtime enforces `MaxMechanismCount = 2`).

docs/subnets/managing-mechanisms-with-sdk.md

@@ -10,6 +10,11 @@ For background on the concepts, see [Understanding Multiple Incentive Mechanisms
 
 See also [Managing Mechanisms with BTCLI](./managing-mechanisms-btcli).
 
+:::tip Hot new feature
+Multiple incentive mechanisms per subnet is a new feature that is still in development. It's initial release on mainnet is expected the week of September 22. In the meantime, it can be experimented with using a locally run chain.
+
+See [Announcements](../learn/announcements) for updates.
+:::
 
 **Prerequisites**
 - A local Subtensor chain running. See: [Run a Local Bittensor Blockchain Instance](../local-build/deploy)

docs/subnets/metagraph.md

@@ -71,6 +71,30 @@ m = Metagraph(netuid=14, network="finney", sync=True)
 m = Metagraph(netuid=14, network="finney", lite=False, sync=True)
 ```
 
+### Mechanism-aware metagraphs (multiple incentive mechanisms)
+
+Subnets can run multiple incentive mechanisms. The SDK supports selecting a mechanism and exposes mechanism-related fields:
+
+- Metagraph accepts a `mechid` parameter (default `0`).
+- New fields: `mechid: int`, `mechanisms_emissions_split: list[int]`, `mechanism_count: int`.
+
+```python
+from bittensor.core.metagraph import Metagraph
+
+# Default mechanism (0)
+meta = Metagraph(netuid=14, network="finney", sync=True)
+print(meta.mechid)  # 0
+print(meta.mechanism_count)  # e.g., 2
+print(meta.mechanisms_emissions_split)  # e.g., [60, 40]
+
+# Specific mechanism (1)
+mech_meta = Metagraph(netuid=14, network="finney", sync=True, lite=False)
+mech_meta.mechid = 1
+await mech_meta.sync()  # or re-init with mechid in helper constructors
+```
+
+See also: [Multiple Incentive Mechanisms Within Subnets](./understanding-multiple-mech-subnets.md).
+
 ### Smart Contract Access (Metagraph Precompile)
 
 For smart contract integration, you can access metagraph data through the **Metagraph Precompile** at address `0x0000000000000000000000000000000000000802`. This provides read-only access to individual neuron metrics and network information.

docs/subnets/understanding-multiple-mech-subnets.md

@@ -9,11 +9,17 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 This page explores how subnets can implement multiple incentive mechanisms to distribute emissions across different evaluation criteria.
 
+:::tip Hot new feature
+Multiple incentive mechanisms per subnet is a new feature that is still in development. It's initial release on mainnet is expected the week of September 22. In the meantime, it can be experimented with using a locally run chain.
+
+See [Announcements](../learn/announcements) for updates.
+:::
+
 For an introduction to incentive mechanisms in general, see [Understanding Incentive Mechanisms](../learn/anatomy-of-incentive-mechanism). For the basics of subnets, miners, validators, and the blockchain, see [Components of the Bittensor platform](../learn/neurons).
 
-<!-- For procedural coverage, see: -->
-<!-- - [Managing Mechanisms with SDK](managing-mechanisms-with-sdk) -->
-<!-- - [Managing Mechanisms with BTCLI](./managing-mechanisms-btcli) -->
+For coverage of the procedures involved, see:
+- [Managing Mechanisms with SDK](./managing-mechanisms-with-sdk)
+- [Managing Mechanisms with BTCLI](./managing-mechanisms-btcli)
 
 Historically, each subnet operates with a single **incentive mechanism**, a function that validators run to assign weights to miners based on the value of their work. Subnets can now support **multiple incentive mechanisms**, allowing a subnet creator to apportion the subnet's emissions across different evaluation criteria, each running Yuma Consensus _independently_ with separate bond pools to evaluate miners' performance on distinct tasks.
 

sidebars.js

@@ -135,8 +135,8 @@ const sidebars = {
         "subnets/subnet-creators-btcli-guide",
         "subnets/subnet-hyperparameters",
         "subnets/working-with-subnets",
-        // "subnets/managing-mechanisms-with-sdk",
-        // "subnets/managing-mechanisms-btcli",
+        "subnets/managing-mechanisms-with-sdk",
+        "subnets/managing-mechanisms-btcli",
         "subnets/uid-trimming",
         "subnets/subnet-deregistration",
         "subnets/walkthrough-prompting",