Fix Docs Structure & Repair Internal Links

.gitbook.yaml

@@ -1,97 +1,97 @@
 root: ./
 
 redirects:
-  build-apps/references/bns: clarity/example-contracts/bns.md
-  build-apps/references/gaia: stacks-in-depth/gaia.md/README.md
-  docs/blockchain/stacks-blockchain-api: stacks-101/api.md
-  docs/clarity: clarity/overview.md
-  docs/clarity/crash-course: clarity/clarity-crash-course.md
-  docs/clarity/language-functions: clarity/functions.md
-  docs/clarity/language-keywords: clarity/keywords.md
-  docs/clarity/language-types: clarity/types.md
-  docs/clarity/noteworthy-contracts/bns-contract: clarity/example-contracts/bns.md
-  docs/clarity/noteworthy-contracts/stacking-contract: clarity/example-contracts/stacking.md
-  docs/clarity/noteworthy-contracts/xbtc: clarity/example-contracts/xbtc.md
-  docs/clarity/sample-contracts: clarity/example-contracts/audited-starter-contracts.md
-  docs/clarity/security: clarity/decidability.md
-  docs/clarity/security/decidable: clarity/decidability.md
-  docs/contribute: stacks-101/what-is-stacks.md
-  docs/contribute/docs: stacks-101/what-is-stacks.md
-  docs/contribute/translations: stacks-101/what-is-stacks.md
-  docs/cookbook: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/creating-an-ft: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/creating-an-nft: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/get-sats-per-stx: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/parse-a-btc-tx: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/post-conditions: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/sending-bitcoin-with-hiro-wallet: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/stacks-js-auth: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/stacks-js-sending-transactions: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/cookbook/verifying-a-btc-tx-was-mined: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/gaia: stacks-in-depth/gaia/README.md
-  docs/gaia/configuration: stacks-in-depth/gaia/configuration.md
-  docs/gaia/deploy-gaia-hub: stacks-in-depth/gaia/deploy-gaia-hub.md
-  docs/gaia/gaia-on-ec2: stacks-in-depth/gaia/gaia-on-ec2.md
-  docs/gaia/setup-linux: stacks-in-depth/gaia/setup-linux.md
-  docs/gaia/setup-mac: stacks-in-depth/gaia/setup-mac.md
-  docs/glossary: stacks-101/what-is-stacks.md
-  docs/intro: stacks-101/what-is-stacks.md
-  docs/nakamoto: nakamoto-upgrade/what-is-the-nakamoto-release.md
-  docs/nakamoto/bitcoin-mev-mitigation: nakamoto-upgrade/nakamoto-in-10-minutes.md
-  docs/nakamoto/block-production: nakamoto-upgrade/nakamoto-in-10-minutes.md
-  docs/nakamoto/neon: nakamoto-upgrade/testnets/neon.md
-  docs/nakamoto/signer: nakamoto-upgrade/running-a-signer.md
-  docs/nakamoto/stacking: nakamoto-upgrade/stacking-flow.md
-  docs/next-steps: stacks-101/what-is-stacks.md
-  docs/nodes-and-miners: stacks-in-depth/nodes-and-miners/README.md
-  docs/nodes-and-miners/digitalocean: stacks-in-depth/nodes-and-miners/run-a-node-with-digital-ocean.md
-  docs/nodes-and-miners/hosted-nodes: stacks-in-depth/nodes-and-miners/run-a-node-with-a-hosted-provider.md
-  docs/nodes-and-miners/miner-costs-and-fees: stacks-in-depth/nodes-and-miners/miner-costs-and-fees.md
-  docs/nodes-and-miners/miner-mainnet: stacks-in-depth/nodes-and-miners/mine-mainnet-stacks-tokens.md
-  docs/nodes-and-miners/miner-testnet: stacks-in-depth/nodes-and-miners/mine-testnet-stacks-tokens.md
-  docs/nodes-and-miners/quicknode: stacks-in-depth/nodes-and-miners/run-a-node-with-quicknode.md
-  docs/nodes-and-miners/run-a-node: stacks-in-depth/nodes-and-miners/run-a-node-with-docker.md
-  docs/nodes-and-miners/stacks-node-configuration: stacks-in-depth/nodes-and-miners/stacks-node-configuration.md
-  docs/nodes-and-miners/verify-miner: stacks-in-depth/nodes-and-miners/verify-miner.md
-  docs/services-using-stacks/defi: stacks-101/what-is-stacks.md
-  docs/services-using-stacks/more: stacks-101/what-is-stacks.md
-  docs/services-using-stacks/nft: stacks-101/what-is-stacks.md
-  docs/services-using-stacks/stacks-info-sites: stacks-101/what-is-stacks.md
-  docs/services-using-stacks/wallets: stacks-101/what-is-stacks.md
-  docs/stacks-academy: stacks-101/what-is-stacks.md
-  docs/stacks-academy/accounts: stacks-101/accounts.md
-  docs/stacks-academy/authentication: stacks-101/authentication.md
-  docs/stacks-academy/bns: stacks-101/bitcoin-name-system.md
-  docs/stacks-academy/btc-connection: stacks-101/bitcoin-connection.md
-  docs/stacks-academy/microblocks: nakamoto-upgrade/nakamoto-in-depth/what-about-microblocks.md
-  docs/stacks-academy/mining: stacks-101/mining.md
-  docs/stacks-academy/network: stacks-101/network.md
-  docs/stacks-academy/post-conditions: stacks-101/post-conditions.md
-  docs/stacks-academy/proof-of-transfer: stacks-101/proof-of-transfer.md
-  docs/stacks-academy/sips: stacks-101/sips.md
-  docs/stacks-academy/stacking: stacks-101/stacking.md
-  docs/stacks-academy/stacks-blockchain-api: stacks-101/api.md
-  docs/stacks-academy/technical-specs: stacks-101/technical-specifications.md
-  docs/stacks-academy/testnet: stacks-101/testnet.md
-  docs/stacks-academy/transactions: stacks-101/transactions.md
-  docs/stacks-academy/what-is-stacks: stacks-101/what-is-stacks.md
-  docs/stacks-academy/whitepapers: stacks-101/whitepapers.md
-  docs/tutorials: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/tutorials/community-tutorials: tutorials/community-tutorials.md
-  docs/tutorials/hello-stacks: tutorials/hello-stacks-quickstart-tutorial.md
-  docs/understand-stacks/testnet: stacks-101/testnet.md
-  docs/write-smart-contracts: clarity/overview.md
-  references/bns-contract: clarity/example-contracts/bns.md
-  references/language-functions: clarity/functions.md
-  understand-stacks/microblocks: nakamoto-upgrade/nakamoto-in-depth/what-about-microblocks.md
-  understand-stacks/mining: stacks-101/mining.md
-  understand-stacks/network: stacks-101/network.md
-  understand-stacks/proof-of-transfer: stacks-101/proof-of-transfer.md
-  understand-stacks/stacking: stacks-101/stacking.md
-  understand-stacks/testnet: stacks-101/testnet.md
-  understand-stacks/transactions: stacks-101/transactions.md
-  write-smart-contracts/language-functions: clarity/functions.md
-  write-smart-contracts/overview: clarity/overview.md
-  write-smart-contracts/principals: clarity/types.md
-  write-smart-contracts/tokens: tutorials/tokens.md
-  sbtc/introduction: concepts/sbtc/README.md
+  build-apps/references/bns: docs/reference/clarity/example-contracts/bns.md
+  build-apps/references/gaia: docs/learn/stacks-101/stacks-among-other-layers.md
+  docs/blockchain/stacks-blockchain-api: docs/learn/stacks-101/README.md
+  docs/clarity: docs/learn/clarity/overview.md
+  docs/clarity/crash-course: docs/build/get-started/clarity-crash-course.md
+  docs/clarity/language-functions: docs/reference/clarity/functions.md
+  docs/clarity/language-keywords: docs/reference/clarity/keywords.md
+  docs/clarity/language-types: docs/reference/clarity/types.md
+  docs/clarity/noteworthy-contracts/bns-contract: docs/reference/clarity/example-contracts/bns.md
+  docs/clarity/noteworthy-contracts/stacking-contract: docs/reference/clarity/example-contracts/stacking.md
+  docs/clarity/noteworthy-contracts/xbtc: docs/reference/clarity/example-contracts/xbtc.md
+  docs/clarity/sample-contracts: docs/reference/clarity/example-contracts/audited-starter-contracts.md
+  docs/clarity/security: docs/learn/clarity/decidability.md
+  docs/clarity/security/decidable: docs/learn/clarity/decidability.md
+  docs/contribute: docs/contribute/README.md
+  docs/contribute/docs: docs/contribute/README.md
+  docs/contribute/translations: docs/contribute/README.md
+  docs/cookbook: docs/build/get-started/developer-quickstart.md
+  docs/cookbook/creating-an-ft: docs/build/get-started/create-a-token
+  docs/cookbook/creating-an-nft: docs/build/get-started/create-a-token
+  docs/cookbook/get-sats-per-stx: docs/build/get-started/developer-quickstart.md
+  docs/cookbook/parse-a-btc-tx: docs/build/get-started/developer-quickstart.md
+  docs/cookbook/post-conditions: docs/build/post-conditions/overview.md
+  docs/cookbook/sending-bitcoin-with-hiro-wallet: docs/build/get-started/developer-quickstart.md
+  docs/cookbook/stacks-js-auth: docs/build/stacks.js/overview.md
+  docs/cookbook/stacks-js-sending-transactions: docs/build/stacks.js/build-transactions.md
+  docs/cookbook/verifying-a-btc-tx-was-mined: docs/build/get-started/developer-quickstart.md
+  docs/gaia: docs/build/gaia/README.md
+  docs/gaia/configuration: docs/build/gaia/configuration.md
+  docs/gaia/deploy-gaia-hub: docs/build/gaia/deploy-gaia-hub.md
+  docs/gaia/gaia-on-ec2: docs/build/gaia/gaia-on-ec2.md
+  docs/gaia/setup-linux: docs/build/gaia/setup-linux.md
+  docs/gaia/setup-mac: docs/build/gaia/setup-mac.md
+  docs/glossary: docs/learn/stacks-101/what-is-stacks.md
+  docs/intro: docs/learn/stacks-101/what-is-stacks.md
+  docs/nakamoto: docs/reference/nakamoto-upgrade/what-is-the-nakamoto-release.md
+  docs/nakamoto/bitcoin-mev-mitigation: docs/reference/nakamoto-upgrade/nakamoto-in-10-minutes.md
+  docs/nakamoto/block-production: docs/reference/nakamoto-upgrade/nakamoto-in-10-minutes.md
+  docs/nakamoto/neon: docs/reference/nakamoto-upgrade/setting-up-a-primary-post-nakamoto-testnet-node.md
+  docs/nakamoto/signer: docs/operate/run-a-signer/README.md
+  docs/nakamoto/stacking: docs/operate/stacking-stx/README.md
+  docs/next-steps: docs/learn/stacks-101/what-is-stacks.md
+  docs/nodes-and-miners: docs/operate/run-a-node/README.md
+  docs/nodes-and-miners/digitalocean: docs/operate/run-a-node/run-a-node-with-digital-ocean.md
+  docs/nodes-and-miners/hosted-nodes: docs/operate/run-a-node/run-a-node-with-a-hosted-provider.md
+  docs/nodes-and-miners/miner-costs-and-fees: docs/operate/run-a-miner/miner-costs-and-fees.md
+  docs/nodes-and-miners/miner-mainnet: docs/operate/run-a-miner/mine-mainnet-stacks-tokens.md
+  docs/nodes-and-miners/miner-testnet: docs/operate/run-a-miner/mine-testnet-stacks-tokens.md
+  docs/nodes-and-miners/quicknode: docs/operate/run-a-node/run-a-node-with-quicknode.md
+  docs/nodes-and-miners/run-a-node: docs/operate/run-a-node/run-a-node-with-docker.md
+  docs/nodes-and-miners/stacks-node-configuration: docs/reference/node-operations/stacks-node-configuration.md
+  docs/nodes-and-miners/verify-miner: docs/operate/run-a-miner/verify-miner.md
+  docs/services-using-stacks/defi: docs/learn/stacks-101/what-is-stacks.md
+  docs/services-using-stacks/more: docs/learn/stacks-101/what-is-stacks.md
+  docs/services-using-stacks/nft: docs/learn/stacks-101/what-is-stacks.md
+  docs/services-using-stacks/stacks-info-sites: docs/learn/stacks-101/what-is-stacks.md
+  docs/services-using-stacks/wallets: docs/learn/stacks-101/what-is-stacks.md
+  docs/stacks-academy: docs/learn/stacks-101/what-is-stacks.md
+  docs/stacks-academy/accounts: docs/learn/network-fundamentals/accounts.md
+  docs/stacks-academy/authentication: docs/learn/network-fundamentals/authentication.md
+  docs/stacks-academy/bns: docs/learn/network-fundamentals/bitcoin-name-system.md
+  docs/stacks-academy/btc-connection: docs/learn/stacks-101/bitcoin-connection.md
+  docs/stacks-academy/microblocks: docs/learn/stacks-101/stacks-among-other-layers.md
+  docs/stacks-academy/mining: docs/learn/block-production/mining.md
+  docs/stacks-academy/network: docs/learn/network-fundamentals/network-basics.md
+  docs/stacks-academy/post-conditions: docs/learn/transactions/post-conditions.md
+  docs/stacks-academy/proof-of-transfer: docs/learn/stacks-101/proof-of-transfer.md
+  docs/stacks-academy/sips: docs/learn/network-fundamentals/sips.md
+  docs/stacks-academy/stacking: docs/learn/block-production/stacking.md
+  docs/stacks-academy/stacks-blockchain-api: docs/learn/stacks-101/README.md
+  docs/stacks-academy/technical-specs: docs/learn/network-fundamentals/technical-specifications
+  docs/stacks-academy/testnet: docs/learn/network-fundamentals/mainnet-and-testnets.md
+  docs/stacks-academy/transactions: docs/learn/transactions/how-transactions-work.md
+  docs/stacks-academy/what-is-stacks: docs/learn/stacks-101/what-is-stacks.md
+  docs/stacks-academy/whitepapers: docs/learn/stacks-101/what-is-stacks.md
+  docs/tutorials: docs/build/get-started/developer-quickstart.md
+  docs/tutorials/community-tutorials: docs/build/more-guides/community-tutorials.md
+  docs/tutorials/hello-stacks: docs/build/get-started/developer-quickstart.md
+  docs/understand-stacks/testnet: docs/learn/network-fundamentals/mainnet-and-testnets.md
+  docs/write-smart-contracts: docs/learn/clarity/overview.md
+  references/bns-contract: docs/reference/clarity/example-contracts/bns.md
+  references/language-functions: docs/reference/clarity/functions.md
+  understand-stacks/microblocks: docs/learn/stacks-101/stacks-among-other-layers.md
+  understand-stacks/mining: docs/learn/block-production/mining.md
+  understand-stacks/network: docs/learn/network-fundamentals/network-basics.md
+  understand-stacks/proof-of-transfer: docs/learn/stacks-101/proof-of-transfer.md
+  understand-stacks/stacking: docs/learn/block-production/stacking.md
+  understand-stacks/testnet: docs/learn/network-fundamentals/mainnet-and-testnets.md
+  understand-stacks/transactions: docs/learn/transactions/how-transactions-work.md
+  write-smart-contracts/language-functions: docs/reference/clarity/functions.md
+  write-smart-contracts/overview: docs/learn/clarity/overview.md
+  write-smart-contracts/principals: docs/reference/clarity/types.md
+  write-smart-contracts/tokens: docs/build/get-started/create-a-token
+  sbtc/introduction: docs/learn/sbtc/README.md

