docs: explain read-only simulation behavior in Interact tutorial

[Copilot]

The "Interact" section of the getting-started deploy-to-testnet tutorial silently produces a Simulation identified as read-only message with no context, leaving users confused about whether their invocation succeeded and when --send=yes is actually required.

Changes

• docs/build/smart-contracts/getting-started/deploy-to-testnet.mdx: Added a :::note callout after the expected hello invocation output explaining:
  • The hello function is read-only (no storage writes), so the CLI automatically runs it as a free local simulation—no transaction submitted, no fees incurred
  • The Simulation identified as read-only. Send by rerunning with --send=yes message is expected and can be ignored here; the returned value is already correct
  • --send=yes is only relevant for state-changing functions where the simulation result must be committed on-chain

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Build: Interact tutorial missing explanation of read-only simulation</issue_title>
<issue_description>

What version are you using?

stellar 25.1.0

What did you do?

I followed the "Interact" section of the Soroban tutorial (https://developers.stellar.org/docs/build/smart-contracts/getting-started/deploy-to-testnet#interact) and ran:

stellar contract invoke \
  --id CDQXVLQECZQ4A5HBTZKYGJJHIUIS5WMTBBMJXZ7HGFCC2QB5J5N7VOR2 \
  --source-account alice \
  --network testnet \
  -- \
  hello \
  --to RPC

What did you expect to see?

Based on the tutorial saying "interact with a deployed contract," I expected it to execute the function on-chain.

What did you see instead?

ℹ️  Simulation identified as read-only. Send by rerunning with `--send=yes`.
["Hello","RPC"]

The CLI says to use --send=yes, but doesn't explain what this means or why.

The Problem

The tutorial doesn't explain that the CLI automatically detects read-only functions and simulates them locally. The hello function is read-only (doesn't modify storage), so:

• It's automatically simulated (no transaction sent to the network)
• The --send=yes message appears but isn't needed for read-only functions
• There's no explanation of what "read-only" means or when you'd actually need --send yes

Suggestion

Add a brief explanation in the tutorial:

1. The hello function is read-only, so it's automatically simulated locally (free, no network transaction needed)
2. The --send=yes message can be ignored for read-only functions
3. Later tutorials will cover state-changing functions that require --send yes to persist changes on-chain

This would prevent confusion about the message and help users understand the difference between simulation and actual execution before they encounter state-changing contracts.

</issue_description>

<agent_instructions>Explain that: In Soroban, read-only functions are contract methods that don't modify any state—they just read data and return values. When you invoke these functions via the Stellar CLI, it automatically detects that they're read-only and runs them as a local simulation instead of submitting an actual transaction to the network.

Here's what's happening:

Automatic simulation: The CLI recognizes your function doesn't change state, so it simulates it locally for free—no network fees, no ledger transaction
The --send=yes message: You'll see "Simulation identified as read-only. Send by rerunning with --send=yes" but you can ignore this for read-only functions. The simulation already gave you the correct result
When to use --send=yes: Only needed for state-changing functions (those that write to storage). For those, simulation shows you what would happen, but you need --send=yes to actually persist changes on-chain</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Build: Interact tutorial missing explanation of read-only simulation #2243

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR adds explanatory documentation to the "Deploy to Testnet" tutorial to clarify the confusing "Simulation identified as read-only" message that appears when invoking read-only contract functions. The change addresses user confusion about when --send=yes is needed and what it means for a function to be "read-only."

Changes:

• Added a :::note callout explaining read-only simulation behavior after the expected output section
• Clarified that read-only functions are automatically simulated locally without fees
• Explained when --send=yes is required (state-changing functions only)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.