docs(mau): document client identity and correct the read-only rule

[ttypic]

Add docs/Client-Identity.md: server/device classification by auth
mode, the client ID precedence, values the CLI refuses, target vs
identity --client-id, and the multi-user demo pattern (two terminals
with --client-id for a demo, a client-scoped token to reproduce device
behaviour exactly).

• Rewrite the --client-id help, the token --client-id help and the
  ABLY_API_KEY / ABLY_TOKEN env-var text, which presented
  --client-id none as a normal option and described per-run random
  client IDs.
• Correct the rule in AGENTS.md, the ably-new-command skill and the
  src/flags.ts comment that client identity is irrelevant for read-only
  commands: under MAU billing reads carry the session's client ID and
  are counted; they just have no reason to act as someone else.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cli-web-cli	Ready	Preview	Oct 1, 2026 12:56pm UTC

[claude-code-ably-assistant]

Walkthrough

This PR corrects a subtle but important misconception in docs, code comments, and flag descriptions: the claim that client identity is "irrelevant" for read-only commands. In reality, every CLI command carries a client ID (and Ably counts it under MAU billing) — read-only commands simply have no reason to act as a different client, so clientIdFlag is still correctly omitted. The PR also adds a new docs/Client-Identity.md reference page documenting server vs. device traffic classification, client ID resolution order, and token auth behaviour.

Changes

Area	Files	Summary
Docs	docs/Client-Identity.md (new)	85-line reference covering MAU classification (server/device), client ID precedence chain, deprecated values, and multi-user simulation patterns
Docs	docs/Environment-Variables/General-Usage.md	Adds a cross-reference link to the new Client-Identity doc
Config / Agent instructions	AGENTS.md	Corrects clientIdFlag guidance and adds Client-Identity.md to the docs/ listing
Skills	.claude/skills/ably-new-command/SKILL.md, references/patterns.md	Replaces "identity is irrelevant for reads" with the accurate "reads carry identity but have no reason to act as someone else"
Commands	src/commands/auth/issue-ably-token.ts, src/commands/auth/issue-jwt-token.ts	Removes the misleading --client-id "none" example; rewrites client-id flag description to warn anonymous tokens are rejected by identified-client apps
Utils / Data	src/data/env-vars.ts	Rewrites ABLY_API_KEY and ABLY_TOKEN client ID help text with accurate per-install identity and MAU billing detail
Flags	src/flags.ts	Updates clientIdFlag JSDoc and description to reflect session identity semantics and token auth behaviour

Review Notes

• Behavioural change (minor UX): The --client-id "none" example is removed from auth issue-ably-token examples, and "none" is now described as deprecated in docs/Client-Identity.md. No runtime behaviour changes — the deprecated value still works with a warning.
• MAU billing clarification: The corrected rule ("reads carry identity, they just don't need to act as someone else") affects how future contributors use clientIdFlag. Reviewers should verify the rationale in docs/Client-Identity.md matches the actual SDK/billing behaviour.
• No new runtime dependencies.
• Skills updated in sync with the flag description change — important because stale skills would cause Claude to regenerate incorrect code.
• No test changes — the PR is purely documentation and description corrections; existing unit tests (including the client-id-target-guard test) cover the identity vs. target distinction.

[claude-code-ably-assistant]

Review: docs(mau): document client identity and correct the read-only rule

Overview: Pure documentation PR — adds a new docs/Client-Identity.md, updates skill files to correct the rationale for omitting clientIdFlag from read-only commands, and sharpens flag/env-var descriptions throughout. No functional logic changes. I checked all factual claims against the implementation.

Verified accurate

• JWT rejection before connecting (line 1731-1736 of base-command.ts) — confirmed via this.fail() call
• "none" is deprecated but still functional with a warning (line 1652-1656 of base-command.ts) — confirmed
• Empty string "" and "*" are rejected via InvalidClientIdError — confirmed in src/services/client-identity.ts
• Classification table (API key → server; JWT with x-ably-clientType: server → server; other tokens → device) — matches ably-client-factory.ts

One concern worth addressing

docs/Client-Identity.md line 73 — self-contradictory MAU claim

Both run under the server classification, so they are not counted or capped as devices. Ably counts client IDs wherever they appear, including in message payloads, so each simulated name may still register as an MAU.

The first sentence correctly states server-classified traffic is not counted as device MAU. The second sentence says the same names "may still register as an MAU," which directly contradicts that. More specifically, the phrase "including in message payloads" implies Ably scans message content to count MAU — that's not how Ably billing works. MAU is connection-based, not payload-scanning.

If the intent is to say "server-classified connections still appear in Ably's analytics with those client IDs" that's a different (and narrower) claim. If the intent is to warn users that server classification isn't a billing escape hatch, the rationale needs to be grounded in the actual billing mechanic. As written, it could cause readers to incorrectly believe they're accumulating MAU charges when they're not, or to make unnecessary architectural changes.

Suggested fix: either drop the second sentence (the first already covers the important point), or replace it with a specific, accurate statement about what Ably does track for server-classified traffic.

Minor

The DXRFC-029 reference in the opening paragraph is an internal document external contributors can't look up. Fine to leave as context for rationale, just worth knowing it will be opaque to OSS contributors.

Otherwise the doc is well-structured, the code-behaviour alignment is accurate, and the skill/AGENTS updates correctly capture the new rationale.