@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/README.md

@@ -1,357 +1,404 @@
-# SitecoreAI Deploy & Sync CLI
-
-TypeScript CLI modeled after the Sitecore DotNet SDK and aligned with the serialization commands in `Sitecore.DevEx`.
-This implementation runs natively (no dependency on the official `sitecore` CLI).
-It also includes a first-class SitecoreAI Deploy API client.
-
-CLI command: `scai` (alias: `sitecoreai-cli`)
-
-Examples below use the installed CLI command `scai` (alias: `sitecoreai-cli`).
-For local development without installation, replace `scai` with `npm run dev --`.
+# scai — SitecoreAI Developer Toolkit
+
+A native TypeScript CLI **and** typed SDK for SitecoreAI — no .NET
+dependency, built for humans and agents alike (`--non-interactive`,
+`--json`, stable exit codes, OS-keychain credential storage).
+
+scai is organized into product-area command groups. The eleven
+top-level groups:
+
+- **`setup`** — configure environments and authenticate (`init`,
+  `login`, `client`, `logout`, `status`).
+- **`policy`** — workspace guardrails: the deny-by-default env
+  allowlist and write-elevation policy.
+- **`provision`** — provision environments and content-as-code. Nests
+  the **Deploy API** (organizations, projects, environments,
+  deployments, source control, editing hosts, logs), Content
+  **Serialization** (pull / push / diff / validate / watch SCS YAML
+  against the Authoring + Management GraphQL APIs), and **Recipes** —
+  declarative template + rendering definitions authored as TypeScript
+  and pushed via the Authoring GraphQL API, with deterministic GUIDs,
+  idempotent re-push, and LIFO rollback.
+- **`content`** — Experience Edge **publishing** behind a tiered
+  consent model, content-version state, and item workflow.
+- **`hygiene`** — read-only content **audits** and gated **cleanup**.
+- **`ops`** — Sitecore Content Operations. Nests **briefs** and
+  **campaigns**.
+- **`brand`** — Sitecore **Brand Management** and **Brand Review**.
+- **`agents`** — SitecoreAI agent authoring and runs.
+- **`sync`** — composed recipe + serialization sync workflows.
+- **`mcp`** — a built-in **Model Context Protocol** server exposing all
+  of the above to agents as workflow-shaped tools.
+- **`cli`** — CLI tooling: config, diagnostics, history, REPL,
+  telemetry.
+
+**Taxonomy.** Some surfaces are nested under a parent group
+(`provision` holds deploy / serialization / recipe; `ops` holds brief /
+campaign) while others — `brand`, `agents`, `sync` — sit at the top
+level. This is intentional and **not** being renamed for 0.1.0: the
+command paths are part of the agent contract documented in
+[AGENTS.md](./AGENTS.md), and external MCP-client configs depend on
+`scai mcp serve`, so the paths are stable.
+
+Conceptually modeled after the dotnet `Sitecore.DevEx` CLI but runs
+natively. CLI command: `scai` (alias: `sitecoreai-cli`).
+
+## What `scai` adds beyond `Sitecore.DevEx`
+
+`scai` covers the dotnet CLI's Serialization and XM Cloud surfaces, and
+adds capabilities that have no dotnet counterpart:
+
+- **Recipes** — declarative TypeScript template + rendering definitions
+  pushed via the Authoring GraphQL API, with deterministic GUIDs,
+  idempotent re-push, and LIFO rollback. See
+  [docs/recipes.md](./docs/recipes.md).
+- **Deploy API extras** — `deploy env get-edge-token`,
+  `get-editing-secret`, `regenerate-context`, `link-repository` /
+  `unlink-repository` (on projects and environments), project
+  `limitation` and `validate-name`, and the `deploy site` and
+  `deploy source-control` command groups.
+- **Agent / CI ergonomics** — `--json`, `--non-interactive`, stable exit
+  codes, OS keychain credential storage (no plaintext on disk),
+  per-environment env-var overrides
+  (`SITECOREAI_ENV_<NAME>_*`), and `SITECOREAI_AUTO_WIZARD=0` to suppress
+  interactive prompts.
+- **Local activity log** — `scai cli history` records redacted command
+  history at `~/.sitecoreai/cli-history.log`.
+- **Interactive REPL** — `scai cli shell` for chained commands in one session.
+- **Anonymous telemetry, on by default (opt-out)** — disable with
+  `scai cli telemetry disable`, `SITECOREAI_TELEMETRY=false`, or the
+  standard `DO_NOT_TRACK` env var. See
+  [docs/telemetry-and-privacy.md](./docs/telemetry-and-privacy.md).
+
+See [docs/parity-with-devex.md](./docs/parity-with-devex.md) for the
+full mapping against `Sitecore.DevEx` and a record of what was
+deliberately not ported.
+
+## Install
+
+```sh
+npm  install -g @sitecoreai-labs/sitecoreai-cli
+pnpm add    -g @sitecoreai-labs/sitecoreai-cli
+yarn global add @sitecoreai-labs/sitecoreai-cli
+```
+
+Requires Node.js >= 20.
 
 ## Quick start
 
