Document shift to 24-word mnemonics in Stacks

[jadonamite]

Description

As a Stacks developer, I need clear and comprehensive documentation regarding the architectural shift to 24-word mnemonics in Clarinet so that I can configure my deployment environments securely and avoid confusing "bip39 errors" during upgrades.

This pull request introduces a new documentation module: "The Configuration Architecture of Clarinet," broken down into three focused guides.

1. Motivation for change:
   Clarinet v2.15.0+ enforces 24-word mnemonics, formally deprecating raw private keys and 12-word phrases. This shift has created friction for developers migrating from legacy setups or other ecosystems (like Ethereum). The current documentation lacks a deep technical explanation of why this change occurred (HD derivation requirements for Simnet) and how to migrate securely.
2. What was changed:
   Added three new extensive Markdown files to the documentation structure:

• 01-cryptographic-architecture.md: Explains the theoretical move to HD wallets, Simnet actor derivation, and 256-bit entropy.
• 02-clarinet-configuration-guide.md: A practical reference for settings.toml, including valid vs. invalid configuration patterns and troubleshooting for "bip39 errors."
• 03-opsec-and-migration-workflows.md: Step-by-step guides for migrating from 12-to-24 words and handling secrets in CI/CD pipelines (GitHub Actions).

3. How does this impact application developers:
   It serves as a definitive resource for debugging deployment configuration errors. It reduces support tickets regarding "bip39 errors" and promotes better OpSec by documenting the encrypted_mnemonic feature and proper CI/CD injection methods.
4. Link to relevant issues and documentation:

• Addresses confusion around "bip39 error" in Clarinet v2.15.0+.
• Relates to stacks-core security standards.

5. Provide examples of use cases with code samples:

• Troubleshooting: A developer encountering Error: bip39 error can consult 02-clarinet-configuration-guide.md to identify that their 12-word phrase is the cause.
• Configuration Reference: The docs provide copy-pasteable valid TOML:

[accounts.deployer]
# 24-word mnemonic is MANDATORY
mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art"
derivation = "m/44'/5757'/0'/0/0"

Type of Change

• API reference/documentation update

Does this introduce a breaking change?

No. This is a documentation-only update. It clarifies existing breaking changes in the Clarinet CLI tool but does not alter the code itself.

Are documentation updates required?

• Link to documentation updates: This PR is the documentation update. Added 01-cryptographic-architecture.md, 02-clarinet-configuration-guide.md, and 03-opsec-and-migration-workflows.md.

Testing information

1. Is testing required for this change? No code changes were made.
2. If it’s a bug fix, list steps to reproduce the bug: N/A.
3. Briefly mention affected code paths: None.
4. List other affected projects if possible: None.
5. Things to watch out for when testing: Verify that Markdown tables and code blocks render correctly in the GitHub UI.

Checklist

• Code is commented where needed (N/A)
• Unit test coverage for new or modified code paths (N/A)
• npm run test passes (N/A)
• Changelog is updated
• Tag 1 of @maintainer

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}