[E2 step 0d] Cross-repo env-var documentation (canonical source: Backend CLAUDE.md)

[jakebromberg]

Summary

Phase 0 prerequisite. Blocks E2-BS step 1 substrate. Cross-repo env-var documentation for the §4.2 feature flags. A single coordinated checklist-PR per repo (one commit per repo) adds the flags with consistent descriptions and defaults.

Deliverables

Per-repo target:

• Backend, LML, semantic-index — amend .env.example (verified to exist in those repos at PR-open time).
• discogs-etl, musicbrainz-cache, wikidata-cache — amend the repo's CLAUDE.md "Configuration" section (these repos don't currently use .env.example-driven flags).

Single source of truth: Backend's CLAUDE.md. A new "Cross-cache-identity feature flags" subsection lists ALL flags from §4.2 (including cache-side and LML/semantic-index flags), with their owning repo and current default.

Review process (locked):

• Backend CLAUDE.md amendment lands as a single PR; per-consumer-repo PRs cross-reference it.
• Reviewer: project lead (single-maintainer per §3.3.1).

Sync mechanism:

• If a flag is later renamed or its default changes, the change must update both the canonical Backend section AND the consumer repo's local doc in the same PR.
• CI on each consumer repo grep-asserts that the flag's name in code matches the name in the local doc.

Audit (post-launch follow-up)

Quarterly task filed as cross-cache-identity-followup: diff the canonical Backend list against actual code references in each consumer repo.

Flags to document (per §4.2)

Includes — but is not limited to — BS_USE_LIBRARY_IDENTITY (Backend reads from new tables), BS_USE_LIBRARY_IDENTITY_WRITES (Backend writes to new tables; flips after reads stabilize), LML_INCLUDE_IDENTITY_RESPONSE (LML emits the v2 response shape), WXYC_LIBRARY_HOOK_VERSION (cache loaders pick v1 or v2 schema), BS_LIBRARY_IDENTITY_GATE_THRESHOLD (gate-check unresolved-row threshold; default 1000). Full list lives in §4.2 and is replicated to Backend CLAUDE.md.

Acceptance

• Backend CLAUDE.md "Cross-cache-identity feature flags" section merged.
• Each consumer repo's local doc updated and cross-references the canonical section.
• CI grep-assertion live in each consumer repo.
• Followup issue filed (cross-cache-identity-followup label, NOT on this project board).

Plan reference

plans/library-hook-canonicalization/plan.md §4.2 (full feature-flag inventory).

Parent

Epic: #663 (E2)