-Install dependencies (npm/pnpm/yarn/bun are all supported):
+Get from zero to a working environment in three commands:
 
-```
-npm install
-pnpm install
-yarn install
-bun install
-```
+```sh
+# 1. Configure an environment (writes sitecoreai.cli.json + caches a Deploy token)
+scai setup init --wizard
 
-Configure an environment (writes to `sitecoreai.cli.json` and creates it if missing):
+# 2. Confirm what got written
+scai setup status
 
-```
-scai init
-scai init --environment-name local --project "My Project" --environment "Dev"
+# 3. Pull serialized content from the configured CM
+scai provision serialization pull --environment-name local
 ```
 
-Interactive wizard setup:
+Running `scai setup init` with no flags defaults to the interactive wizard. To
+configure a specific environment non-interactively:
 
+```sh
+scai setup init \
+  --environment-name local \
+  --project "My Project" \
+  --environment "Dev" \
+  --deploy-token "$SITECOREAI_DEPLOY_TOKEN"
 ```
-scai init --wizard
-```
-
-Running `init` without flags defaults to the wizard. Provide flags to skip prompts.
-Use `--skip-deploy-lookup` to avoid Deploy API lookups and just enter the CM host.
 
-Auto-setup on startup:
+`--skip-deploy-lookup` skips the Deploy API lookup and just prompts for
+the CM host.
 
-- When you run a command and no config or auth token is found, the CLI launches the init/login wizard.
-- In non-interactive/CI mode, it skips auto-setup and prints a hint instead.
-- Disable auto-setup with `SITECOREAI_AUTO_WIZARD=0`.
-
-Check configured environments:
-
-```
-scai status
-```
-
-Validate configuration:
-
-```
-scai config validate
-```
+## MCP — first-class agent integration
 
-Run a serialization command:
+scai is built to be driven by agents, not just people. `scai mcp serve`
+launches a Model Context Protocol server bound to one Sitecore
+environment:
 
-```
-scai serialization pull --environment-name local
+```bash
+scai mcp serve --environment-name dev
 ```
 
-List environments from the Deploy API:
-
-```
-scai deploy environments list --project "My Project" --type cm
-```
+It exposes scai's developer surfaces as **54 workflow-shaped tools** —
+deploy, serialization, recipes, hygiene, publishing, brand, brief,
+campaign, workflow, webhook, agent automation, and inspection —
+designed around real tasks rather than 1:1 wrappers of library calls.
+Every write tool requires an explicit per-call `allowWrite: true`;
+there is no session-wide override. Compatible with Claude Code, Claude
+Desktop, Cursor, Cline, and any other MCP-speaking client.
 
-Upload deployment source from a directory:
+Need a URL instead of a spawned process — e.g. to point a browser-hosted
+client at it? Run the Streamable HTTP transport:
 
-```
-scai deploy deployments source --id <deploymentId> --directory ./my-app
+```bash
+scai mcp serve --transport http --port 3399   # → http://127.0.0.1:3399/mcp
 ```
 
