@varde-flyt/vfac 0.7.0 → 0.8.0

package/README.md

@@ -26,11 +26,19 @@ vfac guide
 vfac whoami
 ```
 
-`doctor` checks the endpoint, the API, whether this client is new enough for the
-platform it is pointed at, your credential and what that credential reaches, in
-that order, and reports the first thing that is actually wrong. A platform
-declares the oldest client it supports; below that, `doctor` fails and says so
-before sending your credential anywhere.
+`doctor` checks the endpoint, which Project this terminal has selected, the API,
+whether this client is new enough for the platform it is pointed at, your
+credential and what that credential reaches, in that order, and reports the first
+thing that is actually wrong. A platform declares the oldest client it supports;
+below that, `doctor` fails and says so before sending your credential anywhere.
+
+The selected Project and the Projects your credential reaches are two different
+lines, and reading the second as the first is the mistake worth naming: a command
+with no `--project` uses the SELECTED one, and having access to a Project is not
+the same as being in it. `doctor` also says so when it has just started a fresh
+config because the old one could not be read — the endpoint and Project you had
+set are gone in that case, and the unreadable file is kept beside it rather than
+discarded.
 
 `doctor` is also the one command that contacts a host other than your own
 platform: it asks `registry.npmjs.org` whether a newer `vfac` has been published.
@@ -73,6 +81,22 @@ vfac get product-instance <productInstanceId>
 Secrets are supplied per apply and never belong in the manifest — a manifest is a
 file you commit. `vfac plan` lists the ones an apply will still need.
 
+### `metadata.key` is the name you choose
+
+`manifest init` writes one into the file, derived from `--name`. It is what the
+platform recognises the resource by on every later apply, and it is the one
+identifier in a manifest that is yours: a resource key is 3–63 characters of
+lowercase letters, digits and hyphens, starting with a letter and ending with a
+letter or digit.
+
+**A key is claimed for good, and a delete does not release it.** The record of a
+deleted resource keeps its key, so a manifest that named it can never apply again
+— `vfac plan` answers `GONE` — and a replacement needs a different key. That is
+worth knowing before the delete rather than after it, because after it there is
+nothing to undo; `vfac lifecycle delete` says the same thing at the prompt. If
+what you want is to stop the service and keep the option of bringing it back,
+`vfac lifecycle suspend` is the reversible one.
+
 ## Reading a setting from another resource
 
 A setting may take its value from an output another resource publishes, instead