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

AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repo. Every claim below is sourced from the
+Makefile, `go.mod`, `ci.yml`, `CONTRIBUTING.md`, or verified source files — do not add
+unverified commands or paths.
+
+## Overview
+
+`flow-cli` is the official command-line tool for the Flow blockchain: deploy contracts, run
+transactions/scripts, manage accounts/keys, and run a bundled emulator. Go 1.25.1 module
+(`github.com/onflow/flow-cli`), built on [Cobra](https://github.com/spf13/cobra). All
+blockchain logic is delegated to the external `github.com/onflow/flowkit/v2` module. Entry
+point is `cmd/flow/main.go`. License: Apache-2.0.
+
+## Build and Test Commands
+
+CGO is required (BLS crypto). `go build` / `go test` need these env vars set:
+`CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11"`.
+
+- `make binary` — build `./cmd/flow/flow`; ldflags inject version, commit, and analytics tokens
+- `make test` — `go test -coverprofile=coverage.txt ./...` with CGO flags set
+- `make ci` — `generate test coverage` (this is what GitHub Actions runs)
+- `make coverage` — emits `index.html` and `cover-summary.txt`, only when `COVER=true`
+- `make lint` — `golangci-lint run -v ./...`; depends on `make generate`
+- `make fix-lint` — golangci-lint with `--fix`
+- `make generate` — `go generate ./...`; run before `lint`, `ci`, or any test touching generated code
+- `make check-headers` — `./check-headers.sh`, verifies Apache-2.0 header on every `.go` file
+- `make check-tidy` — `go mod tidy` (CI runs this; fails if `go.mod`/`go.sum` drift)
+- `make clean` — removes binaries under `cmd/flow/`
+- `make versioned-binaries` — cross-compiles linux/darwin/windows × amd64/arm64
+- `make publish` — uploads versioned binaries to `gs://flow-cli` via `gsutil`
+- `make release` — runs `ghcr.io/goreleaser/goreleaser-cross:v1.25.0` in Docker
+- `make test-e2e-emulator` — `flow -f tests/flow.json emulator start`
+- `SKIP_NETWORK_TESTS=1 make test` — skip tests that reach Flow mainnet/testnet (CONTRIBUTING.md)
+- `nix develop` — enter dev shell from `flake.nix`; then `go run cmd/flow/main.go`
+
+## Architecture
+
+Cobra CLI. `cmd/flow/main.go` wires every subcommand into the root `flow` command and defines
+eight command groups (super, resources, interactions, tools, project, security, manager, schedule).
+
+**`internal/command/`** — shared framework. `command.Command` wraps `cobra.Command` with two
+run modes: `Run` (no project state) and `RunS` (requires `*flowkit.State` loaded from
+`flow.json`). `AddToParent()` handles loading `flow.json`, gateway/network resolution,
+`flowkit.Services` init, version check, analytics, and error formatting. Global flags
+(`internal/command/global_flags.go`): `--network`, `--host`, `--log`, `--output`, `--filter`,
+`--save`, `--config-path`, `--yes`, `--skip-version-check`. Every `Result` must implement
+`String()`, `Oneliner()`, and `JSON()`.
+
+**`internal/super/`** — super commands (`flow init`, `flow dev`, `flow generate`, `flow flix`).
+Scaffolding engine under `internal/super/generator/` with `templates/` and `fixtures/`.
+
+**Feature packages** (`internal/<name>/`) — one per top-level command; each exports a
+`Cmd *cobra.Command` (or `Command`) registered in `main.go`:
+`accounts`, `blocks`, `cadence`, `collections`, `config`, `dependencymanager`, `emulator`,
+`events`, `evm`, `keys`, `mcp`, `project`, `quick` (`flow deploy`, `flow run`), `schedule`
+(transaction scheduler: `setup`/`get`/`list`/`cancel`/`parse`), `scripts`, `settings`,
+`signatures`, `snapshot`, `status`, `test`, `tools` (`dev-wallet`, `flowser`), `transactions`,
+`version`. Support: `internal/util/`, `internal/prompt/`.
+
+**`build/build.go`** — version/commit variables injected via `-ldflags` at build time.
+**`common/branding/`** — styling/ASCII constants.
+**`flowkit/`** (top-level) — **historical artifact**; contains only `README.md` and
+`schema.json`. All Go code moved to the external `github.com/onflow/flowkit/v2`.
+**`docs/`** — hand-maintained Markdown reference pages, one per command, published to
+developers.flow.com.
+**`testing/better/`** — shared test helpers.
+
+## Conventions and Gotchas
+
+- **`make generate` before `make lint` and CI workflows.** `lint` declares `generate` as a
+  prerequisite; `ci` runs `generate test coverage` in that order.
+- **CGO is not optional.** Plain `go build ./...` / `go test ./...` without the CGO env vars
+  above will fail on the BLS crypto dependency (`__BLST_PORTABLE__`).
+- **Register new commands via `command.Command.AddToParent(cmd)`** (not raw `cmd.AddCommand`)
+  so shared boilerplate — `flow.json` load, gateway init, error formatting — runs. See
+  `cmd/flow/main.go` for both registration styles.
+- **Command naming is `noun verb`** (`flow accounts get`, not `flow get-accounts`) — see
+  "CLI Guidelines" in `CONTRIBUTING.md`.
+- **Prefer flags over positional args.** Use an arg only for the single primary required value.
+- **`--output json` must always work.** Every `Result` implements `JSON()`; never gate
+  machine-readable output behind a subcommand.
+- **stdout for normal output, stderr for errors.** No stack traces on error; `--log debug`
+  is the escape hatch.
+- **Every `.go` file needs the Apache-2.0 header.** `check-headers.sh` greps for
+  `Licensed under the Apache License` or `Code generated (from|by)` and fails CI otherwise.
+- **goimports `local-prefixes: github.com/onflow/flow-cli`** (`.golangci.yml`) — internal
+  imports group separately from third-party.
+- **Linters enabled:** `errcheck`, `govet`, `ineffassign`, `misspell`, plus `goimports`
+  formatter. CI pins `golangci-lint v2.4.0` (`.github/workflows/ci.yml`).
+- **`SKIP_NETWORK_TESTS=1`** skips tests that reach mainnet/testnet nodes — use in Nix or
+  egress-restricted CI (CONTRIBUTING.md "Skipping Network-Dependent Tests").
+- **`syscall.Exit` in `cmd/flow/main.go` is intentional** — works around a gRPC cleanup
+  regression that appeared in Go 1.23.1 (inline comment in `main.go`).
+- **`version.txt` is deprecated** for CLI versions after v1.18.0 (CONTRIBUTING.md
+  "Releasing"). The semver is derived from the git tag via `-ldflags` into `build.semver`.
+- **Analytics tokens (`MIXPANEL_PROJECT_TOKEN`, `ACCOUNT_TOKEN`) are baked in at build time**
+  via ldflags in the Makefile — rebuild, don't patch the binary.
+
+## Files Not to Modify
+
+- `go.sum` — regenerate via `go mod tidy` / `make check-tidy`, never hand-edit.
+- `flake.lock` — update via `nix flake update`.
+- `flowkit/` top-level directory — legacy stub; real code lives in `github.com/onflow/flowkit/v2`.
+- `version.txt` — deprecated post v1.18.0; leave it.
+- `cli-banner.svg`, `cli.gif` — release artifacts.

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+Release notes and version history for flow-cli are tracked via GitHub Releases:
+
+- https://github.com/onflow/flow-cli/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-cli in your research or reference it, please cite it as below."
+title: "flow-cli: The Flow Command-Line Interface"
+authors:
+  - name: "Flow Foundation"
+    website: "https://flow.com"
+repository-code: "https://github.com/onflow/flow-cli"
+url: "https://flow.com"
+license: Apache-2.0
+type: software
+keywords:
+  - flow
+  - flow-network
+  - flow-cli
+  - cadence
+  - blockchain
+  - developer-tools

README.md

@@ -1,4 +1,11 @@
-<br />
+# flow-cli — The Flow Command-Line Interface
+
+[![License](https://img.shields.io/github/license/onflow/flow-cli)](https://github.com/onflow/flow-cli/blob/master/LICENSE)
+[![Release](https://img.shields.io/github/v/release/onflow/flow-cli)](https://github.com/onflow/flow-cli/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-cli.svg)](https://pkg.go.dev/github.com/onflow/flow-cli)
+
 <p align="center">
   <a href="https://developers.flow.com/tools/flow-cli/install">
     <img src="./cli-banner.svg" alt="Logo" width="270" height="auto">
@@ -17,8 +24,16 @@
     <a href="https://github.com/onflow/flow-cli/blob/master/CONTRIBUTING.md#cli-guidelines">Read Guidelines</a>
   </p>
 </p>
-<br />
-<br />
+
+## TL;DR
+
+- **What:** Official command-line interface for the Flow network. Deploy contracts, run transactions and scripts, manage accounts and keys, and run a local emulator from your terminal.
+- **Who it's for:** Developers building dapps, smart contracts, or tooling on Flow.
+- **Why use it:** A single tool covering project scaffolding, local development, contract deployment, and network interaction across emulator, testnet, and mainnet.
+- **Status:** see [Releases](https://github.com/onflow/flow-cli/releases) for the latest version.
+- **License:** Apache-2.0.
+- **Related repos:** [onflow/cadence](https://github.com/onflow/cadence) · [onflow/flow-go](https://github.com/onflow/flow-go) · [onflow/fcl-js](https://github.com/onflow/fcl-js)
+- The reference command-line interface for the Flow network, open-sourced since 2019.
 
 ## Installation
 
@@ -29,7 +44,7 @@ To install the Flow CLI, follow the [installation instructions](https://develope
 You can find the CLI documentation on the [CLI documentation website](https://developers.flow.com/tools/flow-cli).
 
 ## Features
-The Flow CLI is a command line tool that allows you to interact with the Flow blockchain. 
+The Flow CLI is a command line tool that allows you to interact with the Flow network.
 Read about supported commands in the [CLI documentation website](https://developers.flow.com/tools/flow-cli).
 
 ```
@@ -82,3 +97,35 @@ The Flow CLI includes several commands to interact with Flow networks, such as q
 ## Contributing 
 
 Read [contributing](./CONTRIBUTING.md) document.
+
+## FAQ
+
+**What is the Flow CLI?**
+The Flow CLI is a command-line tool for interacting with the Flow network. It supports deploying contracts, sending transactions, running scripts, managing accounts and keys, and running a local emulator.
+
+**How do I install the Flow CLI?**
+Follow the installation instructions at [developers.flow.com/tools/flow-cli/install](https://developers.flow.com/tools/flow-cli/install). Installers are provided for macOS, Linux, and Windows.
+
+**How do I start a new Flow project?**
+Run `flow init` to scaffold a new project. This uses the super commands described in the Features section above.
+
+**Does the Flow CLI include a local emulator?**
+Yes. The CLI bundles the [Flow Emulator](https://developers.flow.com/tools/emulator) so you can develop and test locally before deploying to testnet or mainnet.
+
+**Where can I find the reference for `flow.json`?**
+See [docs/configuration.md](./docs/configuration.md) in this repo and the [configuration reference](https://developers.flow.com/tools/flow-cli) on the docs site.
+
+**How do I report a bug or request a feature?**
+Open an issue at [github.com/onflow/flow-cli/issues](https://github.com/onflow/flow-cli/issues). For security issues, follow [SECURITY.md](./SECURITY.md).
+
+**What license is the Flow CLI released under?**
+Apache-2.0. See [LICENSE](./LICENSE).
+
+## 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)