Generate AGENTS.md when running stellar contract init

cmd/crates/soroban-test/tests/it/init.rs

@@ -39,6 +39,11 @@ fn init() {
         .arg(".")
         .assert()
         .success();
+    sandbox
+        .dir()
+        .child("AGENTS.md")
+        .assert(predicate::str::contains("stellar contract build"));
+
     sandbox
         .dir()
         .child("Cargo.toml")

cmd/soroban-cli/src/commands/contract/init.rs

@@ -196,6 +196,7 @@ mod tests {
         runner.run().unwrap();
 
         assert_base_template_files_exist(&project_dir);
+        assert_agents_md_covers_build_and_test(&project_dir);
 
         assert_contract_files_exist(&project_dir, "hello_world");
         assert_excluded_paths_do_not_exist(&project_dir);
@@ -224,12 +225,28 @@ mod tests {
 
     // test helpers
     fn assert_base_template_files_exist(project_dir: &Path) {
-        let expected_paths = ["contracts", "Cargo.toml", "README.md"];
+        let expected_paths = ["contracts", "Cargo.toml", "README.md", "AGENTS.md"];
         for path in &expected_paths {
             assert!(project_dir.join(path).exists());
         }
     }
 
+    fn assert_agents_md_covers_build_and_test(project_dir: &Path) {
+        let agents = read_to_string(project_dir.join("AGENTS.md")).unwrap();
+        assert!(
+            agents.contains("stellar contract build"),
+            "AGENTS.md should document stellar contract build"
+        );
+        assert!(
+            agents.contains("cargo test"),
+            "AGENTS.md should document cargo test"
+        );
+        assert!(
+            agents.contains("wasm32v1-none"),
+            "AGENTS.md should mention the WASM target"
+        );
+    }
+
     fn assert_contract_files_exist(project_dir: &Path, contract_name: &str) {
         let contract_dir = project_dir.join("contracts").join(contract_name);
 

cmd/soroban-cli/src/utils/contract-workspace-template/AGENTS.md

@@ -0,0 +1,58 @@
+# Agent instructions
+
+This is a Stellar smart-contract workspace (Soroban). Each contract is a workspace member under `contracts/<name>/`.
+
+## Layout
+
+- `Cargo.toml` — workspace root; contract crates inherit `soroban-sdk` from here
+- `contracts/<name>/src/lib.rs` — contract implementation (`#![no_std]`)
+- `contracts/<name>/src/test.rs` — host-side unit tests
+
+## Build
+
+From the workspace root:
+
+```sh
+stellar contract build
+```
+
+That compiles every `cdylib` member to WASM. Artifacts land in `target/wasm32v1-none/release/*.wasm`. Build one crate with `stellar contract build --package <name>`.
+
+Do not substitute this with `cargo build --target wasm32v1-none`. `stellar contract build` applies the flags and metadata the network expects.
+
+The `wasm32v1-none` Rust target must be installed (`rustup target add wasm32v1-none`). Rust 1.84 or newer is required for that target. Rust 1.82 and 1.83 cannot build contracts.
+
+## Test
+
+Host tests run with the normal Cargo test harness (not on-chain):
+
+```sh
+cargo test
+```
+
+A single crate: `cargo test -p <name>`.
+
+## Deploy and invoke
+
+On testnet, after a successful build:
+
+```sh
+stellar contract deploy \
+  --wasm target/wasm32v1-none/release/<name>.wasm \
+  --source-account <identity> \
+  --network testnet \
+  --alias <alias>
+
+stellar contract invoke \
+  --id <alias> \
+  --network testnet \
+  --source-account <identity> \
+  -- hello --to world
+```
+
+The sample `hello_world` contract exposes `hello(to: String) -> Vec<String>`. Replace that with your own functions; `stellar contract invoke --id <id> -- -h` prints the generated CLI for the deployed contract.
+
+## Further reading
+
+- https://developers.stellar.org/docs/build/smart-contracts/overview
+- https://github.com/stellar/soroban-examples

cmd/soroban-cli/src/utils/contract-workspace-template/README.md

@@ -13,6 +13,7 @@ This repository uses the recommended structure for a Soroban project:
 │       │   └── test.rs
 │       └── Cargo.toml
 ├── Cargo.toml
+├── AGENTS.md
 └── README.md
 ```