docs: asset canister guide

[marc0olo]

Summary

• How the asset canister works (HTTP serving, compression, certification, SPA routing, permissions)
• Limitations (no SSR, no dynamic routes, storage limits)
• icp.yaml configuration with recipe syntax and full-stack example
• .ic-assets.json5 configuration (security headers, caching, allow_raw_access, SPA aliasing)
• Deploy workflows (local, mainnet, update-only)
• Canister discovery (ic_env cookie, @icp-sdk/core, dev server setup)
• Programmatic uploads with AssetManager from @icp-sdk/canisters
• Upload permissions (Prepare/Commit/ManagePermissions roles)
• Verification commands and common issues troubleshooting

Sync recommendation

informed by dfinity/icskills — skills/asset-canister/SKILL.md, dfinity/portal — docs/building-apps/frontends/using-an-asset-canister.mdx, dfinity/portal — docs/building-apps/frontends/uploading-serving-assets.mdx

[marc0olo]

Review

Must-fix (3)

1. Invalid CLI command (line 143) — icp canister id frontend doesn't exist in icp-cli. Should use icp canister list.

2. Wrong CLI syntax (line 280) — icp canister update-settings should be icp canister settings update.

3. Banned dfx reference (line 189) — "This replaces the legacy dfx pattern..." violates the no-dfx rule. Remove or rewrite.

Suggestions (4)

4. Missing static-website template coverage — Content brief mentions static-website template and example links (hosting/static-website, hosting/photo-storage, hosting/my_crypto_blog) — none are included.

5. icp sync deserves more explanation — Brief mention at line 165 could note when to prefer it over full redeploy.

6. version recipe parameter undocumented — The asset-canister recipe supports a version param to pin the WASM version.

7. Upstream comment format — Same em dash issue as PR docs: access management guide #29: needs informed by dfinity/portal — docs/... (with em dash).

[marc0olo]

Feedback addressed:

• Replaced nonexistent icp canister id with icp canister list
• Fixed icp canister update-settings → icp canister settings update
• Removed banned dfx reference (rewrote sentence about .env files)
• Expanded icp sync explanation (skips WASM reinstall, only uploads changed files)
• Added static-website template link and photo-storage example in Next steps
• Fixed Upstream comment format (added em dash separators)