croct-tech/croct

Use when writing, reading, reviewing, or debugging Croct's Contextual Query Language (CQL): audience criteria, croct.evaluate() / useEvaluation / <Personalization query> / Next.js cql tag queries, Evaluation API query bodies (/client/web/evaluate, /external/web/evaluate), and dynamic content values ("type": "dynamic", "expression"). Covers context variables (user, session, page, location, campaign, cart, device, browser, context, now/today), data types and conversions, accessors and selectors ('s, property X of, [1st], [*], [...]), tests (is, matches, is like, contains either, is between, is defined, is returning), quantifiers (some ... satisfies), macros, modifiers, event expressions (user has viewed a page, user has abandoned a cart, user has completed goal), audience estimation, and recipes. Triggers: "write an audience", "target mobile users in New York", "CQL syntax error", "audience never matches", "unavailable estimate".

Use when connecting Croct to a third-party platform or migrating to Croct from another personalization or experimentation tool. Covers Storyblok (Optimize by Croct app, @croct/plug-storyblok, Storyblok withCroct, resolveContent, croct/plug-storyblok, CroctStoriesApi), Sanity and Strapi (slot fallback, dynamic zones, metadata.contentSource), Shopify Hydrogen storefront events, Shopify custom pixel (croctPixel, PUBLIC_CROCT_SHOPIFY_PIXEL, checkout and order tracking), VTEX, Google Tag Manager data layer, Microsoft Clarity tags, HubSpot forms (hbspt.forms.create, hs-form-event), firmographic providers 6sense, Demandbase, Clearbit Reveal, and ZoomInfo WebSights (firmographics attributes, account-based audiences in CQL), and migrations from Mutiny and Ninetailed (Experience component, Contentful sunset). Triggers include cdn.croct.io/plug-integration scripts, "personalize Storyblok blocks", "track Shopify checkout", "send VTEX events", "ABM personalization", "replace Mutiny".

Use when installing or using a Croct SDK in application code: rendering slot content, evaluating CQL queries, server or client fetching, prerendering, identifying users, app ID / API key env vars, testing, or debugging. Covers JavaScript (@croct/plug, croct.fetch, croct.evaluate), React (@croct/plug-react, <CroctProvider>, useContent, <Slot>, useEvaluation, useCroct), Next.js (@croct/plug-next, fetchContent, cql, middleware/proxy, NEXT_PUBLIC_CROCT_APP_ID, CROCT_API_KEY), Vue (@croct/plug-vue), Nuxt (@croct/plug-nuxt), Shopify Hydrogen (@croct/plug-hydrogen), PHP (croct/plug-php), Laravel, Symfony, and Drupal. Triggers: slot IDs like home-hero@1, SlotContent, "Croct is not plugged in", "initial content is required for server-side rendering", "Did you forget to configure Croct's middleware?", CORS errors.

Use when designing or changing Croct content models: regular vs union components, what becomes a component, slot, structure, or primitive attribute; writing component schema JSON (structure, union, reference, text, number, boolean, list, @croct/file, @croct/richText rich text, format, choices, optional, private, position); writing content definition JSON (static/dynamic values, nullable, default, {{placeholder}} paths); slot default, localized, experience, experiment, or content group content; schema limit errors (30 attributes, 6 nesting levels, 10 union members, complexity score 50); component versioning and breaking changes (home-hero@2); refactoring (duplicate and modify, duplicate and replace, flatten and merge); Markdown in text attributes with @croct/md-lite. Phrasings: "model content for a hero", "add an attribute to the banner component", "support variations", "component is too complex", "localize the hero", "translations", preferredLocale.

Use when planning or implementing personalization or A/B testing with Croct: creating an experience (audience, slots, content, priority, scheduling, drafts), adding an experiment (A/B/n, primary goal ID, traffic allocation, variants, cross-device consistency), wiring the code it needs (slots, croct.track('goalCompleted', {goalId}), orderPlaced, leadGenerated, userSignedUp), server-side feature-flag experiments, redirect experiments, personalization recipes (UTM campaigns, ABM, search terms, location, free shipping, interests, blog readers, leads, customers, organic intent, HubSpot forms), or reading the experience, experiment, application, or workspace dashboards (probability to be best, potential loss, "Experiment in progress", "Recommended winner", "No clear winner", "Track your goal"). Phrasings: "personalize the hero for LinkedIn visitors", "A/B test this CTA", "which variant won?", "why does my experiment show no conversions?".

Use when collecting data with Croct: tracking events with croct.track, useCroct().track, or the standalone track from @croct/plug/api; choosing built-in events (goalCompleted, eventOccurred, orderPlaced, productViewed, cartModified, checkoutStarted, leadGenerated, interestShown, postViewed, userSignedUp) and knowing which are auto-tracked; writing profile or session attributes with user.edit() / session.edit() patches (set, combine, increment, custom.*); identifying users with identify, anonymize, setToken, userId, userIdResolver; signed user tokens, anonymity scope, sessions, identity resolution; sharing identity across subdomains with cookies; proxying api.croct.io via baseEndpointUrl because ad blockers drop requests; bot exclusion. Phrasings: "track a conversion", "tracking plan", "send purchase events", "events not showing up", "experiment says track your goal", "two sessions on login".

Use when calling Croct's HTTP APIs directly instead of an SDK: from a backend, edge function, serverless handler, script, data pipeline, or custom client. Covers the Content API (/client/web/content, /external/web/content, static-content), Evaluation API (/client/web/evaluate, /external/web/evaluate), Event Tracking API (/client/web/track), and Data Export API (/export/events, /export/session, /export/user, @croct/export, croct-export-client). Triggers: api.croct.io; headers X-App-Id, X-Api-Key, X-Client-Id, X-Token, X-Client-Ip, X-Suspension-Reason; API key permissions; signed user tokens; trusted origins and CORS errors; nextCursor pagination; 202 Accepted with no body; Problem Details errors under croct.help/api/ like missing-client-id, forbidden-origin, unsigned-token, invalid-query, invalid-payload; "fetch Croct content with curl", "export Croct events to a warehouse", "evaluate CQL from my server".

Use when driving the Croct CLI (croct, npx croct@latest): setting up Croct in a project with croct init, adding or removing slots and components (croct add slot, croct add component, croct remove ...), syncing generated types and fallback content (croct install, croct update, croct upgrade), editing croct.json or its version specifiers ("home-hero": "1 - 3"), authenticating (croct login, croct logout, CROCT_API_KEY, CROCT_TOKEN), running the CLI non-interactively in CI (--no-interaction, --cwd), creating API keys (croct create api-key), opening the admin (croct admin), deep links (croct://..., croct open, enable deep-link), or writing, testing, and publishing CLI templates (template.json5, croct use, croct create template, template actions such as create-resource, add-slot, download, expressions ${options.name}). Also when SlotContent<'home-hero@1'> types or slots.d.ts are stale, or default content is outdated.

Use when a task involves Croct in any way and you need orientation: what Croct is, how its concepts fit together (organization, workspace, application, component, slot, experience, audience, experiment, default and fallback content), which Croct skill to load next, or how to look up the live Croct documentation. Triggers: "Croct", croct.com, app.croct.com, docs.croct.com, croct.json, npx croct, @croct/* packages, croct/plug-* PHP packages, slot IDs like home-hero@1, "personalization management system", adding personalization or A/B testing to a site with Croct, or replacing Optimizely, VWO, Mutiny, or Ninetailed with Croct.