CLAUDE

CLAUDE.md — Ruby SDK Wiki

This directory is the published, public wiki for the Convert Ruby SDK. It contains two categories of pages.

Shared Docs vs Ruby-Specific Docs

• Shared docs (lowercase-hyphenated filenames, e.g. rule-evaluation.md, data-management.md, segments.md, bucketing-algorithm.md, and everything listed under "Core Concepts (Shared)" / "How-To Guides (Shared)" in AI_Index.md) — Do not edit these files here. They are the cross-SDK concept docs whose canonical source lives in a private backend repo (path within that repo: public/js/tracking/full-stack-docs/, with concepts/ and guides/ subdirs). The same files appear in the JavaScript, PHP, and Android SDK wikis. Any edit made here will be overwritten when the backend sync is run against this wiki.

• Ruby-specific docs (CamelCase filenames, e.g. Quickstart.md, Installation.md, Initialization.md, Configuration.md, ReturnTypes.md, CodeExamples.md, ForkSafety.md, TrackingControl.md, Testing.md, Changelog.md) — These are Ruby-only and are edited directly in this wiki.

Decision Rule Before Editing Anything

1. Check the filename.
   • Lowercase-hyphenated → shared → edit the canonical source in the backend repo (public/js/tracking/full-stack-docs/) instead, never here.
   • CamelCase → Ruby-specific → edit here.
2. AI_Index.md and this CLAUDE.md are wiki-specific and edited here.

Backend Sync Status

The backend sync workflow (sync-to-wikis.yml) targets the JavaScript, PHP, Android, and Ruby SDK wikis. This Ruby wiki is in its target matrix with keep_lang: ruby, so each shared doc here is regenerated from the canonical backend source on every sync and carries Ruby code fences only (foreign-language fences are stripped). Treat every shared doc here as read-only — any edit made directly in this wiki is overwritten on the next sync; fix the canonical source in the backend repo (public/js/tracking/full-stack-docs/) instead.

Writing Rules for Ruby-Specific Docs (Public Audience)

This wiki is public. The JavaScript, PHP, and Android SDK wikis are also public. The backend wiki and the backend repo are private. When writing or editing any Ruby-specific doc here:

1. Never reference the private backend wiki or any private repo. No links to backend.wiki/*, no "see the backend wiki for details." If the content is needed, inline it; otherwise omit.
2. Never reference internal backend filesystem paths (backend/public/..., backend/apiDoc/..., etc.) — readers do not have that tree. Use the gem name (convert_sdk), module/class names (ConvertSdk, ConvertSdk::Context, ConvertSdk::BucketingManager), and method names. For public specs, link to a known-valid URL.
3. Never invent URLs — and never write a link to a page in THIS wiki as a full URL. Guessed GitHub wiki URLs are a common failure: org, repo, slug and casing are all easy to get wrong. Link to another page here by bare page name — [Rule evaluation](rule-evaluation), [Configuration](Configuration), anchors included ([Configuration](Configuration#retries)). GitHub resolves a bare name against the wiki it is rendering, so it looks and behaves exactly like the full URL for a reader on github.com, and it cannot carry a wrong org or repo because it names neither. It is also the only form that works for a reader inside a Claude session: this wiki ships inside the Convert Claude plugin as a read-only mirror, and a skill's link table routes an absolute URL to "external" — so the page sitting on disk beside it is never opened, and for the wikis whose source repo is private the fallback fetch returns 404. Only a link to a different wiki stays absolute (https://github.com/convertcom/<repo>/wiki/<Page>), because there a bare name would resolve inside this wiki and land on the wrong page. If you do not know an external URL is correct, do not write it.
4. Prefer module-level and class/method references over file paths and line numbers. ConvertSdk::Context#run_experience ages better than a lib/convert_sdk/... path.
5. Ground every API claim in the actual SDK. Public module/class names, method names, keyword arguments, defaults, and enum/sentinel values must match the released convert_sdk gem — not assumptions. The public surface is the module factory ConvertSdk.create, the Client (create_context, flush/release_queues, postfork, on), and the Context (run_experience(s), run_feature(s), track_conversion, set_default_segments, run_custom_segments, update_visitor_properties, get_visitor_data, get_config_entity). Misses return frozen sentinels with a nil #key; nothing raises into the host.