Clarify config storage: JSONC canonical, dotenv as env-var-loader convenience

[gwpl]

AI Assistant:

Proposal: clarify JSONC as canonical config, dotenv as env-var-loader convenience

Summary

Update the base-webctl config-storage prescription from "dual layers, both first-class" to "JSONC canonical, dotenv back-compat / scalar-override convenience." Aligns the family with mature-CLI conventions (Cargo, gh, kubectl) and addresses observed drift across the four sibling tools.

Problem

Today the family-wide config story is:

• infra-config-precedence-2fc5.md — dotenv overrides JSONC. Both layers are first-class.
• infra-directory-structure-f868.md — .env.{tool} and {tool}.config.jsonc are peers under ~/.config/CLIAI/.
• infra-dotenv-configuration-r7m3.md:157 — dotenv unsuitable for nested/structured data.
• infra-client-profile-registry-lf4f.md — 4-layer JSONC merge defined.

Lived reality across sibling tools tells a different story:

Tool	On-disk config	Notes
telegram-webctl	dotenv only (repo-root)	JSONC loader exists, no JSONC file in use
chatgpt-webctl	YAML at ~/.config/.../chatgpt-webctl.config.yaml	Drifted from prescribed JSONC; loader silently accepts both .jsonc and .yaml
linkedin-webctl	dotenv only (~/.config/CLIAI/linkedin-webctl/)	JSONC loader exists, no JSONC file
base-webctl	n/a (spec-only repo)	—

The spec says "dual is canonical and intentional." The drift says "users found the prescription confusing or insufficient." Three tools have JSONC infra they never use; the one that adopted structured config chose a different format (YAML) than the spec.

Proposed clarification

JSONC at ~/.config/CLIAI/{client}/webctl/{tool}.config.jsonc
  = CANONICAL persistent config (scalars + structured)

.env.{tool} (walked up from CWD)
  = back-compat env-var loader; convenience for local-machine overrides
    and CI/devops workflows; SAME SEMANTICS as setting CLIAI_{TOOL}_* env vars

Precedence stays the same; framing changes:

defaults
  < JSONC config (4-layer merge)
    < dotenv (acts as env-var loader; conceptually = layer of env vars)
      < CLIAI_{TOOL}_* env vars (explicit)
        < legacy compat env (CHROME_WS_PORT, etc.)
          < CLI flags

New work goes in JSONC. Dotenv stays parsed for back-compat indefinitely; no hard deprecation timeline. Tools document JSONC as the primary location in their dotenv.{tool}.example template headers.

Rationale — why now

• Cargo precedent: TOML canonical + env vars for scalars. Cargo explicitly forbids structured data in env vars. Treating dotenv as "env-var file with the same constraints" matches.
• gh / kubectl precedent: single canonical config file (YAML), env vars for overrides. No .env.gh walk-up.
• npm anti-precedent: .npmrc + package.json dual-format split is a well-documented DX pain point. The CLIAI dotenv+JSONC mirror has the same shape.
• telegram-webctl just shipped a backend lifecycle CLI requiring structured config (backends map, probe_order, launch + stop/suspend/resume commands per backend). Forcing this through dotenv is impossible without ugly CSV encoding. This is the case infra-dotenv-configuration-r7m3.md:157 predicted — and the first family-wide forcing function for canonicalizing JSONC.

Cross-tool migration path

No forced changes to existing tools. The clarification is documentation-only initially:

1. Update the four spec docs to reframe the dual layer (this PR).
2. Each tool adds a "Config Storage" section to its AGENTS.md pointing JSONC-first (telegram-webctl did this already at commit XXXX — link once landed).
3. chatgpt-webctl can migrate YAML → JSONC at its own cadence, or the spec can be relaxed to explicitly bless JSONC-or-YAML for structured data.
4. linkedin-webctl gets JSONC starter when its users hit a structured-config use case.

Open questions

• Should chatgpt-webctl's YAML drift be formalized (spec allows JSONC or YAML), or should that tool migrate to JSONC?
• Is there appetite for a base-webctl migrate-config helper script that ingests dotenv and emits JSONC equivalent?

Reference

• telegram-webctl design + implementation: commits cda8002..a232e0d on master; full schema at docs/backend-config.design.md; canonical JSONC example now lives at ~/.config/CLIAI/default/webctl/telegram-webctl.config.jsonc (gitignored / user-machine).
• Decision discussion: telegram-webctl AGENTS.md "Config Storage" section.