docs: developer onboarding pass for all entry-point READMEs (#1466)

* docs: developer onboarding pass for all entry-point READMEs

Every category directory now has a proper entry point focused on getting
a newcomer from zero to a running example:

- Root README: contribution invitation removed (repo is not soliciting
  external PRs while examples are restructured for the developer docs),
  'New here?' path rewritten with language-labeled links (hello_world →
  who_am_i), wasm/ listed alongside the other categories.
- motoko/ and hosting/ READMEs rewritten; rust/, native-apps/, and wasm/
  READMEs created: each opens with a start-here path, then a categorized
  index of every example with a one-line description and relative links,
  and closes with the canonical security-best-practices link.
- vetkeys indexes: motoko/vetkeys/README.md created; rust/vetkeys/README.md
  rewritten to link the local examples instead of the upstream vetkeys
  repository (which it pointed at exclusively, under partly wrong names).
- Link conventions applied throughout: Internet Identity mentions link the
  developer docs guide in integration contexts (id.ai stays only for
  live-instance references, e.g. ic-pos mainnet notes); all external links
  verified against the current docs site; all relative links checked.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(hosting): clarify certified-assets (static-site) vs legacy asset canister

The hosting examples run on the @dfinity/static-site recipe
(certified-assets canister), which replaces the legacy asset canister
going forward. Name both, state the direction, and mark photo-storage as
the deliberate legacy exception (AssetManager uploads).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: marc0olo

README.md

@@ -6,11 +6,9 @@ Get started building on ICP with the sample applications in this repository. Fro
 
 The projects in this repository are not intended to be used as commercial applications and do not provide any explicit or implied support or warranty of any kind.
 
-You can also contribute your own project or suggest updates to published projects using the standard GitHub workflow.
-
 ## Sample applications
 
-**New here?** Start with [hello_world](motoko/hello_world/) (Motoko) or [hello_world](rust/hello_world/) (Rust) — a simple full-stack canister with a frontend. For user authentication with Internet Identity, see [who_am_i](motoko/who_am_i/) or [who_am_i](rust/who_am_i/).
+**New here?** Start with `hello_world` ([Motoko](motoko/hello_world/) or [Rust](rust/hello_world/)) — a simple full-stack canister with a frontend. Then move on to `who_am_i` ([Motoko](motoko/who_am_i/) or [Rust](rust/who_am_i/)) to add user authentication with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity).
 
 Canister examples are organized by language:
 
@@ -21,6 +19,7 @@ Frontend-only and native app examples:
 
 - [hosting/](hosting/) — frontend examples (React, static sites, etc.)
 - [native-apps/](native-apps/) — Unity and other native app integrations
+- [wasm/](wasm/) — canisters written directly in WebAssembly
 
 ## Local development
 

hosting/README.md

@@ -1,7 +1,22 @@
 # Hosting examples
 
-## Basic
+Frontend-only examples that run entirely on the Internet Computer — static sites, web apps, and game builds served on-chain with no custom backend. Each example is self-contained: follow its README to deploy it locally with `icp-cli`.
 
