feat: update Registry guide

docs/site/docs/registry.md

@@ -1,31 +1,99 @@
 # Registry Guide
 
-The Stellar Registry is a system for publishing, deploying, and managing smart contracts on the Stellar network. This guide explains how to use the registry CLI tools to manage your contracts.
+The Stellar Registry is a system for publishing, deploying, and managing smart contracts—and their underlying Wasms—on the Stellar network. This guide explains how to use the Registry CLI and UI to manage your contracts.
+
+<div class="videoWrapper">
+  <iframe src="https://www.youtube-nocookie.com/embed/xAlWmJOdMSQ?si=n2yYDkKbyqTAhiNP" title="Stellar Registry Full Walk-Through" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</div>
 
 ## Overview
 
-The registry system consists of two main components:
+At its core, Stellar Registry is a smart contract.
+
+### Core Concepts
+
+The Registry smart contract keeps track of two kinds of information:
+
+1. **Wasms**: Stellar smart contracts are compiled to [WebAssembly](https://webassembly.org/), aka Wasm. The `.wasm` file you get at the end of a [`stellar scaffold build` command](./cli#build-command) needs to be uploaded to the Stellar blockchain. Without Registry, this is done with Stellar CLI using `stellar contract upload`.
+
+   This gets your Wasm file/blob/binary/module on-chain, _identified only by its content hash._ This looks like a string of 65 hexadecimal characters like `d1d4e69…`.
+
+   Stellar Registry allows you, the contract author, to also give that Wasm module a _name_ and a _version._ Key insight: Stellar is _already a module-distribution system_, like NPM or Crates.io. Registry makes it usable.
+
+2. **Contracts:** Once a Wasm is on-chain, many contracts can use it. You can deploy a Contract for a Wasm you didn't write; someone else could deploy multiple Contracts all using your Wasm. If you're familiar with Object Oriented Programming, think of the Contract as the _instance_ and the Wasm as the _class._ A Wasm defines behavior; a Contract holds data (including a reference to the Wasm).
+
+   :::note Contracts don't have versions
+
+   You always interact with a Contract's live, latest version.
+
+   :::
+
+So that's it, at its core: Stellar Registry is a smart contract, which gives other smart contracts names, and which gives Wasms both names and versions.
+
+### Quick Links
 
-1. **On-chain registry contracts** - A root "verified" registry and an "unverified" registry
-2. The `stellar-registry` CLI tool for interacting with the registries
+Around the core smart contract, Stellar Registry wraps other tooling:
 
-### Registry Types
+- [Stellar Registry UI](https://rgstry.xyz), `rgstry.xyz`, where you can browse and search all Wasms and Contracts currently registered. [Source](https://github.com/stellar-registry/ui)
+- [Stellar Registry CLI](https://crates.io/crates/stellar-registry-cli), the main interface used to _write_ to Stellar Registry today. This is the tool you use to _publish Wasms_ and _deploy Contracts_ to Stellar Registry, or to register already-uploaded Wasms and already-deployed Contracts. [Source](https://github.com/stellar-registry/cli)
+- [Stellar Registry Rust Macros](https://crates.io/crates/stellar-registry), to simplify your cross-contract calls when authoring contracts. [Source](https://github.com/stellar-registry/cli/tree/main/crates/stellar-registry-macro)
+- [Stellar Registry GitHub Actions](https://github.com/stellar-registry/actions), for creating [SEP-55 attested builds](https://github.com/stellar-expert/soroban-build-workflow) of your project Wasm files, uploading them to the blockchain, incrementing your Registry series' version, and auto-publishing your Wasm to Registry. [Coming soon](https://github.com/stellar-registry/oz-combined-wasms/issues/1)
+- **Stellar Registry Governance**: to get your Contracts & Wasms into the root registry (no `unverified/` prefix; more on this below) or to get your own subregistry (your own prefix, like `oz/` or `circle/`, to which you can publish Wasms & deploy Contracts freely), you need to put in a request with the Stellar Registry security council. The Stellar Registry UI contains forms for doing this ([coming soon](https://github.com/stellar-registry/ui/issues/51)), but if you want to do so in the underlying system itself:
+  - on Testnet, [use Tansu](https://testnet.tansu.dev/governance/?name=stellarregistry)
+  - on Mainnet, use [github.com/stellar-registry/gov](https://github.com/stellar-registry/gov/issues) (Tansu coming soon)
+- Stellar Registry API [testnet](https://stellar-registry-testnet.fly.dev/) and [mainnet](https://stellar-registry-mainnet.fly.dev/), the backends for Stellar Registry UI. Use at your own risk: domains may change and rate-limiting schemes may harden. [Source](https://github.com/stellar-registry/indexer)
 
-There are two types of registries:
+Next, let's learn more about that `unverified/` prefix.
+
+### Subregistries
+
+Did we say Registry was _one_ contract? This isn't quite true. The _root_ Registry is one contract, but some of the contracts that it tracks are themselves Registries, running the same [Registry Wasm](https://stellar.rgstry.xyz/wasms/registry). These are _subregistries_.
+
+Most, like the root Registry, are locked down, _managed_ Registries. You cannot publish Wasms or deploy Contracts to the `oz` or `circle` subregistries, for obvious security reasons.
+
+The `unverified` subregistry, though, is _unmanaged._ Anyone can publish and deploy to it. As its name indicates, you _should not trust Wasms and Contracts in this subregistry._ If you see the `unverified` prefix on a Wasm/Contract name, _be careful!_
+
+Some popular subregistries, to help you get a sense of how this all works:
+
+- [`oz/`](https://stellar.rgstry.xyz/wasms?query=oz), the Open Zeppelin Wasms (managed [by the Stellar Registry team](https://stellar.rgstry.xyz/wasms?query=oz))
+- [`circle/`](https://stellar.rgstry.xyz/contracts?query=circle), containing the official [`usdc`](https://stellar.rgstry.xyz/contracts/circle/usdc) and [`eurc`](https://stellar.rgstry.xyz/contracts/circle/eurc) tokens
+- `unverified/`: check out [Testnet Wasms](https://testnet.rgstry.xyz/wasms?query=unverified) and [Testnet Contracts](https://testnet.rgstry.xyz/contracts?query=unverified) as well as [Mainnet Wasms](https://stellar.rgstry.xyz/wasms?query=unverified) and [Mainnet Contracts](https://stellar.rgstry.xyz/contracts?query=unverified) to get a sense of how noisy this subregistry can be!
+
+When you first publish or deploy to Stellar Registry, you will need to use the `unverified` subregistry.
+
+This:
+
+```bash
+# ✅ WORKS
+stellar registry publish --wasm-name unverified/my-wasm
+```
 
-- **Verified (Root) Registry** - A managed registry where a manager account must approve initial publishes and contract name registrations. This ensures that established contracts in the verified registry have been vetted. If interested in having your contract added to the registry please open an issue and we can begin to verify your contract and project.
-- **Unverified Registry** - An unmanaged registry where anyone can publish wasms or register contract names without approval.
+Not this:
+
+```bash
+# ❌ DOES NOT WORK
+stellar registry publish --wasm-name my-wasm
+```
+
+:::tip
+
+For full working example of the `publish` command, [see below](#using-the-unverified-registry).
+
+:::
+
+Then, once you're ready, you can use the [governance process linked above](#quick-links) to get into the root Registry, into a different subregistry, or to get your own subregistry.
 
 ### Name Resolution
 
 Names in the registry support namespace prefixes. The CLI resolves names using the root registry as the source of truth:
 
 - `my-contract` - Looks up in the verified (root) registry
 - `unverified/my-contract` - First fetches the `unverified` registry contract ID from the root registry, then looks up `my-contract` in that registry
+- `some-other-subregistry/my-contract` — Same as above. Looks up `some-other-subregistry` in the root registry, then looks up `my-contract` in that registry.
 
 ### Name Normalization
 
-All names are normalized before storage:
+All names are normalized by the [stellar-registry-name](https://crates.io/crates/stellar-registry-name) crate before storage:
 
 - Underscores (`_`) are converted to hyphens (`-`)
 - Uppercase letters are converted to lowercase
@@ -36,16 +104,25 @@ All names are normalized before storage:
 
 ## Prerequisites
 
-- Install the registry CLI:
+Install the registry CLI:
+
+```bash
+cargo install --locked stellar-registry-cli
+```
+
+As this currently embeds Stellar CLI as a dependency, it takes some time. To make it faster, you can use [cargo-binstall](https://github.com/cargo-bins/cargo-binstall):
 
 ```bash
-cargo install --git https://github.com/stellar-registry/cli stellar-registry-cli
+cargo install cargo-binstall
+cargo binstall stellar-registry-cli
 ```
 
 ## Commands
 
 ### Publish Contract
 
+Stellar Registry prefers the verb _publish_, rather than the more generic "upload." You're not merely uploading a Wasm blob to the blockchain; you're publishing a module. Like other module-distribution systems, you then keep control of this name, and the rights to publish new versions in the series.
+
 Publish a compiled contract to the Stellar Registry:
 
 ```bash
@@ -65,7 +142,7 @@ Options:
 - `--binver`: Binary version (optional, extracted from contract metadata if not provided)
 - `--dry-run`: Simulate the publish operation without actually executing it (optional)
 
-**Note:** For the verified registry, the manager must approve initial publishes. For the unverified registry, use the `unverified/` prefix.
+**Note:** For the root registry, the governance process ([see above](#quick-links)) must approve initial publishes. For the unverified registry, use the `unverified/` prefix.
 
 ### Deploy Contract
 
@@ -87,15 +164,13 @@ Options:
 - `--wasm-name`: The name of the previously published contract to deploy, supports prefix notation (required)
 - `--version`: Specific version of the published contract to deploy (optional, defaults to most recent version)
 - `--deployer`: Optional deployer address for deterministic contract ID resolution (advanced feature)
-- `CONSTRUCTOR_ARGS`: Optional arguments for the constructor function
-
-Note: Use `--` to separate CLI options from constructor arguments.
+- `-- [CONSTRUCTOR_ARGS]`: `--` is a standard CLI separator between "arguments for the main process" and "arguments for the sub-process". `stellar registry deploy` creates an "implicit CLI" for the deployed contract, passing `CONSTRUCTOR_ARGS` to it. If the Wasm being deployed does not have a `__constructor`, you do not need this.
 
-**Note:** For the verified registry, the manager must approve deploying with a registered name. For the unverified registry, use the `unverified/` prefix.
+**Note:** For the root registry, the governance process ([see above](#quick-links)) must approve initial publishes. For the unverified registry, use the `unverified/` prefix.
 
 ### Deploy Unnamed Contract
 
-Deploy a published contract without registering a name in the registry. This is useful when you want to deploy a contract but don't need name resolution:
+Deploy a published contract without registering a name in the registry. This is useful when you want to deploy a contract but don't need name resolution. You can do this with the "Deploy a contract using this Wasm" button on any Wasm page in https://stellar.rgstry.xyz/wasms, or to use the CLI:
 
 ```bash
 stellar registry deploy-unnamed \
@@ -138,19 +213,7 @@ Options:
 
 This allows you to add existing contracts to the registry for name resolution without redeploying them.
 
-**Note:** For the verified registry, the manager must approve name registrations. Use the `unverified/` prefix for the unverified registry.
-
-### Install Contract
-
-Install a deployed contract as an alias to be used by `stellar-cli`:
-
-```bash
-stellar registry create-alias <CONTRACT_NAME>
-```
-
-Options:
-
-- `CONTRACT_NAME`: Name of the deployed contract to install, supports prefix notation like `unverified/my-contract` (required)
+**Note:** For the root registry, the governance process ([see above](#quick-links)) must approve initial publishes. For the unverified registry, use the `unverified/` prefix.
 
 ### Publish Hash
 
@@ -173,6 +236,8 @@ Options:
 - `--author (-a)`: Author address (optional, defaults to source account)
 - `--dry-run`: Simulate the operation without executing (optional)
 
+**Note:** For the root registry, the governance process ([see above](#quick-links)) must approve initial publishes. For the unverified registry, use the `unverified/` prefix.
+
 ### Fetch Contract ID
 
 Look up the contract ID of a deployed contract by its registered name:
@@ -185,6 +250,48 @@ Options:
 
 - `CONTRACT_NAME`: Name of the deployed contract, supports prefix notation like `unverified/my-contract` (required)
 
+### Create Contract Alias
+
+A common pattern is `fetch-contract-id` (see above) and then using `stellar contract alias` to create a local alias to the named contract. `create-alias` does that in one command:
+
+```bash
+stellar registry create-alias <CONTRACT_NAME> [LOCAL_NAME]
+```
+
+Example:
+
+```bash
+stellar registry create-alias circle/usdc
+```
+
+This creates contract alias `usdc` (without the `circle` prefix), which you can then use to transfer assets:
+
+```bash
+stellar contract invoke --id usdc -- transfer \
+    --from account-1 \ # as created with `stellar keys`
+    --to account-2 \
+    --amount 10000000 # 1 USDC; always check an asset's `decimals` before sending
+```
+
+:::caution Careful with SACs!
+
+The `usdc` transfer example above uses `contract invoke`, which uses the Soroban wrapper/interface for the USDC token. This Soroban wrapper/interface is called a Stellar Asset Contract (SAC). Not all legacy systems notice transfers made via SAC. Always test transfers with small amounts and verify your target system works as expected. If you need to use a Stellar Classic transaction, the equivalent to the above would be:
+
+```bash
+stellar tx new payment --asset USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN \
+    --source account-1 \
+    --destination account-2 \
+    --amount 10000000
+```
+
+:::
+
+Options:
+
+- `CONTRACT_NAME`: Name of the deployed contract, supports prefix notation like `unverified/my-contract` (required).
+- `LOCAL_NAME`: Optional custom local name for the alias. If not provided, uses the name from the registry.
+- `--force` / `-f`: Force overwrite if an alias with the same name already exists, and allow aliasing a contract flagged as compromised in the registry.
+
 ### Fetch Hash
 
 Fetch the Wasm hash of a published contract:
@@ -230,7 +337,7 @@ The registry CLI respects the following environment variables:
 - `STELLAR_NETWORK_PASSPHRASE`: Network passphrase (default: Test SDF Network ; September 2015)
 - `STELLAR_ACCOUNT`: Source account to use
 
-These variables can also be in a `.env` file in the current working directory.
+These variables can also be in a `.env` file in the current working directory if your shell is configured to respect `.env`.
 
 You can also configure `stellar-cli` defaults:
 
@@ -241,11 +348,11 @@ stellar network use testnet
 
 ## Example Workflow
 
-### Publishing to the Unverified Registry
+### Using the Unverified Registry
 
 For most users, the unverified registry allows publishing without manager approval:
 
-1. Publish a contract to the unverified registry:
+#### 1. Publish a contract to the unverified registry:
 
 ```bash
 stellar registry publish \
@@ -254,34 +361,41 @@ stellar registry publish \
   --binver "1.0.0"
 ```
 
-2. Deploy the published contract with constructor arguments:
+#### 2. Register an already-uploaded Wasm with the unverified registry:
 
 ```bash
-stellar registry deploy \
-  --contract-name unverified/my-token-instance \
+stellar registry publish-hash \
+  --wasm-hash d1d4e69… \
   --wasm-name unverified/my-token \
-  --version "1.0.0" \
-  -- \
-  --name "My Token" \
-  --symbol "MTK" \
-  --decimals 7
+  --version "1.0.0"
 ```
 
-3. Install the deployed contract locally:
+#### 3. Deploy a contract with constructor arguments from an on-Registry Wasm:
 
 ```bash
-stellar registry create-alias unverified/my-token-instance
+stellar registry deploy \
+  --contract-name unverified/my-token \
+  --wasm-name oz/ft-standard \
+  --version "1.0.0" \
+  -- \
+  --name "My Token" \
+  --symbol "MTK" \
+  --decimals 7 \
+  --owner G123… \
+  --initial_supply 100
 ```
 
-4. Use the installed contract with `stellar-cli`:
+#### 4. Register an already-deployed Contract with the unverified registry:
 
 ```bash
-stellar contract invoke --id my-token-instance -- --help
+stellar registry register-contract \
+  --contract-name <NAME> \
+  --contract-address <CONTRACT_ADDRESS> \
 ```
 
-### Publishing to the Verified Registry
+### Using a Verified Registry
 
-The verified registry requires manager approval for initial publishes. Contact the registry manager to get your contract approved for publication.
+A verified registry, such as the root registry, requires manager approval for initial publishes & deploys. Use the governance process [described above](#quick-links) to get your contract approved for publication.
 
 ## Best Practices
 
@@ -290,22 +404,7 @@ The verified registry requires manager approval for initial publishes. Contact t
 3. Always test deployments on testnet before mainnet
 4. Use the `--dry-run` flag to simulate operations before executing them
 5. Document initialization parameters used for each deployment
-6. Use environment variables or `.env` files for different network configurations
-
-## Registry Contract Addresses
-
-The **verified (root) registry** contract is deployed at different addresses for each network:
-
-- **Testnet**: `CBFFTTX7QKA76FS4LHHQG54BC7JF5RMEX4RTNNJ5KEL76LYHVO3E3OEE`
-- **Mainnet**: `CCRKU6NT4CRG4TVKLCCJFU7EOSAUBHWGBJF2JWZJSKTJTXCXXTKOJIUS`
-- **Futurenet**: `CBUP2U7IY4GBZWILAGFGBOGEJEVSWZ6FAIKAX2L7PYOEE7R556LNXRJM`
-- **Local**: `CDUK4O7FPAPZWAMS6PBKM7E4IO5MCBJ2ZPZ6K2GOHK33YW7Q4H7YZ35Z`
-
-The **unverified registry** is deployed by the root registry and can be looked up using:
-
-```bash
-stellar contract invoke --id <ROOT_REGISTRY_ID> -- fetch_contract_id --contract-name unverified
-```
+6. Use explicit `--source` and `--network` settings in every command, rather than relying on `stellar network use` and `stellar keys use` settings
 
 ## Troubleshooting
 
@@ -319,7 +418,7 @@ stellar contract invoke --id <ROOT_REGISTRY_ID> -- fetch_contract_id --contract-
 
 4. **Network configuration**: Verify your network settings match the intended deployment target (testnet vs mainnet).
 
-5. **Manager approval required**: For the verified registry, initial publishes and contract name registrations require manager approval. Use the `unverified/` prefix to publish without approval.
+5. **Manager approval required**: For the verified registry, initial publishes and contract name registrations require manager approval (see "governance" section [above](#quick-links)). Use the `unverified/` prefix to publish without approval.
 
 6. **Invalid name**: Names must start with an alphabetic character and contain only alphanumeric characters, hyphens, or underscores. Rust keywords cannot be used as names.
 

docs/site/src/css/custom.css

@@ -248,3 +248,17 @@ table thead tr {
   width: 1px;
   white-space: nowrap;
 }
+
+/* ── Responsive (fluid width) video ─────────────────── */
+.videoWrapper {
+  position: relative;
+  padding-bottom: 56.25%; /* 16:9 */
+  height: 0;
+}
+.videoWrapper iframe {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}