chore(examples): update README (#3116)

<!-- please provide a detailed description of the changes made in this
pull request. -->

Updates the examples README.

<details><summary>Contributors' checklist...</summary>

- [x] Added new tests, or not needed, or not feasible
- [x] Provided an example (e.g. screenshot) to aid review or the PR is
self-explanatory
- [x] Updated the official documentation or not needed
- [x] No breaking changes were made, or a `BREAKING CHANGE: xxx` message
was included in the description
- [x] Added references to related issues and PRs
- [x] Provided any useful hints for running manual tests
</details>

---------

Co-authored-by: Danny <[email protected]>

examples/README.md

@@ -1,21 +1,37 @@
-# Gnolang examples
+# Examples
 
-This folder showcases Gnolang realms and library demos. These examples not only aid in engine testing but also provide a glimpse into the potential of Gnolang's capabilities.
+This folder showcases example Gno realms (smart contracts) and pure packages (libraries).
+These examples provide a glimpse into the potential of gno.land and the capabilities of Gno,
+while also serving as a test suite for the GnoVM.
 
-While sharing contracts here can enhance engine testing, it's not mandatory. If considering a separate repository for contracts, be aware that this might restrict the experience due to the continuous efforts around `gno mod` support. A key point to note is that the main repository cannot reference separate code, which might pose developmental challenges.
+Pure packages and realms in this folder are pre-deployed to gno.land testnets,
+making them readily available for on-chain use. However, **there is no guarantee
+that the code is bug-free, so it should be used with caution and an understanding of potential risks.**
 
-## Personal Realms & Shared Content
-
-**Prioritizing Shared Content:** As we expand our examples and use-cases, it's essential to prioritize shared content that benefits the broader community. These examples serve as a foundation and reference for all users.
-
-**Personal Realms Inclusion:** We're open to personal realms, but they must exemplify best practices and inspire others. To maintain our repository's organization, we may decline some realms. If so, consider uploading onchain and keeping source code separately. For higher acceptance odds, offer useful or original examples.
+## Structure
 
-**Recommended Approach:** 
-- Use `r/demo` and `p/demo` for generic examples and components that can be imported by others. These are meant to be easily referenced and utilized by the community.
-- Personal realms are welcomed if they are easily maintainable with the Continuous Integration (CI) system. If a personal realm becomes cumbersome to maintain or doesn't align with the CI's checks, it might be relocated to a less prominent location or even removed. 
+This folder mimics the gno.land package path system; the "root" of the system is
+the `gno.land` folder. Next, it branches out to `p/` and `r/`, which contain
+pure packages and realms, respectively.
 
-## Usage
-
-Our recommendation is to use the [gno](../gnovm/cmd/gno) utility to develop contracts locally before publishing them on-chain. This approach offers a faster and streamlined workflow, along with additional debugging features. Simply fork or create new contracts and refer to the Makefile. Once everything looks good locally, you can then publish it on a localnet or testnet.
+## Personal Realms & Shared Content
 
-For further guidance and insights, please refer to the [`awesome-gno` tutorials](https://github.com/gnolang/awesome-gno#tutorials).
+**Prioritizing Shared Content:** As we expand our examples and use-cases, it's
+essential to prioritize shared content that benefits the broader community.
+These examples serve as a foundation and reference for all users.
+
+**Personal Realms & Pure Packages:** We welcome personal realms that
+exemplify best practices and inspire others. To maintain the organization
+of the monorepo, some submissions may be declined. If so, consider uploading
+[permissionlessly](../docs/gno-tooling/cli/gnokey/state-changing-calls.md#addpackage)
+and storing the source code in a separate repo. For higher
+acceptance odds, offer useful and original examples.
+
+**Recommended Approach:**
+- Use `r/demo` and `p/demo` for generic examples and components that can be
+  imported by others. These are meant to be easily referenced and utilized by the
+  community.
+- Packages under personal namespaces, such as in [r/leon](./gno.land/r/leon),
+  are welcome if they are easily maintainable with the Continuous Integration (CI)
+  system. If a personal realm becomes cumbersome to maintain or doesn't align with
+  the CI's checks, it might be relocated to a less prominent location or even removed.