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. 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.