Update wkg docs to be more comprehensive

Signed-off-by: Kate Goldenring <[email protected]>

Author: kate-goldenring

component-model/src/creating-and-consuming/distributing.md

@@ -6,86 +6,110 @@ Publishing and distribution are not defined by the core component model, but for
 
 You can get involved with improving the packaging and hosting of Wasm components by joining the [Bytecode Alliance Packaging Special Interest Group (SIG)](https://github.com/bytecodealliance/governance/blob/main/SIGs/sig-packaging/proposal.md).
 
-## Registry Tooling
+## The `wkg` Registry Tool
 
-The [`wasm-pkg-tools` project](https://github.com/bytecodealliance/wasm-pkg-tools) enables fetching and publishing Wasm Components to OCI or Warg registries. It contains a `wkg` CLI tool that eases distributing and fetching components and WIT packages. The following examples walk through using `wkg`.
+The [`wasm-pkg-tools` project](https://github.com/bytecodealliance/wasm-pkg-tools) enables fetching and publishing Wasm components to OCI registries. It contains a `wkg` CLI tool that eases distributing and fetching components and WIT packages. `wkg` contains several subcommand:
 
-## Distributing Components Using `wkg`
+- `wkg oci` - is a CLI wrapper around the [oci-wasm](https://github.com/bytecodealliance/rust-oci-wasm) crate which enables pushing/pulling Wasm artifacts to/from any OCI registry
+- `wkg publish` - pushes *library* components or WIT packages
+- `wkg get` - pulls *library* components or WIT packages
+- `wkg wit` - commands for interacting with WIT files and dependencies
+- `wkg config` - interact with the `wkg` configuration
 
-A component is pushed to an OCI registry using `wkg oci push`. The example below pushes to a GHCR:
+The following sections detail a subset of actions that can be performed with `wkg`.
 
-```sh
-wkg oci push ghcr.io/user/hello:0.1.0 hello.wasm
-```
+## `wkg` Configuration Files
 
-## Fetching Components Using `wkg`
+The `wkg` tool uses a configuration file to understand where to publish and fetch specific packages to and from. It provides the ability to configure:
 
-A component is pulled from a OCI registry using `wkg oci pull`. The example below pulls a component from GHCR:
-
-```sh
-wkg oci pull ghcr.io/user/hello:0.1.0 -o hello.wasm
-```
+- a default registry for all packages at the top level of the file
+- a default registry for all packages of a specific namespace under `[namespace_registries]`. This section can be used to configure the registry of all `wasi` namespaced packages, such as `wasi:clocks` and `wasi:http`.
+- an override for package of a specific namespace under `[package_registry_overrides]`. This section can be used to fetch/publish a specific package of a namespace from/to a different location than all other packages of that namespace. For example, maybe you want to fetch `wasi:http` from a different registry.
+- credentials for a registry under `[registry."<registry-name>".oci]`
+- and more! See the [`wkg` docs for more configuration options](https://github.com/bytecodealliance/wasm-pkg-tools?tab=readme-ov-file#configuration).
 
-## Configuring `wkg` to Fetch WASI Packages
+For example, to fetch WASI packages, such as `wasi:clocks` and `wasi:http`, a line can be added under the `namespace_registries` section for the `wasi` namespace. Specifically, the example below configures `wkg` to fetch WASI packages from the [WebAssembly OCI GitHub Container Registry](https://github.com/orgs/WebAssembly/packages), where the latest interfaces are published upon WASI releases. To edit your `wkg` config file, simply run `wkg config --edit`.
 
-The `wkg` tool uses a configuration file to store settings with a default location of `$XDG_CONFIG_HOME/wasm-pkg/config.toml`. It must be configured to know which registry to use for which package namespaces. The following is a convenient configuration to ensure you can fetch WASI packages from the [WebAssembly OCI registry](https://github.com/WebAssembly/WASI/pkgs/container/wasi), where the latest interfaces are published upon WASI releases.
+> Remember, all package names consist of the a namespace field followed by the package field. The package name `wasi:clocks` has a namespace of `wasi` and package field of `clocks`. In this way, the following configuration ensures that `wkg` will know to route fetches and publishes of any `wasi:x` to the configured location.
 
 ```toml
 # $XDG_CONFIG_HOME/wasm-pkg/config.toml
 default_registry = "ghcr.io"
 
 [namespace_registries]
+# Instruct wkg to use the OCI protocol to fetch packages with the `wasi` namespace from ghcr.io/webassembly
 wasi = { registry = "wasi",  metadata = { preferredProtocol = "oci", "oci" = {registry = "ghcr.io", namespacePrefix = "webassembly/" } } }
-
-[package_registry_overrides]
-
-[registry]
 ```
 
-## Distributing WIT Packages using  `wkg`
-
-The `wkg` tool uses a [configuration file](https://github.com/bytecodealliance/wasm-pkg-tools?tab=readme-ov-file#configuration) to store settings with a default location of `$XDG_CONFIG_HOME/wasm-pkg/config.toml`. It must be configured to know which registry to use for which package namespaces. The following configuration, instructs `wkg` to use [ttl.sh](https://ttl.sh/) OCI registry for all packages with the `foo` namespace.
+As a more generic example, The following configuration, instructs `wkg` to use [ttl.sh](https://ttl.sh/) OCI registry for all packages with the `docs` namespace.
 
 ```toml
 # $XDG_CONFIG_HOME/wasm-pkg/config.toml
 default_registry = "ghcr.io"
 
 [namespace_registries]
-foo = { registry = "foo-registry",  metadata = { preferredProtocol = "oci", "oci" = {registry = "ttl.sh", namespacePrefix = "wasm-components/" } } }
+# Instruct wkg to use the OCI protocol to fetch packages with the `foo` namespace from ttl.sh/wasm-components
+docs = { registry = "docs-registry",  metadata = { preferredProtocol = "oci", "oci" = {registry = "ttl.sh", namespacePrefix = "wasm-components/" } } }
+```
 
-[package_registry_overrides]
+## Distributing WIT and Library Components using  `wkg publish`
 
-[registry]
-```
+Once you've [configured `wkg`](#wkg-configuration-files) to know where to publish packages to, you can use the `wkg publish` command to publish library *components* or *interfaces* to be consumed by others.
 
-Now, `foo` packages can be built and published using `wkg`.
+Imagine you have defined the following `adder` world in WIT:
 
-```sh
-mkdir wit
-cat > wit/foo.wit << EOL
-package foo:[email protected];
+```wit
+package docs:[email protected];
 
-interface do-something {
-    reduce: func(a: u32, b: u32) -> u32;
+interface add {
+    add: func(a: u32, b: u32) -> u32;
 }
 
-world example {
-    export do-something;
+world adder {
+    export add;
 }
-EOL
+```
+
+You can publish this *WIT* using `wkg` by wrapping it up as a Wasm component. Yes, you heard that right! We are packaging WIT as Wasm.
+
+```sh
 
 wkg wit build
-wkg publish foo:bar@0.1.0.wasm
+wkg publish docs:adder@0.1.0.wasm
 ```
 
-This will publish the component to `ttl.sh/wasm-components/foo/bar:0.1.0`
+If you had configured `wkg` as described in the [`wkg` configuration section](#wkg-configuration-files), this would publish the component to `ttl.sh/wasm-components/docs/adder:0.1.0`. This WIT can then be fetched using `wkg get`, specifying the format `wit`:
 
-## Configuring `wkg` to Fetch Custom Packages
+```sh
+wkg get --format wit docs:[email protected]
+```
+
+Instead of publishing the WIT interface, you could publish the built component by running:
+
+```sh
+wkg publish adder.wasm --package docs:[email protected]
+```
+
+This component can then be fetched by running:
+
+```sh
+wkg get docs:[email protected]
+```
+
+## More Generic Operations with `wkg oci`
+
+The `wkg oci` subcommand is a CLI wrapper around the [oci-wasm](https://github.com/bytecodealliance/rust-oci-wasm) crate which enables pushing/pulling Wasm artifacts to/from any OCI registry. Unlike `wkg publish` and `wkg get` it is not limited to library components, as providing the WIT package is not required.
+
+A component is pushed to an OCI registry using `wkg oci pull`. The example below pulls a component from a GitHub Container Registry.
+
+```sh
+wkg oci push ghcr.io/user/component:0.1.0 component.wasm
+```
 
-After configuring `wkg` to know where to pull `foo` namespaced packages from, the `bar` package can be pulled with `wkg get`:
+To pull a component, run:
 
 ```sh
-wkg get --format wit foo:bar@0.1.0
+wkg oci pull ghcr.io/user/component:0.1.0 -o component.wasm
 ```
 
 ## Fetching WIT Package Dependencies using `wkg`
@@ -100,7 +124,7 @@ world target-world {
 }
 ```
 
-One may be tempted to simply get the `wasi:http` package with `wkg get  --format wit wasi:[email protected] -o wit/deps/http/`. However, `wasi:http` depends on other WASI packages such as `wasi:clocks` and `wasi:io`. To make sure to fetch a package and all its dependencies, use `wkg fetch`, which will read the package containing the world(s) you have defined in the given wit directory (`wit` by default). It will then fetch the
+You may be tempted to simply get the `wasi:http` package with `wkg get  --format wit wasi:[email protected] -o wit/deps/http/`. However, `wasi:http` depends on other WASI packages such as `wasi:clocks` and `wasi:io`. To make sure to fetch a package and all its dependencies, use `wkg wit fetch`, which will read the package containing the world(s) you have defined in the given wit directory (`wit` by default). It will then fetch the
 dependencies and write them to the `deps` directory along with a lock file.
 
 After placing the above file in `./wit`, run the following to fetch the dependencies: