Blogs

A note on using async computed fields with Optimizely Graph

Mon, 09 Nov 2026 06:44:00 GMT

Computed fields can be async, but do they work smoothly with the Graph C# SDK?

Visual Builder without Next.js, Part 2: The Routing Decision Travels, the Engine Contract Doubles

Sun, 08 Nov 2026 00:00:00 GMT

One content tree, two engines, one edge: a strangler for Astro and Next.js on CMS 13. The same routing decision in a Next.js proxy and in a Cloudflare Worker, measured with the checks from part 1.

Stride on SaaS CMS and Frontend Hosting, with Claude Code

Sat, 07 Nov 2026 21:42:54 GMT

This post shows how I set up the Optimizely Stride sample site on a new Optimizely CMS (SaaS) instance. The front end is on Optimizely Frontend Hosting. It deploys from the CLI and from GitHub Actions. I used Claude Code to do most of the work.

Stride is a Next.js sample site from Optimizely. Optimizely announced it in the CMS (SaaS) release notes on 23/07/2026. It uses the Content JS SDK, Visual Builder compositions and Tailwind CSS.

The Stride README gives the basic steps. On a new instance, I found seven problems that the README does not cover. This post gives each problem, its cause and the fix. At the end, there is a prompt that you can give to Claude Code to do the same setup.

Content goes from the CMS to Graph when you publish it. The site reads the content from Graph. Code goes from your computer or GitHub Actions to Frontend Hosting.

What you need

A CMS (SaaS) instance with Optimizely Graph. You need admin access to create API keys and import data.
A Frontend Hosting project in the DXP management portal. The plan shows as "SaaS Frontend Host". It has Test1, Test2 and Production environments.
Node.js 22 or 24. Stride asks for ^22.23.4 || ^24.22.1. I used 22.22.3. The install gave a warning, and the build worked.
npm or yarn. Do not use pnpm. Frontend Hosting accepts only package-lock.json or yarn.lock.
A GitHub repository, if you want to deploy from GitHub Actions.

1. Create the project with cms-create-app

Use the @optimizely/cms-create-app package to create the project. Do not copy the templates/stride folder from the content-js-sdk repository. In that repository, the SDK and the CLI are workspace:* dependencies. The Frontend Hosting deploy does not accept these. The package changes them to the latest published versions.

npx @optimizely/cms-create-app@1.1.0 stride-saas --template nextjs-stride --pm npm --ci none

This gave me @optimizely/cms-sdk 3.1.0, @optimizely/cms-cli 3.1.0 and Next.js 16.3.6. Version 1.1.0 of the package was published on 03/11/2026.

The package does not include two files. Add them before your first commit:

.gitignore. Copy it from the template. Add /node_modules/. Add !.env.example, because the .env* rule also hides that file.
.env.example. Copy it from the template. It lists all the variables that Stride and the CLI use.

I also added a .gitattributes file with * text=auto eol=lf. I work on Windows, and the platform builds on Linux.

2. Connect the project to the CMS

In the CMS, go to Settings → API Keys. Copy the Graph single key. Create an API key for the CLI. Put these values in .env:

Variable	Value
OPTIMIZELY_CMS_URL	The URL of your instance
OPTIMIZELY_GRAPH_SINGLE_KEY	Settings → API Keys
OPTIMIZELY_CMS_CLIENT_ID, OPTIMIZELY_CMS_CLIENT_SECRET	The API key that you created
APPLICATION_HOST	The URL of the site (see step 6)

Give the API key access rights before you push the configuration:

Go to Settings → Set Access Rights.
Select the root.
Select Apply settings for all subitems.
Give the API key full permissions.

Note: I did not do this the first time. The push sent the content types and display templates. Then it stopped with a 403 error ("Required access is 'create'") when it tried to create the start page.

Push the configuration:

npm run config:push

This command sends the content types and display templates to the CMS. It also creates the Stride application and an empty Home page. The empty Home page becomes the start page. Step 3 shows why this is a problem.

3. Import the content and fix the start page

Go to Settings → Import Data.
Upload stride_content.episerverdata.
Select the root as the destination.
Select Update existing content items with matching ID.
Start the import.

Note: The README gives the file name ExportedFile.episerverdata. The file in the template is stride_content.episerverdata.

My import showed "Import failed". But the summary showed that all 34 content items, 26 content types and 6 style settings were imported. The three errors were all about the Validators property of one form. Step 4 gives the cause.

Problem: The site shows a 404 error for /en.

Cause: config:push created an empty Home page and made it the start page. The import does not replace this page. The imported Home page gets the name "Home(2)", and all the pages go under /en/home2/. The empty Home page is not published, so Graph has no page at /en.

Fix:

Go to Settings → Applications → Stride.
Change the start page to Home(2).
Delete the empty Home page.

When I checked Graph again, the pages had the correct URLs.

Then change optimizely.config.mjs. If you do not, the next config:push sets the start page back to the empty Home page. Remove the content array. Set entryPoint to the imported Home page:

applications: [
  {
    key: 'stride',
    // The imported Stride start page, not the empty "home" that the template creates
    entryPoint: 'cms://content/a8ff42c351e74f65a2f26223950c54ab',
    // ...
  },
],

This GUID is the Home page in stride_content.episerverdata, so it is the same on all instances.

4. Register only the Forms elements that your instance has

Problem: The home page works, but most other pages show a 500 error. Graph returns six errors, for example:

Unknown type "OptiFormsNumberElement". Did you mean "OptiFormsSubmitElement", ...

Cause: Stride calls initForms() in lib/initialization.ts. This function registers all ten Optimizely Forms element types. The SDK then puts all ten types in the query for each page that can contain a form. My instance had only four of them: the form container, Textbox, Textarea and Submit. If one type is unknown, Graph rejects the full query.

To see the types that your instance has, run npx optimizely-cms-cli config pull -r -j. This difference in Forms versions is also the probable cause of the Validators errors in step 3.

Fix: Do not call initForms(). Register only the types that your instance has:

initContentTypeRegistry([
  // ...Stride's own types
  OptiFormsContainerDataContentType,
  OptiFormsTextboxElementContentType,
  OptiFormsTextareaElementContentType,
  OptiFormsSubmitElementContentType,
  OptiFormsDependencyRuleContentType,
  OptiFormsConditionContentType,
]);

initReactComponentRegistry({
  resolver: {
    // ...Stride's own components
    OptiFormsContainerData: FormContainer,
    OptiFormsTextboxElement: FormInput,
    OptiFormsTextareaElement: FormTextarea,
    OptiFormsSubmitElement: FormSubmit,
  },
});

Restart the dev server after this change. The registry is set one time, when the server starts. After the restart, all 16 Stride pages returned status 200, and the Contact Us form showed correctly. When your instance gets the other Forms elements, use initForms() again.

5. Preview and drafts do not need the Graph app key

The setup asks only for the Graph single key. The single key gives only published content. Older headless builds used the Graph app key and secret to get drafts.

The SDK uses preview tokens. The Stride application has usePreviewTokens: true. When an editor opens a page in edit mode or in Visual Builder, the CMS opens the /preview route of the site. The URL contains a preview_token that is valid for a short time. getPreviewContent() sends this token to Graph, and Graph returns the draft. When the editor saves, the CMS sends a new token, and the SDK uses it.

Visual Builder in the CMS test environment. The preview on the right is the Stride site on Frontend Hosting Test1.

You need the app key and secret only for server-side requests outside an editor session, with the SDK option auth: { type: 'hmac' }. Examples are restricted content, deleted or expired items, and search that includes drafts. Stride does not need these. The app key and secret can read all content in Graph. Do not put them in a public site unless a feature needs them.

6. Deploy to Frontend Hosting from the CLI

CLI 3.1.0 has a deploy command. In the Frontend Hosting beta, you made a zip file with the name <name>.head.app.<version>.zip. Then you uploaded it with the EpiCloud PowerShell module. Now you use one command:

npm run deploy -- --env Test1

The command does these steps:

It checks the project.
It runs next build on your computer. A build error stops the deploy before the upload.
It makes the zip file. The zip file does not include build output, node_modules, .env files or the content export.
It uploads the zip file with the DXP Deployment API.
It starts the deployment, waits for it, and completes it.

Get the credentials from the API tab in the DXP management portal. Put them in .env as OPTIMIZELY_DXP_PROJECT_ID, OPTIMIZELY_DXP_CLIENT_KEY and OPTIMIZELY_DXP_CLIENT_SECRET.

To check the zip file before you upload it, run npx optimizely-cms-cli deploy --output ./out. This command writes the zip file to a local folder. It does not upload it.

Use the front-end environment that matches your CMS environment

Problem: The deploy to Test1 was successful, but all published pages showed a 404 error. Visual Builder preview on Test1 worked.

Cause: Each Frontend Hosting environment is linked to a CMS environment. The platform gives each front-end environment the CMS URL and the Graph keys of its linked CMS environment. My Test1 was linked to the CMS test environment. I set up Stride in the CMS Production environment, so Graph on Test1 had no Stride pages. Preview worked because the CMS sends its own preview token with each preview request.

I found this with a temporary API route. The route showed the CMS URL that the site received, and a short hash of the Graph key. Both were different from the values in my .env.

Fix: Put the content in the CMS environment that is linked to your front-end environment. You can deploy to the front-end environment that is linked to the CMS environment with your content, or copy the content to the other CMS environments. I copied the content to the CMS test environment, which is linked to Test1.

Copy the content to the other CMS environments

Do these steps in each CMS environment that does not have the content. I did them in the CMS test environment, which is linked to Test1.

Create an API key for the CLI, and give it full access rights on the root.
Import stride_content.episerverdata at the root. Do this before the first config:push.
Push the configuration with the CMS URL, the API key and the APPLICATION_HOST of that environment.

I keep the values for the test environment in a second file, .env.cms-test, and use a second script:

"config:push:test": "node --env-file=.env.cms-test node_modules/@optimizely/cms-cli/bin/run.js config push optimizely.config.mjs"

The CLI loads .env with dotenv, which does not replace variables that are already set. So the values from .env.cms-test are used. In optimizely.config.mjs, the primary host comes from APPLICATION_HOST, so one file works for all environments:

const host = new URL(process.env.APPLICATION_HOST.trim()).host;
// ...
hosts: [{ authority: host, type: 'primary', preferredUrlScheme: 'https' }],

If you import before the first push, the empty Home page from step 3 does not occur. The push creates the application with the imported Home page as the start page. Graph showed the new URLs a few minutes later. Test1 then returned status 200 for all pages, without a new deploy, because the site reads Graph at request time.

Set the hostname and APPLICATION_HOST

Graph makes all page URLs from the primary host of the application. The SDK finds a page only when APPLICATION_HOST is the same as that host. If they are different, all pages show a 404 error.

Get the hostname of the front-end environment from the Hostnames tab in the DXP management portal.
In optimizely.config.mjs, set this hostname as the only host, with the type primary.
Run npm run config:push.
In your local .env, set APPLICATION_HOST to https://<hostname>.

