docs: add TL;DR, FAQ, and GEO enhancements for discoverability

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+Release notes and version history for flow-core-contracts are tracked via GitHub Releases:
+
+- https://github.com/onflow/flow-core-contracts/releases
+
+For user-facing changes per version, see the Releases page.

CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use flow-core-contracts in your research or reference it, please cite it as below."
+title: "flow-core-contracts: Cadence protocol contracts for the Flow network"
+authors:
+  - name: "Flow Foundation"
+    website: "https://flow.com"
+repository-code: "https://github.com/onflow/flow-core-contracts"
+url: "https://flow.com"
+license: Unlicense
+type: software
+keywords:
+  - flow
+  - flow-network
+  - cadence
+  - core-contracts
+  - staking
+  - proof-of-stake

README.md

@@ -1,19 +1,33 @@
-# Flow Core Smart Contracts
+# flow-core-contracts — Cadence Protocol Contracts for the Flow Network
 
-These are the smart contracts that define the core functionality of the Flow protocol.
+[![License](https://img.shields.io/github/license/onflow/flow-core-contracts)](https://github.com/onflow/flow-core-contracts/blob/master/LICENSE)
+[![Release](https://img.shields.io/github/v/release/onflow/flow-core-contracts?include_prereleases)](https://github.com/onflow/flow-core-contracts/releases)
+[![Discord](https://img.shields.io/discord/613813861610684416?label=Discord&logo=discord)](https://discord.gg/flow)
+[![Built on Flow](https://img.shields.io/badge/Built%20on-Flow-00EF8B)](https://flow.com)
+[![Go Reference](https://pkg.go.dev/badge/github.com/onflow/flow-core-contracts/lib/go/templates.svg)](https://pkg.go.dev/github.com/onflow/flow-core-contracts/lib/go/templates)
+
+## TL;DR
+
+- **What:** Cadence smart contracts that define core protocol functionality of the Flow network, including FLOW token, staking, delegation, epochs, service account, fees, scheduled transactions, and random beacon history.
+- **Who it's for:** Flow node operators, staking and delegation service builders, protocol researchers, and Cadence developers integrating with Flow protocol contracts.
+- **Why use it:** Canonical source of the protocol-level contracts deployed to Flow networks (Emulator, Testnet, Mainnet), plus reusable Cadence transaction templates and a Go template package.
+- **Status:** see [Releases](https://github.com/onflow/flow-core-contracts/releases) for the latest version.
+- **License:** Unlicense.
+- **Related repos:** [onflow/cadence](https://github.com/onflow/cadence), [onflow/flow-go](https://github.com/onflow/flow-go), [onflow/flow-ft](https://github.com/onflow/flow-ft)
+- The reference set of core staking and token contracts for the Flow network, open-sourced since 2020.
 
 # What is Flow?
 
-Flow is a new blockchain for open worlds. Read more about it [here](https://www.onflow.org/).
+Flow is a Layer 1 blockchain built for consumer applications, AI Agents, and DeFi at scale. Read more at [flow.com](https://flow.com).
 
 # What is Cadence?
 
-Cadence is a new Resource-oriented programming language
-for developing smart contracts for the Flow Blockchain.
-Read more about it [here](https://www.docs.onflow.org)
+Cadence is a resource-oriented programming language
+for developing smart contracts for the Flow network.
+Read more about it at [cadence-lang.org](https://cadence-lang.org).
 
 We recommend that anyone who is reading this should have already
-completed the [Cadence Tutorials](https://docs.onflow.org/docs/getting-started-1)
+completed the [Cadence Tutorials](https://cadence-lang.org/docs/tutorial/first-steps)
 so they can build a basic understanding of the programming language.
 
 ## FlowToken
@@ -59,7 +73,7 @@ This contract defines fees that are spent for executing transactions and creatin
 This contract defines fees that are spent to pay for the storage that an account uses.
 There is a minimum balance that an account needs to maintain in its main `FlowToken` Vault
 in order to pay for the storage it uses.
-You can see [more docs about storage capacity and fees here.](https://docs.onflow.org/concepts/storage/#overview)
+You can see [more docs about storage capacity and fees here.](https://developers.flow.com/build/basics/fees)
 
 ## Service Account Contract
 
@@ -143,7 +157,7 @@ as well as the process for adding and removing nodes from the network via Epochs
 Each node identity stakes tokens with these contracts, and also gets paid rewards with their contracts.
 This contract also manages the logic for users to delegate their tokens to a node operator
 and receive their own rewards. You can see an explanation of this process in the staking section
-of the [Flow Docs website](https://docs.onflow.org/token/staking/).
+of the [Flow Docs website](https://developers.flow.com/networks/staking).
 
 You can find all the transactions for interacting with the IDTableStaking contract with unlocked FLOW
 in the `transactions/idTableStaking` directory, though it is recommended to use the staking collection
@@ -156,7 +170,7 @@ with all the epoch smart contracts in the following directories:
 `transactions/quorumCertificate/`
 
 You can also find scripts for querying info about staking and stakers in the `transactions/idTableStaking/scripts/` directory.
-These scripts are documented in the [staking scripts section of the docs](https://docs.onflow.org/staking/scripts/)
+These scripts are documented in the [staking scripts section of the docs](https://developers.flow.com/networks/staking/staking-scripts-events)
 
 ## Flow Locked Tokens contract
 
@@ -169,7 +183,7 @@ These scripts are documented in the [staking scripts section of the docs](https:
 | Mainnet  | `0x8d0e87b65159ae63` |
 
 This contract manages the two year lockup of Flow tokens that backers purchased in the initial
-token sale in October of 2020. See more documentation about `LockedTokens` [here.](https://docs.onflow.org/flow-token/locked-account-setup/)
+token sale in October of 2020. See more documentation about `LockedTokens` [here.](https://developers.flow.com/networks/staking/staking-options)
 
 ## Flow Staking Collection Contract
 
@@ -181,12 +195,12 @@ as the `LockedTokens` contract on all the networks.
 A Staking Collection is a resource that allows its owner to manage multiple staking
 objects in a single account via a single storage path, and perform staking and delegation actions using both locked and unlocked Flow.
 
-Before the staking collection, accounts could use the instructions in [the unlocked staking guide](https://docs.onflow.org/staking/unlocked-staking-guide/)
+Before the staking collection, accounts could use the instructions in [the unlocked staking guide](https://developers.flow.com/networks/staking/staking-options)
 to stake with tokens. This was a bit restrictive, because that guide (and the corresponding transactions) only supports one node and one delegator object
 per account. If a user wanted to have more than one per account, they would either have to use custom transactions with custom storage paths for each object,
 or they would have had to use multiple accounts, which comes with many hassles of its own.
 
-The same applies to the [locked tokens staking guide](https://docs.onflow.org/staking/locked-staking-guide/).
+The same applies to the [locked tokens staking guide](https://developers.flow.com/networks/staking/staking-options).
 We only built in support for one node and one delegator per account.
 
 The staking collection is a solution to both of these deficiencies. When an account is set up to use a staking collection,
@@ -207,7 +221,7 @@ then all the changes are handled for them and there is nothing for you to worry
 
 * The staking collection contract stores [a dictionary of staking objects](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowStakingCollection.cdc#L68) from the staking contract that are used to manage the stakers tokens. Since they are dictionaries, there can be as many node or delegator objects per account as the user wants.
 * The resource only has one set of staking methods, which route the call to the correct staking object based on the arguments that the caller specifies. (nodeID, delegatorID)
-* The contract also stores an [optional capability to the locked token vault](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowStakingCollection.cdc#L63) and [locked tokens `TokenHolder` resource](https://github.com/onflow/flow-core-contracts/blob/master/ontracts/FlowStakingCollection.cdc#L73). This is only used if the user already has a locked account. The staking collection does not change the locked account setup at all, it only has access to it and to the locked vault.
+* The contract also stores an [optional capability to the locked token vault](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowStakingCollection.cdc#L63) and [locked tokens `TokenHolder` resource](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowStakingCollection.cdc#L73). This is only used if the user already has a locked account. The staking collection does not change the locked account setup at all, it only has access to it and to the locked vault.
 * The collection makes the staking objects and vault capability fields private, because since it has access to the locked tokens, it needs to mediate access to the staking objects so users cannot withdraw tokens that are still locked from the sale. The resource has fields `unlockedTokensUsed` and `lockedTokensUsed`, to keep track of how many locked and unlocked tokens are being used for staking in order to allow the user to withdraw the correct amount when they choose to.
 * The staking collection contract is a brand new contract that will be deployed to the same account as the existing locked tokens contract. A few of the fields on the `LockedTokens` contract have been updated to have `access(account)` visibility instead of `access(self)` because the staking collection contract needs to be able to access to them in order to work properly.
 * We also included a public interface and getters in the contract so you can easily query it with an address to get node or delegator information from a collection.
@@ -255,4 +269,36 @@ to the team and we would be happy to help!
 
 The works in these folders are under the [Unlicense](https://github.com/onflow/flow-core-contracts/blob/master/LICENSE):
 
-- [src/contracts](https://github.com/onflow/flow-core-contracts/tree/master/contracts)
+- [contracts](https://github.com/onflow/flow-core-contracts/tree/master/contracts)
+
+## FAQ
+
+**Q: What is in this repository?**
+A: Cadence smart contracts that define core protocol functionality on the Flow network (FLOW token, fees, staking, delegation, epochs, service account, scheduled transactions, random beacon history, and related utilities) plus transaction templates for interacting with them.
+
+**Q: Where are these contracts deployed?**
+A: Addresses for Emulator, Testnet, and Mainnet deployments are listed alongside each contract section in this README.
+
+**Q: How do I run the tests?**
+A: Run `make test` from the repository root. Tests rely on the transaction templates in the `transactions/` directory.
+
+**Q: How can I use the transaction templates from Go?**
+A: Import the `lib/go/templates` package (`go get github.com/onflow/flow-core-contracts/lib/go/templates@<version>`) and call the template getters exposed by the `*_templates.go` files.
+
+**Q: Which staking setup should new integrations use?**
+A: The Staking Collection is recommended. It supports multiple node or delegator objects per account and unifies the locked and unlocked staking flows behind a single interface.
+
+**Q: Where can I learn more about Cadence?**
+A: See the Cadence language reference at [cadence-lang.org](https://cadence-lang.org).
+
+**Q: Where can I read the formal audit report?**
+A: Flow Core Contracts were audited by Quantstamp in July 2021; the [final report](https://certificate.quantstamp.com/full/epoch-functionality-contracts.pdf) is linked in the Audit section above.
+
+## About Flow
+
+This repo is part of the [Flow network](https://flow.com), a Layer 1 blockchain built for consumer applications, AI Agents, and DeFi at scale.
+
+- Developer docs: https://developers.flow.com
+- Cadence language: https://cadence-lang.org
+- Community: [Flow Discord](https://discord.gg/flow) · [Flow Forum](https://forum.flow.com)
+- Governance: [Flow Improvement Proposals](https://github.com/onflow/flips)