-- [`static-website`](https://github.com/dfinity/examples/tree/master/hosting/static-website) -- simple HTML website demo.
-- [`Unity-WebGL-sample`](https://github.com/dfinity/examples/tree/master/hosting/unity-webgl-template) -- simple Unity WebGL sample.
-- [`Godot-HTML5-sample`](https://github.com/dfinity/examples/tree/master/hosting/godot-html5-template) -- Godot HTML5 sample.
+These examples use the `@dfinity/static-site` recipe, which deploys the [certified-assets canister](https://github.com/dfinity/certified-assets) — the successor of the legacy [asset canister](https://docs.internetcomputer.org/guides/frontends/asset-canister) going forward, adding response certification, clean-URL canonicalization, and `_headers`/`_redirects` configuration. The one deliberate exception is [`photo-storage`](photo-storage/): it demonstrates programmatic uploads via `AssetManager`, an API only the legacy asset canister provides.
+
+**New to ICP?** Start with [`static-website`](static-website/), the smallest possible deployment, then [`react`](react/) for a typical single-page app setup.
+
+Prerequisites and dev-container setup are covered in the [repository README](../README.md).
+
+## Examples
+
+- [`static-website`](static-website/) — deploy a plain HTML/CSS website on ICP.
+- [`react`](react/) — a minimal React single-page application hosted fully on-chain.
+- [`photo-storage`](photo-storage/) — store and manage photos programmatically with `AssetManager` from `@icp-sdk/canisters/assets` (runs on the legacy asset canister).
+- [`godot-html5-template`](godot-html5-template/) — deploy a Godot HTML5 game build.
+- [`unity-webgl-template`](unity-webgl-template/) — deploy a Unity WebGL game build.
+- [`oisy-signer-demo`](oisy-signer-demo/) — connect to the OISY wallet signer, fetch token balances, and perform ICRC transfers.
+
+## Security considerations and best practices
+
+If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices.

motoko/README.md

@@ -1,7 +1,63 @@
 # Motoko examples
 
-These examples demonstrate the use of Motoko as a backend language on the ICP platform.
+Canonical examples for building canisters on the Internet Computer with [Motoko](https://docs.internetcomputer.org/languages/motoko). Each example is self-contained: follow its README to deploy it locally with `icp-cli` and run its tests. Most examples have a Rust counterpart in [`../rust/`](../rust/) implementing the same Candid interface.
 
-## Security considerations and security best practices
+**New to ICP?** Start with [`hello_world`](hello_world/) — a full-stack canister with a frontend and the structural template for all examples. Then try [`who_am_i`](who_am_i/) for user authentication with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity).
 
-If you base your application on one of these examples, it is recommended that you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/building-apps/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices.
+Prerequisites and dev-container setup are covered in the [repository README](../README.md).
+
+## Getting started
+
+- [`hello_world`](hello_world/) — full-stack "Hello, world!" with a Motoko backend and a Vite frontend.
+- [`backend_only`](backend_only/) — the minimal canister: a single `greet` query function, no frontend.
+- [`who_am_i`](who_am_i/) — sign in with Internet Identity and see the principal your app receives.
+
+## Full-stack applications
+
+- [`daily_planner`](daily_planner/) — monthly calendar with notes and tasks; fetches historic facts via HTTPS outcalls.
+- [`superheroes`](superheroes/) — CRUD application with a React frontend.
+- [`filevault`](filevault/) — upload, download, and delete files stored per Internet Identity principal.
+- [`flying_ninja`](flying_ninja/) — 2D side-scroller game with an on-chain leaderboard.
+- [`ic-pos`](ic-pos/) — point-of-sale app accepting ICRC-1 token payments via QR codes.
+- [`llm_chatbot`](llm_chatbot/) — chat with a large language model from a canister.
+
+## Tokens and payments
+
+- [`icp_transfer`](icp_transfer/) — hold ICP in a canister and send it to other accounts via the ICP ledger.
+- [`icrc2-swap`](icrc2-swap/) — safe inter-canister call patterns for ICRC-2 token swaps.
+
+## Chain fusion and signing
+
+- [`basic_bitcoin`](basic_bitcoin/) — send and receive Bitcoin using threshold ECDSA and Schnorr signatures.
+- [`threshold-ecdsa`](threshold-ecdsa/) — a threshold ECDSA signing oracle.
+- [`threshold-schnorr`](threshold-schnorr/) — a threshold Schnorr (BIP340/BIP341, Ed25519) signing oracle.
+- [`evm_block_explorer`](evm_block_explorer/) — fetch block data from Ethereum and other EVM chains via the EVM RPC canister.
+
+## HTTPS outcalls
+
+- [`send_http_get`](send_http_get/) — make a `GET` request to an external API from a canister.
+- [`send_http_post`](send_http_post/) — make a `POST` request to an external API from a canister.
+
+## Inter-canister patterns
+
+- [`parallel_calls`](parallel_calls/) — parallel vs. sequential inter-canister calls.
+- [`pub-sub`](pub-sub/) — publisher/subscriber messaging using shared function references as callbacks.
+- [`composite_query`](composite_query/) — query functions that call other canisters' queries.
+- [`canister_factory`](canister_factory/) — create canisters dynamically via actor classes and the management canister.
+
+## System features
+
+- [`hello_cycles`](hello_cycles/) — the fundamental cycle management operations.
+- [`canister_logs`](canister_logs/) — canister logging with `Debug.print` and trap records.
+- [`low_wasm_memory`](low_wasm_memory/) — react to low Wasm memory with the `lowmemory` system hook.
+- [`query_stats`](query_stats/) — read a canister's own query statistics.
+- [`cert-var`](cert-var/) — certified variables: cryptographically verifiable query responses.
+- [`random_maze`](random_maze/) — cryptographic randomness from the network's random beacon.
+
+## Encryption with vetKeys
+
+The [`vetkeys/`](vetkeys/) directory contains examples for [vetKeys](https://docs.internetcomputer.org/concepts/vetkeys), from the low-level API to complete applications: [`basic_vetkd`](vetkeys/basic_vetkd/), [`basic_ibe`](vetkeys/basic_ibe/), [`basic_bls_signing`](vetkeys/basic_bls_signing/), [`password_manager`](vetkeys/password_manager/), [`password_manager_with_metadata`](vetkeys/password_manager_with_metadata/), and [`encrypted_notes_app_vetkd`](vetkeys/encrypted_notes_app_vetkd/).
+
+## Security considerations and best practices
+
+If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices.

motoko/ic-pos/README.md

@@ -1,6 +1,6 @@
 # IC-POS
 
-IC-POS is a simple Point of Sale (POS) app that accepts [ICRC-1](https://github.com/dfinity/ICRC-1) token payments on the Internet Computer. A merchant logs in with [Internet Identity](https://internetcomputer.org/internet-identity), configures a store, and charges customers by showing a QR code; incoming payments show up in the store with a live balance and transaction history.
+IC-POS is a simple Point of Sale (POS) app that accepts [ICRC-1](https://github.com/dfinity/ICRC-1) token payments on the Internet Computer. A merchant logs in with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity), configures a store, and charges customers by showing a QR code; incoming payments show up in the store with a live balance and transaction history.
 
 To let you try the full flow without spending real funds, this example uses the **TICRC1 test token** ([`3jkp5-oyaaa-aaaaj-azwqa-cai`](https://dashboard.internetcomputer.org/canister/3jkp5-oyaaa-aaaaj-azwqa-cai)) on mainnet, and a local ICRC-1 ledger + index when developing. Because the app talks to any ICRC-1 ledger, the same code works with real tokens (e.g. [ckBTC](https://internetcomputer.org/ckbtc/)) by pointing it at a different ledger.
 

motoko/vetkeys/README.md

@@ -0,0 +1,21 @@
+# vetKeys examples (Motoko)
+
+Examples for [vetKeys](https://docs.internetcomputer.org/concepts/vetkeys) — verifiably encrypted threshold key derivation, the Internet Computer's primitive for on-chain encryption. Each example is self-contained: follow its README to deploy it locally with `icp-cli`. Rust counterparts live in [`../../rust/vetkeys/`](../../rust/vetkeys/).
+
+**Start with** [`basic_vetkd`](basic_vetkd/) to understand the raw API, then move to the SDK-based examples.
+
+## Basics
+
+- [`basic_vetkd`](basic_vetkd/) — the raw VetKD management canister API: symmetric key derivation and IBE without any SDK abstraction.
+- [`basic_ibe`](basic_ibe/) — secure messaging with Identity-Based Encryption, using Internet Identity principals as encryption keys.
+- [`basic_bls_signing`](basic_bls_signing/) — a threshold BLS signing service where users can only sign for their own principal.
+
+## Applications
+
+- [`password_manager`](password_manager/) — a decentralized password manager built on Encrypted Maps, with shareable vaults.
+- [`password_manager_with_metadata`](password_manager_with_metadata/) — extends the password manager with unencrypted metadata alongside encrypted passwords.
+- [`encrypted_notes_app_vetkd`](encrypted_notes_app_vetkd/) — end-to-end encrypted note-taking with multi-device access and note sharing.
+
+## Security considerations and best practices
+
+If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices.

native-apps/README.md

@@ -0,0 +1,13 @@
+# Native app examples
+
+Examples for integrating native applications (mobile, desktop, game engines) with canisters on the Internet Computer. Each example is self-contained: follow its README to deploy the canister side with `icp-cli` and build the native app.
+
+Prerequisites and dev-container setup are covered in the [repository README](../README.md).
+
+## Examples
+
+- [`unity_ii_deeplink`](unity_ii_deeplink/) — authenticate a Unity mobile app through [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity) using a browser-based bridge canister and deep-link callbacks, then call a canister with the resulting delegation.
+
+## Security considerations and best practices
+
+If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices.

native-apps/unity_ii_deeplink/README.md

@@ -1,6 +1,6 @@
 # Unity + Internet Identity
 
-This example shows how a Unity mobile app can authenticate users through [Internet Identity](https://internetcomputer.org/internet-identity) and call an ICP canister using the resulting delegation identity.
+This example shows how a Unity mobile app can authenticate users through [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity) and call an ICP canister using the resulting delegation identity.
 
 The example consists of three parts:
 

rust/README.md

@@ -0,0 +1,80 @@
+# Rust examples
+
+Canonical examples for building canisters on the Internet Computer with [Rust](https://docs.internetcomputer.org/languages/rust). Each example is self-contained: follow its README to deploy it locally with `icp-cli` and run its tests. Most examples have a Motoko counterpart in [`../motoko/`](../motoko/) implementing the same Candid interface.
+
+**New to ICP?** Start with [`hello_world`](hello_world/) — a full-stack canister with a frontend and the structural template for all examples. Then try [`who_am_i`](who_am_i/) for user authentication with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity).
+
+Prerequisites and dev-container setup are covered in the [repository README](../README.md).
+
+## Getting started
+
+- [`hello_world`](hello_world/) — full-stack "Hello, world!" with a Rust backend and a Vite frontend.
+- [`backend_only`](backend_only/) — the minimal canister: a single `greet` query function, no frontend.
+- [`backend_wasm64`](backend_wasm64/) — the same minimal canister compiled for the Wasm64 target.
+- [`who_am_i`](who_am_i/) — sign in with Internet Identity and see the principal your app receives.
+
+## Full-stack applications
+
+- [`daily_planner`](daily_planner/) — monthly calendar with notes and tasks; fetches historic facts via HTTPS outcalls.
+- [`flying_ninja`](flying_ninja/) — 2D side-scroller game with an on-chain leaderboard.
+- [`photo_gallery`](photo_gallery/) — upload and view photos served via the HTTP gateway with cacheable responses.
+- [`llm_chatbot`](llm_chatbot/) — chat with a large language model from a canister.
+
+## Tokens and payments
+
+- [`icp_transfer`](icp_transfer/) — hold ICP in a canister and send it to other accounts via the ICP ledger.
+- [`receiving-icp`](receiving-icp/) — generate account identifiers and check balances to receive ICP.
+- [`exchange-rates`](exchange-rates/) — query crypto and fiat exchange rates from the Exchange Rate Canister (XRC).
+- [`stake_neuron_from_cli`](stake_neuron_from_cli/) — stake ICP into an NNS neuron from a Rust CLI binary using `ic-agent`.
+
+## Chain fusion and signing
+
+- [`basic_bitcoin`](basic_bitcoin/) — send and receive Bitcoin (P2PKH, P2WPKH, P2TR addresses).
+- [`basic_ethereum`](basic_ethereum/) — send and receive Ether using threshold ECDSA.
+- [`evm_block_explorer`](evm_block_explorer/) — fetch block data from Ethereum and other EVM chains via the EVM RPC canister.
+- [`threshold-ecdsa`](threshold-ecdsa/) — a threshold ECDSA signing oracle.
+- [`threshold-schnorr`](threshold-schnorr/) — a threshold Schnorr (BIP340/BIP341, Ed25519) signing oracle.
+- [`x509`](x509/) — issue and verify X.509 certificates with threshold signatures.
+
+## HTTPS outcalls
+
+- [`send_http_get`](send_http_get/) — make a `GET` request to an external API from a canister.
+- [`send_http_post`](send_http_post/) — make a `POST` request to an external API from a canister.
+
+## Inter-canister patterns
+
+- [`inter-canister-calls`](inter-canister-calls/) — bounded-wait and unbounded-wait calls, retries, and attaching cycles.
+- [`parallel_calls`](parallel_calls/) — parallel vs. sequential inter-canister calls.
+- [`composite_query`](composite_query/) — query functions that call other canisters' queries.
+- [`guards`](guards/) — how guard functions interact with asynchronous code.
+- [`candid_type_generation`](candid_type_generation/) — generate Rust types from an external canister's `.did` file.
+
+## Canister operations and system features
+
+- [`canister-info`](canister-info/) — retrieve metadata about any canister via the management canister.
+- [`canister-snapshots`](canister-snapshots/) — take and restore canister snapshots.
+- [`canister-snapshot-download`](canister-snapshot-download/) — download and upload canister snapshots.
+- [`canister_logs`](canister_logs/) — canister logging, traps, panics, and error handling.
+- [`low_wasm_memory`](low_wasm_memory/) — react to low Wasm memory with the `on_low_wasm_memory` hook.
+- [`periodic_tasks`](periodic_tasks/) — timers and heartbeats for scheduled execution.
+- [`performance_counters`](performance_counters/) — measure the work a canister performs.
+- [`query_stats`](query_stats/) — read a canister's own query statistics.
+
+## Compute and AI
+
+- [`image-classification`](image-classification/) — run an ONNX machine-learning model inside a canister.
+- [`face-recognition`](face-recognition/) — face detection and recognition with the Tract ONNX engine.
+- [`qrcode`](qrcode/) — long-running image processing in a single message execution.
+- [`simd`](simd/) — WebAssembly SIMD acceleration for compute-heavy workloads.
+
+## Testing
+
+- [`unit_testable_rust_canister`](unit_testable_rust_canister/) — structure a canister for comprehensive unit testing.
+
+## Encryption with vetKeys
+
+The [`vetkeys/`](vetkeys/) directory contains examples for [vetKeys](https://docs.internetcomputer.org/concepts/vetkeys), from the low-level API to complete applications: [`basic_vetkd`](vetkeys/basic_vetkd/), [`basic_ibe`](vetkeys/basic_ibe/), [`basic_timelock_ibe`](vetkeys/basic_timelock_ibe/), [`basic_bls_signing`](vetkeys/basic_bls_signing/), [`password_manager`](vetkeys/password_manager/), [`password_manager_with_metadata`](vetkeys/password_manager_with_metadata/), and [`encrypted_notes_app_vetkd`](vetkeys/encrypted_notes_app_vetkd/).
+
+## Security considerations and best practices
+
+If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices.