Define configuration and CLI contracts (#2)

docs/configuration.md

@@ -0,0 +1,53 @@
+# Configuration
+
+IronStorage uses one small TOML file. Pass an explicit file with
+`--config PATH`; otherwise the CLI loads `ironstorage/config.toml` below the
+native per-user configuration directory:
+
+- Linux and other Unix systems: `$XDG_CONFIG_HOME`, when it is absolute, or
+  `$HOME/.config`;
+- macOS: `$HOME/Library/Application Support`;
+- Windows: `%APPDATA%`.
+
+An explicit relative configuration path is resolved from the process current
+directory. Relative `vault` and `key_material` paths inside the file are
+resolved from the directory containing the resolved configuration file.
+Absolute paths remain absolute. `.` and `..` components are normalized
+lexically; `~` is not expanded. The vault may be absent before `init`, but an
+existing vault must be a directory. Exported key material must already exist
+as a regular file or directory.
+
+```toml
+vault = "../vault"
+default_key = "0123456789ABCDEF0123456789ABCDEF01234567"
+key_material = "keys"
+
+# An array avoids shell interpretation. A quoted command string is also
+# accepted and split without launching a shell.
+editor = ["code", "--wait"]
+
+[[git.remotes]]
+name = "origin"
+url = "https://git.example.test/alice/password-store.git"
+server_id = "personal-git"
+application_id = "ironstorage-cli"
+```
+
+`default_key` is the required identity that the embedded OpenPGP layer resolves
+against the exported key material. It may be a full fingerprint, key ID, or
+exact user ID; ambiguity and key capability checks happen in the key resolver.
+
+Editor selection is deterministic: TOML, `$VISUAL`, `$EDITOR`, then `vim`.
+Commands are split into an executable and argument vector and are never passed
+through a shell. Only the CLI `edit` adapter may eventually launch this
+configured editor.
+
+Git remotes are HTTPS-only. URLs containing user information, passwords,
+queries, or fragments are rejected. `server_id` and `application_id` are opaque
+references used to retrieve credentials from the operating-system secret
+store; duplicate names and duplicate reference pairs are errors.
+
+Passwords, passphrases, tokens, credentials, private keys, and other secret
+values are forbidden in TOML. Unknown fields are rejected. Parse errors never
+echo the source line or value, so an accidentally supplied secret is not
+repeated in diagnostics.