.github/workflows/smart-docs-monitor.yml

@@ -103,9 +103,9 @@ jobs:
                - Determine if it affects user-facing features, APIs, or workflows
 
             3. **Review our documentation:**
-               - Check /concepts directory for all conceptual documentation
-               - Check /guides-and-tutorials directory for tutorials and how-to guides
-               - Check /reference directory for API and reference documentation
+               - Check /docs/learn directory for all conceptual documentation
+               - Check /docs/build and /docs/operate directories for tutorials and guides
+               - Check /docs/reference directory for API and reference documentation
                - Read README.md
                - Look for setup/configuration guides
 

CLAUDE.md

@@ -28,19 +28,20 @@ This repository monitors merged PRs across all Stacks Network and Hiro Systems p
 ## Documentation Structure
 
 ### Primary Documentation Sections
-- `/concepts/` - Conceptual documentation about Stacks, PoX, Clarity, sBTC
-- `/guides-and-tutorials/` - Hands-on tutorials and how-to guides
-- `/reference/` - API reference and technical specifications
+- `/docs/learn/` - Conceptual documentation (Stacks 101, sBTC, Block Production)
+- `/docs/build/` - Developer guides, tutorials, and tools (Clarinet, Stacks.js)
+- `/docs/operate/` - Node operators, miners, and signers guides
+- `/docs/reference/` - API reference and technical specifications
 - `README.md` - Quick start and overview
 
 ### Key Documentation Areas
