diff --git a/README.md b/README.md
index 254078c..1d2be17 100644
--- a/README.md
+++ b/README.md
@@ -1,186 +1,80 @@
-
-
-# Dev Container Features: Self Authoring Template
-
-> This repo provides a starting point and example for creating your own custom [dev container Features](https://containers.dev/implementors/features/), hosted for free on GitHub Container Registry. The example in this repository follows the [dev container Feature distribution specification](https://containers.dev/implementors/features-distribution/).
->
-> To provide feedback to the specification, please leave a comment [on spec issue #70](https://github.com/devcontainers/spec/issues/70). For more broad feedback regarding dev container Features, please see [spec issue #61](https://github.com/devcontainers/spec/issues/61).
-
-## Example Contents
-
-This repository contains a _collection_ of two Features - `hello` and `color`. These Features serve as simple feature implementations. Each sub-section below shows a sample `devcontainer.json` alongside example usage of the Feature.
-
-### `hello`
-
-Running `hello` inside the built container will print the greeting provided to it via its `greeting` option.
-
-```jsonc
-{
- "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
- "features": {
- "ghcr.io/devcontainers/feature-starter/hello:1": {
- "greeting": "Hello"
- }
- }
-}
-```
-
-```bash
-$ hello
+
-Hello, user.
-```
-
-### `color`
+
-Running `color` inside the built container will print your favorite color to standard out.
+# Devcontainer community features
-```jsonc
-{
- "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
- "features": {
- "ghcr.io/devcontainers/feature-starter/color:1": {
- "favorite": "green"
- }
- }
-}
-```
+๐งฐ Community-driven collection of addons for [@devcontainers]
-```bash
-$ color
+
-my favorite color is green
-```
+
-## Repo and Feature Structure
+[Docs website](https://devcontainers-community.github.io/features/)
+| [Official feature index](https://containers.dev/features)
-Similar to the [`devcontainers/features`](https://github.com/devcontainers/features) repo, this repository has a `src` folder. Each Feature has its own sub-folder, containing at least a `devcontainer-feature.json` and an entrypoint script `install.sh`.
+
-```
-โโโ src
-โ โโโ hello
-โ โ โโโ devcontainer-feature.json
-โ โ โโโ install.sh
-โ โโโ color
-โ โ โโโ devcontainer-feature.json
-โ โ โโโ install.sh
-| โโโ ...
-โ โ โโโ devcontainer-feature.json
-โ โ โโโ install.sh
-...
-```
+โ Add extra features to your GitHub Codespace \
+๐ณ Use JSON, not `Dockerfile`s! \
+๐จโ๐ฉโ๐งโ๐ฆ Community-driven maintainership
-An [implementing tool](https://containers.dev/supporting#tools) will composite [the documented dev container properties](https://containers.dev/implementors/features/#devcontainer-feature-json-properties) from the feature's `devcontainer-feature.json` file, and execute in the `install.sh` entrypoint script in the container during build time. Implementing tools are also free to process attributes under the `customizations` property as desired.
+**๐ค We want you!** If you're a community devcontainer feature maintainer, we'd
+love to add you to this project! โค๏ธ If you just want to hand off a devcontainer
+feature that you no longer want to maintain, **that's perfect too**. Open a
+[Discussion] and let's have a friendly chat. ๐
-### Options
+## Usage
-All available options for a Feature should be declared in the `devcontainer-feature.json`. The syntax for the `options` property can be found in the [devcontainer Feature json properties reference](https://containers.dev/implementors/features/#devcontainer-feature-json-properties).
+
+
+
-For example, the `color` feature provides an enum of three possible options (`red`, `gold`, `green`). If no option is provided in a user's `devcontainer.json`, the value is set to "red".
+Add a `features: {}` key to your existing `devcontainer.json` file, or make a
+new one at `.devcontainer/devcontainer.json` in your repository. Then, just add
+[one of the features that we offer] to the object map with an optional `{}`
+options object.
```jsonc
+// .devcontainer/devcontainer.json
{
- // ...
- "options": {
- "favorite": {
- "type": "string",
- "enum": [
- "red",
- "gold",
- "green"
- ],
- "default": "red",
- "description": "Choose your favorite color."
- }
- }
+ "features": {
+ "ghcr.io/devcontainers-community/features/dart": {}
+ }
}
```
-Options are exported as Feature-scoped environment variables. The option name is captialized and sanitized according to [option resolution](https://containers.dev/implementors/features/#option-resolution).
-
-```bash
-#!/bin/bash
-
-echo "Activating feature 'color'"
-echo "The provided favorite color is: ${FAVORITE}"
-
-...
-```
-
-## Distributing Features
-
-### Versioning
+[๐ Read more about each feature on our documentation website!](https://devcontainers-community.github.io/features/)
-Features are individually versioned by the `version` attribute in a Feature's `devcontainer-feature.json`. Features are versioned according to the semver specification. More details can be found in [the dev container Feature specification](https://containers.dev/implementors/features/#versioning).
+## Development
-### Publishing
+
+
-> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/features-distribution/).
->
-> While any registry [implementing the OCI Distribution spec](https://github.com/opencontainers/distribution-spec) can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry.
+๐ฃ The @devcontainers-community organization is still in its early stages. This
+features repository is currently trying to **hit the highlights first**. That
+means popular features first! If you notice a bug ๐ or have an improvement
+suggestion ๐ก we'd love to hear it! ๐
-Features are meant to be easily sharable units of dev container configuration and installation code.
+If you're interested in getting started modifying, adding, or testing a template
+in this repository, you can do so without even leaving your browser thanks to
+GitHub Codespaces! โ๏ธ After optionally forking the repository, you just hit the
+green Code button at the top of the GitHub web UI and then Create codespace on
+main. ๐
-This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will publish each feature to GHCR. By default, each Feature will be prefixed with the `` namespace. For example, the two Features in this repository can be referenced in a `devcontainer.json` with:
-
-```
-ghcr.io/devcontainers/feature-starter/color:1
-ghcr.io/devcontainers/feature-starter/hello:1
-```
+After launching your dev environment and making some changes, you're probably
+going to want to test those changes. Run the `devcontainer features test`
+command to run _all_ the tests, or just `-f` to run a specific one that you're
+working on. Be warned that this involves some heavyweight Docker-ing around!
-The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: `ghcr.io/devcontainers/feature-starter`. This contains information useful for tools aiding in Feature discovery.
-
-'`devcontainers/feature-starter`' is known as the feature collection namespace.
-
-### Marking Feature Public
-
-Note that by default, GHCR packages are marked as `private`. To stay within the free tier, Features need to be marked as `public`.
-
-This can be done by navigating to the Feature's "package settings" page in GHCR, and setting the visibility to 'public`. The URL may look something like:
-
-```
-https://github.com/users//packages/container/%2F/settings
+```sh
+devcontainer features test
```
-
+๐ค Check out our contributing guide to see how to get your changes merged!
-### Adding Features to the Index
-
-If you'd like your Features to appear in our [public index](https://containers.dev/features) so that other community members can find them, you can do the following:
-
-* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io)
- * This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site
-* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file
-
-This index is from where [supporting tools](https://containers.dev/supporting) like [VS Code Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [GitHub Codespaces](https://github.com/features/codespaces) surface Features for their dev container creation UI.
-
-#### Using private Features in Codespaces
-
-For any Features hosted in GHCR that are kept private, the `GITHUB_TOKEN` access token in your environment will need to have `package:read` and `contents:read` for the associated repository.
-
-Many implementing tools use a broadly scoped access token and will work automatically. GitHub Codespaces uses repo-scoped tokens, and therefore you'll need to add the permissions in `devcontainer.json`
-
-An example `devcontainer.json` can be found below.
-
-```jsonc
-{
- "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
- "features": {
- "ghcr.io/my-org/private-features/hello:1": {
- "greeting": "Hello"
- }
- },
- "customizations": {
- "codespaces": {
- "repositories": {
- "my-org/private-features": {
- "permissions": {
- "packages": "read",
- "contents": "read"
- }
- }
- }
- }
- }
-}
-```
+
+[@devcontainers]: https://github.com/devcontainers
+[one of the features that we offer]: https://devcontainers-community.github.io/features/
+[Discussion]: https://github.com/devcontainers-community/features/discussions/new?category=general
+