diff --git a/README.md b/README.md
index fd59f30..be88d9a 100644
--- a/README.md
+++ b/README.md
@@ -291,133 +291,3 @@ options. While it is not high priority, adding support for CLIs that differ from
 As an example, some CLIs may accept multiple options on a flag: `--flag option1 option2`. This is poor design
 as it's unclear to the user if "option2" is another positional arg or not. What we will likely do for behaviors
 like this is allow it, but show a warning that it is not recommended.
-
-## Usage Spec Components
-
-> [!WARNING]
-> This spec is still a work in progress and is subject to change until 1.0
-
-### Top-level metadata
-
-```sh
-name "My CLI"        # a friendly name for the CLI
-bin "mycli"          # the name of the binary
-version "1.0.0"      # the version of the CLI
-author "nobody"      # the author of the CLI
-license "MIT"        # SPDX license the CLI is released under
-
-# help for -h
-before_help "before about"
-about "some help"
-after_help "after about"
-
-# help for --help
-before_long_help "before about"
-long_about "longer help"
-after_long_help "after about"
-example "mycli --help"
-```
-
-### `flag`
-
-```sh
-flag "-u,--user <user>" # one way to define a flag
-flag "--user" { # another way to define the same flag
-  alias "-u"
-  arg "<user>"
-}
-flag "--user" { alias "-u" hide=true } # hide alias from docs and completions
-
-flag "-f,--force" global=true           # global can be set on any subcommand
-flag "--file <file>" default="file.txt" # default value for flag
-flag "-v,--verbose" count=true          # instead of true/false $usage_verbose is # of times
-                                        # flag was used (e.g. -vvv = 3)
-
-flag "--color" negate="--no-color" default=true  # $usage_color=true by default
-                                                 # --no-color will set $usage_color=false
-
-flag "--color" env="MYCLI_COLOR" # flag can be backed by an env var
-flag "--color" config="ui.color" # flag can be backed by a config file
-
-flag "--file <file>"  # args named "<file>" will be completed as files
-flag "--dir <dir>"    # args named "<dir>" will be completed as directories
-
-flag "--file <file>" required_if="--dir"     # if --dir is set, --file must also be set
-flag "--file <file>" required_unless="--dir" # either --file or --dir must be present
-flag "--file <file>" overrides="--stdin"     # if --file is set, previous --stdin will be ignored
-
-flag "--file <file>" long_help="longer help for --help (as oppoosed to -h)"
-
-flag "--shell <shell>" {
-  choices "bash" "zsh" "fish" # <shell> must be one of the choices
-}
-```
-
-### `arg`
-  
-```sh
-arg "<file>"                             # positional arg, completed as a filename
-arg "<dir>"                              # positional arg, completed as a directory
-arg "[file]"                             # optional positional arg
-arg "<file>" default="file.txt"          # default value for arg
-arg "<file>" parse="mycli parse-file {}" # parse arg value with external command
-
-arg "[file]" var=true # multiple args can be passed (e.g. mycli file1 file2 file3) (0 or more)
-arg "<file>" var=true # multiple args can be passed (e.g. mycli file1 file2 file3) (1 or more)
-arg "<file>" var=true var_min=3 # at least 3 args must be passed
-arg "<file>" var=true var_max=3 # up to 3 args can be passed
-
-arg "<shell>" {
-  choices "bash" "zsh" "fish" # <shell> must be one of the choices
-}
-
-arg "<file>" long_help="longer help for --help (as oppoosed to -h)"
-```
-
-### `cmd`
-
-```sh
-# aliases
-cmd "config" help="Manage the CLI config" {
-  alias "cfg" "cf" "cg"  # aliases for the command
-  alias "conf" hide=true # hide alias from docs and completions
-}
-
-cmd "config" hide=true # hide command from docs and completions
-cmd "config" subcommand_required=true # subcommand is not optional
-
-# these are shown under -h
-cmd "config" before_help="shown before the command"
-cmd "config" help="short description"
-cmd "config" after_help="shown after the command"
-
-# these are shown under --help
-cmd "config" before_long_help="shown before the command"
-cmd "config" long_help="longer description"
-cmd "config" after_long_help="shown after the command"
-
-cmd "list" {
-  example "Basic usage" r#"
-    $ mycli list
-    FRUIT  COLOR
-    apple  red
-    banana yellow
-  "#
-  example "JSON output" r#"
-    $ mycli list --json
-    [
-      {"FRUIT": "apple", "COLOR": "red"},
-      {"FRUIT": "banana", "COLOR": "yellow"}
-    ]
-  "#
-}
-```
-
-### `complete`
-
-```sh
-# use a custom completion command for args named "PLUGIN"
-complete "<plugin>" run="mycli plugins list" 
-```
-
-- [ ] "See code" - like in oclif docs
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 19b0370..779c3e0 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -15,15 +15,27 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Examples', link: '/markdown-examples' }
+      { text: 'Spec', link: '/spec/' },
+      { text: 'CLI', link: '/cli/' },
     ],
 
     sidebar: [
       {
-        text: 'Examples',
+        text: 'Spec',
+        link: '/spec/',
         items: [
-          { text: 'Markdown Examples', link: '/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/api-examples' }
+          {
+            text: 'Reference',
+            link: '/spec/reference/',
+            items: [
+              { text: 'cmd', link: '/spec/reference/cmd' },
+              { text: 'arg', link: '/spec/reference/arg' },
+              { text: 'flag', link: '/spec/reference/flag' },
+              { text: 'complete', link: '/spec/reference/complete' },
+              // { text: 'env', link: '/spec/reference/env' },
+              // { text: 'config', link: '/spec/reference/config' },
+            ]
+          },
         ]
       }
     ],