-- **Stacks blockchain concepts** - `/concepts/stacks-101/`
-- **sBTC documentation** - `/concepts/sbtc/`
-- **Clarity language** - `/concepts/clarity/`
-- **Node operations** - `/guides-and-tutorials/nodes-and-miners/`
-- **Signer operations** - `/guides-and-tutorials/running-a-signer/`
-- **Stacking guides** - `/guides-and-tutorials/stack-stx/`
-- **Developer quickstart** - `/guides-and-tutorials/hello-stacks-quickstart-tutorial.md`
+- **Stacks blockchain concepts** - `/docs/learn/stacks-101/`
+- **sBTC documentation** - `/docs/learn/sbtc/`
+- **Clarity language** - `/docs/learn/clarity/`
+- **Node operations** - `/docs/operate/run-a-node/`
+- **Signer operations** - `/docs/operate/run-a-signer/`
+- **Stacking guides** - `/docs/operate/stacking-stx/`
+- **Developer quickstart** - `/docs/build/get-started/developer-quickstart.md`
 
 ## Review Process
 
@@ -58,13 +59,13 @@ This repository monitors merged PRs across all Stacks Network and Hiro Systems p
    - Does this break existing functionality?
 
 3. **Check documentation** - Search our docs for related content:
-   - Use `grep -r "relevant_term" concepts/ guides-and-tutorials/ reference/`
+   - Use `grep -r "relevant_term" docs/learn/ docs/build/ docs/operate/ docs/reference/`
    - Look for mentions of changed functions, APIs, or concepts
    - Check if tutorials reference affected code
 
 4. **Be specific** - Point to exact files and sections that need updates
    - Don't say "update the Clarity docs"
-   - Say "update `/concepts/clarity/language-functions.md` line 145 to reflect new `map-set` signature"
+   - Say "update `/docs/reference/clarity/functions.md` line 145 to reflect new `map-set` signature"
 
 ### What Requires Documentation
 
@@ -193,13 +194,13 @@ Added a new Clarity built-in function `map-insert` that inserts a key-value pair
 ## Documentation Impact
 
 ### Files Needing Updates
-- [ ] `/concepts/clarity/language-functions.md` - Add documentation for map-insert function
-- [ ] `/guides-and-tutorials/clarity-hello-world.md` - Update map operations example
-- [ ] `/reference/clarity-language-reference.md` - Add to function reference table
+- [ ] `/docs/learn/clarity/overview.md` - Add documentation for map-insert function
+- [ ] `/docs/build/get-started/clarity-crash-course.md` - Update map operations example
+- [ ] `/docs/reference/clarity/functions.md` - Add to function reference table
 
 ## Recommended Changes
 
-### In `/concepts/clarity/language-functions.md`
+### In `/docs/learn/clarity/overview.md`
 
 **Section: Map Functions**