Try your first idea

In this tutorial you try two new headlines on a home page, beside the current one: you write them into the home page’s template, declare the page, look at each locally, register what goes live, and look at each in production. It follows a site whose setup is done, with the headlines of RoutingCat’s example site. You ask your agent “Try two headlines on the home page”, and it takes these steps with you.

1. Choose the shape

The idea needs one place on one page: a page home with one slot, hero, whose variants are headlines.

The current headline becomes the default, under its own key, current. The control keeps seeing it, so the measured gain compares routing with what your site shows today.
Each new idea gets a new key, here learns and shows, so that it is compared with the default at the same time, on the same traffic.

Your agent writes the headlines from what your site already says. A claim, such as a number, a testimonial or a price, must be true, so it comes from your site or from you. A headline and a button would be two slots; a redesign would be one slot holding the whole page. See Pages, variants and versions.

2. Write the slot markup

In the template that renders the home page, the headline becomes a slot holding every variant. Here it is in the example site’s home page, once push has stamped it:

      <div data-rc-page="home" data-rc-slot="hero" style="display:contents">
        <div data-rc-variant="current" data-rc-hash="214ccf813b46030bb649a04128e2863d5ace330ed9b0088cc64e18a2286cc6eb" style="display:contents">
          <h1>Route every visitor to what converts</h1>
        </div>
        <div data-rc-variant="learns" data-rc-hash="f0197a0807eb3b098f2e1fb122e5e62a89ef6da4e7fc72f8dae6b0e4b5599202" hidden data-nosnippet>
          <h1>Your pages learn what converts each visitor</h1>
        </div>
        <div data-rc-variant="shows" data-rc-hash="772f7208a1f629e488de631d7b939443bb84344293a1035ea876380fe41eaf31" hidden data-nosnippet>
          <h1>Show each visitor the page that converts them</h1>
        </div>
      </div>

The container names the page and the slot, with data-rc-page and data-rc-slot.
Each variant is a child of it, named with data-rc-variant. The default is the one without hidden; every other variant carries hidden, so a page whose script never runs shows the default alone.
Your agent writes the keys and hidden. push adds the rest: each variant’s data-rc-hash, style="display:contents" and data-nosnippet.

Build a page gives every rule of the markup.

3. Declare the page

In routingcat.config.json, the page takes its key, its routes and a path that doctor checks, and each new variant says what it tries, as its description under variants, by its address. The example site declares its home and pricing pages, and what each of their new variants tries:

  "pages": {
    "home": { "routes": ["/"], "url": "/" },
    "pricing": { "routes": ["/pricing"], "url": "/pricing" }
  },
  "variants": {
    "home/hero:learns": { "description": "Lead with learning" },
    "home/hero:shows": { "description": "Lead with each visitor's own page" },
    "home/subhead:short": { "description": "Half the words" },
    "pricing/lead:start": { "description": "Lead with the free start" },
    "pricing/trial:days30": { "description": "A longer trial" }
  }

A description never shows on your pages and makes no version: npx routingcat show home/hero:learns prints it above the variant’s version, so that you and your agent know later what each idea tried. A name and tags can go beside it.

4. Stamp it

In your repository, run:

npx routingcat push

On a site whose home page has a new slot of four variants:

$ routingcat push
lumen · 1 template · 1 slot, 4 variants
stamps    9 edits
  layouts/index.html:2   home/hero           style="display:contents"
  layouts/index.html:3   home/hero:current   data-rc-hash 58c2042d15ca…
  layouts/index.html:3   home/hero:current   style="display:contents"
  layouts/index.html:6   home/hero:oneclick  data-rc-hash c4a2d99ee3bd…
  layouts/index.html:6   home/hero:oneclick  data-nosnippet
  layouts/index.html:9   home/hero:studio    data-rc-hash 975b5d620955…
  layouts/index.html:9   home/hero:studio    data-nosnippet
  layouts/index.html:12  home/hero:best      data-rc-hash c37fb91bad3a…
  layouts/index.html:12  home/hero:best      data-nosnippet
partial   layouts/partials/routingcat-head.html: written
· routingcat push registered nothing: it registers in CI, with GitHub's token once routingcat link github links this site to its repository, or with the site's deploy key in ROUTINGCAT_DEPLOY_KEY, and neither is here. From this machine, routingcat push --env production registers production once you confirm the plan it shows. Commit what it changed.  (D72)

