Update templates-distribution.md (#152)

Author: bamurtaugh

_implementors/templates-distribution.md

@@ -64,16 +64,13 @@ Tooling that handles publishing Templates will not republish Templates if that e
 
 ## <a href="#packaging" name="packaging" class="anchor"> Packaging </a>
 
-
 Templates are distributed as tarballs. The tarball contains the entire contents of the Template sub-directory, including the `devcontainer-template.json`, `.devcontainer.json` (or `.devcontainer/devcontainer.json`), and any other files in the directory.
 
 The tarball is named `devcontainer-template-<id>.tgz`, where `<id>` is the Templates's `id` field.
 
 A reference implementation for packaging and distributing Templates is provided as a GitHub Action (https://github.com/devcontainers/action).
 
-
-<div id="devcontainer-collection.json"></div>
-### devcontainer-collection.json
+### <a href="#devcontainer-collection" name="devcontainer-collection" class="anchor"> devcontainer-collection.json </a>
 
 The `devcontainer-collection.json` is an auto-generated metadata file.
 
@@ -133,4 +130,65 @@ NAMESPACE=devcontainers/templates
 oras push ${REGISTRY}/${NAMESPACE}:latest \
         --manifest-config /dev/null:application/vnd.devcontainers \
                             ./devcontainer-collection.json:application/vnd.devcontainers.collection.layer.v1+json
-```
+```
+
+## <a href="#guide-to-publishing-templates" name="guide-to-publishing-templates" class="anchor">Guide to publishing Templates</a>
+
+The dev container CLI can be used to publish [Dev Container Template](https://containers.dev/implementors/templates/) artifacts to an OCI registry (that supports the [artifacts specification](https://oras.land/implementors/)).
+
+To see all the available options, run `devcontainers templates publish --help`.
+
+## <a href="#example" name="example" class="anchor">Example</a>
+
+Given a directory that is organized according to the [Templates distribution specification](https://containers.dev/implementors/templates-distribution/) - for example:
+
+```
+├── src
+│   ├── color
+│   │   ├── devcontainer-template.json
+│   │   └──| .devcontainer
+│   │      └── devcontainer.json
+│   ├── hello
+│   │   ├── devcontainer-template.json
+│   │   └──| .devcontainer
+│   │      ├── devcontainer.json
+│   │      └── Dockerfile
+|   ├── ...
+│   │   ├── devcontainer-template.json
+│   │   └──| .devcontainer
+│   │      └── devcontainer.json
+├── test
+│   ├── color
+│   │   └── test.sh
+│   ├── hello
+│   │   └── test.sh
+│   └──test-utils
+│      └── test-utils.sh
+...
+```
+
+The following command will publish each Template above (`color,hello`) to the registry `ghcr.io` with the following namespace (prefix) `devcontainers/templates`.
+
+```
+[/tmp]$  GITHUB_TOKEN="$CR_PAT" devcontainer templates publish -r ghcr.io -n devcontainers/templates ./src
+```
+
+To later apply a published Template (in the example below, the `color` template) with the CLI, the following `apply` command would be used:
+
+```
+[/tmp]$  devcontainer templates apply \
+                 -t 'ghcr.io/devcontainers/templates/color' \
+                 -a '{"favorite": "red"}'
+```
+
+### <a href="#authentication-methods" name="authentication-methods" class="anchor">Authentication Methods</a>
+
+> NOTE: OS-specific docker credential helpers (Docker Desktop credential helper) are not currently recognized by the CLI.  
+- Adding a $HOME/.docker/config.json with your credentials following [this commonly defined format](https://www.systutorials.com/docs/linux/man/5-docker-config-json/).
+   - Your `docker login` command may write this file for you depending on your operating system.
+- Using our custom env variable DEVCONTAINERS_OCI_AUTH
+    - eg: `DEVCONTAINERS_OCI_AUTH=service1|user1|token1,service2|user2|token2`
+
+For publishing to `ghcr.io`
+- Using the `devcontainers/action` GitHub action to handle the `GITHUB_TOKEN` credential for you.
+- Providing a GITHUB_TOKEN with permission to `write:packages`.