Local development still works, because APPLICATION_HOST is only a filter for Graph. CMS preview now opens on this front-end environment.

Note: Do not add localhost:3000 as a second host. Headless applications accept only Primary, Preview and Media hosts. The CMS rejects other types.

Add APPLICATION_HOST as an App Setting

In the DXP management portal, open the App Settings tab. Add APPLICATION_HOST for each environment, with the hostname of that environment. App Settings apply at the next deployment, so add them before you deploy.

Do not add the CMS URL or the Graph keys. The platform gives these five variables to the build and to the site (Frontend Hosting documentation):

OPTIMIZELY_CMS_URL
OPTIMIZELY_GRAPH_GATEWAY
OPTIMIZELY_GRAPH_SINGLE_KEY
OPTIMIZELY_GRAPH_APP_KEY
OPTIMIZELY_GRAPH_SECRET

The App Settings list does not show these variables. When I tried to add OPTIMIZELY_CMS_URL, the portal said that the name already exists.

7. Deploy from GitHub Actions

The cms-create-app package can make a workflow with the --ci github option. I added my workflow later. It uses the same file, with two changes. It does not deploy when a commit changes only Markdown files. A manual run lets you select the environment.

name: Deploy to Optimizely

on:
  push:
    branches: [main]
    paths-ignore: ['**.md', '*.episerverdata']
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [Test1, Test2, Production1]
        default: Test1