It reads your templates as the config’s sources name them, checks each slot, stamps each variant’s hash, and writes the head partial again, which now lists the page, its slot and its variants. On your machine, it registers nothing, and says so: commit what it changed, the template and the partial together. Your CI’s push --check fails on a template or a partial that push would still change.

5. Look at each variant locally

Serve your site on your machine, or on any host your config doesn’t list: there the page runs in development mode, shows the defaults and records nothing. Open the home page with ?rc=hero:learns at the end of its URL: it shows that headline, with a badge naming it, until you open it with ?rc=off. The choice lasts for the browser tab. It works for any variant the head partial lists, so run push after each edit.

6. Check what will go live

npx routingcat plan

On the same site:

$ routingcat plan
lumen · this code against production (dp_01m3yfqdsgfkr9jahvnyvk6gaa, commit 4be1c07) · contract 1.0

home  new page · route / · objective signup, 24 h (from routingcat.config.json)
  hero  new slot · default current
    + current   "Edit photos like a pro"                  the default, which the control always sees
    + oneclick  "Pro-level photo edits in one click"      scorecard against current
    + studio    "Your photos, studio-ready"               scorecard against current
    + best      "Make every photo your best one"          scorecard against current

In production this goes LIVE, with routing within about 2 minutes:
  the control keeps seeing the defaults · the random slice of visits is split evenly
  the rest are routed toward signup, as the model learns which variant works for whom
A production push applies only what its templates changed since the previous production push.
A push in CI on another branch registers these versions as a preview and changes nothing live.

limits    4 of 100 variants · 1 of 20 slots · 4 of 1,000 combinations
          the site: 3 live variants, the defaults not counted, of the 10 the Hobby account's sites share
valid     push will accept this                                                   (exit 0)

plan reads your templates and config as push does, compares them with production, and registers nothing:

each new headline gets a scorecard against current from the moment it goes live;
on Hobby, it counts the site’s live variants, the defaults not counted, toward the 10 the account’s sites share: past them, a new variant is held rather than served;
exit code 0 means push will accept the page; 1 means it would reject it, and the line says what to fix.

Your agent tells you what will go live, in plain words, before it does.

7. Deploy and register

Commit and deploy as usual, then register the deploy as your site does:

In your CI, the workflow’s push --check passes before the deploy, and its push right after the deploy registers it, ending with RoutingCat’s receipt: routingcat LIVE home: …, routing within about 2 minutes. A host’s deploy script that pushes does the same at the end of the deploy.
Without either, right after the deploy, npx routingcat push --env production shows you the plan; once you agree, your agent runs it again with --confirm and the digest it printed. Set up RoutingCat shows each step.

This push changes what visitors see. Within about 2 minutes, 90% of your visitors are routed between the three headlines; the control keeps seeing current.

On Hobby, routing waits for a card on file. Until the site’s owner adds one, the receipt reads routingcat NOT LIVE routing waits for a card on file: add one at …, nothing charged, and the page keeps showing current. Routing starts within about 2 minutes of the card, with no new push: see Add a card to start routing.

npx routingcat doctor now adds three checks for the page: home live, first decision and first render beacon. The last two arrive once a browser shows the page: open it in yours.

8. See a variant in production

npx routingcat preview home/hero:learns

It prints a signed link, valid for one hour, that opens your home page with that headline and a small preview badge. On your site, the link carries its token after #, so it never reaches your server or your logs. The visit stays out of results, and your own variants stay as they were. See Change, preview and deploy.

9. Watch the first days

Routing learns once a day on Hobby, and on Pro as conversions mature, at most hourly, from visits whose window has closed. With the 24-hour window, a visit starts to shape routing a day or two later on Hobby, about a day later on Pro.
New headlines start cautiously, at signal New, with a limited share of visits until evidence builds. A small random slice of visits is always split evenly.
The measured gain starts wide. It shows no range while visits are few, then a range; while that range spans zero, the direction isn’t known yet.
Wait for the evidence. Checking every day and acting on the first good day overstates gains.

Ask your agent “How is it going?”: it runs npx routingcat status and says each number with how sure it is. See Read and explain results. The page’s screen on your dashboard shows the same figures: see Read the dashboard. Once one headline is clearly ahead, promoting it makes it the default; see Change what’s live.