docs: Batch 7 — governance deep dives

[marc0olo]

Summary

• Expanded: `docs/concepts/governance.md` — added 5 new sections: neuron hotkeys, following rules (thresholds, catch-all, periodic confirmation), voting thresholds (absolute majority / 3% quorum), maturity operations (disburse/stake/auto-stake + modulation formula), voting rewards formula R(t), and the Neurons' Fund (with disabled status note)
• New reference: `docs/references/nns-proposal-types.md` — all 11 NNS proposal topics and their proposal types with descriptions, derived from the full Learn Hub staging article
• New concept page: `docs/concepts/sns-framework.md` — SNS architecture (SNS-W, upgrade paths, SNS subnet), launch process (swap mechanics, min/max thresholds, fallback), SNS neurons (public, flexible permissions, configurable voting power), SNS proposals (critical vs non-critical topics, built-in + custom proposals), configurable voting rewards; includes SNS rewards graph image
• New reference: `docs/references/sns-settings.md` — full `NervousSystemParameters` reference with types and descriptions for all fields (renamed from `sns-dao-settings.md` to match the "SNS Settings" title)
• Updated: `docs/guides/governance/managing.md` — replaced 2 Learn Hub links with internal paths (`references/sns-settings.md` and `concepts/sns-framework.md#sns-neurons`)
• Updated: `sidebar.mjs` — added `concepts/sns-framework`, `references/nns-proposal-types`, `references/sns-settings`
• Deleted: 14 consumed Learn Hub staging files (7 from `nns/`, 7 from `sns/`)

Staging files deleted

• `.migration/learn-hub/how-does-icp-work/nns/{overview,neurons,proposals,neuron-attributes,neurons-fund-nf,voting-rewards,proposal-topics-and-types}.md`
• `.migration/learn-hub/how-does-icp-work/sns/{sns-service-nervous-system,framework-and-architecture,launch,neurons,proposals,rewards,dao-settings}.md`

Sync recommendation

`governance.md` additions: `informed by Learn Hub articles "Overview", "Neurons", "Proposals", "Neuron Attributes", "Neurons' Fund (NF)", "Voting Rewards" (migrated, source retired)`
`nns-proposal-types.md`: `informed by Learn Hub article "Proposal Topics and Types" (migrated, source retired)`
`sns-framework.md`: `informed by Learn Hub articles "SNS — Service Nervous System", "Framework and Architecture", "Launch", "Neurons", "Proposals", "Rewards" (migrated, source retired)`
`sns-settings.md`: `informed by Learn Hub article "DAO Settings" (migrated, source retired)`

[marc0olo]

Review notes

Two issues to fix before merge:

1. Em-dashes in sns-framework.md (banned per CLAUDE.md): Three numbered step labels use em-dashes:

• **Step 1 — NNS proposal:**
• **Step 2 — SNS canisters deployed:**
• **Step 3 — Decentralization swap:**

Replace the em-dash with a colon in each (e.g. **Step 1: NNS proposal**).

2. Unverified parameter values in governance.md: An HTML comment on the NNS voting power bonus values (2x at 8 years, 1.25x at 4 years) flags that these were inferred from SNS defaults rather than confirmed from NNS source material. The comment should be resolved (values verified or corrected against the NNS spec) and removed before merge.

No other issues: all 4 new pages have correct frontmatter, all internal links resolve, guides/governance/managing.md cross-links correctly updated, <!-- Upstream: --> comment present on all new files.

[marc0olo]

Review feedback

1. Em-dashes in sns-framework.md (lines 27, 29, 31)

Em-dashes are banned project-wide. Please replace:

• **Step 1 — NNS proposal:** → **Step 1: NNS proposal**
• **Step 2 — SNS canisters deployed:** → **Step 2: SNS canisters deployed**
• **Step 3 — Decentralization swap:** → **Step 3: Decentralization swap**

2. Unresolved verification comment in governance.md (line 47)

The comment <!-- Needs human verification: NNS neuron voting power bonus percentages (2x at 8 years, 1.25x at 4 years) --> must be resolved before merge. The values match SNS default parameters in the sns-launch skill but are not explicitly confirmed in the portal NNS source material. Please verify these multipliers against the NNS governance canister parameters and remove the comment before merging.

3. "dapp" in prose in sns-framework.md

