Rework cloud-connect-dev recipe onto the spice cloud enrollment flow (#597)

* Fix cloud-connect-dev recipe: point the Cloud Connect doc links at the published pages

Both Cloud Connect links 404: /docs/deployment/cloud/cloud-connect and
/docs/deployment/cloud/cloud-connect/service are unreleased pages, published
under /docs/next/ until v2.2 ships. The `spice connect` CLI reference
resolves at the released path, but that page documents the superseded command
(no `spice connect service install`, no `spiced --token`), so it points at
/docs/next/ too — the flow this recipe and its validate.sh assert.

Also align the docker-compose.yml comment with the README's PG_PASSWORD, since
the README states that secret names are matched exactly.

* recipe(cloud-connect-dev): sign in with spice login

The CLI's own failure hint for an unauthenticated link reads "Run `spice
login`, then retry `spice cloud link`". A reader who gets stuck reads the
error before they re-read the recipe, so the recipe uses the same spelling.

Also say that `spice cloud status` reads from Spice Cloud and needs that
session: it reports project health from the control plane, so unlike the
purely local checks in validate.sh it does not work signed out.

* recipe(cloud-connect-dev): create the project from the CLI

`spice cloud project create <name>` with no `--kind` creates the unattached
Cloud Connect project that `spice cloud link` attaches to, so the recipe no
longer sends the reader to the portal to make one. Setup is CLI end to end:
`spice login`, `spice cloud project create`, `spice cloud link`, `spice run`.

`--kind` is the discriminator. Naming one asks for a Spice-managed project and
requires `--region`; omitting it asks for a Cloud Connect project, which has no
region to choose. `--region` and the hosted-runtime flags are refused rather
than ignored when no kind is given, so the README says so.

validate.sh asserts that distinction. `execute_project_create` resolves
placement before it connects, so both refusals are argument validation: they
answer with no account and create nothing. The exit code is asserted alongside
the message, so a future ordering change that created the project before
validating it would fail the check rather than pass silently.

`spice cloud link` still requires a terminal and a user login. Creating the
project from the CLI does not change that.

./validate.sh: 37 passed, 0 failed, TEST PASSED (was 33 passed, 0 failed).

* recipe(cloud-connect-dev): set the project secret from the CLI

`spice cloud secrets set PG_PASSWORD "$SPICE_DEMO_PG_PASSWORD"` replaces the
portal walkthrough, and `spice cloud secrets list` confirms it. Linking resolves
the project, so neither needs `--project`.

The value is a required positional argument. There is no stdin, file, or
environment form: `SecretsSetArgs.value` is a bare `String` with no clap
attribute, and the only stdin read in the module is the project-delete prompt.
So the recipe passes the shell variable, which keeps the password out of shell
history — history records the line as typed — but the expanded value is still in
the process argument list while the command runs, and the README says so and
points at the portal for a shared machine.

`spice cloud secrets get` prints the value to stdout, so the confirmation step
uses `list`, which reports names and timestamps only.

validate.sh asserts the four subcommands exist and that the README passes the
password by variable and never calls `secrets get`. Nothing sets, reads, or
deletes a real secret: these commands reach the control plane, and a validator
that mutates a cloud project when a developer happens to be logged in is worse
than the coverage it would buy.

The compose comment tracks the credential to the project rather than to the
portal, which is where it now goes.

./validate.sh: 43 passed, 0 failed, TEST PASSED (was 37 passed, 0 failed).
README URLs re-checked: 4/4 HTTP 200.

* recipe(cloud-connect-dev): run the README checks above the version gate

The checks that only read README.md need no CLI, but sat below the version
gate with the ones that do. CI installs the stable CLI, so the gate skips
everything under it and those checks never ran there — including the guard
that fails if the recipe spells the database password literally instead of
passing \$SPICE_DEMO_PG_PASSWORD. That is the one check that most needs to
run on every pull request.

Group them into a README section above the gate. The CLI sections keep only
what actually needs a CLI: the --help listings, the project-kind refusals, and
the non-interactive link refusal.

No assertion is added or removed. Locally, where the gate passes, the suite is
unchanged at 43 passed, 0 failed. On a CI image whose CLI predates the flow,
the checks that run before the gate go from 16 to 23.

---------

Co-authored-by: Claude <claude@Claudes-Mac-mini.local>
Co-authored-by: Phillip LeBlanc <879445+phillipleblanc@users.noreply.github.com>

Author: 3 people

cloud-connect-dev/README.md

@@ -2,7 +2,7 @@
 
 Works with Spice CLI v2.2 or later.
 
-Use this recipe to connect a local Spice instance to Spice Cloud. You will deploy live changes, deliver a secret, and reconnect the instance.
+Use this recipe to link a local Spice instance to Spice Cloud. You will deploy live changes, deliver a secret, and restart the instance.
 
 ## Prerequisites
 
@@ -16,34 +16,75 @@ Install the Spice CLI:
 curl https://install.spiceai.org | /bin/bash
 ```
 
-## 1. Connect the instance
+## 1. Link the instance
 
 Clone the cookbook and open this recipe:
 
 ```shell
 git clone https://github.com/spiceai/cookbook.git
 cd cookbook/cloud-connect-dev
-spice connect
 ```
 
-Log in to Spice Cloud when the command prompts you. Select an organization. Accept `cloud-connect-dev` as the project name.
+Sign in to Spice Cloud:
 
-If that name is in use, accept the suggested name.
+```shell
+spice login
+```
+
+Create the project. With no `--kind`, this creates a Cloud Connect project — one your own runtime serves, which has no region to choose:
+
+```shell
+spice cloud project create cloud-connect-dev
+```
+
+If that name is taken in your organization, pick another and use it everywhere below.
+
+`--region`, and the hosted-runtime flags such as `--replicas` and `--memory`, are refused here rather than ignored. They configure a Spice-managed project, which you ask for with `--kind set` or `--kind cluster`.
+
+Link this directory to the project:
+
+```shell
+spice cloud link <org>/cloud-connect-dev
+```
+
+`spice cloud link` enrolls this directory as an instance and attaches it to the project. It needs an interactive terminal; omit the project to choose one from a list. For an unattended machine, mint an enrollment key in the portal and start the runtime with `spiced --token <enrollment-key>` instead.
+
+```text
+✓ Linked the enrolled instance to project <org>/cloud-connect-dev
+
+Start this instance in the current directory with:
+  spice run
+
+You can now use commands without specifying --project:
+  spice cloud deploy
+  spice cloud logs
+  spice cloud secrets list
+```
+
+Linking adds `.spice/` to `.gitignore`, the directory holding the instance's mTLS private key.
+
+A project with no stored Spicepod is seeded from the local `spicepod.yaml`, so the project now defines the `data` dataset. Later local edits are not synchronized; deploy to change what the instance runs.
+
+Start the instance:
+
+```shell
+spice run
+```
 
 Leave the runtime open. Open the monitor link in the output.
 
 In a second terminal, check the connection:
 
 ```shell
 cd cookbook/cloud-connect-dev
-spice connect status
+spice cloud status
 ```
 
-## 2. Deploy a live change
+The report covers the project, its latest deployment, and the instances serving it, then closes with this directory's own state under `Local enrolled-instance state:`. It reads from Spice Cloud, so it needs the session `spice login` created.
 
-A deployment replaces the Spicepod the instance runs. In the Spice Cloud portal, open the project Spicepod and paste in the contents of this recipe's local `spicepod.yaml`, so the deployed Spicepod still defines the `data` dataset.
+## 2. Deploy a live change
 
-Add this view to the project Spicepod, below the datasets:
+A deployment replaces the Spicepod the instance runs. In the Spice Cloud portal, open the project Spicepod and add this view below the datasets:
 
 ```yaml
 views:
@@ -80,13 +121,30 @@ docker compose exec postgres \
   -c 'SELECT count(*) FROM public.orders;'
 ```
 
-In the portal, open the project's **Settings → Secrets** and add:
+Store the password as a project secret. Linking set this directory's project, so `--project` is not needed:
+
+```shell
+spice cloud secrets set PG_PASSWORD "$SPICE_DEMO_PG_PASSWORD"
+```
+
+```text
+✓ Secret 'PG_PASSWORD' set successfully
+```
+
+The value is a command argument. Passing the variable keeps the password out of your shell history, but the expanded value is visible in the process list to anyone else on the machine while the command runs. On a shared machine, set it in the portal under **Settings → Secrets** instead.
+
+Confirm the name without printing the value:
+
+```shell
+spice cloud secrets list
+```
 
-| Name          | Value                              |
-| ------------- | ---------------------------------- |
-| `PG_PASSWORD` | Value of `$SPICE_DEMO_PG_PASSWORD` |
+```text
+NAME          UPDATED
+PG_PASSWORD   2026-01-06T16:22:00Z
+```
 
-Secret names are matched exactly. A Spicepod that references a name the project does not define is rejected when you deploy it, and the portal names the closest match it holds.
+Secret names are matched exactly. A Spicepod that references a name the project does not define is rejected when you deploy it, and Spice Cloud names the closest match it holds.
 
 Add this dataset to the project Spicepod in the portal — not to the local `spicepod.yaml`:
 
@@ -129,10 +187,11 @@ The query returns:
 Confirm the delivery:
 
 ```shell
-spice connect status
+spice cloud status
 ```
 
 ```text
+Local enrolled-instance state:
   secrets:     1 delivered: PG_PASSWORD
 ```
 
@@ -172,11 +231,11 @@ In the first terminal, press `Ctrl-C`. Start the instance again from the same di
 spice run
 ```
 
-You do not need to run `spice connect` again. The existing identity reconnects the instance.
+You do not need to run `spice cloud link` again. The existing identity reconnects the instance.
 
 The instance now serves the deployed `runtime` settings, and the deployment reports nothing pending.
 
-> **Warning:** Spice Cloud invalidates the identity if the instance stays offline for more than 30 days. Enroll the instance again to reconnect it.
+> **Warning:** Spice Cloud invalidates the identity if the instance stays offline for more than 30 days. Link the directory again to reconnect it.
 
 ## 6. Validate the recipe
 
@@ -190,10 +249,16 @@ These checks do not connect to Spice Cloud or use credentials.
 
 ## 7. Clean up
 
-Stop the runtime. Remove the Cloud Connect instance and project:
+Stop the runtime first — `spice cloud unlink` refuses while the instance is running. Then detach this directory:
+
+```shell
+spice cloud unlink
+```
+
+Unlinking releases the enrolled instance, removes its local identity, and uninstalls its service if one is installed. The project keeps its Spicepod, secrets, and deployment history. Delete it when you are finished with it:
 
 ```shell
-spice connect remove
+spice cloud project delete <org>/cloud-connect-dev
 ```
 
 Stop PostgreSQL and delete its volume:
@@ -205,11 +270,18 @@ unset SPICE_DEMO_PG_PASSWORD
 
 ## Run as a service
 
-To keep the instance running after you close the terminal, see [Cloud Connect as a service](https://spiceai.org/docs/deployment/cloud/cloud-connect/service).
+To keep the instance running after you close the terminal, install a service for this directory:
+
+```shell
+spice cloud service install
+```
+
+`spice cloud service` also has `start`, `stop`, `restart`, and `uninstall`. Uninstalling keeps the Cloud identity, so `spice run` still reconnects the instance.
 
 Windows does not support the managed service.
 
+See [Cloud Connect as a service](https://spiceai.org/docs/next/deployment/cloud/cloud-connect/service).
+
 ## Learn more
 
-- [Cloud Connect](https://spiceai.org/docs/deployment/cloud/cloud-connect)
-- [`spice connect` reference](https://spiceai.org/docs/cli/reference/connect)
+- [Cloud Connect](https://spiceai.org/docs/next/deployment/cloud/cloud-connect)

cloud-connect-dev/docker-compose.yml

@@ -1,9 +1,9 @@
 # A local PostgreSQL for the secrets step of the README.
 #
 # The password is never written here. It is read from the environment, and the
-# same value is what you set as the `pg_password` secret in the Spice Cloud
-# portal — so the one credential this recipe uses exists in your shell and in
-# the portal, and in no file this repository tracks.
+# same value is what you set as the `PG_PASSWORD` secret on the Spice Cloud
+# project — so the one credential this recipe uses exists in your shell and in
+# the project, and in no file this repository tracks.
 services:
   postgres:
     image: postgres:16-alpine