diff --git a/.agents/skills/deco-site-workflow/references/schema.md b/.agents/skills/deco-site-workflow/references/schema.md
index 677ef6ba..a9802983 100644
--- a/.agents/skills/deco-site-workflow/references/schema.md
+++ b/.agents/skills/deco-site-workflow/references/schema.md
@@ -82,7 +82,9 @@ Missing everywhere: exit 64 with
 
 The CLI sends `Authorization: Bearer <token>` to Studio. It takes the token from:
 
-1. `DECO_TOKEN`, when set (use a Studio API key; this is the CI path);
+1. `DECO_TOKEN`, when set (this is the CI path): a Studio API key, or, for `deco schema push` only,
+   the site's own site token (the one the site passes to `createCMS({ token })`, issued in the
+   project's settings). A revoked site token gets 401;
 2. else the output of `npx decocms auth token --target=<DECO_STUDIO_URL>` (Studio CLI's session; the
    CLI has no login of its own). Log in once with `npx decocms auth login --target=https://studio.decocms.com`.
    `deco login` prints that command.
@@ -136,7 +138,7 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     env:
-      DECO_TOKEN: ${{ secrets.DECO_TOKEN }}   # a Studio API key
+      DECO_TOKEN: ${{ secrets.DECO_TOKEN }}   # a Studio API key, or the site token
       # DECO_SITE: my-store                   # only if it isn't in wrangler.* vars or .env
     steps:
       - uses: actions/checkout@v4
diff --git a/packages/blocks/src/v8/cli/run.ts b/packages/blocks/src/v8/cli/run.ts
index 2c7b55ba..37ce409d 100644
--- a/packages/blocks/src/v8/cli/run.ts
+++ b/packages/blocks/src/v8/cli/run.ts
@@ -102,7 +102,8 @@ Commands:
             a site: createCMS({ blocks, content }))
   schema    turn the types in .deco/index.ts into .deco/schema.gen.json
             (--check: write nothing, fail when the file is out of date; for CI)
-            schema push: upload it so Studio can draw forms (CI, on production deploys)
+            schema push: upload it so Studio can draw forms (CI, on production deploys);
+            DECO_TOKEN may be the site's site token (the one createCMS({ token }) takes)
   skills    skills install: copy the agent skills of this @decocms/blocks into the site,
             one folder per skill in .claude/skills (or --dir, relative to the folder that
             contains .deco/); replaces those folders, leaves other skills alone; offline