docs(release): decouple the demo-webchat bump from promotion to latest

[Dmitrii Ostasevich (kwinto)]

Docs-only change to the webchat-release skill. No source or build changes.

Problem

The post-release checklist in §8 listed the demo-webchat bump as step 5, after the "promote to latest" step:

4. After the green light, promote to latest by running the Promote Release to Latest workflow …
5. Update the demo-webchat version in service-webchat …

Read in order, step 5 looks gated on step 4 — and step 4 waits on QA sign-off, roughly a week after publishing. It isn't gated. Pointing demo-webchat at the freshly published pre-release version is exactly what gives QA something to exercise during that window; deferring it until after promotion inverts the dependency and defeats the purpose.

Existing practice already works the correct way, which makes the ordering in the doc actively misleading: the 3.47.0 demo bump (cognigy#13417) landed 2026-07-13, the same day 3.47.0 was published to npm, while promotion to latest ran 2026-07-22 — nine days later.

Change

§8 now splits by what actually waits:

• §8a — same-day work: Testing Webchat check, the demo-webchat bump, ticket tagging, then opening the QA tech-story. Only the QA wait is a blocker.
• §8b — the bump itself, with what it actually involves (previously a one-liner):
  • It's a PR against Cognigy/cognigy, whose main is protected (1 approving review, a required team review, squash-only) — not a direct push. Suggests a worktree so the monorepo checkout's current branch isn't disturbed.
  • The pin is exact (no caret), and the exact pin resolves the pre-release dist-tag fine.
  • package.json must be hand-edited — it has no trailing newline and uses tabs, so npm install <pkg>@<ver> reformats it and appends a newline. Hand-edit plus npm install --package-lock-only keeps it to a single changed line.
  • The lockfile churn wants auditing: @cognigy/webchat should be the only changed direct dependency, everything else transitive (chat-components, and the caret-ranged @radix-ui/* tree beneath it). Includes a script, since eyeballing a ~200-line lockfile diff doesn't scale.
  • The monorepo's pre-commit hooks only target services/service-ui/**, so they no-op here but still produce output — noted so it isn't mistaken for an error.
• §8c — promotion, the only step that waits for QA.

Also documented (both hit during the 3.48.0 release)

• publish.yml is named "Publish to NPM (with pre-release tag)", so gh run list --workflow Publish silently matches nothing. Cost a wasted diagnostic cycle when the workflow appeared not to have fired.
• chat-components' release.yml fails with Bad credentials on an expired RELEASE_ACTION_TOKEN PAT. The tag push succeeds, but no GitHub release is created, so publish.yml (on release: published) never fires and nothing reaches npm — silent unless checked. §0b now has the diagnosis and the gh release create --generate-notes --verify-tag unblock, plus the caveat that switching to GITHUB_TOKEN would stop publish.yml firing at all, since releases created by GITHUB_TOKEN don't trigger workflows. The secret still needs rotating by an admin.

Verification

• npm run prettier:check — pass (Format Check gate).
• npm run lint:a11y — 0 errors.
• Applied in practice while writing it: cognigy#13634 bumps demo-webchat to 3.48.0 following §8b exactly, with a single-line package.json diff and the lockfile audit showing @cognigy/webchat as the only changed direct dependency.

🤖 Generated with Claude Code

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[Copilot]

Pull request overview

Updates the webchat-release skill documentation to reflect the correct real-world release flow: bumping the downstream demo-webchat immediately after publishing the Webchat pre-release (to enable QA during the promotion window), and only promoting to latest after QA sign-off. It also adds troubleshooting guidance for common CI/workflow failure modes that can silently prevent publishing.

Changes:

• Restructures the post-release checklist into “immediate” vs. “wait for QA” steps, explicitly decoupling the demo-webchat bump from promotion.
• Expands the demo-webchat bump section with concrete PR/worktree guidance and a lockfile-audit procedure.
• Documents two workflow-related gotchas: publish workflow name mismatch when using gh, and chat-components release failure mode when the PAT expires.

Comments suppressed due to low confidence (1)

.claude/skills/webchat-release/SKILL.md:259

• Same issue as the lockfile line: the snippet opens services/service-webchat/package.json even though the instructions cd into that directory first. Use the local package.json path so the command works as written.

direct = set(json.loads(open('services/service-webchat/package.json').read()).get('dependencies', {}))