docs: migrate and improve all documentation for Fumadocs

Restructure: move docs/ → content/docs/, .md → .mdx, remove Docusaurus
syntax (admonitions, _category_.json), normalize cross-doc links to
relative paths, add meta.json files for sidebar ordering.

Content improvements on top of the structural move:
- Tutorial series rewritten for Cadence 1.0 (entitlements, updated
  playground links, correct resource syntax throughout)
- Forward-port PR #289: references clarification in language/references.mdx
- Forward-port PR #290: ContractUpdateValidator scope fix in
  language/contract-updatability.mdx
- Forward-port PR #291: testing-framework syntax modernization
- Add frontmatter descriptions to design-patterns and security-best-practices
- Fix Cadence syntax defects found during audit (casing, deprecated keywords)

Author: Aliserag

docs/access-based-security.png content/docs/access-based-security.pngdocs/access-based-security.png renamed to content/docs/access-based-security.png

@@ -1,7 +1,5 @@
 ---
 title: Cadence Anti-Patterns
-sidebar_position: 6
-sidebar_label: Anti-Patterns
 ---
 
 This is an opinionated list of issues that can be improved if they are found in Cadence code intended for production.
@@ -50,9 +48,12 @@ fun transferNFT(id: UInt64, owner: auth(Storage) &Account) {
     transfer(id)
 
     // Sneakily borrow a reference to the user's Flow Token Vault
-    // and withdraw a bit of FLOW
+    // and withdraw a bit of FLOW (modern Cadence 1.0 surface:
+    // owner.storage.borrow with the Withdraw entitlement)
     // BAD
-    let vaultRef = owner.borrow<&FlowToken.Vault>(/storage/flowTokenVault)!
+    let vaultRef = owner.storage.borrow<auth(FungibleToken.Withdraw) &FlowToken.Vault>(
+        from: /storage/flowTokenVault
+    )!
     let stolenTokens <- vaultRef.withdraw(amount: 0.1)
 
     // deposit the stolen funds in the contract owners vault
@@ -83,8 +84,8 @@ Accidentally exposed fields can be a security hole.
 ### Solution
 
 When writing your smart contract, look at every field and function and make sure
-that any functions that you don't want every user to be able to access require access through an [entitlement](./language/access-control.md#entitlements) (`access(E)`),
-or use a non-public [access modifier](./language/access-control.md) like `access(self)`, `access(contract)`, or `access(account)`.
+that any functions that you don't want every user to be able to access require access through an [entitlement](/docs/language/access-control#entitlements) (`access(E)`),
+or use a non-public [access modifier](/docs/language/access-control) like `access(self)`, `access(contract)`, or `access(account)`.
 Declaring a function as `access(all)` is a deliberate design decision to allow completely open and unrestricted access to read that field or call that function and should not be taken lightly.
 
 The only functions that should be `access(all)` are `view` functions and functions the everyone should be able to access and the only fields that should be `access(all)` are basic types like numbers or addresses.

docs/account-structure.png content/docs/account-structure.pngdocs/account-structure.png renamed to content/docs/account-structure.png

@@ -1,19 +1,14 @@
 ---
 title: Protocol Smart Contracts 1.0 Changes Guide
-sidebar_position: 4
-sidebar_label: Core Contracts Guide
 ---
 
 # Protocol Smart Contracts in Cadence 1.0
 
 :::important
-
 On September 4th, 2024, the Flow Mainnet upgraded to Cadence 1.0. In addition to many changes to the Cadence programming language and the Cadence token standards, the Flow Protocol smart contracts were also updated to be compatible with the changes.
 
 All applications that interact with these contracts need to update their transactions and scripts in order to be compatible with these changes.
-
 :::
-
 ## Important info
 
 This document assumes you have a basic understanding of the [Cadence 1.0 improvements] and modifications to the Fungible Token Standard. We encourage you to consult those guides for more details on these changes if you are interested.
@@ -51,8 +46,8 @@ The NFT guide covers a lot of common changes that are required for NFT contracts
 
 The core contracts do not have any meaningful changes outside of what is required to be compatible with Cadence 1.0 and the token standard changes. If you have questions about the core contracts changes for Cadence 1.0, please reach out to the Flow team in Discord and we will be happy to help.
 
-<!-- Relative links. Will not render on the page -->
+{/* Relative links. Will not render on the page */}
 
-[Cadence 1.0 improvements]: ./improvements.md
+[Cadence 1.0 improvements]: /docs/cadence-migration-guide/improvements
 [`master` branch of the flow-core-contracts repo]: https://github.com/onflow/flow-core-contracts
 [PR that made the changes]: https://github.com/onflow/flow-core-contracts/pull/319

docs/anti-patterns.md content/docs/anti-patterns.mdxdocs/anti-patterns.md renamed to content/docs/anti-patterns.mdx

@@ -1,17 +1,12 @@
 ---
 title: Fungible Token Cadence 1.0 Migration Guide
-sidebar_position: 3
-sidebar_label: FT Cadence 1.0 Guide
 ---
 
 # Fungible Tokens in Cadence 1.0
 
 :::important
-
 On September 4th, 2024, the Flow Mainnet upgraded to Cadence 1.0. In addition to many changes to the Cadence programming language, the Cadence token standards also got streamlined and improved. All applications need to migrate their existing Cadence scripts and transactions for the update. If you do not update your code, your application will not function.
-
 :::
-
 This document describes the changes to the Cadence Fungible Token (FT) standard. We'll be using the [`ExampleToken` contract] as an example. Many projects have used `ExampleToken` as a starting point for their projects, so it is widely applicable to most NFT developers on Flow. The upgrades required for `ExampleToken` will cover 90%+ of what you'll need to do to update your contract. Each project most likely has additional logic or features that aren't included in `ExampleToken`, but hopefully, after reading this guide, you'll understand Cadence 1.0 well enough that you can easily make any other changes that are necessary.
 
 As always, there are plenty of people on the Flow team and in the community who are happy to help answer any questions you may have, so please reach out in Discord if you need any help.
@@ -65,7 +60,7 @@ access(all) fun deposit(from: @{FungibleToken.Vault})
 
 If you have any more questions, please ask in discord and the Flow team will be happy to assist!
 
-<!-- Relative links. Will not render on the page -->
+{/* Relative links. Will not render on the page */}
 
 [`ExampleToken` contract]: https://github.com/onflow/flow-ft/blob/master/contracts/ExampleToken.cdc
 [FLIP]: https://github.com/onflow/flips/pull/55
@@ -75,4 +70,4 @@ If you have any more questions, please ask in discord and the Flow team will be
 [this PR in the hybrid custody repo]: https://github.com/onflow/hybrid-custody/pull/164
 [This Discord announcement]: https://discord.com/channels/613813861610684416/811693600403357706/1225909248429527140
 [Flow Contract Browser]: https://contractbrowser.com/
-[NFT Cadence 1.0 migration guide]: ./nft-guide.mdx
+[NFT Cadence 1.0 migration guide]: /docs/cadence-migration-guide/nft-guide

…migration-guide/core-contracts-guide.mdx …migration-guide/core-contracts-guide.mdxdocs/cadence-migration-guide/core-contracts-guide.mdx renamed to content/docs/cadence-migration-guide/core-contracts-guide.mdx docs/cadence-migration-guide/core-contracts-guide.mdx renamed to content/docs/cadence-migration-guide/core-contracts-guide.mdx

@@ -1,7 +1,5 @@
 ---
 title: Cadence 1.0 Improvements & New Features
-sidebar_position: 0
-sidebar_label: Improvements & New Features
 ---
 
 ## 💫 New features
@@ -1789,40 +1787,40 @@ If you have any questions or need help with the upgrade, feel free to reach out
 
 Help is also available during the [Cadence 1.0 Office Hours] each week at 10:00AM PST on the Flow Developer Discord.
 
-<!-- Relative links. Will not render on the page -->
+{/* Relative links. Will not render on the page */}
 
-[FLIP 1043]: https://github.com/onflow/flips/blob/main/cadence/20220708-resource-reference-invalidation.md
-[FLIP 1056]: https://github.com/onflow/flips/blob/main/cadence/20220715-cadence-purity-analysis.md
-[FLIP 111]: https://github.com/onflow/flips/blob/main/cadence/20230417-events-emitted-from-interfaces.md
-[FLIP 118]: https://github.com/onflow/flips/blob/main/cadence/20230711-remove-type-requirements.md
-[FLIP 13]: https://github.com/onflow/flips/blob/main/cadence/20221011-for-loop-semantics.md
+[FLIP 1043]: https://github.com/onflow/flips/blob/main/cadence/20220708-resource-reference-invalidation
+[FLIP 1056]: https://github.com/onflow/flips/blob/main/cadence/20220715-cadence-purity-analysis
+[FLIP 111]: https://github.com/onflow/flips/blob/main/cadence/20230417-events-emitted-from-interfaces
+[FLIP 118]: https://github.com/onflow/flips/blob/main/cadence/20230711-remove-type-requirements
+[FLIP 13]: https://github.com/onflow/flips/blob/main/cadence/20221011-for-loop-semantics
 [FLIP 131]: https://github.com/onflow/flips/pull/131
-[FLIP 242]: https://github.com/onflow/flips/blob/main/cadence/20240123-capcon-get-capability-api-improvement.md
-[FLIP 262]: https://github.com/onflow/flips/blob/main/cadence/20240415-remove-non-public-entitled-interface-members.md
-[FLIP 40]: https://github.com/onflow/flips/blob/main/cadence/20221024-interface-inheritance.md
-[FLIP 43]: https://github.com/onflow/flips/blob/main/cadence/20221018-change-fun-type-syntax.md
-[FLIP 54]: https://github.com/onflow/flips/blob/main/cadence/20221214-auth-remodel.md
-[FLIP 798]: https://github.com/onflow/flips/blob/main/cadence/20220203-capability-controllers.md
-[FLIP 84]: https://github.com/onflow/flips/blob/main/cadence/20230505-remove-priv-and-pub.md
-[FLIP 85]: https://github.com/onflow/flips/blob/main/cadence/20230505-remove-restricted-types.md
-[FLIP 86: Introduce Built-in Mutability Entitlements]: https://github.com/onflow/flips/blob/main/cadence/20230519-built-in-mutability-entitlements.md
-[FLIP 86]: https://github.com/onflow/flips/blob/main/cadence/20230519-built-in-mutability-entitlements.md
-[FLIP 89: Change Member Access Semantics]: https://github.com/onflow/flips/blob/main/cadence/20230517-member-access-semnatics.md
-[FLIP 89]: https://github.com/onflow/flips/blob/main/cadence/20230517-member-access-semnatics.md
-[FLIP 92]: https://github.com/onflow/flips/blob/main/cadence/20230525-account-type.md
-[FLIP 94]: https://github.com/onflow/flips/blob/main/cadence/20230623-entitlement-improvements.md
-[FLIP 941]: https://github.com/onflow/flips/blob/main/cadence/20220516-reference-creation-semantics.md
+[FLIP 242]: https://github.com/onflow/flips/blob/main/cadence/20240123-capcon-get-capability-api-improvement
+[FLIP 262]: https://github.com/onflow/flips/blob/main/cadence/20240415-remove-non-public-entitled-interface-members
+[FLIP 40]: https://github.com/onflow/flips/blob/main/cadence/20221024-interface-inheritance
+[FLIP 43]: https://github.com/onflow/flips/blob/main/cadence/20221018-change-fun-type-syntax
+[FLIP 54]: https://github.com/onflow/flips/blob/main/cadence/20221214-auth-remodel
+[FLIP 798]: https://github.com/onflow/flips/blob/main/cadence/20220203-capability-controllers
+[FLIP 84]: https://github.com/onflow/flips/blob/main/cadence/20230505-remove-priv-and-pub
+[FLIP 85]: https://github.com/onflow/flips/blob/main/cadence/20230505-remove-restricted-types
+[FLIP 86: Introduce Built-in Mutability Entitlements]: https://github.com/onflow/flips/blob/main/cadence/20230519-built-in-mutability-entitlements
+[FLIP 86]: https://github.com/onflow/flips/blob/main/cadence/20230519-built-in-mutability-entitlements
+[FLIP 89: Change Member Access Semantics]: https://github.com/onflow/flips/blob/main/cadence/20230517-member-access-semnatics
+[FLIP 89]: https://github.com/onflow/flips/blob/main/cadence/20230517-member-access-semnatics
+[FLIP 92]: https://github.com/onflow/flips/blob/main/cadence/20230525-account-type
+[FLIP 94]: https://github.com/onflow/flips/blob/main/cadence/20230623-entitlement-improvements
+[FLIP 941]: https://github.com/onflow/flips/blob/main/cadence/20220516-reference-creation-semantics
 [Account keys]: https://developers.flow.com/cadence/language/accounts#account-keys
 [Cadence 1.0 Office Hours]: https://calendar.google.com/calendar/ical/c_47978f5cd9da636cadc6b8473102b5092c1a865dd010558393ecb7f9fd0c9ad0%40group.calendar.google.com/public/basic.ics
-[Cadence mutability restrictions FLIP]: https://github.com/onflow/flips/blob/main/cadence/20211129-cadence-mutability-restrictions.md
-[Entitlements]: https://cadence-lang.org/docs/1.0/language/access-control#entitlements
+[Cadence mutability restrictions FLIP]: https://github.com/onflow/flips/blob/main/cadence/20211129-cadence-mutability-restrictions
+[Entitlements]: ../language/access-control#entitlements
 [Flow Discord]: https://discord.gg/flowblockchain.
 [Flow forum]: http://forum.flow.com/t/streamlined-token-standards-proposal/3075
 [GitHub]: https://github.com/onflow/flow-nft/pull/126
-[Hashing with a domain tag]: https://cadence-lang.org/docs/1.0/language/crypto#hashing-with-a-domain-tag
+[Hashing with a domain tag]: ../language/crypto#hashing-with-a-domain-tag
 [Nested Type Requirements]: https://docs.onflow.org/cadence/language/interfaces/#nested-type-requirements
-[Signature verification]: https://cadence-lang.org/docs/1.0/language/crypto#signature-verification
-[Upgrading Fungible Token Contracts]: ./ft-guide.mdx
-[Upgrading Non-Fungible Token Contracts]: ./nft-guide.mdx
-[Vision]: https://github.com/onflow/flips/blob/main/cadence/vision/mutability-restrictions.md
+[Signature verification]: ../language/crypto#signature-verification
+[Upgrading Fungible Token Contracts]: /docs/cadence-migration-guide/ft-guide
+[Upgrading Non-Fungible Token Contracts]: /docs/cadence-migration-guide/nft-guide
+[Vision]: https://github.com/onflow/flips/blob/main/cadence/vision/mutability-restrictions
 [V2 FungibleToken Standard by joshuahannan — Pull Request #77 — onflow/flow-ft]: https://github.com/onflow/flow-ft/pull/77

docs/cadence-migration-guide/ft-guide.mdx …ocs/cadence-migration-guide/ft-guide.mdxdocs/cadence-migration-guide/ft-guide.mdx renamed to content/docs/cadence-migration-guide/ft-guide.mdx docs/cadence-migration-guide/ft-guide.mdx renamed to content/docs/cadence-migration-guide/ft-guide.mdx

@@ -1,7 +1,6 @@
 ---
 title: Cadence 1.0 Migration Guide
-sidebar_position: 1
-sidebar_label: Cadence 1.0 Migration Guide
+description: "Migrate your Cadence code to 1.0 (Crescendo upgrade, Sep 2024): breaking changes, updated NFT/FT standards, new features, and step-by-step upgrade instructions."
 ---
 
 On September 4th, 2024, the Flow Mainnet upgraded to Cadence 1.0.
@@ -24,10 +23,10 @@ In addition to changes to the Cadence programming language, the Cadence token st
 - [Guide for FT Standard v2]
 - [Cadence 1.0 Improvements & New Features]
 
-<!-- Relative links. Will not render on the page -->
+{/* Relative links. Will not render on the page */}
 
 [Crescendo]: https://flow.com/upgrade/crescendo
-[comprehensive suite of new features and improvements]: ./improvements.md
-[Guide for NFT Standard v2]: ./nft-guide.mdx
-[Guide for FT Standard v2]: ./ft-guide.mdx
-[Cadence 1.0 Improvements & New Features]: ./improvements.md
+[comprehensive suite of new features and improvements]: /docs/cadence-migration-guide/improvements
+[Guide for NFT Standard v2]: /docs/cadence-migration-guide/nft-guide
+[Guide for FT Standard v2]: /docs/cadence-migration-guide/ft-guide
+[Cadence 1.0 Improvements & New Features]: /docs/cadence-migration-guide/improvements

…/cadence-migration-guide/improvements.md …cadence-migration-guide/improvements.mdxdocs/cadence-migration-guide/improvements.md renamed to content/docs/cadence-migration-guide/improvements.mdx docs/cadence-migration-guide/improvements.md renamed to content/docs/cadence-migration-guide/improvements.mdx

@@ -0,0 +1,10 @@
+{
+  "title": "Cadence 1.0 Migration Guide",
+  "pages": [
+    "...",
+    "core-contracts-guide",
+    "ft-guide",
+    "improvements",
+    "nft-guide"
+  ]
+}

docs/cadence-migration-guide/index.md …t/docs/cadence-migration-guide/index.mdxdocs/cadence-migration-guide/index.md renamed to content/docs/cadence-migration-guide/index.mdx docs/cadence-migration-guide/index.md renamed to content/docs/cadence-migration-guide/index.mdx

@@ -1,17 +1,12 @@
 ---
 title: Non-Fungible Token Cadence 1.0 Migration Guide
-sidebar_position: 2
-sidebar_label: NFT Cadence 1.0 Guide
 ---
 
 # Non-Fungible Tokens in Cadence 1.0
 
 :::important
-
 On September 4th, 2024, the Flow Mainnet upgraded to Cadence 1.0. In addition to many changes to the Cadence programming language, the Cadence token standards were also streamlined and improved. All applications' scripts and transactions need to be updated. If you do not update your code, your applications will not function properly.
-
 :::
-
 This document describes the changes to the Cadence Non-Fungible Token (NFT) standard and gives a step-by-step guide for how to upgrade your NFT contract from Cadence 0.42 to Cadence 1.0.
 
 We'll be using the [`ExampleNFT` contract] as an example. Many projects have used `ExampleNFT` as a starting point for their projects, so it is widely applicable to most NFT developers on Flow. The upgrades required for `ExampleNFT` will cover 90%+ of what you'll need to do to update your contract. Each project most likely has additional logic or features that aren't included in `ExampleNFT`, but hopefully, after reading this guide, you'll understand Cadence 1.0 well enough that you can easily make any other changes that are necessary.
@@ -112,7 +107,7 @@ Since `Collection` is an interface, you will need to update every instance in yo
 
 This guide covered the most important changes that are required for the Cadence 1.0 upgrades to NFT contracts. Please ask any questions about the migrations in the #developer-questions channel in discord and good luck with your upgrades!
 
-<!-- Relative links. Will not render on the page -->
+{/* Relative links. Will not render on the page */}
 
 [`ExampleNFT` contract]: https://github.com/onflow/flow-nft/blob/master/contracts/ExampleNFT.cdc
 [`master` branch of the flow-nft repo]: https://github.com/onflow/flow-nft