@varde-flyt/vfac 0.14.1 → 0.15.2

package/README.md

@@ -26,10 +26,10 @@ vfac guide
 vfac whoami
 ```
 
-`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, how this
-terminal is signed in and what that credential reaches, in that order, and reports
-the first thing that is actually wrong. Both ways of signing in count: a Context
+`doctor` checks the endpoint, which Project this terminal has selected and which
+one this command will act in, the API, whether this client is new enough for the
+platform it is pointed at, how this terminal is signed in and what that credential
+reaches, in that order, and reports the first thing that is actually wrong. Both ways of signing in count: a Context
 Gate exchanged from `VFAC_CREDENTIAL_ID` and `VFAC_CREDENTIAL_SECRET`, or a
 sign-in from `vfac login` that is still valid. A platform declares the oldest client it supports;
 below that, `doctor` fails and says so before sending your credential anywhere.
@@ -37,7 +37,10 @@ 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
+the same as being in it. `--project` overrides the selection for one command and
+writes nothing, so `vfac doctor --project prj_…` reports the Project it would act
+in, says the flag is where that came from, and still names what your context has
+selected. `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.
@@ -68,7 +71,7 @@ vfac context set --project <projectId>
 
 ```sh
 vfac product list
-vfac product show <productId>
+vfac product show <productId>          # every setting, and when you must answer it
 vfac manifest init --product <productId> --name "My resource" > resource.yaml
 ```
 
@@ -95,11 +98,28 @@ file pins the release the catalog currently offers. **Plan the run that sets one
 apply will carry**: `plan` takes the flag exactly as `apply` does, and without it
 the plan describes a different request.
 
+`--secret` names a root setting by its name, and a setting inside a group by its
+path — `--secret /upstreamAuth/clientSecret=env:UPSTREAM_CLIENT_SECRET` for the
+`clientSecret` under `upstreamAuth`. `vfac product show` prints that form beside
+EVERY credential the Product declares, with a line saying whether it is required
+of everyone, required when another setting holds a particular value, or required
+because another setting was answered — `dependentRequired` is directional, and
+the line says which way it runs; `vfac manifest init` names the ones required
+outright. A path never names an item of a list: no secret is declared there.
+
 `requiredSecrets` in a plan is what the Product requires for the configuration in
 your document — not a list of what the platform is missing. It names a credential
 whether or not this resource already holds one, so it is not a shopping list to
 act on. `secretsToWrite` is the field that says what this apply would write.
 
+A credential the Product requires for your document — outright, or because of
+what a setting is set to — that the run neither supplies nor the resource already
+holds is refused by `plan` and `apply` alike, before anything is written: the
+error names every one, by the path `--secret` takes, and the command exits 1. So
+is a credential the run DOES supply whose value the Product's own declaration
+refuses: the error names the setting and the bound it missed, never the value.
+`vfac validate` carries no secrets and refuses none; it lists them.
+
 ### `metadata.key` is the name you choose
 
 `manifest init` writes one into the file, derived from `--name`. It is what the
@@ -217,9 +237,11 @@ it.
 ## For an agent or a pipeline
 
 Every command takes `--output json`, and it is the same data rather than a
-prettier subset — the human format of `vfac product show` prints a readable
-selection on purpose and says so at the foot of its output, and the JSON carries
-the whole Product contract.
+prettier subset. The human format of `vfac product show` lists every setting the
+Product declares and says when each must be answered; what it leaves to the JSON
+form is the prose and the value constraints — descriptions, patterns, bounds —
+and it says so at the foot of its output. The JSON carries the whole Product
+contract.
 
 ```sh
 vfac product show <productId> --output json