diff --git a/docs/commands/README.md b/docs/commands/README.md
new file mode 100644
index 00000000..51152045
--- /dev/null
+++ b/docs/commands/README.md
@@ -0,0 +1,4 @@
+# Command documentation (experimental)
+Command documentation is defined in `commands.js`. `build.js` can export a JSON file consumed by other tools (hopefully?).
+
+This documentation is loaded by the `CommandInfo` Vue component, used in `commands.md` for the command page (and maybe other places soon?).
\ No newline at end of file
diff --git a/docs/commands/build.js b/docs/commands/build.js
new file mode 100644
index 00000000..c962c837
--- /dev/null
+++ b/docs/commands/build.js
@@ -0,0 +1 @@
+console.log(JSON.stringify(require("./commands")));
\ No newline at end of file
diff --git a/docs/commands/commands.js b/docs/commands/commands.js
new file mode 100644
index 00000000..c6a31c5f
--- /dev/null
+++ b/docs/commands/commands.js
@@ -0,0 +1,24 @@
+module.exports = {
+    "system-new": {
+        title: "Create a new system",
+        summary: "Creates a new system if you do not already have one.",
+        usage: [
+            {cmd: "system new", desc: "Creates a system with no name."},
+            {cmd: "system new `system-name`", desc: "Creates a named system."}
+        ],
+        arguments: {
+            "system-name": {type: "string", desc: "the name of the system to create", optional: true}
+        }
+    },
+    "system-info": {
+        title: "Look up info about a system",
+        summary: "Shows a system card, either your own or someone else's.",
+        usage: [
+            {cmd: "system", desc: "Looks up your own system."},
+            {cmd: "system `target`", desc: "Looks up another system."}
+        ],
+        arguments: {
+            "target": {type: "system", desc: "the system to look up"}
+        }
+    }
+};
\ No newline at end of file
diff --git a/docs/content/.vuepress/components/Arg.vue b/docs/content/.vuepress/components/Arg.vue
index 27735543..06e8a665 100644
--- a/docs/content/.vuepress/components/Arg.vue
+++ b/docs/content/.vuepress/components/Arg.vue
@@ -21,9 +21,15 @@
     }
         
     .command-argument {
+        font-size: $exampleFontSize;
+        font-family: $exampleFontFamily;
+        color: $exampleTextColor;
+
         padding: 0 0.5rem;
         background-color: lighten($exampleBgColor, 15%);
         border-radius: 4px;
+        
+        line-height: 1.7;
     }
     
     .argument-details {
diff --git a/docs/content/.vuepress/components/Cmd.vue b/docs/content/.vuepress/components/Cmd.vue
index 91b12980..62f07c74 100644
--- a/docs/content/.vuepress/components/Cmd.vue
+++ b/docs/content/.vuepress/components/Cmd.vue
@@ -1,6 +1,7 @@
 <template>
     <p class="command-example">
         <span class="bot-prefix">pk;</span><slot></slot>
+        <span class="example-comment" v-if="comment">// {{ comment }}</span>
     </p>
 </template>
 
@@ -8,8 +9,8 @@
     .command-example {
         font-size: $exampleFontSize;
         font-family: $exampleFontFamily;
-
         color: $exampleTextColor;
+        
         background-color: $exampleBgColor;
         border-radius: 6px;
         
@@ -20,4 +21,15 @@
     .bot-prefix {
         color: $examplePrefixColor;
     }
-</style>
\ No newline at end of file
+    
+    .example-comment {
+        color: $exampleCommentColor;
+        float: right;
+    }
+</style>
+
+<script>
+    export default {
+        props: ["comment"]
+    }
+</script>
\ No newline at end of file
diff --git a/docs/content/.vuepress/components/CmdGroup.vue b/docs/content/.vuepress/components/CmdGroup.vue
index d01ebd9e..12728c9d 100644
--- a/docs/content/.vuepress/components/CmdGroup.vue
+++ b/docs/content/.vuepress/components/CmdGroup.vue
@@ -8,7 +8,8 @@
     .command-example-group {
         background-color: $exampleBgColor;
         border-radius: 6px;
-        
+
+        margin: 0.5rem 0;
         padding: 0.75rem 1.25rem;
     }
     
diff --git a/docs/content/.vuepress/components/CommandInfo.vue b/docs/content/.vuepress/components/CommandInfo.vue
new file mode 100644
index 00000000..ed9a3090
--- /dev/null
+++ b/docs/content/.vuepress/components/CommandInfo.vue
@@ -0,0 +1,91 @@
+<template>
+    <div class="command-info">
+        <h3 :id="cmd">
+            <a class="header-anchor" :href="'#' + cmd">#</a>
+            {{ command.title }}
+        </h3>
+        <p>{{ command.summary }}</p>
+
+        <slot></slot>
+
+        <CmdGroup>
+            <Cmd v-for="usage in command.usage" :comment="usage.desc">
+                <span v-for="part in parseUsage(usage)">
+                    <span v-if="part.type === 'str'">{{ part.str }}</span>
+                    <span v-if="part.type === 'arg'"><Arg>{{ part.arg }}</Arg></span>
+                </span>
+            </Cmd>
+        </CmdGroup>
+
+        <h4>Arguments</h4>
+        <div v-for="(arg, key) in command.arguments">
+            <Arg>{{ key }}</Arg> (<strong v-if="arg.type === 'string'">text</strong><strong v-if="arg.type === 'system'">system ID</strong><span v-if="arg.optional">, <em>optional</em></span>) - {{ arg.desc }}. 
+        </div>
+
+        <!--table>
+            <thead>
+            <tr>
+                <th>Argument</th>
+                <th>Type</th>
+                <th>Description</th>
+            </tr>
+            </thead>
+            <tbody>
+            <tr v-for="(arg, key) in command.arguments">
+                <td>
+                    <Arg>{{ key }}</Arg>
+                </td>
+                <td>{{ arg.type }}</td>
+                <td>{{ arg.desc }}</td>
+            </tr>
+            </tbody>
+        </table-->
+    </div>
+</template>
+
+<script>
+    import commands from "../../../commands/commands";
+
+    export default {
+        props: ["cmd"],
+
+        data() {
+            return {command: commands[this.cmd]};
+        },
+
+        methods: {
+            parseUsage(usage) {
+                if (usage.cmd) usage = usage.cmd;
+
+                const parts = usage.split(/\s/);
+                const output = [];
+                for (const part of parts) {
+                    const match = part.match(/`([\w\-]+)`/);
+                    if (match)
+                        output.push({type: "arg", arg: match[1]});
+                    else
+                        output.push({type: "str", str: part})
+                }
+                return output;
+            }
+        }
+    }
+</script>
+
+<style>
+    .command-info {
+        margin-bottom: 2.5rem;
+    }
+
+    .command-info h3 {
+        margin-bottom: 0;
+    }
+
+    .command-info p {
+        margin-top: 0.25rem;
+    }
+
+    .command-info h4 {
+        margin-bottom: 0.75rem;
+    }
+</style>
\ No newline at end of file
diff --git a/docs/content/.vuepress/styles/palette.styl b/docs/content/.vuepress/styles/palette.styl
index f1328bab..fdee41d4 100644
--- a/docs/content/.vuepress/styles/palette.styl
+++ b/docs/content/.vuepress/styles/palette.styl
@@ -4,6 +4,7 @@ $accentColor = #e8a024;
 // CUSTOM
 $exampleBgColor = $codeBgColor;
 $exampleTextColor = #ffffff;
-$examplePrefixColor = #a3a6a9;
+$examplePrefixColor = #b3b6b9;
+$exampleCommentColor = darken($accentColor, 10%);
 $exampleFontSize = 0.9rem;
 $exampleFontFamily = source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace;
\ No newline at end of file
diff --git a/docs/content/guide/commands.md b/docs/content/guide/commands.md
index f7eb8dc8..071cf94c 100644
--- a/docs/content/guide/commands.md
+++ b/docs/content/guide/commands.md
@@ -1 +1,20 @@
-# Command list
\ No newline at end of file
+# Command list
+
+::: tip HOW TO READ THIS PAGE
+Below is a list of all the commands the bot supports.
+
+Highlighted spaces (eg. <Arg>system-name</Arg> ) are **arguments**, and you should **fill in the blank** with the relevant bit of text. The **Arguments** section below describes what to put in each blank.
+
+When an argument asks for a **system ID**, you can either fill in a system's [5-character ID](./ids.md), **or** you can fill in a Discord account ID, or even a @mention. For example:
+<CmdGroup>
+<Cmd>system <Arg>exmpl</Arg></Cmd>
+<Cmd>system <Arg>466378653216014359</Arg> list</Cmd>
+<Cmd>system <Arg>@PluralKit#4020</Arg> fronter</Cmd>
+</CmdGroup>
+
+When an argument asks for a **member ID**, you can either fill in a member's [5-character ID](./ids.md), or, *if the member is in your own system*, their name. This means that to target a member in another system, you **must** use their ID.
+:::
+
+## System commands
+<CommandInfo cmd="system-info"></CommandInfo>
+<CommandInfo cmd="system-new"></CommandInfo>
\ No newline at end of file
diff --git a/docs/content/guide/ids.md b/docs/content/guide/ids.md
new file mode 100644
index 00000000..92f102a7
--- /dev/null
+++ b/docs/content/guide/ids.md
@@ -0,0 +1,2 @@
+# System and member IDs
+hi!
\ No newline at end of file