Deploy Hub configurations from the CLI (#2955)

* feat(cli): add Hub configuration deploy

Deploy configuration bytes directly to an explicitly targeted Hub project using only caller-supplied origin and organization API key authority.

* refactor(cli): name Hub deploy contracts

* docs(hub): complete deploy CLI guidance

* docs(hub): link deployed API references

* feat(cli): bundle referenced Hub partials

Send exact referenced prompt-partial content alongside YAML so Hub can resolve local includes while inline-only configurations keep the existing request shape.

* fix(cli): match Hub YAML size semantics

Apply the finalized Hub request limit to decoded YAML length and cover multibyte configuration payloads without changing the wire body.

public-docs/hub/configuration/hub-yml.md

@@ -8,9 +8,11 @@ category: Hub
 
 # `hub.yml` reference
 
-A configuration has `environments` and `triggers`. Execution fields belong to each trigger's `steps`.
+A configuration has `environments` and `triggers`. It may also include top-level `project` deployment metadata for `paseo hub deploy`. Execution fields belong to each trigger's `steps`.
 
 ```yaml
+project: my-project
+
 environments:
   - name: development
     kind: daemon
@@ -35,6 +37,8 @@ triggers:
           - text: ${{ paseo.prompt }}
 ```
 
+`project` is an optional bare project slug. The deploy CLI uses it to choose the target project when `-p, --project` is absent. The flag takes precedence over this metadata without rewriting the YAML. `project` is not available to triggers, expressions, or agents.
+
 ## Environments
 
 | Field      | Required    | Notes                                                                                                     |
@@ -131,7 +135,7 @@ Hub counts an actual capability emission; ordinary assistant text does not satis
 
 ## Prompt partials
 
-`include` paths are relative to `.paseo/partials/` and are resolved at the exact GitHub configuration commit. Hub stores the resolved content and SHA-256 hash in the immutable revision. Missing files, unsafe paths, symlinks, submodules, directories, and nested includes are rejected. Manual configurations cannot use repository partials.
+`include` paths are relative to `.paseo/partials/`. For GitHub configuration, Hub reads them at the exact configuration commit and stores the resolved content and SHA-256 hash in the immutable revision. For `paseo hub deploy`, the CLI reads the referenced files from the local project root and sends them in the optional `partials` bundle; the bundle path omits the `.paseo/partials/` prefix. Missing files, unsafe paths, symlinks, submodules, directories, duplicate or unexpected bundle entries, and nested includes are rejected. Manual configurations cannot use repository partials.
 
 ## Deadlines
 

public-docs/hub/configuration/index.md

@@ -16,11 +16,36 @@ A configuration comes from exactly one source:
 
 - **GitHub source**: one repository, the file `.paseo/hub.yml`, on the repository's current default branch.
 - **Manual source**: edited in the dashboard and saved with **Save and activate**.
+- **CLI/API install**: YAML sent explicitly with an organization API key.
 
 Pick a GitHub source by choosing a repository and clicking **Use for configuration**. That syncs immediately and enables automatic deployment.
 
 The path and the branch are fixed. There is no setting for either.
 
+## Deploy from the CLI
+
+From a project checkout, add the target project slug as optional deployment metadata:
+
+```yaml
+project: my-project
+```
+
+Then deploy:
+
+```sh
+PASEO_HUB_URL=https://hub.example.com \
+PASEO_HUB_API_KEY=paseo_pk_... \
+paseo hub deploy
+```
+
+The default path is exactly `.paseo/hub.yml` relative to the current directory. The CLI does not search parent directories or alternate filenames. Use `paseo hub deploy path/to/config.yml` for another file. The bundle root remains the current directory, so partials are always read from `.paseo/partials/` under that directory. `-p, --project <slug>` overrides the file's `project` value without changing the YAML sent to Hub.
+
+For each prompt `include`, the CLI sends one `{ path, content }` entry whose path is relative to `.paseo/partials/`. It sends only files referenced by the main YAML; nested include-looking text inside a partial is not scanned. Missing, unsafe, duplicate, unreadable, non-file, or oversized inputs fail locally before the Hub request. A configuration with only inline prompt blocks sends no `partials` field.
+
+Use `--hub <origin>` or `PASEO_HUB_URL` for the Hub origin, and `--api-key <secret>` or `PASEO_HUB_API_KEY` for the organization API key. A flag takes precedence over its environment variable. The key supplies organization scope and needs `configuration:install`. `project` only selects the deployment target; workflows cannot reference it.
+
+Durable Hub login and credential persistence are not implemented. Supply the origin and API key for each deployment through flags or the current process environment.
+
 ## Sync
 
 A push to the default branch of the configuration repository triggers a sync: