feat(cli): place environments and tasksets in a Project

[solvemproblr]

High-level idea

Add first-class Project selection to the HUD CLI while keeping the normal deploy and task-sync workflow zero-configuration.

Issue

The CLI could only create resources in the team default Project. Teams using multiple Projects could not select a destination, persist a directory choice, or set a machine-wide default. The Projects beta is also feature-gated, so unflagged users need a clear error instead of a generic platform or permission failure.

Solution

• Add hud project, hud project list, hud project create <name>, and hud project use <name-or-id>.
• Add a one-command --project <name-or-id> override to hud deploy and hud sync tasks.
• Persist directory selection as projectId in .hud/config.json and support HUD_DEFAULT_PROJECT as the machine-wide fallback.
• Resolve selection in this order: command flag, directory config, global default, then team default.
• Keep command and global overrides non-persistent.
• Recognize the Projects API feature gate and show an actionable error for unflagged teams. Bare hud project probes the gated endpoint; ordinary deploys and syncs without Project-specific configuration continue using the team default.
• Document the Project concept separately from the detailed CLI reference.

The stable backend error code is added by hud-monorepo#1714. This PR also recognizes the currently deployed error detail during rollout.

Impact

Existing zero-config workflows are unchanged. Selecting a Project controls only where a new environment or taskset is created; it never moves an existing resource.

Test plan

• Staging: Project list, create, create with --no-use, use by name, use by UUID, and bare report
• Staging: deploy through directory config, --project, and HUD_DEFAULT_PROJECT
• Staging: task sync through directory config, --project, and HUD_DEFAULT_PROJECT
• Staging: verify server-side project_id for all created environments and tasksets
• Verify command/global overrides do not change the saved directory Project
• Verify group-level and subcommand-level -C parsing
• Verify unflagged API responses produce the clear CLI error
• Focused CLI tests, repository Ruff checks, and GitHub Python 3.11/3.12/type/template checks

---

Note

Medium Risk
Changes where new platform resources are created and adds permission/feature-gate handling, but existing zero-config deploy/sync behavior is preserved when no Project is selected.

Overview
Adds HUD Projects as the workspace boundary for deploys and task syncs, while keeping the default team Project path unchanged when nothing is configured.

New hud project commands list, create, pin (use), and report the resolved destination; pinning writes projectId to .hud/config.json. hud deploy and hud sync tasks gain --project, and placement follows flag → directory config → HUD_DEFAULT_PROJECT → team default. Overrides do not persist; deploy/upload only send project_id when a non-default Project is selected. Read-only Projects block writes but still allow no-op syncs; the CLI recognizes the Projects beta feature gate with a clear error.

Docs add a Projects reference page and update README, CLI, environment, and tasks guides. Tests cover precedence, deploy payloads, sync upload behavior, and project command parsing.

^{Reviewed by Cursor Bugbot for commit 6637b63. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0a156df. Configure here.}