diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..b4aee04
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2023 xenofem <xenofem@xeno.science>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1584de5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# screencap-bot
+
+this is a cohost bot that periodically posts randomly-chosen
+screencaps from a configured collection of tv series/movies.
+
+## installation
+
+you can build screencap-bot with cargo by cloning this repo, or
+install it as a Nix Flake.  it needs the ffmpeg library, and also
+needs the ffmpeg binary in its `PATH` when it's running.  the default
+package provided by the flake is a wrapped version that adds ffmpeg to
+its `PATH` for you.
+
+## configuration
+
+screencap-bot is configured with the following environment variables,
+which can also be put in a `.env` file in the program's working
+directory:
+
+- `SCREENCAP_BOT_SHOWS_FILE`: path of a YAML file specifying what shows to take screencaps from (default: `./shows.yaml`)
+- `SCREENCAP_BOT_GLOBAL_TAGS`: tags to put on every post the bot makes, as a comma-separated list (eg `bot account,automated post,The Cohost Bot Feed`) (default: none)
+- `SCREENCAP_BOT_POST_INTERVAL`: the interval between posts, in seconds (default: 6 hours)
+- `SCREENCAP_BOT_COHOST_EMAIL`: the email address the bot should use to log into cohost
+- `SCREENCAP_BOT_COHOST_PASSWORD`: the password the bot should use to log into cohost
+- `SCREENCAP_BOT_COHOST_PAGE`: the cohost page the bot should post from
+- `RUST_LOG`: log levels, for the app as a whole and/or for specific
+  submodules/libraries. See
+  [`env_logger`](https://docs.rs/env_logger/latest/env_logger/)'s
+  documentation for details.
+
+### shows
+
+the list of shows the bot should take screencaps from is read from a YAML file with the following structure:
+
+```yaml
+Gundam 0079:
+  path: /home/user/media/Mobile Suit Gundam 0079/
+  tags:
+    - MSG 0079
+    - 0079
+    - First Gundam
+Char's Counterattack:
+  path: /home/user/media/Gundam_CCA.mkv
+  tags:
+    - Char's Counterattack
+    - "Mobile Suit Gundam: Char's Counterattack"
+```
+
+each top-level key is a show title, which will be used in spoiler
+warnings on posts and in image alt text.  each show has two keys:
+
+- `path`: the path of a single video file, or the path of a directory
+  containing numbered video files for each episode of a series. all of
+  the episodes must be directly inside the directory, the bot will not
+  traverse subdirectories to find files.
+- `tags`: a list of tags to put on posts from this show.