docs: add WIP examples of different TOML files for config portability

concepts.md

@@ -0,0 +1,26 @@
+```mermaid
+flowchart TD
+    seeds[Seeds: well-known app configuration repo locations];
+    starter[Starters: editable exports of existing remote repos];
+
+    local_repos[Local Git repos]
+    remote_repos[Remote Git repos];
+
+    local_repos --> remote_repos;
+    remote_repos --> local_repos;
+
+    command_new_from_file([`cpsc new from-seed`]);
+    command_import([`cpsc starter import`]);
+    command_export([`cpsc starter export`]);
+
+    command_new_from_file -->|creates single| local_repos;
+    command_import -->|creates multiple| local_repos;
+
+    seeds --> command_new_from_file;
+    local_repos --> command_export;
+
+    command_export -->|export to| starter;
+    starter -->|set up clones for| command_import;
+
+    apps[3rd party applications with their own config locations] -->|seed-ified by Capisco community| seeds;
+```

repo_example.toml

@@ -0,0 +1,21 @@
+# This is a local repository configuration for [Capisco], likely created via
+# `cpsc new`. If you find the need to edit this manually, it's almost certainly
+# a bug or out-of-date template definition. Please file an issue
+# [upstream][issue tracker]!
+#
+# [Capisco]: https://github.com/capisco-dotfiles/capisco
+# [issue tracker]: https://github.com/capisco-dotfiles/capisco
+
+[capisco]
+type = "repo"
+schema_version = "1"
+
+[repo]
+checkout_location = { type = "xdg", subdir = "nvim" }
+
+[history.template]
+source = "https://github.com/capisco-dotfiles/templates"
+rev = "ASDFASDFASDF"
+template = "neovim"
+variant = "default"
+version = 1

starter_example.toml

@@ -0,0 +1,51 @@
+# This file is a _Capisco starter file_. It's used with [Capisco] (a dotfiles
+# management tool) to clone multiple dotfiles repositories with a single
+# command, i.e.:
+#
+# ```sh
+# $ cpsc export $THIS_FILE # save current configuration of repos
+# $ cpsc import $THIS_FILE # load configuration back again
+# ```
+#
+# [Capisco]: https://github.com/capisco-dotfiles/capisco
+
+[capisco]
+type = "starter"
+schema_version = "1"
+
+[throwaway]
+git_url = "https://github.com/throwaway-fanboy/throwaway"
+# # The following are optional values with their default values provided for
+# # illustration:
+# remote_name = "origin"
+# branch = "main" # Falls back to `"master"`, if not found.
+
+# # Additional remotes can be added using sub-tables of `<name>.remotes`. For
+# # example, if we wanted to add an `upstream` remote, we could do so like
+# # this:
+# [throwaway.remotes.upstream]
+# git_url = "https://github.com/throwaway/throwaway"
+
+# # TODO: Template selection, or actual assignment? I think we should go with
+# # assignment for now, but I'm not sure.
+# #
+# # For best experience with your own repos, it's strongly recommended you
+# # embed a repository configuration (`capisco.toml`) in them. However, you can
+# # also specify or override a configuration here. It uses the same schema as
+# # [template file entries].
+# #
+# # [template file entries]: TODO
+# [throwaway.template]
+# name = "neovim"
+#
+# [throwaway.template.override.windows]
+# standalone = ""
+
+[git]
+git_url = "git@github.com:erichdongubler-dotfiles/git"
+
+[neovim]
+git_url = "git@github.com:erichdongubler-dotfiles/neovim"
+
+[nushell]
+git_url = "git@github.com:erichdongubler-dotfiles/nushell"

template_example.kdl

@@ -0,0 +1,74 @@
+// This is a template definition file for [Capisco]. If you find the need to
+// edit one of these manually, it's almost certainly a bug, missing, or
+// out-of-date. Please file an issue [upstream][issue tracker]!
+//
+// [Capisco]: https://github.com/capisco-dotfiles/capisco
+// [issue tracker]: https://github.com/capisco-dotfiles/capisco
+
+capisco-header {
+	type "template"
+	schema-version 1
+}
+
+template git {
+	version 1 default-variant=home-dir-gitconfig {
+		home-dir-gitconfig {
+			all {
+				type "overlay"
+				root "~"
+				files {
+					.gitconfig
+				}
+			}
+		}
+		xdg {
+			type "global"
+			// `subdir` is inferred to be the template's name when omitted
+		}
+	}
+}
+
+template neovim {
+	version 1 {
+		default {
+			unix {
+				checkout-location {
+					type "xdg"
+					subdir "nvim"
+				}
+			}
+			windows {
+				checkout-location {
+					type "windows-local-appdata"
+					app-name "nvim"
+				}
+			}
+		}
+	}
+}
+
+template nushell {
+	version 1 {
+		all {
+			checkout_location {
+				type "native"
+				qualifier ""
+				org ""
+				app "nushell"
+			}
+		}
+	}
+}
+
+template espanso {
+	version 1 {
+		all {
+			checkout_location {
+				type "native"
+				qualifier ""
+				org ""
+				app "nushell"
+			}
+		}
+	}
+}

template_example.toml

@@ -0,0 +1,59 @@
+# This is a template definition file for [Capisco]. If you find the need to
+# edit one of these manually, it's almost certainly a bug, missing, or
+# out-of-date. Please file an issue [upstream][issue tracker]!
+#
+# [Capisco]: https://github.com/capisco-dotfiles/capisco
+# [issue tracker]: https://github.com/capisco-dotfiles/capisco
+
+[capisco]
+type = "template"
+schema_version = "1"
+
+# ---
+
+[template]
+name = "git"
+
+[[versions]]
+number = 1
+# TODO: Maybe use a `default_variant = false` to force a user to pick?
+default_variant = "home_dir_gitconfig" # defaults to `"default"`
+
+[template.variants.home_dir_gitconfig]
+checkout_location = { type = "overlay", files = [".gitconfig"] }
+
+[template.variants.xdg]
+checkout_location = { type = "xdg" } # `subdir` is omitted, and inferred to be `template.name`'s value
+
+# ---
+
+[template]
+name = "neovim"
+# version = 1
+# default_variant = "default"
+
+[template.variants.default]
+checkout_location = { type = "xdg", subdir = "nvim" }
+# # If we actually wanted the `neovim` segment, we could go with:
+# standalone = { type = "xdg" }
+
+[template.variants.default.windows]
+checkout_location = "~/AppData/Local/nvim" # Paths _must_ start with `~`. If you'd like to see this relaxed, holler at <TODO: ISSUE REF>.
+
+# ---
+
+[template]
+name = "nushell"
+
+[template.variants.default]
+checkout_location = { type = "native" }
+# # The above is shorthand for:
+# checkout_location = { type = "native", qualifier = "", org = "", app = "nushell" }
+
+# ---
+
+[template]
+name = "espanso"
+
+[template.variants.default]
+checkout_location = { type = "native" }