Update README (#292)

* Add Codemodder logo to README

* Add Base Codemod diagram to README

* Update README contents

README.md

@@ -1,43 +1,79 @@
-# codemodder-python
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="img/codemodder-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="img/codemodder-light.png">
+  <img alt="Pixee Logo" src="https://github.com/pixee/pixee-cli/raw/main/img/codemodder.png">
+</picture>
 
-This is the Python version of the [Codemodder Framework](https://codemodder.io/), which builds on traditional codemod frameworks by providing
-codemods with additional context and services. Codemodder plugins inject codemods with the context and services they need to perform complex transforms.
+# codemodder-python
 
-Pluggability and the complex transforms they enable distinguish codemodder codemods from traditional codemods.
+This is the Python version of the [Codemodder Framework](https://codemodder.io/).
 
 Codemodder is sponsored by [pixee.ai](https://pixee.ai).
 
 ## Development Status
 
-The `codemodder-python` project is still under heavy development. 🚧
-
-The project includes a (growing) set of core codemods. It also supports the
-development of custom codemods.
+As of [v0.80.0](https://github.com/pixee/codemodder-python/releases/tag/0.80.0) the codemod API is relatively stable. However, backwards compatibility between releases will not be guaranteed until version 1.0.0.
 
-Many of the existing codemods make use of [Semgrep](https://semgrep.dev/). The
-`codemodder-python` framework will support additional codemod sources in the
-future.
 
-⚠️  The custom codemod API is under heavy development and is subject to change.
-The API should not be treated as stable at this time. ⚠️
+See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
 
 ## Installation
 
+The `codemodder` package is available [on PyPI](https://pypi.org/project/codemodder/). To install, run:
+```
+$ pip install codemodder
+```
+
 To install the package from source, use `pip`:
 
 ```
-pip install .
+$ pip install /path/to/codemodder-python
 ```
 
 ## Running Locally
 
-You can run the codemodder program with
+The codemodder package provides an executable called `codemodder`. This should be available on your path by default after installation.
 
-```codemodder <directory> --output <file> ...```
+For basic usage, run the `codemodder` command with a target directory path:
+
+```
+$ codemodder /path/to/my-project
+```
+
+Note that by default `codemodder` will make changes to files in your target directory. To run `codemodder` without making updates on disk, use the `--dry-run` flag:
+```
+$ codemodder --dry-run /path/to/my-project
+```
 
-```bash
-codemodder --help
+To list all available codemods (including any that are registered with installed plugins), use the `--list` option:
 ```
+$ codemodder --list
+```
+
+For a full list of options, use the `--help` flag:
+```
+$ codemodder --help
+```
+
+## Architecture
+
+Codemods are composed of the following key components:
+* Detector
+* Transformer(s)
+* Metadata
+
+<picture>
+  <source srcset="img/base-codemod.jpg">
+  <img alt="Base Codemod Diagram" src="https://github.com/pixee/pixee-cli/raw/main/img/base-codemod.jpg">
+</picture>
+
+## Custom Codemods
+
+The Python codemodder supports a plugin infrastructure for custom codemods. For users interested in developing a custom codemod plugin, we recommend starting with the [Cookiecutter template](https://github.com/pixee/cookiecutter-codemodder-plugin).
+
+## Documentation
+
+Coming soon!
 
 ## Contributing
 See [CONTRIBUTING.md](CONTRIBUTING.md).