refactor(guides): move cycle-attachment content to inter-canister-calls

[marc0olo]

Summary

• Moves the ## Calling canisters that require cycles section out of the cycles-management guide and into inter-canister-calls as a new ## Calls with attached cycles section. Attaching cycles to a call is a call mechanic, not an operational management concern.
• Also moves the ### Accepting cycles in your canister subsection (which was under "Topping up canisters") to the same new section, since it is the callee-side of the same mechanic.
• Modernizes the moved Motoko examples from the deprecated Cycles.add<system>() imperative style to the current (with cycles = amount) parenthetical syntax, and updates the Rust examples from the low-level msg_cycles_add call to .with_cycles() on the Call builder — consistent with how the rest of inter-canister-calls.mdx is written.
• Extends the callee example to require a specific fee, trap if the attached amount falls short, and accept exactly that fee — excess is returned to the caller automatically. The original "accept all" pattern was a tip-jar, not representative of how real fee-charging canisters (like the XRC) work.
• Renames the callee subsection to ### Charging a cycle fee and the example function to compute() returning (), making clear that cycles are payment for work rather than the subject of the function.
• Fixes icp new proxy --template proxy → icp new proxy --subfolder proxy (no --template flag exists; verified against .sources/icp-cli/docs/reference/cli.md). The bug was present in the original section and carried over during the move.
• Leaves a precise cross-reference in cycles-management.md pointing to the new location.
• Updates four inbound links: concepts/cycles.md (×2), guides/chain-fusion/exchange-rates.mdx (×2).

Sync recommendation

hand-written

Closes #231

[marc0olo]

Code review: one CLI command error found.

All Motoko and Rust examples are correct:

• (with cycles = amount) parenthetical syntax is confirmed correct per the Motoko compiler docs
• Cycles.accept<system>(available) with mo:core/Cycles and mo:core/Runtime imports is correct
• .with_cycles(u128) on the Call builder is confirmed in ic-cdk/src/call.rs
• msg_cycles_available() / msg_cycles_accept() (Rust callee) are correct

Fix needed: The icp new command has no --template flag. The proxy CLI block uses:

icp new proxy --template proxy

The correct flag is --subfolder:

icp new proxy --subfolder proxy

Verified against .sources/icp-cli/docs/reference/cli.md — icp new accepts --subfolder, --git, --path, --branch, --tag, etc. No --template flag exists. This bug was present in the original section in cycles-management.mdx and was carried over unchanged.

[marc0olo]

Feedback addressed:

• Fixed icp new proxy --template proxy → icp new proxy --subfolder proxy (verified against .sources/icp-cli/docs/reference/cli.md)
• Extended "Accepting cycles in the callee" to require a specific fee (100_000_000 as an example constant), trap if available < fee, and accept exactly fee rather than all available cycles — excess is returned to the caller automatically. This matches how real fee-charging canisters (like the XRC) work and avoids silently draining an overpaying caller.

[marc0olo]

Re-reviewed after the follow-up commit. All examples are correct:

CLI fix: --subfolder proxy is now in place. Verified against .sources/icp-cli/docs/reference/cli.md.

Improved callee pattern: the new fee-based accept is correct on both sides.

• Motoko: debug_show fee is a built-in keyword (confirmed in Motoko language manual); Cycles.accept<system>(fee) accepts exactly the fee amount; the Cycles module docs confirm "any remaining available amount is automatically refunded to the caller" on return.
• Rust: msg_cycles_accept(FEE) with FEE: u128 matches the max_amount: u128 signature in ic-cdk/src/api.rs; the "accept exactly the fee; excess is returned automatically" comment is accurate per IC protocol behavior.

All Motoko/Rust imports, anchor links, and the --id-only / --proxy CLI flags are correct. PR looks good.

[raymondk]

we're not removing persistent?

[marc0olo]

I have an issue open to apply modern style Motoko on all shown snippets where this would also be covered: #232

however, I think it should become default behavior in the compiler instead of having to explain why the flag needs to be passed. in theory we should explain this behavior in every snippet where actor is used without persistence keyword.

or we just don't care if somebody copies the actor only snippet without knowing about --default-persistent-actors 😅 but yes, I would like to remove the keyword everywhere.

see also my question on Slack.