Add an agent guide for building and deploying a contract, with AGENTS.md

docs/tools/cli/agent-cli/README.mdx

@@ -22,7 +22,7 @@ Verified against `stellar-cli` 28.1.0.
 Browser wallets are hard for agents. The CLI provides four key agent primitive enhancements:
 
 - **Unified Asset Resolution:** Interacts with native XLM, SAC (Stellar Asset Contracts), or SEP-41 tokens using consistent identifiers (`CODE:ISSUER`, contract ID, or custom alias).
-- **Self-Scaffolding Context:** Running `stellar contract init` automatically generates an `AGENTS.md` guide in local project directories, giving LLMs instant awareness of local commands and tool rules.
+- **Self-Scaffolding Context:** Running `stellar contract init` automatically generates an `AGENTS.md` guide in local project directories, giving LLMs instant awareness of local commands and tool rules. [Build and deploy a contract](./guides/build-and-deploy-contracts.mdx#the-generated-agentsmd) covers what it contains and how to customize it.
 - **Structured JSON Outputs (`--output json`):** The `stellar token` commands return typed JSON, including transaction hashes and a typed error envelope. Coverage elsewhere varies, and `tx send` and `tx new` have no `--output` flag. [Output and errors](./reference/output-and-errors.mdx) lists what each command supports.
 - **Onchain Diagnostic Errors:** When a transaction reverts, the CLI returns the contract's diagnostic event trail inside the error envelope. Agents can read _why_ a transaction failed.
 
@@ -51,6 +51,7 @@ Giving an agent financial execution power requires hard guardrails. The first tw
 
 - [Skills](skills.mdx) covers `stellar skill`, the built-in guide that teaches your agent the CLI's conventions.
 - [Delegate spending](guides/delegate-spending.mdx) is the page to read before any real money is involved.
+- [Build and deploy a contract](guides/build-and-deploy-contracts.mdx) takes your agent from `stellar contract init` to a deployed contract it can call.
 - [Authority & Security Model](reference/authority-model.mdx) is explicit about what the CLI does not protect you from.
 - [Architecture](reference/architecture.mdx) covers how the read and write paths differ, where state lives, and how to split building, signing, and submitting across machines.
 - [Output and errors](reference/output-and-errors.mdx) covers which commands emit structured JSON your agent can branch on, because the coverage is not uniform.

docs/tools/cli/agent-cli/guides/build-and-deploy-contracts.mdx

@@ -0,0 +1,126 @@
+---
+title: Build and deploy a contract
+sidebar_position: 80
+description: Have your agent create a contract project with `stellar contract init`, build, deploy, and invoke it, and use the `AGENTS.md` file the project ships with.
+keywords:
+  [
+    Stellar,
+    agent,
+    AGENTS.md,
+    contract init,
+    contract build,
+    contract deploy,
+    contract invoke,
+    CLI,
+  ]
+---
+
+# Build and deploy a contract
+
+Have your agent create a contract project, build it, deploy it to testnet, and call it. The project comes with an `AGENTS.md` file that tells your agent how to work in it.
+
+## Ask your agent
+
+```text
+Create a Stellar contract project called my-project, build it, deploy it to testnet from agent-1, and call its hello function.
+```
+
+## Before you start
+
+- Follow the [Quickstart](../quickstart.mdx) first. `stellar contract init` writes `AGENTS.md` from `stellar-cli` 28.0.0 on.
+- Install Rust 1.84 or later and the `wasm32v1-none` target with `rustup target add wasm32v1-none`. Rust 1.82 and 1.83 cannot build contracts.
+- Fund a testnet identity, for example `agent-1` from the Quickstart.
+
+## Steps
+
+1. Create the project:
+
+   ```bash
+   stellar contract init my-project
+   cd my-project
+   ```
+
+   This writes a Cargo workspace with one contract in `contracts/hello-world`, plus `README.md` and `AGENTS.md` at the workspace root. Pass `--name <NAME>` for a different contract name.
+
+2. Build every contract in the workspace:
+
+   ```bash
+   stellar contract build
+   ```
+
+   The WASM file lands at `target/wasm32v1-none/release/hello_world.wasm`. The file name uses `_` where the package name has `-`. Add `--package <NAME>` to build one contract.
+
+3. Deploy the contract and save an alias for it:
+
+   ```bash
+   ID=$(stellar contract deploy --wasm target/wasm32v1-none/release/hello_world.wasm --source agent-1 --network testnet --alias hello_world)
+   ```
+
+   stdout is the contract ID alone, on one line. `--alias` replaces an existing alias of the same name without asking, and warns about it on stderr.
+
+   Inside a workspace you can leave out `--wasm`. `deploy` then builds first, deploys every contract, uses each package name as its alias, and prints one contract ID per line.
+
+4. Call the contract:
+
+   ```bash
+   stellar contract invoke --id hello_world --source agent-1 --network testnet -- hello --to world
+   ```
+
+   stdout is the return value as one line of JSON, here `["Hello","world"]`. A function with no return value prints an empty line.
+
+   `hello` only reads, so the CLI simulates the call and does not submit a transaction. It says so on stderr. Add `--send=yes` to submit it anyway. A call that writes state, emits an event, or needs authorization is submitted by default.
+
+   To list a deployed contract's functions and their arguments, run `stellar contract invoke --id hello_world --network testnet -- -h`. It prints the list on stdout and exits with code 1, so do not treat that exit code as a failure.
+
+## Read stdout, not `--output json`
+
+`contract init`, `contract build`, `contract deploy`, and `contract invoke` have no `--output` flag. [Output and errors](../reference/output-and-errors.mdx) lists the commands that do. Parse these four by stream:
+
+| Command | stdout | stderr |
+| --- | --- | --- |
+| `contract init` | Nothing | Each file it writes or skips |
+| `contract build` | Nothing to parse | Cargo progress and the build summary |
+| `contract deploy` | The contract ID | Upload and deploy progress, and the alias warning |
+| `contract invoke` | The return value as JSON | Simulation and submission progress |
+
+Keep the two streams apart. `2>&1` mixes progress lines into the value you parse. A failure prints `❌ error: ...` on stderr and exits non-zero, so check the exit code before you read stdout.
+
+## The generated `AGENTS.md`
+
+`stellar contract init` writes `AGENTS.md` at the workspace root. It is a short Markdown brief for coding agents. It covers:
+
+- **Layout:** the workspace `Cargo.toml`, and each contract's `src/lib.rs` and `src/test.rs` under `contracts/<name>/`.
+- **Build:** `stellar contract build`, where the WASM files land, and `--package` for one contract. It tells the agent not to use `cargo build --target wasm32v1-none`, because `stellar contract build` applies the flags and metadata the network expects.
+- **Toolchain:** the `wasm32v1-none` target and Rust 1.84 or later.
+- **Test:** `cargo test`, or `cargo test -p <name>` for one contract.
+- **Deploy and invoke:** testnet commands for the sample `hello` function, and `-- -h` to list a deployed contract's functions.
+- **Further reading:** links to the smart contract docs and soroban-examples.
+
+The template lives in the CLI source at [`contract-workspace-template/AGENTS.md`](https://github.com/stellar/stellar-cli/blob/v28.1.0/cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md).
+
+`AGENTS.md` describes this project. [`stellar skill`](../skills.mdx) describes the CLI itself. Give your agent both.
+
+### How agents pick it up
+
+`AGENTS.md` follows the [AGENTS.md](https://agents.md) convention. Agents that support it read the file when they work in the project, so there is nothing to install or run. If your agent reads a different instructions file, add a line there that points to `AGENTS.md`.
+
+The file is a copy made when you ran `init`. It does not change when you upgrade the CLI.
+
+### Customize it
+
+`AGENTS.md` is a plain file in your project. Edit it and commit it with the rest of your code. Useful changes:
+
+- Replace the `hello` sample with your own contract names, functions, and arguments.
+- Name the identity and network the agent must use, for example `--source agent-1 --network testnet`.
+- Add your own rules, for example "run `cargo test` before every deploy".
+
+A rule in `AGENTS.md` is an instruction to the agent, not a limit the CLI enforces. To limit what an agent can spend, see [Delegate spending](delegate-spending.mdx).
+
+Running `init` again keeps your edits. For example, `stellar contract init . --name increment` adds a contract and skips every file that already exists, `AGENTS.md` included. `--overwrite` replaces every template file, `AGENTS.md` included, so save your changes before you use it.
+
+## Related pages
+
+- [Skills](../skills.mdx)
+- [Output and errors](../reference/output-and-errors.mdx)
+- [Hello World](../../../../build/smart-contracts/getting-started/hello-world.mdx)
+- [Stellar CLI Manual](../../stellar-cli.mdx)

docs/tools/cli/agent-cli/skills.mdx

@@ -20,6 +20,10 @@ The guide covers `network`, `keys`, `contract`, `container`, and `env`. It tells
 
 The guide is static text compiled into the binary ([source](https://github.com/stellar/stellar-cli/blob/main/cmd/soroban-cli/src/commands/skill/SKILL.md)), so it does not track flag changes or your local config. Where it differs from these docs on the CLI's own conventions, follow the guide. For example, it prefers `--id` over the canonical `--contract-id` because `--id` also works on older releases.
 
+## Project context: `AGENTS.md`
+
+`stellar skill` describes the CLI. A project made with `stellar contract init` also gets an `AGENTS.md` file that describes that project. [Build and deploy a contract](guides/build-and-deploy-contracts.mdx#the-generated-agentsmd) covers what it contains, how agents read it, and how to customize it.
+
 ## Optional: Stellar development skill
 
 [stellar/stellar-dev-skill](https://github.com/stellar/stellar-dev-skill) covers Stellar development beyond the CLI: Soroban contracts, client SDKs, Stellar RPC, assets, wallets, testing, and security. Nothing in these docs needs it. Add it if your agent also writes contracts or application code.

routes.txt

@@ -764,6 +764,7 @@
 /docs/tools
 /docs/tools/cli
 /docs/tools/cli/agent-cli
+/docs/tools/cli/agent-cli/guides/build-and-deploy-contracts
 /docs/tools/cli/agent-cli/guides/build-and-submit-transactions
 /docs/tools/cli/agent-cli/guides/check-balances-and-metadata
 /docs/tools/cli/agent-cli/guides/delegate-spending