diff --git a/modules/feature/workspaces/README.org b/modules/feature/workspaces/README.org
new file mode 100644
index 000000000..c2e3f2c71
--- /dev/null
+++ b/modules/feature/workspaces/README.org
@@ -0,0 +1,75 @@
+#+TITLE: :feature workspaces
+
+This module adds support for workspaces, powered by persp_mode, as well as a unified API for manipulating them.
+
+#+begin_quote
+There are many ways to use workspaces. Some use them to group buffers/windows by project or categories (views, models, logic, etc). I use them differently: on a per-task basis, which may traverse multiple projects or aspects, but are tied to an objective. For example: implement a specific feature or fix a certain bug; sometimes unrelated to the project at hand.
+#+end_quote
+
+* Table of Contents :TOC:
+- [[#install][Install]]
+- [[#features][Features]]
+  - [[#isolated-buffer-list][Isolated buffer-list]]
+  - [[#automatic-workspaces][Automatic workspaces]]
+  - [[#session-persistence][Session persistence]]
+  - [[#workspace-persistence][Workspace persistence]]
+- [[#appendix][Appendix]]
+  - [[#commands--keybindings][Commands & Keybindings]]
+  - [[#api][API]]
+
+* Install
+This module has no additional dependencies.
+
+* Features
+** Isolated buffer-list
+When persp-mode is active, ~doom-buffer-list~ becomes workspace-restricted. You can overcome this by using ~buffer-list~.
+
+** Automatic workspaces
+A workspace is automatically created (and switched to) when you:
+
++ Create a new frame (with =make-frame=; bound to =M-N= by default)
++ Switch to a project using ~projectile-switch-project~ (or its ivy/helm equivalents)
+
+** Session persistence
+By default, your session is autosaved when you quit Emacs (or disable ~persp-mode~). You can load a previous session with ~M-x +workspace/load-session~ or ~:sl[oad]~ (ex command).
+
+You can supply either a name to load a specific session to replace your current one.
+
+** Workspace persistence
+If you'd like to save a specific workspace, use ~M-x +workspace/save~, which can be loaded into the current session (as another workspace) with ~M-x +workspace/load~.
+
+* Appendix
+** Commands & Keybindings
+Here is a list of available commands, their default keybindings (defined in private/hlissner/+bindings.el), and corresponding ex commands (if any -- defined in private/hlissner/+commands.el).
+
+| command                   | key / ex command           | description                                                |
+|---------------------------+----------------------------+------------------------------------------------------------|
+| ~+workspace/new~          | =SPC TAB n=                | Create a new, blank workspace                              |
+| ~+workspace/display~      | =SPC TAB TAB=              | Display open workspaces in the mode-line                   |
+| ~+workspace/load~         | =SPC TAB l=                | Load a saved workspace into the current session            |
+| ~+workspace/load-session~ | =SPC TAB L= / =:sl[oad]=   | Replace current session with a saved one                   |
+| ~+workspace/save~         | =SPC TAB s=                | Save the current workspace to a file                       |
+| ~+workspace/save-session~ | =SPC TAB S= / =:ss[ave]=   | Save current session                                       |
+| ~+workspace/switch-to~    | =SPC TAB .=                | Switch to an open workspace                                |
+| ~+workspace/switch-left~  | =SPC TAB [= / =[ w= / =gT= | Switch to previous workspace                               |
+| ~+workspace/switch-right~ | =SPC TAB [= / =] w= / =gt= | Switch to next workspace                                   |
+| ~+workspace/kill-session~ | =SPC TAB X= / =:sclear=    | Clears the current session (kills all windows and buffers) |
+
+** API
++ ~+workspace-list~ -> list<Struct>
++ ~+workspace-list-names~ -> list<string>
++ ~+workspace-buffer-list &optional PERSP~ -> bool
++ ~+workspace-p OBJ~ -> bool
++ ~+workspace-exists-p NAME~ -> bool
++ ~+workspace-get NAME &optional NOERROR~ -> Struct
++ ~+workspace-current &optional FRAME WINDOW~ -> Struct
++ ~+workspace-current-name~ -> string
++ ~+workspace-load NAME~
++ ~+workspace-load-session NAME~
++ ~+workspace-save NAME~
++ ~+workspace-save-session NAME~
++ ~+workspace-new NAME~
++ ~+workspace-rename NAME NEW-NAME~
++ ~+workspace-delete NAME &optional INHIBIT-KILL-P~
++ ~+workspace-switch NAME &optional AUTO-CREATE-P~
++ ~+workspace-protected-p NAME~ -> bool