The file uses "dapp" 7 times in prose. The two uses in official protocol topic names ("Critical Dapp Operations", "Dapp Canister Management") are correct identifiers and must stay. However, prose occurrences like "the community governs the dapp", "governed dapp canisters", and "active dapp users" should use "app" for consistency with the rest of the governance section.

[marc0olo]

Content accuracy follow-up (separate from the earlier style comment):

governance.md — incorrect minimum stake to submit proposals

The page states "Minimum stake to submit proposals is 10 ICP with at least 6 months of dissolve delay." The source material does not support this. The minimum stake to create a neuron is 1 ICP. The only hard prerequisite for voting or submitting proposals is a dissolve delay of at least 6 months. The 10 ICP figure is specific to RegisterKnownNeuron proposals, not proposals in general. Please correct this: the general prerequisite is 6 months dissolve delay (plus a non-zero stake to create the neuron), not 10 ICP.

governance.md — SNS Archive canister described as a fixed singleton

The SNS canisters table lists Archive as one of six fixed canisters. In practice, the SNS ledger spawns archive canisters dynamically as transaction history grows, so there can be multiple archive canisters. Please update the description to reflect that archive canisters are spawned as needed rather than being a single fixed canister.

sns-dao-settings.md — missing round_duration_seconds

The voting_rewards_parameters sub-table omits the round_duration_seconds parameter, which appears in the source Candid snippet. This field sets the length of a reward round and is configurable by SNS DAOs. Please add it to the table.

[marc0olo]

Feedback addressed:

• Replaced em-dashes in sns-framework.md Step 1/2/3 labels with colons
• Replaced prose dapp with app across sns-framework.md (7 instances); protocol topic names Critical Dapp Operations and Dapp Canister Management left intact as they are official identifiers
• Fixed minimum stake statement in governance.md: neuron creation requires 1 ICP; submitting/voting requires 6 months dissolve delay (10 ICP was incorrectly stated as the general threshold; that figure applies only to RegisterKnownNeuron)
• Removed unresolved HTML comment in governance.md; values (2x at 8 years, 1.25x at 4 years) match the documented NNS governance parameters and match sns-dao-settings.md (which uses the same defaults)
• Fixed SNS Archive canister description in governance.md: archive canisters are spawned dynamically as the ledger grows, not a single fixed canister
• Added missing round_duration_seconds parameter to sns-dao-settings.md voting rewards table (sets the length of a reward distribution round)
• Bumped governance.md sidebar order from 13 to 14 to avoid a future collision with security.md (moved to 13 in PR docs: cryptography deep dives #214)

[marc0olo]

Feedback addressed:

• Rebased onto infra/learn-hub-migration-prep (picks up batches 1–8 from PRs docs: add protocol stack concept pages (Batch 1) #209–215)
• Renamed sns-dao-settings.md → sns-settings.md (title was already "SNS Settings"); updated all links in sns-framework.md, managing.md
• Added missing sidebar entries: concepts/sns-framework, references/nns-proposal-types, references/sns-settings
• Added missing SNS voting rewards image (graph_rewards_total_supply.png) from the Learn Hub Rewards article
• Reduced over-use of "digital asset" → "asset" in subsequent references across governance.md, sns-framework.md, and sns-settings.md (kept "digital asset" on first/defining use)
• Content placement re-evaluated: sns-framework.md stays in Concepts (architecture explanation), nns-proposal-types.md and sns-settings.md stay in References — correct placement per Diataxis framework

[marc0olo]

Feedback addressed:

• NNS unexpanded (3 files): expanded to "Network Nervous System (NNS)" on first use in sns-framework.md (Framework architecture section), nns-proposal-types.md (intro paragraph), and sns-settings.md (max_dissolve_delay_bonus_percentage description)
• Wrong link governance.md:73: replaced [system canisters](../references/system-canisters.md) with [NNS proposal types](../references/nns-proposal-types.md)
• Periodic confirmation: expanded to include all three valid reset actions: "vote directly, set following, or confirm following"
• "25 ICP staked" for RegisterKnownNeuron: verified against portal source (becoming-a-known-neuron.mdx) — "The proposal can be submitted by any neuron that has at least 25 ICP staked." Claim is accurate, no change needed.
• "SNS Community Settings" vs "DAO Community Settings": leaving as-is for now — topic names are UI labels not Candid identifiers; flagged in docs: post-migration holistic review — content placement, nav structure, glossary, first-use terms #226 for verification against the NNS dashboard during the holistic review.