Require project IDs for CLI request scoping (#218)

## Summary

- document the global `--project` flag as accepting project IDs only
- use the Go SDK's typed `option.WithProjectID` client option
- align `KERNEL_PROJECT` examples with the merged API contract

## Why

`X-Kernel-Project-Id` is an ID selector on the merged API. Advertising
project names here can scope a command incorrectly or produce a
confusing not-found response. The typed SDK option also keeps client
configuration aligned with generated SDK behavior.

## Implementation

The request still carries the same `X-Kernel-Project-Id` header. This
changes the public CLI guidance and replaces the manually named header
option with the SDK's first-class project option.

## Verification

- `go test -short -timeout=2m ./...`
- `go vet ./...`
- `gofmt -l cmd`
- `git diff --check`
- crap4go: changed `resolveProjectSelection` CRAP 2.0; root `init` CRAP
5.8

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Small client-option refactor with equivalent header behavior; main
user-facing change is clearer docs that names are not valid for global
scoping.
> 
> **Overview**
> **Global project scoping** (`--project` / `KERNEL_PROJECT`) is now
documented and intended for **project IDs only**, not names, matching
the API’s `X-Kernel-Project-Id` contract.
> 
> Client setup switches from a manual `X-Kernel-Project-Id` header
option to the Go SDK’s **`option.WithProjectID`** (same header, typed
configuration). README and flag help text are updated accordingly,
including clarification that **`api-keys create --project-id`** is
separate from the global scoping flag. Tests use ID-style example
values.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
8f4d57d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: IlyaasK

README.md

@@ -103,6 +103,7 @@ Create an API key from the [Kernel dashboard](https://dashboard.onkernel.com).
 - `--version`, `-v` - Print the CLI version
 - `--no-color` - Disable color output
 - `--log-level <level>` - Set log level (trace, debug, info, warn, error, fatal, print)
+- `--project <project-id>` - Scope requests to a project ID (or set `KERNEL_PROJECT` to a project ID)
 
 ## JSON Output
 
@@ -622,7 +623,7 @@ Automated authentication for web services. The `run` command orchestrates the fu
 - `kernel api-keys create` - Create a new API key
   - `--name <name>` - API key name (required)
   - `--days-to-expire <days>` - Number of days until expiry (1-3650); omit for never
-  - `--project-id <project_id>` - Create a project-scoped API key for this project ID; omit for org-wide. This is different from global `--project`, which only scopes the CLI request.
+  - `--project-id <project_id>` - Create a project-scoped API key for this project ID; omit for org-wide. This is different from global `--project`, which scopes the CLI request to a project ID.
   - `--output json`, `-o json` - Output raw JSON object, including the one-time plaintext key
 
 - `kernel api-keys list` - List API keys

cmd/root.go

@@ -116,7 +116,7 @@ func init() {
 	rootCmd.PersistentFlags().BoolP("version", "v", false, "Print the CLI version")
 	rootCmd.PersistentFlags().BoolP("no-color", "", false, "Disable color output")
 	rootCmd.PersistentFlags().String("log-level", "warn", "Set the log level (trace, debug, info, warn, error, fatal, print)")
-	rootCmd.PersistentFlags().String("project", "", "Project ID or name to scope all requests to (or set KERNEL_PROJECT env var)")
+	rootCmd.PersistentFlags().String("project", "", "Project ID to scope all requests to (or set KERNEL_PROJECT to a project ID)")
 	rootCmd.SilenceUsage = true
 	rootCmd.SilenceErrors = true
 	cobra.OnInitialize(initConfig)
@@ -143,7 +143,7 @@ func init() {
 		projectVal = resolveProjectSelection(projectVal)
 
 		if projectVal != "" {
-			clientOpts = append(clientOpts, option.WithHeader("X-Kernel-Project-Id", projectVal))
+			clientOpts = append(clientOpts, option.WithProjectID(projectVal))
 		}
 
 		client, err := auth.GetAuthenticatedClient(clientOpts...)

cmd/root_test.go

@@ -80,13 +80,13 @@ func TestIsAuthExempt(t *testing.T) {
 
 func TestResolveProjectSelection(t *testing.T) {
 	t.Run("flag value wins over env var", func(t *testing.T) {
-		t.Setenv("KERNEL_PROJECT", "env-project")
-		assert.Equal(t, "flag-project", resolveProjectSelection("flag-project"))
+		t.Setenv("KERNEL_PROJECT", "env-project-id")
+		assert.Equal(t, "flag-project-id", resolveProjectSelection("flag-project-id"))
 	})
 
 	t.Run("env var used when no flag", func(t *testing.T) {
-		t.Setenv("KERNEL_PROJECT", "env-project")
-		assert.Equal(t, "env-project", resolveProjectSelection(""))
+		t.Setenv("KERNEL_PROJECT", "env-project-id")
+		assert.Equal(t, "env-project-id", resolveProjectSelection(""))
 	})
 
 	t.Run("empty when no flag or env var", func(t *testing.T) {