concurrency:
  group: optimizely-deploy-${{ inputs.environment || 'Test1' }}
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_ENVIRONMENT: ${{ inputs.environment || 'Test1' }}
      OPTIMIZELY_DXP_PROJECT_ID: ${{ secrets.OPTIMIZELY_DXP_PROJECT_ID }}
      OPTIMIZELY_DXP_CLIENT_KEY: ${{ secrets.OPTIMIZELY_DXP_CLIENT_KEY }}
      OPTIMIZELY_DXP_CLIENT_SECRET: ${{ secrets.OPTIMIZELY_DXP_CLIENT_SECRET }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx optimizely-cms-cli deploy --env "$DEPLOY_ENVIRONMENT" --yes

Add the three OPTIMIZELY_DXP_* values as repository secrets. Keep cancel-in-progress: false. If you cancel the job, the deployment on the platform does not stop.

I do not run config:push in CI. It needs the CMS client secret in GitHub, and it changes the content model at each merge. I run it myself when a content type changes.

The prompt

Use this prompt with Claude Code to do the same setup. It contains all the fixes in this post. It has two rules. The agent does not handle your secrets, and it stops for you at each step in a portal. Change the folder and repository names. Then start Claude Code in an empty folder and paste the prompt.

Set up the Optimizely Stride sample site on a new Optimizely CMS (SaaS) instance.
Deploy the front end to Optimizely Frontend Hosting. Do one step at a time. Stop for
me at each step that needs the CMS UI, the DXP management portal or a secret.

Rules
- Do not ask me to paste keys, secrets or tokens into the chat. I put them in .env,
  in the portal or in GitHub. Do not print .env values. Only check that each one is set.
- Read the current sources before you use what you remember: the Stride template and
  @optimizely/cms-create-app in github.com/episerver/content-js-sdk, and the source of
  the CLI deploy command. Tell me if a step below does not agree with them.
- Commit after each step. Do not commit .env.

1. Create the project
   - Run: npx @optimizely/cms-create-app <folder> --template nextjs-stride --pm npm --ci none
   - Use npm. Frontend Hosting accepts only package-lock.json or yarn.lock.
   - If .gitignore or .env.example is missing, copy it from templates/stride.
     Make sure that .gitignore includes /node_modules/ and does not hide .env.example.
   - Add .gitattributes with "* text=auto eol=lf".
   - Create a private GitHub repository <owner>/<name> and push.

2. Connect to the CMS
   - Create .env from .env.example. Tell me which values to add.
   - Tell me to give the CLI API key full access rights on the root (Settings >
     Set Access Rights, apply settings for all subitems).
   - Run npm run config:push.

3. Import the content
   - Tell me to import stride_content.episerverdata at Settings > Import Data. Use the
     root as the destination. Select "Update existing content items with matching ID".
   - Errors about the "Validators" property of one form are not a problem.
   - Tell me to set the start page of the Stride application to the imported Home(2)
     page (Settings > Applications > Stride) and to delete the empty Home page.
   - In optimizely.config.mjs, remove the "content" array. Set the Stride entryPoint to
     the imported start page: 'cms://content/a8ff42c351e74f65a2f26223950c54ab'. First
     make sure this GUID is the start page in stride_content.episerverdata.
   - Send a query to Graph with the single key. Make sure the pages are published and
     the URLs start with /en/ and not /en/home2/.

4. Run the site and check all pages
   - Start the dev server. If HTTPS needs "mkcert -install", do not run it. Use http
     and tell me.
   - Get all page URLs from Graph. Request each page and show me the status codes.
   - If Graph reports unknown OptiForms*Element types, compare the types on the
     instance (npx optimizely-cms-cli config pull -r -j) with the types that
     initForms() registers. Replace initForms() with registration of only the Forms
     types that the instance has. Restart the dev server after the change.

5. Frontend Hosting
   - First do a test: npx optimizely-cms-cli deploy --output <temporary folder>.
     Make sure the zip file has no .env file and no node_modules folder.
   - Ask me which front-end environment is linked to the CMS environment that has
     the content, and for its hostname (Hostnames tab in the portal). In
     optimizely.config.mjs, make it the only host, with the type primary. Headless
     applications accept only Primary, Preview and Media hosts. Run config:push.
     Set APPLICATION_HOST in .env to https://<that hostname>.
   - Tell me to add APPLICATION_HOST as an App Setting for that environment. The platform
     gives OPTIMIZELY_CMS_URL and the Graph keys.
   - Run npm run deploy -- --env <that environment>. Then check the live pages and the preview
     from the CMS. If the published pages show 404 but preview works, the front-end
     environment is linked to a CMS environment that does not have the content.

6. GitHub Actions
   - Add a workflow that runs npx optimizely-cms-cli deploy when I push to main
     (Test1), and on a manual run (I select the environment). Set cancel-in-progress
     to false. Tell me to add the three OPTIMIZELY_DXP_* repository secrets.
     Do not run config:push in CI.

At the end, give me a short list: what is done, what you checked, and what is not done.

Lessons

Change optimizely.config.mjs after the import. Each config:push writes the start page and the hosts from this file.
If one page works and the other pages show a 500 error, read the GraphQL errors. One unknown type stops the full query.
Find out which CMS environment each front-end environment is linked to before you deploy. The platform supplies the CMS URL and the Graph keys, and you cannot change them in App Settings.
Make APPLICATION_HOST and the primary host the same.
The deploy is fast on your computer and slow on the platform. The build, zip and upload took a few minutes. Most of the time is the build on the platform.

Claude Code read the SDK and CLI source in node_modules to find the cause of each problem: the Forms registration, the preview tokens and the start page in config:push. It sent queries to Graph to see which pages were published. It stopped at each step that needed me in a portal or needed a secret.

What changed in Optimizely LanguageManager 5.5.4

Sat, 07 Nov 2026 08:20:49 GMT

LanguageManager 5.5.4 for Optimizely CMS 12 has no public release notes. I compared it to 5.5.3 and found no new features, but an axios upgrade that fixes 36 known vulnerabilities.

Log your Optimizely Graph queries

Fri, 06 Nov 2026 07:10:00 GMT

Log Graph calls from .NET in in a way where it's easy to copy the query and parameters to GraphiQL.

Introducing Optimizely Feature Flagging: Flag Your Content Model

Tue, 03 Nov 2026 11:30:18 GMT

Feature flag Optimizely CMS content properties without code changes: visibility, validation, editors and whole content types, with any flag provider.

Introducing Optimizely Content Seeder: Seed Your CMS from Code

Tue, 03 Nov 2026 11:30:18 GMT

Seed Optimizely CMS 12 and 13 with pages, blocks, media and Visual Builder sections from a fluent C# definition, with optional AI-written content.

Optimizely DXP Alert: Are You Affected by the October 2026 Node.js Security Vulnerabilities?

Mon, 02 Nov 2026 19:12:54 GMT

On October 27, 2026, Optimizely published a security advisory regarding recently disclosed Node.js vulnerabilities affecting Node.js 22.x, 24.x, and 26.x release lines. Optimizely confirmed there...

The post Optimizely DXP Alert: Are You Affected by the October 2026 Node.js Security Vulnerabilities? appeared first on Madhu Anbalagan's Blog.

Build Your First Opal Tool in C#

Mon, 02 Nov 2026 11:14:19 GMT

Optimizely ships a C# SDK for building custom

Introducing Publishing Timeline for Optimizely CMS 13

Mon, 02 Nov 2026 09:36:42 GMT

When working with scheduled content in Optimizely CMS, having a clear overview of what's going live and when can be really helpful, especially when managing content across multiple languages and timezones.

Following my previous add-on for scheduling content across different timezones, I wanted to explore another part of the publishing experience: making it easier for editors to see what's coming up.

That led me to build Publishing Timeline, a free, open-source add-on for Optimizely CMS 13.

What does Publishing Timeline do?

Publishing Timeline adds a panel below the native Workflow Status gadget on the CMS Dashboard. It appears when the Scheduled tab is selected, without replacing or modifying the existing gadget.

It provides two ways to explore upcoming publications.

Table view

The table provides a list of scheduled content, including the publishing date, language, and who last modified each item. Editors can filter the results and open content directly in the CMS editor.

Publishing Timeline — Table view

Calendar view

The calendar displays scheduled publications in a monthly view, making it easier to see what's planned for a particular day or across the month. When multiple items are scheduled for the same day, the +N more option opens a popup showing additional publications and their scheduled times.

Publishing Timeline — Calendar view with additional scheduled items

Both views share the same language, date, and timezone filters, so editors can switch between them without losing their selections.

Working across timezones

One of the features I wanted to include was the ability to view scheduled publishing times in different timezones.

For example, if you're coordinating content across Cairo, London, and New York, you can switch the timeline to see when each item is scheduled to go live in the selected timezone.

This only changes how the publishing times are displayed. The actual publishing schedule remains unchanged.

Getting started

Publishing Timeline supports Optimizely CMS 13.4.0 and later (below 14.0.0) and .NET 10.

The add-on is now available on the Optimizely NuGet feed.

Install the package using the .NET CLI:

dotnet add package Mardy.Optimizely.PublishingTimeline --version 1.0.0

Make sure the Optimizely NuGet feed is configured as a package source in your project or development environment.

No additional startup configuration is required. After installation, open the CMS Dashboard and navigate to Workflow Status → Scheduled. The Publishing Timeline panel will appear below the native gadget.

The add-on is read-only and doesn't change how Optimizely schedules or publishes content.

Source code and feedback

The project is open source under the MIT license.

GitHub: Mardy.Optimizely.PublishingTimeline

NuGet package: Optimizely NuGet feed (v1.0.0)

I'd be happy to hear your feedback or ideas for future improvements!

What else changed in Optimizely CMS 13.5.1

Sun, 01 Nov 2026 10:57:23 GMT

Optimizely CMS 13.5.1 lists a single Graph fix in its release notes. I decompiled the packages and found more: a new setting that lets editors find expired content, and more!

New logo and login page in Optimizely CMS 13.5

Fri, 30 Oct 2026 19:56:21 GMT

CMS 13.5.0 quietly ships a new logo and a redesigned login page.

Is your website agent-ready? Using Cloudflare's readiness tool to assess your website

Thu, 29 Oct 2026 17:55:56 GMT

One of my friends and fellow MVPs, Minesh Shah recently blogged about optimising one of his websites for full AX and agent readiness https://www.linkedin.com/pulse/designing-ax-what-agent-ready-website-actually-needs-minesh-shah-woi4e/ and this led me to have a look at some of my own sites and also to re-explore what tools are available. I found this amazing Cloudflare tool that's been around for a number of months. It can really help guide the path between assessment of agent readiness and action, as it also generates AI prompts to help you solve the gaps.

In this blog post, I'll go through a little bit about agent readiness, and also how to use the tool and how to connect it into your AI harness using the skill (it has an MCP too)

Part one: the visitor you didn't design for

For twenty-five years we have built websites for two audiences: people, and the search engines that send people to us. Every navigation decision, every page template and every SEO checklist assumes that, sooner or later, a human being is going to look at the page.

That assumption is breaking. A growing share of the research, comparison and shortlisting that used to happen on our sites now happens inside an AI assistant. A customer asks ChatGPT, Claude, Gemini or Copilot to compare three products, summarise a returns policy or find a supplier that meets a specification. The assistant goes out, reads the web on their behalf, and comes back with an answer. Sometimes that answer includes a link to you. Often the customer acts on it without ever seeing your homepage.

In my last post on WebMCP I looked at the far end of this journey: giving agents structured actions they can take on your site. This post is about the step that comes before any of that. Before an agent can act on your site, it has to be able to find it, read it and understand what it is allowed to do with it. That is what being agent-ready means, and most sites, including plenty of well-built Optimizely sites, are not there yet.

Why this is a leadership conversation, not just a developer ticket

It is tempting to file this under "technical SEO" and hand it to the development team. That undersells it. Agent-readiness raises questions that belong with marketing, digital and legal leadership as much as with engineering:

Do we want AI assistants to recommend us? If so, the crawlers that feed AI answers need to be able to reach and read our content.
Are we happy for our content to train AI models? That is a separate decision from appearing in AI answers, and most organisations have never made it explicitly.
What does an agent see when it reads our product and service pages? If it can only parse half the page, it will fill the gaps from somewhere else, possibly a competitor or an out-of-date review.
Who owns this? Today, in most organisations, the honest answer is "nobody", which means the decision is being made by default settings.

The sites that will do well in the next few years are the ones that make these choices deliberately rather than discovering them by accident.

The business benefits of getting it right

Be found

Appear in the AI answers where customers now research and shortlist.

Be described accurately

Content agents can read means they get your story right.

Own your AI policy

Decide search, AI answers and training separately, in machine-readable form.

Serve agents for less

Lightweight Markdown is cheaper to serve and easier to use accurately.

Ready for agentic commerce

Discovery and readability come before any agent can check out.

Measure progress

A 0–5 readiness score leadership can baseline, target and track.

Quick wins first

The early levels are mostly configuration, not new development.

→

Start today

Scan your site in under a minute and share the result internally.

Treat it like mobile-friendly in 2012

There is a useful parallel with the shift to mobile. For a few years, a mobile-friendly site was a differentiator. Then it became table stakes, and the sites that hadn't adapted were quietly penalised. Agent-readiness is on the same curve, and we are early on it. The standards are still settling and the scoring will change, but the direction is clear. The cost of starting now is low; the cost of starting late is being invisible to a growing share of your customers' journeys.

Part two: how to measure it and fix it

The good news is that you no longer have to guess where you stand. Two tools make this practical.

Step 1: Scan your site with isitagentready.com

Is It Agent Ready? is a free scanner from Cloudflare. Enter a URL and it runs a set of checks against the emerging standards for AI agents, grouped into five categories:

Category	What it looks at
Discoverability	robots.txt, sitemap, Link response headers, DNS for AI Discovery (DNS-AID)
Content accessibility	Whether the site returns Markdown when an agent asks for it
Bot access control	AI bot rules in robots.txt, Content Signals, Web Bot Auth
API, auth, MCP and skill discovery	API Catalog, OAuth discovery, MCP Server Card, A2A Agent Card, Agent Skills index, WebMCP and related standards
Commerce (scored only for e-commerce sites)	Agentic payment and commerce protocols such as x402, MPP, UCP and ACP

The result is a readiness level from 0 to 5:

Level	Name	What it takes
0	Not Ready	Fails the basic checks
1	Basic Web Presence	Two of: robots.txt, sitemap, Link headers
2	Bot-Aware	Level 1, plus AI bot rules and Content Signals in robots.txt
3	Agent-Readable	Level 2, plus Markdown content negotiation
4	Agent-Integrated	Level 3, plus one of: MCP Server Card, A2A Agent Card, Agent Skills index, API Catalog
5	Agent-Native	Level 4, plus two of: Web Bot Auth, all integrations, auth metadata

The most useful part of the report is the "how to implement" section: for each failing check it gives you a ready-made prompt to paste into a coding agent such as Claude Code, Cursor or GitHub Copilot. As Cloudflare points out on the page, these are AI-generated recommendations, so treat them as a starting point and review them like any other change.

My advice: run it against your production site today. It takes under a minute, and the result is usually a useful conversation starter with stakeholders.

Step 2: Bring it into your workflow with the agent-ready-cloudflare skill

The web scanner is great for a one-off check. For ongoing work, and especially if you look after more than one site, the agent-ready-cloudflare skill is the more powerful option. It is a community-published Agent Skill that wraps the same scanner so you can drive it from Claude (or any agent that supports skills).

What it gives you:

Scanning from your agent. Ask "scan example.com for agent readiness" and the skill calls the scanner's API and produces a structured Markdown report: your level, a pass/fail summary per category, and what you need for the next level.
Fix prompts for every failing check. The scanner's API only returns an implementation prompt for the next level up. The skill includes templates for all the checks, so its report rebuilds the full set of web-UI style prompts (goal, issue, fix, links to the relevant RFCs and specs) for everything that fails.
25 implementation sub-skills. Each standard (robots.txt, Content Signals, Markdown negotiation, Link headers, API Catalog, MCP Server Card, Agent Skills index, WebMCP and so on) has its own short guide covering requirements, the Cloudflare shortcut where one exists, and how to validate.
Batch scanning. It documents how to scan a list of domains with a polite delay between requests, which is ideal for agencies, multi-brand groups or anyone running several Optimizely sites.

The scanner is also exposed as an MCP server (https://isitagentready.com/mcp, with a scan_site tool), so you can connect it directly to an MCP-capable agent if you prefer.

A practical workflow looks like this:

Install the skill in Claude.
Ask it to scan each of your sites and save the reports.
Pick the target level for each site (Level 3 is a sensible first goal).
Hand the generated fix prompts to your development team, or to a coding agent working in your solution, and review the output.
Re-scan to confirm the checks now pass, and repeat on a regular cadence.

Start today

Run the scan, share the result, and agree who owns your AI content policy. The report and the skill will tell you exactly what to fix; the harder and more valuable work is deciding what you want agents to be able to do with your site.

How can Niteco help you?

Niteco is the largest global certified Optimizely CMS and Commerce partner, with deep expertise in the Optimizely Agent Platform.

Optimizely

The largest global partner. Powered by technical excellence and innovation. Accelerated by AI.

400+

AI-trained experts

Certified by leading platforms like Optimizely, Microsoft, Contentful & Adobe.

2000+

Successful projects

We have vast experience from years of delivering digital platforms for clients in diverse sectors.

Optimizely MVPs

Largest team with OMVPs. Meaning the best & most experienced Optimizely minds will work with you.

As Optimizely's largest certified partner in Optimizely CMS, Commerce, and the agent platform, we can help you with any of your strategic initiatives globally around content, commerce, or your organisational AI.

If you would like help making your Optimizely site agent-ready, get in touch with us at Niteco: https://niteco.com/contact-us/

Visual Builder without Next.js, Part 1: What Astro Has to Rebuild on CMS 13 PaaS

Thu, 29 Oct 2026 13:16:53 GMT

Series: Part 1: What Astro Has to Rebuild on CMS 13 PaaS · Part 2: Does It Survive DXP? (Redis-backed ISR, Graph webhooks, Cloudflare and preview at scale)

Status: built and tested in October 2026 against an Alloy-based CMS 13.4.2, then 13.5.0, with Optimizely Graph, @optimizely/cms-sdk and @optimizely/cms-cli 3.1.0-beta.0, Astro 7.4.2 and Node 24.19.0. The three problems that cost the most were reproduced again on 29 October against the packages as published on npm. Everything here is either measured, read in the SDK's source and guides, or a design choice; where it matters, the text says which. The code, the checks and the CMS setup notes are in the companion repository, pino-labs/astro-visual-builder-cms13.

The question

Do we have to pick Next.js to get Visual Builder? No. Astro renders it. But rendering was the easy part. Taking Next.js away also takes away what it quietly does around the SDK, and each of those pieces has to be supplied by hand: who owns the content model, how a composition becomes HTML, how a draft reaches the preview frame, which application a path belongs to, and how one editor's preview stays out of a visitor's page.

"Without Next.js" does not mean without React: the demo deliberately mixes .astro, React and Svelte components behind one registry. This part is about what had to be rebuilt. Part 2 asks whether the same architecture survives production on DXP: Redis-backed ISR, Graph webhooks, Cloudflare and preview at scale.

What changed, and what I found in practice

Two releases opened the door. On 31 August Optimizely added Astro to DXP front-end hosting, and on 24 September the CMS (SaaS) release notes for JavaScript SDK 3.0 called the SDK core framework-neutral and published an Astro sample. The SDK's README still positions React and Next.js as its first-class integrations; what the core offers Astro is primitives, not an integration.

The version boundary matters in practice. At the time of testing, the framework-neutral entry point, @optimizely/cms-sdk/core, and the platform: 'paas' option were only available in the 3.1.0 beta: latest is 3.0.2, and its package exports neither. In the packages I inspected, both first appear in 3.1.0-beta.0, published on 20 October under the beta tag. The Astro sample takes the SDK from its own monorepo (workspace:*). Copy it into a project with 3.0.2 and its Svelte route, which is built on @optimizely/cms-sdk/core, does not resolve, because 3.0.2 does not export that entry point. Everything below runs on the beta, pinned to the exact version; when 3.1.0 ships, re-run the checks before you upgrade.

Before you start: CMS 13 PaaS with Graph, 13.4.2 or later, and Node 22.23.4 or later on the 22 line, or Node 24 or 26 (Astro 7.4.0 raised the floor to 22.22.0, and the 7.4.2 patch to 22.23.4). The 13.4.2 minimum is not an Astro requirement: 13.4.1 fixes a culture-specific data-loss bug (CMS-57780), and the 13.4.2 database update restores the values lost before the fix. I tested on CMS 13.4.2 and 13.5.0 with Astro 7.4.2 on Node 24.19.0. DXP front-end hosting is needed only for the production checks in part 2. This is not a CMS 12 tutorial: the implementation depends on the CMS 13 REST API and the CMS 13 Graph schema.

The architecture

CMS 13 owns composition: editors arrange sections, rows, columns and elements in Visual Builder and pick display templates. Graph serves that composition as data. Astro turns it into HTML through one component registry, where .astro, React and Svelte components sit side by side and render on the server; only components marked as islands (client:*) are hydrated in the browser.

Figure 1. CMS 13 owns the composition, Graph serves it as data, Astro renders it through one registry. Only components marked as islands are hydrated in the browser.

Who owns the content model?

This is the first architectural decision, and CMS 13 gives you two answers. A content type can be owned by C# and mirrored into TypeScript, or owned by TypeScript and pushed into the CMS.

Figure 2. Two directions: C# owns the type and config pull mirrors it, or TypeScript owns the type and config push creates it. One source of truth per type.

Both work. Pick one per type. The CMS REST API treats code-managed types as read-only: config pull gets them, and generates typed files for them, only with --includeReadOnly, and the CMS rejects a push that includes one. My recommendation after testing both models: keep legacy page types in C#, model everything Visual Builder needs (experiences, sections, elements, display templates) in the frontend repository, and regenerate the TypeScript mirror of the C# types with config pull. In CLI 3.1.0-beta.0 that has to happen in a terminal (ask me how I know): without one, the CLI prints the manifest as JSON and writes no files, even with --output. The fix (CMS-57658) is on the SDK's main branch, so with the next CLI release CI can regenerate the mirror too.

One source of truth per type, never two.

On the Alloy-based CMS I tested against, the rule was not theoretical. Alloy ships a C# ArticlePage, the same name as the TypeScript ArticlePage, so I renamed the C# type to AlloyArticlePage before the first push. Same GUID, content untouched.

Optimizely's FAQ for CMS 13.0.0 recommends managing types where they are primarily used, names .NET code as the typical case for PaaS headless, and calls full PaaS headless support an area of ongoing development. API-managed Visual Builder types worked in the CMS 13 setup I tested; the broader PaaS headless story is still evolving. Two PaaS gotchas are easy to miss. OPTIMIZELY_CMS_URL is the runtime and preview URL, while the CLI talks to the CMS REST API through OPTIMIZELY_CMS_API_URL (or --host). And the token the CMS issues to the CLI's OAuth client carries the client id and the api:admin scope, but no roles (decoded on 13.4.2, with a client defined in configuration): enough for content types, display templates and the application, but config push also creates the application's start content, which is checked against the content ACL. On a root that grants Everyone only Read, the push stops with a 403 until the client gets Read and Create there. Everything on the CMS side (the Graph instance, the OAuth client and its access, the Headless application and its preview URL) is in the repository's web/docs/cms13-setup.md; the code paths below are relative to web/.

Configure the SDK for PaaS

// src/lib/optimizely.ts (excerpt)
  config({
    apiKey: OPTIMIZELY_GRAPH_SINGLE_KEY,
    graphUrl: OPTIMIZELY_GRAPH_GATEWAY, // a URL with no path gets /content/v2 appended
    platform: 'paas', // CMS 13 PaaS; the SDK does not detect the product. Needs SDK >= 3.1.0-beta.0.
    fragment: { richTextFormat: 'both' }, // 3.x fetches json only by default
    // Path lookups also match _metadata.url.base. Without it every application on the CMS answers for
    // the same path, and the first hit may be another site's start page. The value is the Headless
    // application's primary host as Graph stores it, scheme included (https://localhost:3001).
    ...(OPTIMIZELY_APPLICATION_HOST ? { query: { host: OPTIMIZELY_APPLICATION_HOST } } : {}),
  });

The SDK does not infer the hosting model from the Graph endpoint, so select the PaaS platform explicitly; the SDK's PaaS guide gives the reason: without it, queries that use a SaaS-only feature fail against PaaS. In 3.1.0-beta.0 the two adapters still build the same queries. A comment in the SDK source says why the PaaS adapter is a copy of the SaaS one: so that SaaS changes don't reach PaaS.

query.host matters as soon as the CMS has more than one application. Astro often joins a CMS that already serves a site, as a second application. Every application's start page then matches the same path. The SDK's troubleshooting guide covers this case (I get content from the wrong site); on my test CMS the symptom was less obvious: the first hit was Alloy's start page, a type Astro does not register. The page rendered empty. Bind the Headless application's host to a language as well (locale: 'en' in optimizely.config.mjs). Otherwise CMS 13 puts the start page at /en/.

Rendering Visual Builder without React

This is the heart of the series. The official sample's main routes render a composition with React's OptimizelyComposition from @optimizely/cms-sdk/react/server, which renders every node through the async server component OptimizelyComponent. It works, but it hands the whole page to one React render, and Astro cannot place an island anywhere inside it. The sample's newer /svelte/ route uses the core's planning, but again hands the whole page to one framework and does not cover preview. The core entry point exposes the same planning as plain functions, so Astro can own the page instead.

The bridge is one registry for every framework:

// src/lib/astroRegistry.ts
import { ComponentRegistry } from '@optimizely/cms-sdk/core';
import LandingExperience from '@/components/LandingExperience.astro';
import ArticlePage from '@/components/ArticlePage.astro';
import BlankSection from '@/components/BlankSection.astro';
import Hero from '@/components/react/Hero';
import Tile, { SquareTile } from '@/components/react/Tile';
import CallToAction from '@/components/react/CallToAction';
import MonthlySpecial from '@/components/svelte/MonthlySpecial.svelte';
import FAQIsland from '@/components/islands/FAQIsland.astro';
import Spotlight from '@/components/Spotlight.astro';

// One registry for .astro, React and Svelte components. Everything renders on the server;
// the only client JavaScript comes from the wrappers in src/components/islands/.
export const registry = new ComponentRegistry({
  LandingExperience,
  ArticlePage,
  BlankSection,
  Hero,
  Tile: { default: Tile, tags: { Square: SquareTile } },
  CallToAction,
  MonthlySpecial,
  FAQ: FAQIsland,
  Spotlight,
});

resolveContentComponent(content, { registry }) looks components up in this registry and nothing else (passing a registry replaces the SDK's global component registries, with no fallback), so nothing in the application imports @optimizely/cms-sdk/react/server. A display template with a tag selects a variant. When the Square style is picked on a tile, the node carries that display template's key. The planner (planGridSection() for a tile inside a section, planComposition() at the top level) maps it to the tag Square through the templates registered with initDisplayTemplateRegistry(). That registry is global, and the registry option does not replace it. tags.Square renders the tile.

The composition itself is about twenty lines of Astro:

---
// src/components/OptimizelyComposition.astro
import { planComposition, resolveContentComponent, isWrappedComponent, type ExperienceNode } from '@optimizely/cms-sdk/core';
import { registry } from '@/lib/astroRegistry';

interface Props { nodes: ExperienceNode[] }
const { nodes } = Astro.props;
const items = planComposition(nodes);
---
{items.map((item) => {
  if (item.kind === 'unknown') return null;
  const r = resolveContentComponent(item.content, { tag: item.tag, registry });
  if (!r.component) return null;
  const Component = r.component as any;
  const props = { content: r.contentProps, displaySettings: item.displaySettings };
  // A component node gets the preview wrapper; a section node carries its own data-epi-* attributes.
  return isWrappedComponent(item)
    ? <div {...(item.previewAttrs ?? {})}><Component {...props} /></div>
    : <Component {...props} {...(item.previewAttrs ?? {})} />;
})}

planComposition() turns the experience's nodes into a flat plan; isWrappedComponent() separates component nodes, which get a <div> carrying the preview attributes, from sections, which take the attributes themselves. Sections hand their rows and columns to planGridSection(), and a recursive GridItems.astro renders the grid; row and column display templates arrive as displaySettings and become CSS classes, so the design system, not the editor, decides what "large padding" looks like.

One Astro rule shapes the rest. A dynamic tag such as <Component /> cannot carry a client:* directive, because Astro must know at build time what to bundle. So each island is a small static wrapper in src/components/islands/, registered under its content type, and grep -rn "client:" src/components lists every component that ships JavaScript. In the demo that is one Svelte FAQ, while the React tiles, a Svelte price card and an .astro Spotlight next to them render on the server and ship nothing.

The practical consequence is the one that matters for a CMS team: the CMS content model no longer has to be tied to a single frontend framework. A component can be reimplemented in React, Svelte or .astro while its content type and the Visual Builder composition stay the same, as long as the replacement keeps the props contract the registry passes it.

Live preview

Preview is one route, src/pages/preview.astro. The CMS opens it in an iframe with the content key, version, locale, context and a short-lived preview token; getPreviewContent() fetches the draft through Graph, and the page renders it through the same registry as the public site, so editors see exactly the components visitors get.

Figure 3. The Landing experience in CMS 13.5.0: the editor's properties on the left, the Astro preview route in the frame on the right. The hero, the Spotlight and the FAQ come from the same registry as the public site; the hero and the Spotlight render on the server, the FAQ (outlined by the editor's overlay) is the one Svelte island.

Figure 4. One route, the same registry as the public site, and a full reload after every save. Graph checks the token; the public site never sees drafts.

The CMS's communicationinjector.js connects the frame to the editor, and createContentSavedListener() from the core entry point navigates the frame, after each save, to the preview URL the CMS sends with the event, which carries a new token. It is a plain <script> with no React on the client, and the reload is a full one, since this page does not use Astro's client router. The route sends private, no-store, noindex and a frame-ancestors policy for the CMS origin. Graph checks the token: a bad or expired one gets a 401 from Graph, and the route answers 401 without detail and caches nothing. It does the same for any other failure to fetch the draft; the reason goes to the server log.

On the CMS side, keep Graph's ContentVersionSynchronizationMode at its default, All: the preview reads the exact version the CMS asks for, and PublishedOnly would leave drafts out of the index. The public site reads with the single key, which by design never sees drafts, and here the unpublished start page was visible with the app key and secret and invisible with the single key.

One expectation to set with editors coming from CMS 12: headless sites have no inline editing on the page. They get property overlays that open the field in the editor, as Optimizely's CMS 13 FAQ notes.

Request isolation: one observation

Without a per-request scope preview still renders, so nothing looks wrong. With adapter.run() removed from the middleware of the built site (the adapter itself still configured), a sequential test against the real CMS 13.5.0 and Graph showed the problem: after one preview request with a token issued by the CMS, the next public render of the same article carried that token in a rich-text image URL (?preview_token=…). On this Astro server path, the SDK's request context, where getPreviewContent() keeps the token, was not scoped per server request. That shows preview context reaching public output; it does not show that the token could be used to read drafts, and I did not try. A preview token does not belong in public HTML either way. With adapter.run() back, the same sequence leaves no token in public HTML.

Figure 5. The same two requests with and without a per-request scope. A configured adapter read outside run() falls back to one shared store, silently.

The SDK's request-context and framework-agnostic core guides prescribe exactly this: in frameworks other than React, configure an adapter and run each request inside it. Neither guide says what happens when a configured adapter is read outside run(); only a doc comment in the adapter's source does. The adapter falls back to one process-wide store. No error, no warning. That is how a token set by one request reached another. On the SDK's main branch (CMS-58169, merged on 28 October, not yet on npm) media URLs no longer carry the token unless the preview opts in with forceMediaToken, which narrows this symptom; the shared fallback is still there. In short, this is a reproduced failure mode of one integration: SDK 3.1.0-beta.0 in an Astro server, with the adapter configured but run() missing. On its own, it does not establish a vulnerability in the SDK. With the documented request-scoping pattern, the token stayed out of public HTML in every test described here.

In this project the fix is the guide's pattern: an AsyncLocalStorage, configured once and entered for every request:

// src/lib/context.ts
import { AsyncLocalStorage } from 'node:async_hooks';
import { configureAdapter, MemoryAdapter } from '@optimizely/cms-sdk/core';

export const adapter = new MemoryAdapter(new AsyncLocalStorage());
configureAdapter(adapter);

// src/middleware.ts
import { defineMiddleware } from 'astro:middleware';
import { adapter } from '@/lib/context';

// Wraps the whole render, so every await inside components still sees this request's context.
export const onRequest = defineMiddleware((_context, next) => adapter.run(() => next()));

A check guards it: 12 preview requests interleaved with 12 public requests to the freshly purged article put no preview_token in public HTML, the preview HTML still carries it, and the check fails when adapter.run() is removed. Part 2 looks at the mechanism in depth: where the SDK keeps this context, how that differs between runtimes, and how it behaves on DXP.

So, why Astro?

Visual Builder: framework-neutral planning lets Astro, React and Svelte components take part in the same composition. Only components marked as islands are hydrated in the browser.
Measured: the article page ships no <script>; the landing experience loads 14.6 kB gzip (14,647 bytes), the Svelte runtime and the FAQ, only when the FAQ scrolls into view, plus 2.2 kB of inline island loader; the React client that @astrojs/react builds (68.2 kB gzip) is loaded by no page.
Architecture: React becomes optional. The content model survives a change of framework.

This does not make Astro a replacement for Next.js. I would still choose Next.js for a site that is mostly application (authenticated dashboards, heavy client state), for a team already invested in React Server Components, or for a component library that is React-only and has no reason to change.

Caveats

Beta SDK. The /core entry point this design rests on, and the platform option, need 3.1.0-beta.0; the SDK itself has supported CMS 13 since 2.0 (May 2026), and I did not test 3.0.2 against PaaS. Pin the beta exactly and re-test at 3.1.0.
PaaS headless is still evolving. The FAQ for CMS 13.0.0 describes it as an area of ongoing development. In 3.1.0-beta.0, platform: 'paas' selects an adapter that builds the same queries as SaaS; that is true of this version, and later ones may differ.
CMS 13 only. CMS 12 with Graph does not qualify.
Version mismatch to watch. Astro 7.4.2 requires Node 22.23.4 or later. Below it the astro CLI (dev, build, preview) exits with an error; the built server does not check. Optimizely's front-end hosting documentation still lists Node 22.12.0 or later for Astro. That is a mismatch in the documentation, and I have not seen an actual incompatibility; part 2 checks the Node version the DXP build slot actually runs.
Expect no inline editing on headless sites; editors get overlays.
Not exercised here: Opti ID, the DXP build slot, Redis and Cloudflare. Part 2 covers DXP, with the checks to run on Test1.

The problems that cost the most

Three problems cost the most. Before publishing I reproduced each of them again, on 29 October, against the CMS 13 instance and the packages as published on npm:

Problem	Why	Fix
npm install @optimizely/cms-sdk installs 3.0.2; importing @optimizely/cms-sdk/core fails (ERR_PACKAGE_PATH_NOT_EXPORTED in Node), and nothing in that version knows platform: 'paas'	the /core entry point and the platform option first ship in 3.1.0-beta.0, under the beta tag; latest is still 3.0.2	pin @optimizely/cms-sdk and @optimizely/cms-cli to exactly 3.1.0-beta.0
config push answers The client credentials are invalid, although the CMS issues that client a token	without OPTIMIZELY_CMS_API_URL or --host, the CLI requests its token from the default SaaS gateway (api.cms.optimizely.com), which does not know a PaaS client; it never reads OPTIMIZELY_CMS_URL. Documented in the CLI reference, but the error reads as a credentials problem	OPTIMIZELY_CMS_API_URL=https://<cms-host>; the CLI also loads .env from the directory it runs in
A TypeScript type with the key of a C# class is not saved: the CLI prints ✔ Configuration file uploaded, then …can only be updated by modifying this model, and exits with an error	types registered from .NET models (source: "_server") are read-only through the REST API; the CMS answers 200 with an errors list, and the CMS leaves those types out of config pull unless you pass --includeReadOnly	change the type in C#, or give the TypeScript type its own key; pull C# types only into a folder that config push does not read

The full list, with the CMS setup and every version I pinned, is in the repository. That includes the 403 on the start content, the start-page routing and the relative media URLs.

How I tested it

Every code excerpt is from the companion repository. It type-checks with astro check (0 errors) and passes 10 unit tests for the cache provider of part 2. Its 28 checks (HTTP-level assertions in eight groups) ran against the real CMS 13.5.0 and Optimizely Graph, on a test article whose draft has an image in its rich text, with a preview token issued by the CMS REST API (GET /_cms/v1/content/{key}/versions/{version}/previews). Checks 1 to 6 ran through the repository's test/checks.sh. The repository's versions of checks 7 and 8 are written for local runs, so I ran those two with a separate script, whose logic is now in the repository as test/real-checks-7-8.mjs: a real publish through the same REST API, after which Graph served the new version within about two seconds on this test instance (polled once a second; 1.5 to 1.6 s in three runs), and a scan of the client bundle for the real key values.

The checks that matter for this part: the article page ships no <script>, the landing page stays under 20 KiB of JavaScript, images load from the CMS, a bad preview token gets a 401 with no-store, and no preview token leaks into public HTML under concurrency. That run also caught a bug. It was in my own code: on the stored-query path the SDK uses (?stored=true), Graph returns rich text's json as a string. Without that parameter it is an object, and behind Graph's CDN either shape can come back. The SDK's RichText accepts both shapes, but my media rewrite walked the raw value and missed images inside rich text until it parsed the string first.

The instance is an Alloy-based CMS 13 on .NET 10 with ASP.NET Identity, with Astro added as a second, Headless application. On 13.4.2, config push created the model, the start content and the application through the CMS REST API, and the pages rendered from Graph; the 403, start-page routing and media URLs came from that run. After upgrading the same CMS to 13.5.0, the preview frame in Visual Builder showed the Astro page (figure 3), and the server log showed the frame reloading about a second after every save and again after publishing. Two things I have not yet confirmed in the editor: the Square style switching the component, and click-to-field focus. What the run does not cover (Opti ID, DXP, Redis and Cloudflare) is part 2's job, measured on Test1.

Verdict

Yes: with the 3.1.0 beta, Astro can render Visual Builder content on CMS 13 PaaS, but it is not a drop-in replacement for the Next.js integration. The framework-neutral SDK provides the primitives; the application still has to provide the integration around them: one registry for its components, a preview route and its reload, routing that knows which application a path belongs to, and a request scope for the SDK's context. For the platform team, the useful feedback is about failure modes. The SDK's guides cover each of these pieces. What they don't show is where a missing piece fails silently: a configured MemoryAdapter read outside run() falls back to a shared store, the CLI without OPTIMIZELY_CMS_API_URL asks the SaaS gateway for its token and reports a credentials error, and config push prints ✔ Configuration file uploaded before the CMS's errors.

The interesting part is not replacing Next.js. It is separating Optimizely's content composition model from the frontend framework, and knowing what you have to rebuild when you do.

Part 2 takes a closer look at request isolation and asks the production question: can the same architecture survive DXP (Redis-backed ISR, Graph webhooks, Cloudflare and preview) without a redeploy for every publish?

Repository: pino-labs/astro-visual-builder-cms13, the code, the checks and the CMS 13 setup notes.

Series: Part 1: What Astro Has to Rebuild on CMS 13 PaaS · Part 2: Does It Survive DXP? (Redis-backed ISR, Graph webhooks, Cloudflare and preview at scale)

Sources

All links checked on 2026-10-29. The release notes moved from support.optimizely.com to docs.optimizely.com; the old addresses redirect.

2026 Optimizely CMS 13 release notes: DXP support for Astro (31 Aug 2026), the JavaScript SDK on CMS 13, the CMS-57780 culture-specific data-loss fix in 13.4.1 and the restore of deleted values in 13.4.2 (26 Oct 2026), 13.5.0 (27 Oct 2026)
2026 CMS (SaaS) release notes: JavaScript SDK 3.0, the framework-neutral SDK core and the Astro sample (24 Sep 2026)
@optimizely/cms-sdk on npm: latest 3.0.2, beta 3.1.0-beta.0 (20 Oct 2026); release notes on GitHub
FAQs for CMS 13: where content types live on PaaS headless, and no inline editing on headless sites
episerver/content-js-sdk: Astro sample, CMS PaaS guide, framework-agnostic core, request context, CLI reference and troubleshooting; on the main branch, changes CMS-58169 (media preview token opt-in, merged 28 Oct 2026) and CMS-57658 (config pull output flags outside a terminal, merged 26 Oct 2026)
Host a frontend with Optimizely: Node.js 22.12.0 or later for Astro on DXP front-end hosting
Astro ISR caching and Optimizely Graph webhooks: the DXP page for Astro, also listing Node.js 22.12.0 or later
Prior work on SaaS CMS: Jacob Pretorius, Build a headless blog with Astro and Optimizely SaaS CMS Part 4 - SSR & Visual Builder Experiences (21 July 2025)

Stack: Optimizely CMS 13.4.2 and 13.5.0 (Alloy-based, .NET 10, ASP.NET Identity) with Optimizely Graph, @optimizely/cms-sdk and @optimizely/cms-cli 3.1.0-beta.0, Astro 7.4.2 on Node 24.19.0, React and Svelte components behind one registry. Optimizely, Astro, Next.js, React and Svelte are trademarks of their respective owners; this article is not affiliated with them.

Optimizely certifications in 2026: the new programme explained

Thu, 29 Oct 2026 00:00:00 GMT

How Optimizely's 2026 certification programme works: Foundation, Core and Advanced tiers, 17 product tracks, renewal, and which path to take.

Visual Builder without Next.js, Part 1: What Astro Has to Rebuild on CMS 13 PaaS

Thu, 29 Oct 2026 00:00:00 GMT

A field report on the framework-neutral CMS SDK 3.1 beta: Visual Builder, the content model and live preview in Astro, on a real CMS 13.

What Mattered More Than the API. Part 5: Process Uptime and the Benchmark

Wed, 28 Oct 2026 08:00:00 GMT

A long-running app imported 7x slower than a freshly restarted one, the finding that beat every API optimization, plus runnable benchmark jobs.

Virtual Teammates in Optimizely Mark: a hands-on first look

Tue, 27 Oct 2026 09:44:35 GMT

Virtual Teammates are the most interesting thing Optimizely has shipped on its agent platform this year, and the hardest to evaluate from a demo. They are not another agent. They are persistent AI workers with their own login, mailbox, memory and job description, and they keep working when you close the tab.

The Optimizely MVP organisation has just been given access, so I spent a day taking them apart: reading the docs, walking every screen in the directory, and enabling the SEO & AI Search Analyst against a real site with real Google Analytics 4 and Search Console data. Every screenshot below is from that session, unedited apart from cropping. This post covers what they are, how they are configured end to end, what my teammate actually found, where I think they earn their keep, and the gotchas I hit on the way.

A quick note on naming, because it will trip you up. Opal is now the Optimizely Agent Platform, and the assistant and app you work in are called Mark. The UI says Mark, the docs mostly say Mark, and some help articles and the release notes page still say Opal. They are the same product. Virtual Teammates were released on 25/08/2026 with five roles. The Web Manager and Content Marketer arrived on 13/10/2026, and a Translation Specialist is now in the directory too.

Teammate, not agent

The difference is persistence and identity. An agent runs when you invoke it and forgets you when it finishes. A Virtual Teammate is hired once, given a job, and then runs that job on a schedule or in response to events, building up memory as it goes.

Optimizely describes four layers, and they map neatly onto things you already know in Mark:

Tools. Connectors to systems like GA4, Search Console, Semrush, HubSpot or Slack. The same connectors your agents already use.
Agents and workflows. Packaged tasks the teammate runs from Mark, with your permission.
Jobs. Workflows the teammate runs on its own, on a schedule or an event. This is the bit that makes it a teammate.
Teammate layer. A persistent identity, memory, personality and job description wrapped around the rest.

The identity part is more literal than I expected. Each teammate gets its own Opti ID account, login and email address, flagged as a virtual user. It does not consume a product seat. It inherits nothing from the person who hired it, so you grant it access exactly as you would a new starter. Inside Optimizely products it acts as itself. Outside them it acts through accounts a human connects on its behalf, because a teammate cannot complete an OAuth consent itself.

You work with it through Team Messages, a Slack-style messaging layer inside Mark with direct messages, groups and channels. Teammates can message each other too, and can join Teams and Slack meetings to share summaries. The default autonomy model is sensible: the teammate drafts and proposes, you approve or redirect in Team Messages, and you widen what it can do unattended as trust builds.

The directory: eight teammates

The MVP organisation's directory lists eight teammates. Each has a CV-style card ("Why hire me", "Experience", "Tools used") and a set of jobs you can switch on or off when enabling it. All jobs are on by default.

The Virtual Teammates directory in Mark. Each card is a "resume" with the jobs it does and the tools it works with.

The table below is taken from the enable screens in the MVP instance on 27/10/2026.

Teammate	Jobs	Connectors it asks for
SEO & AI Search Analyst	Audit AEO readiness (daily), Research industry trends, Monitor performance (SEO and GEO anomaly scan), Research keywords (daily, from Conductor and Search Console)	GA4, Search Console at enablement. Conductor and Semrush at hire.
Marketing Analyst	Traffic and acquisition pulse (weekly), Content performance (weekly), Conversion summary (monthly), Anomaly detection (daily), Marketing Analyst actions, Self evaluation	GA4, Search Console, Tag Manager
CRO Manager	Generate experimentation roadmap (PIE scored), Write test plans, Monitor experiment portfolio (daily SRM and stat sig checks), Analyse and report results, Configure experiments	GA4. Works natively in Web Experimentation.
Personalization Strategist	Identify opportunities, Design campaign plan, Build campaign, Monitor performance, Impact overview	GA4, Search Console, Salesforce, Google Ads, Figma
Content Marketer	Monitor industry trends (daily), Track competitor content (weekly), Surface pipeline gaps (weekly, from Salesforce), Self evaluation	Salesforce
Web Manager	Perform audit compliance, Manage site health, Manage website updates, Audit report actions	None. Works natively in CMS.
Translation Specialist	Create translations, Audit translations	None. Works natively in CMS.
Chief of Staff	Daily brief, Weekly brief, Meeting prep, Meeting recap, Competitive intel	Teams, Outlook mail and calendar, OneDrive and SharePoint, or Gmail, Drive and Google Calendar. Plus Salesforce.

Two things stand out. First, the Marketing Analyst and Content Marketer both ship a Self evaluation job that scores each run against expected results and logs what worked. That is the memory story in practice, and it is the job I would watch most closely. Second, the Web Manager and Translation Specialist need no third-party connectors at all. For CMS-heavy clients they are the lowest-friction place to start.

Configuration, end to end

Setup happens in two halves: an admin enables a teammate for the organisation, then any permitted user hires their own copy of it. It touches four places: Mark, Connect Platform (the old ODP app directory), Opti ID, and the third-party tool itself. Here is the full path I took, in order.

1. Before you start: email domain (admin)

Check Settings > Email Domain in Mark. Every teammate gets a mailbox on your Mark email domain, so this must be configured and verified first. In the MVP org it already was.

Settings > Email Domain. The verified domain is where each teammate's mailbox lives.

2. Enable the teammate and choose its jobs (admin)

Go to Directory > Virtual Teammates, or Grow your team > Browse the directory from the empty Teammates page, and select Details on a card. This drops you straight into the enable wizard, where every job is on by default. Turn off any you don't want offered. Once a teammate is enabled, the same list lives under the cog on its card as Manage jobs, next to Freeze hiring.

The SEO & AI Search Analyst's four jobs. Admins can switch any of them off for the whole organisation.

After enablement the card shows "1 hired" and a Hire button. The cog holds the organisation-level controls.

3. Install the connectors (admin)

Select Set up connectors. The wizard lists the third-party tools the teammate needs, with a tick for anything already installed and Add connector for anything missing. This example is the Marketing Analyst, where GA4 and Search Console were already in place and Tag Manager was not.

The connector step of the enable wizard.

Add connector opens the connector's app in Connect Platform in a new tab. GA4 showed as installed when the tab opened; Search Console needed Install App. Installing accepts the third-party add-on terms.

The Search Console connector is an app in Connect Platform's App Directory.

4. Configure GA4 in Connect Platform (admin)

Search Console needs no org-level configuration because each user authenticates with OAuth. GA4 does. Open the GA4 app's Settings tab and you get four sections.

The GA4 Mark app settings. The instance-level OAuth toggle is off by default, so each person uses their own Google login.

Under GA4 Properties, add the property ID (from GA4 under Admin > Property details) and an optional nickname. I added realyield.co.uk.

The property ID in Google Analytics, under Admin > Property details.

The property registered in the connector, with its nickname.

Global Filter lets you pin every standard report to one hostname. It is always applied and Mark cannot override it, which is useful when one GA4 property tracks several sites. It does not apply to realtime reports.

The optional hostname filter.

Finally, under Add to Mark, select Add to Mark to register the tools with your Mark account. The spinner gave no feedback and reverted, but it had worked: about a minute later the row showed a tick with Remove from Mark and Sync, and the Mark Connectors page had flipped from "Add connector" to "Connect".

Registered. Do the same for the Search Console app.

The Connectors page in Mark once both Google connectors were registered.

Back in the wizard, select Enable teammate. The card in the directory now says Hire.

5. Hire your teammate (any permitted user)

Hiring is a four-screen wizard:

Name it. Select Hire and give it a name. Mine is Rankin. A name with no spaces keeps the email address clean. You can change the avatar here too.
Choose where it works. Pick the product and instance. The MVP org offered cms and oa. I left it unset, as realyield does not run on Optimizely. The screen is honest that this only tells it where to work. It does not grant access.
Connect its tools. Under Day one essentials, select Connect for each tool. This opens a Google OAuth pop-up that a human must complete, because the teammate cannot consent for itself. Conductor and Semrush appear here too, but as "Set up its tools on the Connectors page first".
Start working together. Once both show Connected, select Start working together, then Go to your teammate. You land in a Team Messages DM.

The hire wizard, from naming to connected tools.

6. Grant access inside Optimizely products (Opti ID admin)

If the teammate will work inside Optimizely products, give its Opti ID user a role on each instance in the Opti ID Admin Center. For CMS 13 and CMS SaaS, also add it under Settings > Set Access Rights with only the rights its jobs need (Read, Create, Change, Delete, Publish or Administer). I skipped this, as Rankin only needed Google data.

Managing a teammate

Every hired teammate appears under Virtual Teammates > Teammates with its own email address, managers, status and start date.

Rankin on the Teammates list, with its own address on the Mark email domain.

Each teammate has two areas. Supervise shows Activity (upcoming and completed job runs, with status, priority and trigger) and Work (everything it has produced).

Activity. The four scheduled jobs are queued, with Audit AEO readiness next up.

Settings covers Identity, Tools, Product Connections and Permissions. Identity holds the basics and a personality, which shapes how it writes and reasons. There are four templates, or you can build your own.

Identity: name, email and start date.

The personality templates: the tastemaker, the hype machine, the pragmatist and the stress tester.

Tools shows what it can reach. Connections you own can be disconnected here; anything an admin has not set up shows as "Contact Admin".

Rankin's tools. GA4 and Search Console are connected; Semrush and Conductor need an admin.

Permissions is where the governance lives. Roles set who manages the teammate and which other people can message it.

Roles. Managers get full access; teammates only what you allow.

Conversation guardrails set what it shares with each audience: managers, named teammates, and anyone in the organisation.

Conversation guardrails per audience.

Jobs can be reordered, switched off, or added. Add job offers Create job or Install from catalog, so you are not limited to the defaults.

Jobs, with the Add job menu open.

Interactions lists the channels it listens on. By default that is instant messaging, and the description shows the tool set it uses to read and reply in Team Messages. Deactivation sits at the bottom and is permanent.

Interactions and deactivation.

Hands-on: what Rankin found on realyield.co.uk

Rankin found a likely GA4 tracking break on its first run, and that alone made the setup worthwhile. realyield.co.uk is a UK buy-to-let analysis side project of mine. It is a small site, which makes it a good test: there is not much data to hide behind.

The onboarding interview

The first message was not a report. It was six questions: domain, competitors, business goals and how SEO contributes to each, priority content areas, keyword focus, and which actions it may take without approval.

Rankin's opening message in Team Messages.

I answered in one message and told it to propose everything first. It played the configuration back, flagged that I had not given a fixed keyword list, and said it had no data yet so would not invent findings.

My answers, and Rankin's confirmation of its working configuration.

The first snapshot

I asked for the last 28 days against the previous 28. The reply came six minutes later, clearly labelled as proposals with nothing actioned. The headline was not a ranking problem at all:

GA4 Organic Search sessions fell 59% (164 against 398) while Search Console clicks fell only 17% (209 against 251).
Every GA4 channel dropped together: 381 sessions against 934 in total, with Direct, Organic Social and AI Assistant traffic all falling at once.
Organic sessions ran at 12 to 20 a day until 1 October, then 1 to 7 a day from 2 October. Search Console clicks show no such step. The GA4-to-GSC ratio went from 1.6x to 0.5x overnight.
It concluded this is probably a tag or consent change around 1 to 2 October, marked it as an unconfirmed hypothesis, and told me to treat GA4 page-level data as unreliable until it is checked.

The first half of the snapshot: the tracking flag and the Search Console scoreboard.

That is exactly the cross-source reasoning a human analyst should do and usually doesn't. The raw data backs it up. GA4's traffic acquisition report shows every channel falling off a cliff at the start of October:

GA4 traffic acquisition for realyield.co.uk, last 90 days. Every channel steps down at the start of October.

Search Console over the same period shows no such step in clicks:

Search Console performance for realyield.co.uk, last three months. Clicks hold steady through October.

The Search Console analysis was just as specific. Clicks were within one standard deviation of the daily mean since 1 July (8.7 a day, SD 3.8, against 7.5 now). 41% of the impression loss was a single query, "rent vs buy calculator", spiking to 6,536 impressions and falling back to 41. The real drift was position: impression-weighted average position went from 16.0 to 21.7 over four weeks, with desktop slipping from 16.6 to 22.4 while mobile improved from 15.4 to 13.6.

It then broke down top pages and found the anomalies worth acting on:

/tools/personal-vs-ltd-company lost 45% of the total click loss on its own. Position held and impressions fell only 9%, so CTR halved from 3.7% to 1.9%. A CTR problem, not a ranking one.
Location pages: 270 URLs with impressions (5,053 impressions, 29 clicks), and 90% of them with no clicks at all. "average rent in" queries had 381 impressions at position 9.7 and no clicks.
The core net yield calculator sits at position 55.7 with no clicks.
Housekeeping: the login subdomain appears in search and should be noindex.

Top pages, top queries and the other anomalies.

The action plan

Five prioritised proposals, each with a first step: fix GA4 tracking and add calculator completion as a key event; rework the core calculator page for "rental yield calculator" and "net yield calculator"; pilot a new location page template on six named cities and read CTR after four weeks; recover CTR on the page that halved; and build a manual AI-citation baseline of about 20 questions because no citation tool is connected. It then listed two further opportunities outside my stated priorities and asked for a steer rather than assuming.

AI visibility, the five proposed actions, and the questions it wanted answered.

Where it fell short

It was honest about it. With no Conductor, Semrush or AI-citation connector, it could not report competitor rankings or citation share, which is half of the "AI Search" in its job title. It also could not find a Team Messages channel to post into, so it put everything in our DM. And at the time of writing none of its four scheduled jobs had run yet, so the daily cadence, memory and self-improvement claims are still untested. I'll follow up once it has a fortnight of runs behind it.

Where they earn their keep

The pattern that fits is recurring, data-heavy work that nobody owns and everybody means to do. Teammates are weakest where the work is a one-off, and strongest where the value comes from turning up every day. Here is where I would start with clients, roughly in order of effort.

Search and AEO monitoring for marketing teams without an SEO. The SEO & AI Search Analyst gives a daily AEO readiness audit, a keyword digest and anomaly alerts off GA4 and Search Console. For mid-market Optimizely clients who rely on an agency retainer for this, it is a real change in cadence.
Weekly reporting that people actually read. The Marketing Analyst replaces the Monday GA4 export. Its 15% channel-movement threshold and "content win of the week" are opinionated defaults, which is what you want from a report.
Content governance on CMS 13 and SaaS. The Web Manager scans content at publish time for brand, legal, style and accessibility issues and stages fixes for approval. Pair it with the Translation Specialist for multi-locale sites. Neither needs a third-party connector, so the only real setup is CMS access rights.
Experimentation hygiene. The CRO Manager's daily SRM, zero-conversion and overrun checks are the boring safety net most programmes lack. Its test plans include sample size and runtime, and it stages experiments in Web Experimentation as drafts for QA.
Personalisation programmes that stall after launch. The Personalization Strategist runs the whole loop from opportunity to campaign build to impact overview, all staged for review.
Leadership admin. The Chief of Staff does daily and weekly briefs, meeting prep and recaps across Microsoft 365 or Google Workspace. Useful, but it competes with Copilot and Gemini, which most clients already pay for.

For partners there is a second angle. A teammate is a packaged, governed role you can hand a client in week one of a build, before their own team is in place. That changes the shape of a launch: the site goes live with an always-on analyst and a content governance check already running.

Governance, credits and gotchas

The governance model is the strongest part of the design. Teammates are real Opti ID users, so access is granted, audited and revoked like any starter's. Managers get full access; other teammates see only what conversation guardrails allow; jobs can be switched off per teammate by its manager, or per organisation by an admin, who can also freeze hiring. Pausing keeps history. Deactivating is permanent and deletes the teammate's memory and context, so pause unless you mean it.

Credits are the open question. Mark uses pooled credits across eligible products, and Scott Reed's October state of play notes that scheduled, webhook and email triggers bill to whoever created the trigger, at an average of 2 credits for chat up to 200 for an XL agent run. The Virtual Teammates docs do not yet say how a teammate's daily jobs are metered or who pays. A teammate running four daily jobs could be a meaningful line item, so model it before you put one in front of a client.

The gotchas I hit:

Org-level data, personal teammate. GA4 property IDs are registered on the connector app for the whole organisation, so everyone in the org sees the list. Data access still runs through each person's own Google OAuth by default, so the exposure is the property name and ID, not the data. That changes if an admin turns on the app's instance-level OAuth option. Think about both before listing client properties in a shared partner sandbox.
No feedback on registration. "Add to Mark" in Connect Platform spins, then silently reverts. It had worked; the Mark Connectors page just took a minute to catch up. The enable wizard also does not refresh connector status until you reload it.
Tool lists disagree. The SEO card shows four tools, but enablement asks for only GA4 and Search Console. Conductor and Semrush then appear at hire time as "Set up its tools on the Connectors page first", and on the teammate's Tools page as "Contact Admin", even though Semrush shows as installed on the Connectors page.
Choosing an instance is not access. The UI says so clearly, but it is still an extra trip to the Opti ID Admin Center, and for CMS a second trip to Set Access Rights.
OAuth needs a human. Every third-party connection is a pop-up a person must complete. Plan this into onboarding sessions with clients rather than assuming an admin can do it alone.
Three names, one product. Opal, Agent Platform and Mark all appear in the UI, docs and connector descriptions. Brief clients on this up front.

Verdict

Virtual Teammates are worth taking seriously, and worth piloting now on one narrow job. The identity and governance model is properly thought through, the onboarding interview is better than most agency kick-offs, and the first piece of analysis I got back was specific, cautious and correct about the thing that mattered most.

The weak spots are setup friction and cost visibility. Enablement spans Mark, Connect Platform, Opti ID and the CMS, with status that lags and tool lists that disagree. And until Optimizely documents how a teammate's scheduled jobs consume credits, I would not promise a client a monthly figure.

My recommendation for partners: pick one client with a clear recurring gap, usually search monitoring or content governance, hire one teammate with propose-only permissions, and review its output weekly for a month before widening its autonomy. That is how you would onboard a junior hire, and it is the right mental model here too.

Sources

Virtual Teammates overview, Optimizely docs
Enable Virtual Teammates, Optimizely docs
Hire a Virtual Teammate, Optimizely support
Manage your Virtual Teammate, Optimizely support
Manage Virtual Teammates for your organization, Optimizely support
2026 release notes, Optimizely docs
Virtual Teammates vs AI agents, Optimizely Field Notes
Optimizely Agent Platform: October state of play, Scott Reed
Optimizely retires DXP label, bets everything on agent platform, CMSWire

I Turned My Tech Bookshelf Into an MCP Server (in .NET)

Mon, 26 Oct 2026 21:45:00 GMT

Overview

If you are like me you have been buying tech ebooks for years. Manning early access books, Packt and Apress bundles, Humble Bundles, a few Leanpub books. Mine were scattered across OneDrive, an old Calibre library, a Dropbox export and my Downloads folder. Some of them I owned three times. Some of them I had paid for and never even downloaded.

A handful of them are about our platform: EPiServer 7 CMS Development, Episerver: The Missing Manual, Pro Episerver Commerce and the CMS Development Fundamentals course book.

We have been using Claude Code against our CMS 12 / Commerce 14 solution for a while now, and I kept thinking the answers to a lot of my questions were sitting in books I already paid for. I didn't want "what the model remembers from the internet." I wanted my books, with page numbers, so I could go check.

So I built a small RAG server over them that any MCP client can call. Along the way I hit a problem that may be familiar if you have pointed an AI at Optimizely content.

(Full disclosure: the part that reads the PDFs and EPUBs is a few Python scripts because the libraries for that are better there. The server that the agent actually talks to is ASP.NET Core on .NET 10. It all runs locally on one machine.)

The Mess

Before any of this was searchable, here is what I was working with:

1,656 ebook files spread across several locations
609 of them were byte-for-byte duplicates (turns out the old Calibre library was built from the same Dropbox folder)
Files named _ - Unknown.pdf and a whole series of comics where every PDF's title was Layout 1
64 Kindle files named only by their ASIN
Several versions of the same Manning early access (MEAP) book
An ASP.NET 3.5 book sitting right next to ASP.NET Core in Action, Third Edition

Point an AI at that pile and you get a confident answer from the wrong edition of the wrong book.

Getting It Into Shape

Most of the work was here. The search part turned out to be easy.

First, every file gets scanned into a SQLite catalog (path, size, hash and whatever metadata is in the file). Then duplicates are found by SHA-256 hash, not by file name. Same name doesn't mean same book and a different name doesn't mean a different book.

Next, files get grouped into books by ISBN when there is one, otherwise by title and first author. Then each book gets enriched from Open Library for subjects, publication year and real titles (for the files named things like appsandserviceswithnet10.pdf).

Then every tech book gets a relevance tier of current, dated or legacy, based on the publication year and the tech versions in the title. I wasn't ready to delete my old ASP.NET 4 books, so legacy just means they are hidden by default.

The Shelf browser filtered to Episerver. Three of the four books are tagged Dated.

Finally, nothing gets moved on its own. The organizer writes a manifest (move this, remove that duplicate or superseded early access version, here's why), I read it, and only then does it run. Every move is logged with its old and new path, so I can reverse it by hand. The only things it deletes are byte-identical duplicates (re-hashed first) and older MEAP versions.

The manifest helped right away. The first dry run had C PROGRAMMING COOK.pdf, HTML5 Cook.epub and jQuery and JavaScript Phras.pdf in it. The regex I wrote to strip "(eBook)" off the end of titles was also eating the end of "Cookbook" and "Phrasebook". It also had all of the Locke & Key comics headed for a _Not books folder thanks to that Layout 1 title. Both were small fixes, and I found them by reading a CSV instead of wondering weeks later why search results looked odd.

The Index

Once the files were cleaned up the index was almost boring:

One passage per PDF page, so citations point to a PDF page you can open (the number printed in the book can be a few pages lower because of front matter). EPUBs get split into roughly 2,000-character chunks.
SQLite FTS5 with the Porter stemmer, ranked by BM25
1,119 books and documents (about 1,050 of them tech books) and 315,000 passages in a single file

No vector database and no embeddings. Plain keyword search with page numbers is cheap and easy to check, and it works well enough for tech books because the questions are full of exact names like IContentLoader, IOrderEvents or ISelectionFactory. I can add embeddings later if keyword search misses things.

The .NET MCP Server

The server is an ASP.NET Core app using the official MCP C# SDK (ModelContextProtocol.AspNetCore 2.3.0) and Microsoft.Data.Sqlite. The whole thing is around 250 lines.

The HTTP part of Program.cs is short (the real file also has a --stdio branch, covered below):

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<BookIndex>();
builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithTools<BookTools>();

var app = builder.Build();
app.MapMcp("/mcp");
app.Run();

It exposes three read-only tools: search_books, read_passage and find_books. The tool description is the only documentation the agent sees, so I use it to explain what the tiers mean:

[McpServerTool(Name = "search_books", ReadOnly = true)]
[Description("""
    Full-text search across a personal library of ~1,100 books and documents ... Books marked legacy
    (outdated technology, e.g. ASP.NET Web Forms or books published in 2012 or earlier) are excluded unless
    includeLegacy is true; passages from 'dated' books may describe older APIs, so check them
    against current docs.
    """)]
public string SearchBooks(string query, int limit = 8, bool includeLegacy = false)

Agents search like developers, which means queries like IContentLoader.Get<T>. That isn't valid FTS5 syntax and would throw an error. So the search tries the query as written, then all of the words, then any of the words:

private static IEnumerable<string> MatchExpressions(string query)
{
    yield return query;                                    // as written
    var words = Regex.Matches(query, @"[\p{L}\p{N}_]+").Select(m => $"\"{m.Value}\"").ToList();
    if (words.Count == 0) yield break;
    yield return string.Join(" ", words);                  // every word
    if (words.Count > 1) yield return string.Join(" OR ", words);   // any word
}

One gotcha in case you try something similar: the catalog is in a second SQLite file, so each connection runs ATTACH DATABASE ... AS cat. Microsoft.Data.Sqlite pools connections, so the second request got a connection that already had cat attached and threw "database cat is already in use". Check pragma_database_list before you attach.

Searches take a few milliseconds when the terms match (a loose any-word query can take tens). It only listens on localhost and the databases are opened read-only.

The Version Problem

Here are the top three of the seven passages search_books returns for IContentLoader.Get<T> (trimmed for space):

1. Episerver The Missing Manual — Jon D Jones (2021), p. 41
   … IContentLoader is a read-only API, meaning it only exposes methods t…
2. Episerver Commerce: A problem - solution approach — Quan Mai (2014), p. 151 [dated: may describe older APIs]
   … this(ServiceLocator.Current.GetInstance<IContentLoader>()) …
3. EPiServer 7 CMS Development — Joel Abrahamsson (2013), p. 97 [dated: may describe older APIs]
   … IContentLoader.Get<T>(ContentReference) : T Retrieves a …

All three are right for when they were written. But two of them would steer a CMS 12 developer the wrong way, because ServiceLocator.Current.GetInstance<>() is exactly the pattern we are trying to get rid of on CMS 12 in favor of constructor injection. Without the tier flag the agent sees three sources that agree with each other and goes with it. With the flag it calls it out: the 2013 book uses the service locator, on CMS 12 inject it.

This isn't really about books. Optimizely sites live for years. Content, internal wikis, old blog posts (yes, including mine) and codebases have EPiServer 7, CMS 11 and CMS 12 answers sitting side by side. If you point an AI at that, whether it's Opal, Copilot or something you built yourself, it will happily hand you the 2013 answer if the 2013 answer matches your words best.

A few things that worked for me:

I cleaned up and deduped before indexing. Duplicate content doesn't just take up space, it gets two votes.
I tagged things by version and freshness, and archived instead of deleting. My old ASP.NET books are still there, they are just out of the default search.
I put the tier in the result, not just in the ranking. The agent can only say "this might be outdated" if the result says so.
I dry-ran anything that writes, and read the manifest.

Hooking It Up

The server can run two ways. For Claude Code I use stdio, which means Claude Code starts the server itself whenever it needs it and there's nothing to remember to run:

dotnet publish -c Release -o publish
claude mcp add shelf -s user -- dotnet C:\path\to\publish\ShelfServer.dll --stdio --Shelf:DataDir=C:\path\to\data

(One gotcha there: .NET's command line config treats --stdio as a key that wants a value, so it swallowed the next argument, which was my data folder. I strip --stdio out before handing the args to the host builder.)

For VS Code, run the server with dotnet run (it listens on localhost:5199) and add a .vscode/mcp.json to your solution:

{ "servers": { "shelf": { "type": "http", "url": "http://localhost:5199/mcp" } } }

Then from inside your CMS 12 solution ask something like "How should I load a page by ContentReference in a CMS 12 view component? Cite my books."

I asked exactly that, ending with "Use my book library and cite book and page."

Claude Code answering from the shelf server. Page numbers are PDF pages.

The agent made 8 search_books calls and quoted three passages. I checked each quote against the index:

ASP.NET Core Recipes by John Ciliberti (2017), p. 148: in a view component, dependencies are passed in through the constructor, the same way as in a controller.
Episerver: The Missing Manual by Jon D Jones (2021), p. 42: constructor-injecting IContentLoader is how you should access the Episerver APIs.
Episerver: The Missing Manual (2021), p. 41: Get<T> with a specific page type saves you from casting. The same page says ServiceLocator hides dependencies and makes code harder to test.

The answer: inject IContentLoader in the view component's constructor and call Get<T> with the ContentReference. It combined a general ASP.NET Core book (for view components) with an Optimizely book (for IContentLoader), which is what I wanted.

Answers change from run to run. In an earlier run of the same question the agent cited a page that was one off from the real one. That is why I keep page numbers in the output: check them before you rely on them.

Thank you to Quan Mai, Jon D Jones, Joel Abrahamsson (author of EPiServer 7 CMS Development) and John Ciliberti for writing the books this post draws on.

A Few Caveats

This only works for DRM-free books. My Kindle and other DRM-locked purchases are in the catalog but aren't searchable (the indexer only reads DRM-free PDF and EPUB), and I'm not stripping DRM to change that. Keyword search will miss some things that embeddings would catch. And "dated" is a guess based on publication years and version numbers in titles, so it's wrong sometimes. It is still better than an agent with no idea which decade a passage came from.

If you would like to see the server code, let me know in the comments and I will share it.

Is anyone else pointing an AI at their Optimizely content and running into the same version problem? How are you tagging what's current? Let me know in the comments.

Time Zone-Aware Scheduled Publishing in Optimizely CMS 13

Mon, 26 Oct 2026 07:02:50 GMT

Scheduling content for audiences in different time zones is a common requirement, especially for websites managed by editors across multiple regions.

Optimizely CMS already supports scheduled publishing, but editors working across time zones may need to calculate the equivalent time in their own time zone before scheduling content.

For example, an editor in Cairo might want a page to go live at 5:00 PM in London. Without a target time-zone selector, the editor needs to calculate the corresponding local time, taking daylight saving time changes into account.

To simplify this workflow, I built Time Zone Publishing, a lightweight, open-source add-on for Optimizely CMS 13.

How it works

The add-on introduces a new Schedule Publish by Time Zone command alongside the existing scheduling option in the CMS Publish menu.

Figure 1: The new scheduling command in the native CMS Publish menu.

Editors can access the feature directly from the familiar publishing interface without navigating to a separate tool.

Selecting the command opens a scheduling dialog where editors can:

Search for and select an IANA time zone.
Choose the intended publication date and time in that zone.
See the equivalent time in their browser's local time zone.
Confirm the schedule using the existing CMS publishing mechanism.

Figure 2: Scheduling publication in London with a local-time preview for Cairo.

In this example, the page is scheduled for October 30, 2026, at 5:00 PM in London, which corresponds to 7:00 PM in Cairo.

Once the editor confirms the schedule, the add-on converts the selected local date and time to UTC and uses the native CMS scheduled publishing functionality.

This keeps the scheduling workflow aligned with the platform rather than introducing a separate background job or publishing service.

Handling daylight saving time

One important consideration when scheduling across time zones is daylight saving time (DST).

During DST transitions, certain local times may be:

Nonexistent: When clocks move forward and skip a period of time.
Ambiguous: When clocks move backward and a local time occurs twice.

The add-on validates both scenarios and prevents editors from confirming a schedule with an invalid or ambiguous local time.

Key features

Schedule publishing using a selected target time zone.
Searchable IANA time-zone selection.
Automatic conversion to UTC.
Preview of the equivalent browser-local time.
Validation of daylight saving time transitions.
Integration with the native CMS Publish menu.
No additional scheduling service or background job required.

Compatibility and installation

Time Zone Publishing v0.1.1 targets .NET 10 and supports Optimizely CMS 13.0.0 or later. The add-on has been successfully tested with CMS 13.0.0 and 13.4.0.

The add-on is available on the Optimizely NuGet feed and can be installed directly into an existing CMS 13 application.

Installation:

dotnet add package Mardy.Optimizely.TimeZonePublishing --version 0.1.1

Source code

GitHub: Optimizely.TimeZonePublishing

NuGet package: Optimizely NuGet feed

Note: The add-on is designed for CMS 13 and is not intended for direct installation into CMS 12 applications.

Feedback, suggestions, and contributions are welcome.