SC-74483: Correct the local variables and secrets model (#100)

* Quix-74483: Correct the local variables and secrets model in the docs

The pages described a variables model the CLI never implemented. Three
of them stated that 'inputType: Secret' with 'secretKey' is normalized
into 'ProjectVariable' with 'variableKey' on save; the CLI writes and
keeps whichever of the two you declare, and because they read their
local values from different files ('.secrets' versus
'.quix.yaml.variables') the claim sent readers to the wrong file. Both
mechanisms are now documented side by side, everywhere they appear.

Project variables and variable groups were undocumented as a local
concern: '.quix.yaml.variables' is described in all three of its roles,
including that 'quix init' seeds the keys and that a group's secret
member resolves there rather than from '.secrets'. The '.env'
walkthroughs gain the Project Variables and Groups sections, secret
values are shown blank with an explanation of how they still reach the
application, and '.gitignore' lists its sixth entry.

'quix cloud variables' had no page at all while the CLI's own help
linked to one, so the reference section now exists. Stale console
output is corrected against real runs: the compose service is
'kafka_broker', deployment names lowercase with underscores in service
and container names, and the broker console is served on port 8080.

Every statement was verified by running the CLI. The generated pages
come from 'quix docs'; the site builds with no new warnings.

* Quix-74483: Document the options that change what a command does

'pipeline update' has options that decide which applications it touches
and what happens to their variables, and none were described: notably
'--reset', which empties the deployments and topics sections before
rebuilding them, discarding hand-tuned replica counts, resource limits,
versions and topic settings. It now carries a warning saying so.
'pipeline up' gains its '--keep-variables' and
'--preserve-dockerignore' behaviour.

'apps variables import' contradicted itself about whether existing
values are replaced. They always are: the command passes
replaceAppVariables unconditionally, and the only entries it leaves
alone are secrets and secret group members, whose defaultValue holds a
key rather than a value.

The commands summary gains the project variables group and drops a
duplicated topics row; the two context-environment pages agree on one
spelling of the command. Nav order for the new pages now matches what
'quix docs' emits, so regenerating is a no-op.

* Quix-74483: Replace hand-written generated pages with generator output

The five 'cloud variables' reference pages were transcribed from the
CLI's --help text, which renders differently from the command model the
generator reads: it omits an Aliases line when the only alias matches
the command name, and it showed the environment argument as required
where the model has it optional. Regenerating with 'quix docs' corrects
both. The two 'up' pages pick up the compose.local.yaml naming fix from
the CLI.

'cloud/users/tokens/create.gen.md' is deliberately left alone: its
documented default is today plus a year, so regenerating it only
replaces one stale date with another.

* Quix-74483: Repoint the local development links that 404

Every in-repo link on the local development pages pointed at a sibling
of the page rather than of the docs root, so all thirteen returned 404
in the built site - the Quickstart link and every CLI reference link
the tutorials lean on, plus one carrying a doubled slash. Verified by
fetching each from a local build: they now resolve.

The remaining 'quix-cloud/...' links are untouched. They are meant to
resolve in the assembled documentation site, where quix-cli sits
alongside quix-cloud, and cannot resolve in this repository alone.

* Quix-74483: Correct the last inconsistent cross-section links

Two pages one level below the docs root reached sibling sections with a
single '../', the prefix a root-level page uses. Every other page at
that depth uses '../../', so both were one level short and would land
outside the section in the assembled site. The pipeline view image on
the template page pointed above the docs root as well, so it never
rendered; the file it wants sits in 'docs/images'.

Left alone: 'cli-template.md' links to 'cli-reference.md', which does
not exist in any form here, and the page is not in the navigation.

* Quix-74483: Remove the orphaned template tutorial

'cli-template.md' arrived as a copy of a page from the main
documentation site and was dropped from the navigation in 6d1a752
(August 2024) when its sibling was relocated to How-To instead. Nothing
has linked to it since, so it has been unreachable for two years, and
its walkthrough still uses the command names from before the CLI was
restructured. Its cross-section links never resolved here either -
'cli-reference.md' has never existed in this repository in any form.

The pipeline screenshot goes with it, as that page was its only user.
Every link warning the build now reports is a deliberate reference to a
sibling documentation section, resolved when the site is assembled.

* Quix-74483: Connect running locally to the files the values live in

The local development story is told through three files, but the pages
that walk a reader through running an application stopped at '.env'.
Neither mentioned '.secrets' or '.quix.yaml.variables', so the two files
a value actually has to be typed into were invisible to anyone following
that path, and the blank line a secret leaves behind looked like
something to fix.

'quix run' now documents where each variable comes from, including the
secrets it resolves from those files as it starts the process and the
deployment that decides which key each one is read by - previously the
page described the '.env' file alone. The local development walkthrough
gains the file model itself: which file holds what, keyed by what, and
why the committed YAML carries only a reference.

* Quix-74483: Correct what a fact-check found against the CLI

An adversarial pass over these pages checked 41 claims against the
merged CLI and found eight that did not hold. The one that mattered
promised that typing a value beside a blank secret line gets it stored:
only the Secrets section does that, so a reader following it for a
secret project variable or a group member was being sent to a file
nothing reads. Those two now point at '.quix.yaml.variables' and say
plainly that a value typed into '.env' is used by the run that reads it
but never promoted out of it.

The rest were smaller and equally checkable: the import page omitted
project variables from the entries it never overwrites and never
mentioned the '--reset' option its own generated block documents; a
secret was described as masked in the UI where the API in fact withholds
it, wording that collided with how HiddenText is described a page away;
'cloud variables' stores the secret flag per value but reports it per
key, so one secret environment marks the whole row; two quoted console
blocks on the update page had drifted from what the command prints; and
'--verbose' shows the variables read from '.env' rather than the
environment the process ends up with.

Also documents the behaviour of the accompanying CLI change: a refresh
keeps a line it cannot resolve rather than blanking it, which leaves
plaintext behind when a variable becomes secret until the file is
rebuilt.

Author: emanuel-quix

docs/How-To/cli-github-actions.md

@@ -18,7 +18,7 @@ But sometimes, a developer may make code changes to a branch directly, without u
 The basic procedure to use the Quix CLI in a GitHub Action is:
 
 1. Install the Quix CLI using the [Curl command](https://github.com/quixio/quix-cli?tab=readme-ov-file#installation-of-quix-cli){target=_blank}.
-2. Authenticate the CLI with Quix Cloud using the command `quix login <pat>`, where `<pat>` is the [personal access token](../develop/authentication/personal-access-token.md) for the environment. 
+2. Authenticate the CLI with Quix Cloud using the command `quix login <pat>`, where `<pat>` is the [personal access token](../../develop/authentication/personal-access-token.md) for the environment. 
 3. Run your CLI command or commands.
 
 In this case you'll run the command to synchronize the repository with Quix using the command `quix cloud env sync <workspace-id>`. You can obtain the Workspace ID from your environment settings.

docs/cli-commands-summary.md

@@ -29,7 +29,7 @@ This quick reference guide lists common use cases for the Quix CLI with the corr
 | Use Case                                                                       | Command              |
 | ------------------------------------------------------------------------------ | -------------------- |
 | [Create a new application](./cli-reference/apps/create.md)                     | `quix app add`       |
-| [Edit the variables of an application](./cli-reference/apps/edit.md)           | `quix app edit`      |
+| [Edit the application values](./cli-reference/apps/edit.md)                    | `quix app edit`      |
 | [List applications in the project](./cli-reference/apps/list.md)               | `quix app list`      |
 | [Add a variable to an application](./cli-reference/apps/variables/create.md)   | `quix app vars add`  |
 | [Edit the variables of an application](./cli-reference/apps/variables/edit.md) | `quix app vars edit` |
@@ -54,16 +54,15 @@ This quick reference guide lists common use cases for the Quix CLI with the corr
 | ---------------------------------------------------------------------------------------------- | -------------------------- |
 | [Start local pipeline broker](./cli-reference/broker/up.md)                                    | `quix broker up`           |
 | [Stop local pipeline broker](./cli-reference/broker/down.md)                                   | `quix broker down`         |
-| [List all the topics from your pipeline broker](./cli-reference/broker/topics/list.md)         | `quix broker topic list`   |
-| [Read the content of a topic from your pipeline broker](./cli-reference/broker/topics/read.md) | `quix broker topic read`   |
+| [List all the topics from your pipeline broker](./cli-reference/broker/topics/list.md)         | `quix broker topics list`  |
 | [Read messages from a topic in your pipeline](./cli-reference/broker/topics/read.md)           | `quix broker topics read`  |
 | [Write messages to a topic in your pipeline](./cli-reference/broker/topics/write.md)           | `quix broker topics write` |
 
 ## SDK Broker Configuration
 
 | Use Case                                                                             | Command                                         |
 | ------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| [Set SDK broker to custom local address](./cli-reference/sdk/broker/set.md)          | `quix sdk broker set <broker-address> --enable` |
+| [Set SDK broker to custom local address](./cli-reference/sdk/broker/set.md)          | `quix sdk broker set <address> --enable`        |
 | [Set SDK broker to Quix Cloud](./cli-reference/sdk/broker/cloud.md)                  | `quix sdk broker cloud`                         |
 | [Set SDK broker to default local configuration](./cli-reference/sdk/broker/local.md) | `quix sdk broker local`                         |
 
@@ -76,6 +75,16 @@ This quick reference guide lists common use cases for the Quix CLI with the corr
 | [Run and stop deployed version of the application](./cli-reference/run.md)      | `quix run --stop`      |
 | [Run and intercept deployed version of the application](./cli-reference/run.md) | `quix run --intercept` |
 
+## Cloud Project Variables
+
+| Use Case                                                                                | Command                                           |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| [List the project variables of an environment](./cli-reference/cloud/variables/list.md) | `quix cloud variables list <workspace-id>`        |
+| [Get a single project variable](./cli-reference/cloud/variables/get.md)                 | `quix cloud variables get <key> <workspace-id>`   |
+| [Create or update a project variable](./cli-reference/cloud/variables/set.md)           | `quix cloud variables set <key> <value>`          |
+| [Store a project variable encrypted at rest](./cli-reference/cloud/variables/set.md)    | `quix cloud variables set <key> <value> --secret` |
+| [Delete a project variable](./cli-reference/cloud/variables/delete.md)                  | `quix cloud variables delete <key>`               |
+
 ## Common Options
 
 Quix CLI offers several common options that can be used across all commands:

docs/cli-reference/apps/variables/create.gen.md

@@ -18,6 +18,6 @@ quix apps variables create [options]
 - `--name <name>`: Variable name
 - `--default-value <default-value>`: Default value
 - `--description <description>`: Variable description
-- `--type <FreeText|HiddenText|InputTopic|OutputTopic|Secret|Topic>`: Variable input type
+- `--type <FreeText|HiddenText|InputTopic|Options|OutputTopic|ProjectVariable|Secret|Topic|VariableGroup>`: Variable input type
 - `--required`: If this flag is set, the variable will be required
 

docs/cli-reference/apps/variables/create.md

@@ -4,7 +4,9 @@
 
 The `quix apps vars create` command allows you to create new variables for your application through an interactive process. This command updates the `app.yaml` file with the new variables, ensuring your application configuration is current.
 
-When you run the command, you are prompted to select an application (if not already in an application directory), choose the variable type (Input Topic, Output Topic, Free Text, Secret), and provide details such as the variable name, description, default value, and whether it is required. The new variable is then added to the `app.yaml` file.
+When you run the command, you are prompted to select an application (if not already in an application directory), choose the variable type (Input Topic, Output Topic, Free Text, Secret, Project Variable), and provide details such as the variable name, description, default value, and whether it is required. The new variable is then added to the `app.yaml` file.
+
+A Project Variable references a key in the project variables store instead of carrying its own value — see [cloud variables](../../cloud/variables/index.md). Variable groups are not offered by the picker; they are declared directly in `app.yaml` or come from the cloud.
 
 !!! tip
     You can create required variables without providing a value, but this may slow down the deployment process if you rely on the default application values. Providing values for required variables helps ensure a smoother and faster deployment.
@@ -37,6 +39,7 @@ Once you select the application, a prompt for selecting the variable type appear
   Output Topic
 > Free Text
   Secret
+  Project Variable
 ```
 
 Continue selecting until all the values are provided:

docs/cli-reference/apps/variables/edit.gen.md

@@ -18,6 +18,6 @@ quix apps variables edit [options]
 - `--name <name>`: Variable name
 - `--default-value <default-value>`: Default value
 - `--description <description>`: Variable description
-- `--type <FreeText|HiddenText|InputTopic|OutputTopic|Secret|Topic>`: Variable input type
+- `--type <FreeText|HiddenText|InputTopic|Options|OutputTopic|ProjectVariable|Secret|Topic|VariableGroup>`: Variable input type
 - `--required`: If this flag is set, the variable will be required
 

docs/cli-reference/apps/variables/edit.md

@@ -4,7 +4,7 @@
 
 The `quix apps vars edit` command allows you to edit existing variables for your application through an interactive process. This command updates the `app.yaml` file with the modified variable values, ensuring your application configuration remains current.
 
-When you run the command, you are prompted to select an application (if not already in an application directory), choose the variable you want to edit, and modify its details such as the variable type (Input Topic, Output Topic, Free Text, Secret), description, default value, and whether it is required. The updated variable is then saved to the `app.yaml` file.
+When you run the command, you are prompted to select an application (if not already in an application directory), choose the variable you want to edit, and modify its details such as the variable type (Input Topic, Output Topic, Free Text, Secret, Project Variable), description, default value, and whether it is required. The updated variable is then saved to the `app.yaml` file.
 
 !!! tip
     Editing variables promptly ensures that your application configuration is always accurate and up-to-date, preventing potential issues during deployment.
@@ -47,6 +47,7 @@ Once you select the application, a prompt for selecting the variable type appear
   Input Topic
   Free Text
   Secret
+  Project Variable
 ```
 
 Continue selecting until all the values are provided:

docs/cli-reference/apps/variables/import.md

@@ -4,7 +4,7 @@
 
 The `quix applications variables import` command updates the `app.yaml` file with variables from the `.env` file. This process ensures that the environment-specific configurations in the `.env` file are accurately reflected in the `app.yaml` file, which is used by your Quix applications.
 
-- **Existing Variables**: If a variable from the `.env` file matches an existing variable in the `app.yaml` file, its value will be updated only if the `replaceAppVariables` flag is set to true.
+- **Existing Variables**: If a variable from the `.env` file matches an existing variable in the `app.yaml` file, its `defaultValue` is replaced by the value from the `.env` file. This command always replaces — there is no option to import new variables while leaving existing ones alone. Values under the `### Secrets ###` and `### Project Variables ###` sections, and secret members of a variable group, are the exception: they are never overwritten, because their `defaultValue` holds a key that points at the value rather than the value itself. Every project variable is protected this way, secret or not.
 - **New Variables**: If a variable from the `.env` file does not exist in the `app.yaml` file, it will be added. The type of the new variable is determined based on its name:
   - Variables containing "output" are classified as `OutputTopic`.
   - Variables containing "input" or "topic" are classified as `InputTopic`.
@@ -40,4 +40,4 @@ This command will start an interactive process. If your current directory is not
   ✗ Cancel
 ```
 
-After selecting the application, the variables from the `.env` file will be imported into the `app.yaml` file. Existing variables in the `app.yaml` file will be updated with values from the `.env` file, while variables not defined in the `.env` file will remain untouched.
+After selecting the application, the variables from the `.env` file will be imported into the `app.yaml` file. Existing variables in the `app.yaml` file will be updated with values from the `.env` file, while variables not defined in the `.env` file will remain untouched — unless you pass `--reset`, which empties `app.yaml` of variables first, so anything absent from `.env` is gone.

docs/cli-reference/apps/variables/list.md

@@ -4,7 +4,9 @@
 
 The `quix apps vars list` command lists all variables for a selected application. This command provides an overview of the current configuration variables in the `app.yaml` file.
 
-When you run the command, you are prompted to select an application (if not already in an application directory). After selecting the application, the command retrieves and displays a table of all variables, including their names, default values, descriptions, types (Input Topic, Output Topic, Free Text, Secret), and whether they are required.
+When you run the command, you are prompted to select an application (if not already in an application directory). After selecting the application, the command retrieves and displays a table of all variables, including their names, default values, descriptions, the type exactly as written in `app.yaml` — `ProjectVariable` and `VariableGroup` included — and whether they are required.
+
+For a `Secret` or a `ProjectVariable` the default value column holds the key the value is looked up under, not the value itself.
 
 !!! tip
     Regularly listing your application variables helps you keep track of your configuration and ensure everything is correctly set up.
@@ -32,8 +34,9 @@ A table containing all your local application variables is printed:
 ```
 ✓ Found application 'Event Detection Transformation'
 
-  Name   | Default value | Description                                      | Type        | Is required?
- --------|---------------|--------------------------------------------------|-------------|--------------
-  input  | f1-data       | This is the input topic for f1 data              | InputTopic  | ✓
-  output | hard-braking  | This is the output topic for hard braking events | OutputTopic | ✓
+  Name    | Default value  | Description                                      | Type            | Is required?
+ ---------|----------------|--------------------------------------------------|-----------------|--------------
+  input   | f1-data        | This is the input topic for f1 data              | InputTopic      | ✓
+  output  | hard-braking   | This is the output topic for hard braking events | OutputTopic     | ✓
+  db_host | shared.db.host | Database hostname for this environment           | ProjectVariable | ✓
 ```

docs/cli-reference/broker/down.md

@@ -31,14 +31,14 @@ Executing 'docker compose down'
 Once the command is executed, Docker Compose will stop and remove the containers:
 
 ```text
-Container githubrepo-kafka-broker-1  Stopping
+Container githubrepo-kafka_broker-1  Stopping
 Container githubrepo-console-1  Stopping
 Container githubrepo-console-1  Stopped
 Container githubrepo-console-1  Removing
 Container githubrepo-console-1  Removed
-Container githubrepo-kafka-broker-1  Stopped
-Container githubrepo-kafka-broker-1  Removing
-Container githubrepo-kafka-broker-1  Removed
+Container githubrepo-kafka_broker-1  Stopped
+Container githubrepo-kafka_broker-1  Removing
+Container githubrepo-kafka_broker-1  Removed
 Network githubrepo_default  Removing
 Network githubrepo_default  Removed
 ```

docs/cli-reference/broker/up.gen.md

@@ -15,6 +15,6 @@ quix broker up [options]
 **Options:**
 
 - `--directory <directory>`: If specified, it will use that directory instead of the current one
-- `--dry-run`: Generate 'compose.yaml' without running it
+- `--dry-run`: Generate 'compose.local.yaml' without running it
 - `-t, --create-topics`: Create topics specified in the quix.yaml