-## Agent/CI usage
-
-For non-interactive usage, authentication flows, and CM vs Editing Host guidance, see
-[`AGENT_CI.md`](./AGENT_CI.md).
-
-Future enhancements: see [`ROADMAP.md`](./ROADMAP.md).
-
-Agent metadata and skills:
-
-- Machine-readable config: [`agent.json`](./agent.json)
-- Skills index: [`skills/README.md`](./skills/README.md)
-
-## Configuration
-
-Configuration is read from `sitecoreai.cli.json` at your project root (use `--config` to
-point at a different directory). `init` creates or updates an environment in the
-`envProfiles` section, creates the config if it does not exist, and can set the default
-environment with `--set-default`.
-
-Key behaviors:
-
-- `--environment-name` selects the environment key inside `envProfiles`.
-- Global output flags: `--json`, `--quiet`, and `--log-file <path>`.
-- `--ref` lets an environment inherit auth/settings from another environment.
-- Deploy API access uses a SitecoreAI access token cached in the OS keychain (`deployToken`).
-  This token includes SitecoreAI CM/admin scopes in addition to Deploy scopes.
-- `init` can accept `--deploy-token` directly or obtain a token via interactive login or client credentials.
-- `login` only refreshes the SitecoreAI access token for an existing environment.
-- CM access/refresh tokens are cached in the OS keychain when
-  `settings.cacheAuthenticationToken` is `true` (default: `true`).
-- For client credentials, provide secrets via environment variables
-  (`SITECOREAI_CLIENT_SECRET` or `SITECOREAI_ENV_<NAME>_CLIENT_SECRET`).
-- Environment settings can be overridden with environment variables for CI or secrets.
-  Global overrides (`SITECOREAI_CLIENT_SECRET`, etc.) apply only to the active environment,
-  while per-environment overrides (`SITECOREAI_ENV_DEMO_DEPLOY_TOKEN`) always apply.
-- CLI history is written to `~/.sitecoreai/cli-history.log` (override with `SITECOREAI_HISTORY_PATH`).
-- Use `history` to view recent CLI activity from that log.
-- Use `history --show-path` to print the log file path.
-- Module files (`*.module.json`) are validated against the serialization module schema.
-
-Telemetry:
-
-- Modeled after the Vercel Skills CLI: anonymous usage events and opt-out via env vars. [github.com/vercel-labs/skills](https://github.com/vercel-labs/skills/)
-- On first use, the CLI prompts for consent and stores it in `settings.telemetryEnabled` in `sitecoreai.cli.json`.
-- If `settings.telemetryEnabled` is unset, telemetry is disabled until consent is recorded.
-- Override with env vars: `SITECOREAI_TELEMETRY=false`, `DISABLE_TELEMETRY=1`, or `DO_NOT_TRACK=1`.
-- Uses a `ci=1` flag when running in CI.
-- Sends command names, durations, and a random nonce (no full args); sensitive flags are redacted.
-- The telemetry service derives an approximate region from CDN headers (e.g., `US-CA`) and does not store raw IPs.
-- The CLI uses a built-in production telemetry endpoint. For development, override with
-  `SITECOREAI_TELEMETRY_URL`.
-- Telemetry schema: `https://schemas.sitecoreai.dev/v1/telemetry.schema.json`.
-- Telemetry payloads are validated against the telemetry schema before sending.
-
-Telemetry status:
+See [docs/mcp.md](./docs/mcp.md) for client config snippets, the full
+tool inventory, write-gate semantics, and v1 limitations.
 
-```
-scai telemetry status
-```
+## Recipes
 
-## Privacy
+Declarative Sitecore template + rendering definitions, authored as
+TypeScript files alongside React components and pushed to the CMS via the
+Authoring GraphQL API. Five recipe kinds are stable in 0.1.0:
+`ComponentTemplate`, `ContentTemplate`, `ComponentSection`,
+`DesignParametersTemplate`, `Enumeration`.
 
-Telemetry is strictly anonymous and minimal. We do not send file contents, full arguments,
-tokens, or user identifiers. The payload includes only the command name, duration, CLI
-version, schema version, a CI flag when applicable, and an approximate region derived
-from CDN headers (client-supplied region values are ignored). The telemetry service uses
-client IPs only for rate limiting and does not store raw IPs (logs keep only anonymized IP
-prefixes). You can opt out at any time via `settings.telemetryEnabled` or the environment
-variables above.
+> **`.recipe.ts` files are executed code, not data — run them in a
+> sandbox.** A `.recipe.ts` is TypeScript that, when loaded, runs its
+> top-level code. Only `recipe compile`, `recipe push`, and `recipe diff`
+> load `.recipe.ts` source; `recipe plan` operates strictly on a
+> pre-compiled `.ir.json` and never executes recipe code.
+>
+> By default scai loads every `.recipe.ts` in a **forked child-process
+> sandbox**: the child runs the recipe with a clean, deny-by-default
+> environment — none of scai's `SITECOREAI_*` secrets, deploy tokens, or
+> OAuth credentials reach recipe code — and a kill-timeout that fires if a
+> recipe hangs. Only validated, JSON-serialisable `Recipe` data crosses
+> back over the IPC channel. Set `SITECOREAI_RECIPE_SANDBOX=0` to fall
+> back to the legacy in-process load (for debugging, or a runtime where
+> forking fails); doing so logs a warning.
+>
+> What the sandbox does **not** do: the child still runs as the same OS
+> user as scai, so it can read and write the filesystem and make network
+> requests. The sandbox stops a hostile recipe from stealing scai's
+> secrets or crashing scai — it is not a general filesystem/network jail.
+> Treat recipe files like any other build script (`webpack.config.js`,
+> `vite.config.ts`): only run `scai provision recipe` against repos and
+> recipe files you trust. See [docs/recipe-sandbox.md](./docs/recipe-sandbox.md).
+
+Locate recipes via the `recipes` glob in `sitecoreai.cli.json` (default
+`recipes/**/*.recipe.ts`). The lifecycle:
+
+```sh
+# compile — loads .recipe.ts (in the sandbox) → emits compiled .ir.json
+scai provision recipe compile --input recipes/cta-button.recipe.ts --output cta-button.ir.json \
+  --templates-root /sitecore/templates/Project/<site>/Components \
+  --renderings-root /sitecore/layout/Renderings/Project/<site>
+
+# plan — read-only diff against a tenant; operates on a compiled .ir.json,
+# never executes recipe code
+scai provision recipe plan -n sandbox --input cta-button.ir.json
+
+# push --what-if — dry-run; loads .recipe.ts (sandbox) or an .ir.json, no writes
+scai provision recipe push -n sandbox --what-if
+
+# push --allow-write — apply for real
+scai provision recipe push -n sandbox --allow-write
+```
+
+A second push is idempotent (zero mutations). Partial failure rolls back
+via LIFO unwind of snapshot-driven inverse mutations. Cross-recipe
+references (`template:<handle>`, `enumHandle: "<handle>"`) resolve to
+deterministic GUIDs at compile time.
+
+See [docs/recipes.md](./docs/recipes.md) for the full surface, including
+the trust-model defenses, authoring examples, and graduation roadmap for
+composition kinds (PartialDesign, PageDesign, SiteTemplate, SiteRecipe,
+ContentItem — present in source, not in the 0.1.0 stability promise).
+
+## Publishing
+
+`scai content publish` wraps the SAI Publishing REST API
+(`edge-platform.sitecorecloud.io/authoring/publishing/v1`) and adds a
+two-step safety flow on top:
+
+```sh
+# 1. Dry-run — prints scope + a 5-minute scope token (no API write)
+scai content publish item --site marketing --include-subitems -n sandbox
+
+# 2. Real call — pass the token back to authorize the publish
+scai content publish item --site marketing --include-subitems -n sandbox \
+  --allow-write --confirm-token <token-from-step-1>
+
+# 3. Watch until terminal (or rely on the auto-watch in --non-interactive)
+scai content publish status <jobId> -n sandbox --watch
+```
+
+Verbs:
+
+| Verb                       | What                                                                                                                              |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `publish item`             | Item / subtree publish. Address by `--items <guid>`, `--paths <path>`, or `--site <name>`. Composable.                            |
+| `publish all`              | Whole-environment republish to Edge. Max gating: always requires `--confirm-token` + typed env-name confirmation.                 |
+| `publish unpublish`        | `never-publish` (reversible, default), `expire-now` (reversible), or `delete` (NOT reversible, typed-item-path confirm per item). |
+| `publish status [<jobId>]` | Inspect one job or list queued/running. Add `--watch` to follow until terminal.                                                   |
+| `publish cancel <jobId>`   | Cancel a single job, or `--all-queued` to sweep the env.                                                                          |
+| `publish history`          | Read the local audit log (`~/.sitecoreai/audit.log`) with env/since/command/outcome filters.                                      |
+
+The companion `scai content version` verbs (`inspect`,
+`set-validity`, `set-never-publish`) handle the CM-side content-state
+fields that affect what `scai content publish` picks up.
+
+**Auth:** publishing needs an **environment-level** automation client
+(carries `xmcpub.jobs.t:*` scopes), not the org-level client most other
+scai commands use. Cloud Portal → Environments → [env] → Automation
+Clients → Create. scai will mint and cache the publishing-scoped JWT
+transparently when env-level `clientId`/`clientSecret` are present in
+config or via `SITECOREAI_ENV_<NAME>_CLIENT_ID` / `_CLIENT_SECRET`.
+
+**Naming gotcha:** the API field `xmc.site.mode` is whole-_environment_,
+not whole-_site_ — legacy XM terminology from when one Sitecore instance
+== one site. Empirically verified against the SAI Publishing API. To
+publish a single Sitecore site, use
+`scai content publish item --site <name> --include-subitems`.
+
+See [docs/publish-walkthrough.md](./docs/publish-walkthrough.md) for
+copy-pasteable runbooks (single page, whole site, whole env,
+unpublish, queue cleanup, CI flow, common errors);
+[docs/parity-with-devex.md](./docs/parity-with-devex.md) for safety
+model details and the consent record shape; and
+[docs/roadmap.md](./docs/roadmap.md) for what's still on the roadmap.
+
+## Using as a library
+
+`@sitecoreai-labs/sitecoreai-cli` is dual-purpose: a CLI **and** a typed
+TypeScript SDK. The CLI binary is only on `bin`. The package root is
+intentionally not importable — there is no `main` entry. SDK consumers
+import from a subpath; the package root throws `ERR_PACKAGE_PATH_NOT_EXPORTED`
+so a stray `require("@sitecoreai-labs/sitecoreai-cli")` can never
+execute the CLI by accident.
+
+Each surface ships from its own subpath with its own stability
+contract. The most ergonomic seam is the `create*Client(options)`
+factory; the underlying option-first functions are also exported for
+callers that prefer the bag-of-functions style.
+
+```ts
+// Recipes — compile a declarative recipe and push it to the CMS
+import {
+  compileRecipe,
+  buildPlan,
+  executeIr,
+  createAuthoringClient,
+  createSitesApiClient,
+} from "@sitecoreai-labs/sitecoreai-cli/recipe";
+
+// Deploy API — environments, deployments, logs
+import { createDeployApiClient } from "@sitecoreai-labs/sitecoreai-cli/deploy";
+const deploy = createDeployApiClient({ accessToken: process.env.SITECOREAI_DEPLOY_TOKEN! });
+const projects = await deploy.fetchAllProjects();
+
+// Serialization (Authoring + Management GraphQL) — items, roles, users, publish
+import { createSitecoreApiClient } from "@sitecoreai-labs/sitecoreai-cli/serialization";
+const sc = createSitecoreApiClient({ host, accessToken });
+const meta = await sc.fetchItemMetadata("master", "/sitecore/content/Home");
+
+// Publishing API — XM Cloud publish jobs, with the structured consent
+// argument required for any destructive call
+import {
+  submitPublishJob,
+  mintScopeToken,
+  type PublishConsent,
+} from "@sitecoreai-labs/sitecoreai-cli/publishing";
+
+// Sites API — CRUD over sites, collections, languages, jobs (unstable)
+import { listSites, addLanguage } from "@sitecoreai-labs/sitecoreai-cli/unstable/sites";
+
+// Hygiene — audits + cleanups, output adapters, baselines, history
+import { runAuditOrphans, createHygieneApiClient } from "@sitecoreai-labs/sitecoreai-cli/hygiene";
+
+// Brand — Brand Review SARIF + JSON pipelines (unstable)
+import {
+  generateBrandReview,
+  runBrandReview,
+} from "@sitecoreai-labs/sitecoreai-cli/unstable/brand";
+
+// Webhooks + Workflow — Sitecore event handlers and item workflow operations
+import { createWebhookApiClient } from "@sitecoreai-labs/sitecoreai-cli/webhooks";
+import { createWorkflowApiClient } from "@sitecoreai-labs/sitecoreai-cli/workflow";
+
+// Errors — every subpath throws `ScaiError`; import the type from `/errors`
+import { ScaiError, type ScaiErrorCode } from "@sitecoreai-labs/sitecoreai-cli/errors";
+```
+
+### Subpath exports
+
+The SDK is split into a **stable core** and an **`unstable/` namespace**.
+
+**Stable core** — these subpaths carry the SemVer stability contract
+below:
+
+```
+./recipe    ./deploy     ./serialization   ./errors
+./envelope  ./config     ./publishing      ./content
+./hygiene   ./webhooks   ./workflow        ./sync
+```
+
+**Unstable** — these subpaths carry **no stability promise**. Their
+shape may change in any minor (or patch) release without a major bump
+or a changeset. The `brand`, `brief`, `sites`, `campaigns`, and `agents`
+APIs are reverse-engineered from observed traffic. Pin an exact scai
+version if you depend on them:
+
+```
+./unstable/agents      ./unstable/brand        ./unstable/brief
+./unstable/campaigns   ./unstable/scripting    ./unstable/sites
+./recipe/unstable      — recipe composition kinds (PageDesignRecipeSchema,
+                         SiteRecipeSchema, PartialDesign, …)
+```
+
+### Stability contract (0.1.0)
+
+The symbols re-exported from a **stable-core** subpath's `index.ts` are
+the public SDK contract. Anything reachable only via the `@/...` path
+alias (reaching into `src/` internals), or via any `unstable/` subpath
+(including `./recipe/unstable`), is **not** part of the contract and may
+change between scai versions without notice.
+
+Breaking changes to a stable-core exported symbol require a major
+version bump (per Changesets). New symbols are additive and ship in
+minor versions. `unstable/*` subpaths are exempt from all of this — by
+design, so in-progress surfaces can ship and iterate without churning
+the major version.
+
+## Going deeper
+
+- [Command reference](./docs/commands.md) — every command and flag,
+  generated from the source.
+- [Configuration](./docs/configuration.md) — config file, env vars,
+  profiles, auth.
+- [Serialization](./docs/serialization.md) — SCS push/pull/diff
+  semantics and module configs.
+- [Deploy](./docs/deploy.md) — Deploy API surface, selection rules,
+  editing hosts.
+- [Recipes](./docs/recipes.md) — declarative recipe authoring, trust
+  model, lifecycle commands, cross-recipe references.
+- [MCP](./docs/mcp.md) — `scai mcp serve`, tool inventory, write gate,
+  agent integration.
+- [Telemetry and privacy](./docs/telemetry-and-privacy.md) — what gets
+  sent, how to opt out.
+- [Release process](./docs/release.md) — versioning and publishing.
+- [Quality gates](./docs/quality-gates.md) — where each gate is enforced.
+- [Roadmap](./docs/roadmap.md) — what's coming next.
+- [Parity with `Sitecore.DevEx`](./docs/parity-with-devex.md) — full
+  mapping against the dotnet CLI and a record of what was deliberately
+  not ported.
 
-## Data handling and retention
-
-- Local history is stored in `~/.sitecoreai/cli-history.log` (override with `SITECOREAI_HISTORY_PATH`)
-  and grows until you delete or rotate it.
-- Telemetry payloads are minimal and do not include full arguments or credentials. Retention
-  and aggregation are determined by the telemetry service.
+For agent / CI usage, see [AGENTS.md](./AGENTS.md).
 
 ## Troubleshooting
 
-- **Config not found:** run `scai init` or pass `--config <path>`.
-- **Auth required:** run `scai login` or `scai init` to refresh tokens.
-- **Network/timeouts:** verify the CM host/authority, and increase
-  `settings.apiClientTimeoutInMinutes` if needed.
-- **Deploy token missing:** provide `--deploy-token` or configure
-  `SITECOREAI_DEPLOY_TOKEN`.
-
-## Release management
-
-This repo uses Changesets for versioning and release automation.
-
-Local workflow:
-
-```
-npm run changeset
-```
-
-- Select the version bump type (patch/minor/major).
-- Commit the generated `.changeset/*.md` file.
-
-CI workflow:
-
-- Push to `main` and the Changesets GitHub Action will open a release PR.
-- Merge the release PR to publish to npm (requires `NPM_TOKEN` secret).
-
-Manual release:
-
-```
-npm run version
-npm run release
-```
-
-## Serialization API usage
-
-Serialization commands use the Sitecore Management API (GraphQL) at
-`/sitecore/api/management` on the configured CM host.
-
-- **Authentication:** OAuth2 via the configured `authority`. The CLI supports client credentials
-  and interactive browser login, and caches access tokens in `sitecoreai.cli.json`.
-- **Items:** GraphQL queries to read items, metadata, and history for pull/push/diff workflows.
-- **Roles/Users:** GraphQL queries for role/user sync (pull/push).
-- **Watch:** GraphQL history polling to detect remote changes and pull deltas.
-- **Filesystem:** YAML files in the module serialization paths using deterministic YAML output.
-
-## Commands
-
-Serialization commands (alias: `ser`):
-
-- `serialization info`
-- `serialization explain`
-- `serialization pull`
-- `serialization push`
-- `serialization diff`
-- `serialization validate`
-- `serialization watch`
-- `serialization package create` (alias: `pkg`)
-- `serialization package install` (alias: `pkg`)
-
-Environment commands:
-
-- `init`
-- `login`
-- `logout`
-- `status`
-- `history`
-
-Deploy API commands:
-
-- `deploy organizations get`
-- `deploy organizations health`
-- `deploy organizations license`
-- `deploy organizations launch-demo`
-- `deploy projects list`
-- `deploy projects limitation`
-- `deploy projects validate-name`
-- `deploy projects get`
-- `deploy projects create`
-- `deploy projects update`
-- `deploy projects link-repository`
-- `deploy projects unlink-repository`
-- `deploy projects delete`
-- `deploy environments list`
-- `deploy environments limitation`
-- `deploy environments get`
-- `deploy environments create`
-- `deploy environments variables list`
-- `deploy environments variables create`
-- `deploy environments variables delete`
-- `deploy environments deployments list`
-- `deploy environments deployments create`
-- `deploy environments get-edge-token`
-- `deploy environments get-editing-secret`
-- `deploy environments regenerate-context`
-- `deploy environments promote`
-- `deploy environments restart`
-- `deploy environments link-repository`
-- `deploy environments unlink-repository`
-- `deploy environments delete`
-- `deploy logs list`
-- `deploy logs view`
-- `deploy logs data`
-- `deploy editing-host list`
-- `deploy editing-host create`
-- `deploy editing-host update`
-- `deploy editing-host delete`
-- `deploy editing-host deploy`
-- `deploy source-control list`
-- `deploy source-control state`
-- `deploy source-control access-token`
-- `deploy source-control validate`
-- `deploy source-control repository get`
-- `deploy source-control repository branches`
-- `deploy source-control repository validate`
-- `deploy source-control repository create-from-template`
-- `deploy source-control providers`
-- `deploy source-control templates`
-- `deploy source-control get`
-- `deploy source-control delete`
-- `deploy deployments list`
-- `deploy deployments get`
-- `deploy deployments status`
-- `deploy deployments deploy`
-- `deploy deployments cancel`
-- `deploy deployments source`
-- `deploy deployments watch`
-- `deploy deployments logs`
-
-Aliases:
-
-- `deploy org` → `deploy organizations`
-- `deploy proj` → `deploy projects`
-- `deploy env` → `deploy environments`
-- `deploy sc` → `deploy source-control`
-- `deploy dep` → `deploy deployments`
-- `deploy log` → `deploy logs`
-- `deploy eh` → `deploy editing-host`
-
-Deploy selection rules:
-
-- Projects: use `--id` or `--name`. Project link/unlink requires `--id`.
-- Environments: use `--id` or `--name`, optionally scoped with `--project`.
-- Environment create requires `--project`.
-- Environment create supports `--cm-only` to create a CM-only environment.
-- Project create requires `--name`.
-- Tenant types: `0` = nonprod, `1` = prod.
-- Project source control ID mapping: create uses `integrationId`, update uses `sourceControlIntegrationId`.
-- Source control integrations and deployments: use `--id`.
-- Project link-repository requires `repositoryId` and `integrationId` (others optional).
-- Environment link-repository requires `repositoryName`, `repositoryId`, `integrationId`,
-  `repositoryRelativePath`, and `repositoryBranch`.
-- Source control repository create-from-template requires `--provider` (`ado` or `github`)
-  and template fields (`templateRepository`, `templateOwner`, `repositoryName`, `owner`,
-  `integrationId`).
-- Deploy deployments source accepts `--file` (archive) or `--directory` (auto-zip).
-
-Aliases:
-
-- `serialization` -> `ser`
-- `serialization package` -> `pkg`
-
-## Development
-
-Run in dev mode:
-
-```
-npm run dev -- serialization info --help
-```
-
-Lint and format:
-
-```
-npm run lint
-npm run format
-```
-
-Build:
-
-```
-npm run build
-```
+| Symptom              | Try                                                                      |
+| -------------------- | ------------------------------------------------------------------------ |
+| Config not found     | `scai setup init` or pass `--config <path>`                              |
+| Auth required        | `scai setup login` or `scai setup init` to refresh tokens                |
+| Network / timeouts   | Verify the CM host/authority; raise `settings.apiClientTimeoutInMinutes` |
+| Deploy token missing | Pass `--deploy-token` or set `SITECOREAI_DEPLOY_TOKEN`                   |
 
-Run tests:
+For more, see the [configuration docs](./docs/configuration.md) or run
+`scai <command> --help`.
 
-```
-npm run test
-```
+## Contributing
 
-Integration tests (requires env vars):
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Working on the repo itself uses
+`pnpm`; end users can install via any package manager.
 
-```
-npm run test:integration
-```
+## License
 
-Watch tests:
-
-```
-npm run test:watch
-```
-
-Run built CLI:
-
-```
-node dist/cli.js serialization info --help
-```
+[MIT](./LICENSE).