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

As of this writing the backend sync workflow targets only the JavaScript and PHP SDK wikis; the Ruby wiki is not yet in its target matrix. The shared docs in this wiki were copied from a sibling SDK wiki (which is itself synced from the canonical backend source) with their relative links rewritten to this wiki's URLs. When the Ruby wiki is added to the backend sync, those shared docs will be regenerated and overwritten — so continue to treat them as read-only here.

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. Guessed GitHub wiki URLs are a common failure — org, repo, slug, and casing are all easy to get wrong. If you do not know a URL is correct, do not write it. Prefer the verified wiki URLs already used across these pages (https://github.com/convertcom/ruby-sdk/wiki/<Page>).
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.