diff --git a/README.md b/README.md
index e38d2ae..85d9af4 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,15 @@
 # nas
-small go nas platform for my raspberry pi
+bringing filesystems together
 
-## usage
+## about
 
-### configuration
+this project aims to be an easy-to-manage web application that allows the management of cloud storage, whether it be on
+the host machine or part of a remote api. this is intended mostly for my own use, but i am documenting it in a way that
+i hope allows others to pick it up and improve on it down the line.
+
+if something is unclear, feel free to open an issue :)
+
+## configuration
 
 unlike the initial version of this project, the current build uses _providers_ to determine how to handle various 
 functions related to files. currently, two are implemented, `disk` and `backblaze`, since they are the primary providers
@@ -25,27 +31,34 @@ backblaze:
 
 (read more here: [#providers](#providers))
 
-### running
+## running
 
-after adding the providers you would like to use, the application can be run simply with `./nas`.
+after adding the providers you would like to use, the application can be run simply with `./nas`. it will attach to port
+`:3000`.
 
-### building
+## building
 
 this project uses go modules and a makefile, so building should be relatively straightforward. 
 
  - `make` will build the project for your system's architecture.
+ - `make run` will run the project with `go run`
  - `make pi` will build the project with the `GOOS=linux GOARCH=arm GOARM=5 go` flags set for raspberry pis.
  
-### providers
+## providers
+
+"providers" provide a handful of functions to interact nicely with a filesystem, whether it be on local disk or on a 
+remote server via an api. best-effort is done to keep these performant, up to date and minimal.
 
 there are a few built-in providers, and more can be added by opening a pull request.
 
 |name|service|configuration example|
 |----|-------|---------------------|
-|disk|local filesystem|disk.yml|
-|backblaze|backblaze b2|backblaze.yml|
+|disk|local filesystem|assets/config_examples/disk.yml|
+|backblaze|backblaze b2|assets/config_examples/backblaze.yml|
 
-#### custom provider
+you can find a full configuration file under `assets/config_examples/providers.yml`
+
+### custom provider
 
 custom file providers can be implemented by adding a new go file to the `files` module. it should
 implement the `FileProviderInterface` interface.
\ No newline at end of file
diff --git a/assets/config_examples/README.md b/assets/config_examples/README.md
new file mode 100644
index 0000000..e69de29
diff --git a/assets/config_examples/backblaze.yml b/assets/config_examples/backblaze.yml
new file mode 100644
index 0000000..c311c24
--- /dev/null
+++ b/assets/config_examples/backblaze.yml
@@ -0,0 +1,9 @@
+# The Backblaze provider requires an application key, application key ID, and bucket ID to use.
+# You can find steps for generating there here: https://www.backblaze.com/b2/docs/application_keys.html
+# Keys should have at least the listBuckets, readFiles, writeFiles and shareFiles permissions for a bucket.
+backblaze:
+  provider: backblaze
+  config: # Provider-specific files.
+    applicationKeyId: aaaaaaaaaaaa
+    applicationKey: aaaaaaaaaaaa
+    bucket: aaaaaaaaaaaa
\ No newline at end of file
diff --git a/assets/config_examples/disk.yml b/assets/config_examples/disk.yml
new file mode 100644
index 0000000..b42e3f0
--- /dev/null
+++ b/assets/config_examples/disk.yml
@@ -0,0 +1,5 @@
+# The disk provider is the most basic of providers, requiring only a path on disk to write and retrieve files to and
+# from.
+disk:
+  provider: disk
+  path: /tmp/nas # This is only used for the `disk` provider right now, and indicates where to manage files.
\ No newline at end of file
diff --git a/assets/config_examples/providers.yml b/assets/config_examples/providers.yml
new file mode 100644
index 0000000..5c19b86
--- /dev/null
+++ b/assets/config_examples/providers.yml
@@ -0,0 +1,20 @@
+# A "provider" is a service that provides access to a filesystem.
+#
+# A full configuration for every provider implemented in the application.
+# You can find full breakdowns for each provider's configuration in it's respective file under
+# `assets/config_examples/`.
+#
+# Schema is as follows:
+# Provider Name: string - used to identify which filesystem to access.
+#   provider: string - should be one of the built-in providers.
+#   path: string - optional, just used for `disk` right now.
+#   config: mapping - used for provider-specific configuration values, such as authentication.
+disk:
+  provider: disk
+  path: /tmp/nas
+backblaze:
+  provider: backblaze
+  config:
+    applicationKeyId: aaaaaaaaaaaa
+    applicationKey: aaaaaaaaaaaa
+    bucket: aaaaaaaaaaaa