cycles-management: add pitfall for icp cycles transfer vs icp canister top-up

[joozzed]

Summary

• Adds pitfall Fix multi-canister Rust factory: API corrections for ic-cdk 0.18 #7 to cycles-management: icp cycles transfer credits the recipient's cycles-ledger balance, not a canister's execution/compute cycle balance — pointing it at a canister principal silently fails to fund the canister, with no error and no visible change in icp canister status.
• Adds a correct/wrong command comparison to the "Top Up a Canister" section.
• Adds evaluations/cycles-management.json (did not previously exist) with 2 output evals and trigger evals covering this distinction.

Found via a real incident: made this exact mistake twice in a row against a live mainnet canister before realizing icp canister top-up was the correct command.

Test plan

• npm run validate — 26 skills validated, all passed, no new warnings
• Eval 1 "Top up a mainnet canister" — WITH skill 3/3, WITHOUT skill 1/3
• Eval 2 "Cycles transfer does not fund a canister" — WITH skill 4/4, WITHOUT skill 3/4
• Trigger evals — should-trigger 4/4, should-not-trigger 3/3

Eval 1: Top up a mainnet canister

WITH skill: 3/3 passed
  ✅ Uses 'icp canister top-up <canister> --amount <N> -e ic' (or -n ic with a principal)
  ✅ Does NOT suggest 'icp cycles transfer' to fund the canister
  ✅ Mentions that --amount supports k/m/b/t suffixes, or shows a concrete amount like 600b or 1000000000000

WITHOUT skill: 1/3 passed
  ❌ Uses 'icp canister top-up <canister> --amount <N> -e ic' (or -n ic with a principal)
     → Uses the old dfx tool ('dfx ledger top-up' / 'dfx cycles top-up') rather than 'icp canister top-up -e ic'.
  ✅ Does NOT suggest 'icp cycles transfer' to fund the canister
  ❌ Mentions that --amount supports k/m/b/t suffixes, or shows a concrete amount like 600b or 1000000000000
     → Uses a generic placeholder '<ICP>' and never mentions suffixes or a concrete cycle amount.

Eval 2: Cycles transfer does not fund a canister

WITH skill: 4/4 passed
  ✅ Explains that 'icp cycles transfer' moves cycles to the recipient's cycles-ledger balance, not the canister's execution/compute cycle balance
  ✅ States that the canister cannot use cycles sent this way
  ✅ Recommends 'icp canister top-up <canister> --amount <N> -e ic' as the correct fix
  ✅ Does NOT suggest that running 'icp cycles transfer' again will move the parked cycles into the canister's execution balance

WITHOUT skill: 3/4 passed
  ✅ Explains that 'icp cycles transfer' moves cycles to the recipient's cycles-ledger balance, not the canister's execution/compute cycle balance
  ✅ States that the canister cannot use cycles sent this way
  ❌ Recommends 'icp canister top-up <canister> --amount <N> -e ic' as the correct fix
     → Suggests 'icp cycles top-up <canister-id> 600000000000 -n ic' — wrong subcommand/flags.
  ✅ Does NOT suggest that running 'icp cycles transfer' again will move the parked cycles into the canister's execution balance

Trigger evals

Should trigger: 4/4 correct
  ✅ "How do I top up my canister with more cycles?"
  ✅ "My canister ran out of cycles and froze, what do I do?"
  ✅ "I sent cycles to my canister's principal with icp cycles transfer but it's still low on cycles"
  ✅ "How do I fund a canister on mainnet before deploying?"

Should NOT trigger: 3/3 correct
  ✅ "Add a wallet connect button for ICRC token transfers in my dapp"
  ✅ "How do I integrate Internet Identity login into my frontend?"
  ✅ "Implement ICRC-1 transfer logic inside my canister"

[github-actions]

Thank you for contributing! Unfortunately this repository does not accept external contributions yet.

We are working on enabling this by aligning our internal processes and our CI setup to handle external contributions. However this will take some time to set up so in the meantime we unfortunately have to close this Pull Request.

We hope you understand and will come back once we accept external PRs.

— The DFINITY Foundation

[marc0olo]

Hey @joozzed, thanks for the contribution! I will check this on Monday and see if we can open the repo for external contributions.

[github-actions]

Thank you for contributing! Unfortunately this repository does not accept external contributions yet.

We are working on enabling this by aligning our internal processes and our CI setup to handle external contributions. However this will take some time to set up so in the meantime we unfortunately have to close this Pull Request.

We hope you understand and will come back once we accept external PRs.

— The DFINITY Foundation

[cla-idx-bot]

Dear @joozzed,

In order to potentially merge your code in this open-source repository and therefore proceed with your contribution, we need to have your approval on DFINITY's CLA.

If you decide to agree with it, please visit this issue and read the instructions there. Once you have signed it, re-trigger the workflow on this PR to see if your code can be merged.

— The DFINITY Foundation

[marc0olo]

Reviewed and verified all commands against the live icp CLI (v1.0.2). Accurate, and a genuinely useful pitfall — nice catch on a real footgun.

Verified against the CLI:

• icp cycles transfer <AMOUNT> <RECEIVER> and icp canister top-up --amount <AMOUNT> <CANISTER> — both confirmed
• --amount k/m/b/t suffixes — confirmed verbatim in --help
• top-up backend ... -e ic (name → needs environment) and cycles transfer ... -n ic (principal → network) are both consistent with the repo's own flag guidance in icp-cli/SKILL.md

The core claim holds: the cycles ledger tracks balances per-principal, so crediting a canister's principal ≠ the canister's execution balance, and icp canister status reflects only the latter. Silent no-op for funding is correct.

One optional nit: icp cycles transfer also supports k/m/b/t suffixes, so the WRONG example could use 600b instead of 600000000000 — then the two lines differ only in the meaningful way (subcommand + flag), which is the point of the side-by-side.

LGTM.