Okapi

Product

What it is

It isn't a site template. Okapi is the content and editing layer you add to an Astro project. Your project stays yours: your pages, your design and your deployment. Okapi adds:

With your agent

Add it to your project

The installation is written up in the repo's INSTALL.md, designed so any coding agent can follow it: Claude Code, Codex, Cursor or another. Open your agent in the project folder and ask.

New or existing project

• Empty folder: the agent starts from the Okapi repo, which is already an Astro project with example blocks that you replace later.
• Existing project: the agent first analyzes it and tells you what fits and what's risky, before installing anything. It stops if the project uses Tailwind 3, Preact or Solid, already has Sanity, or runs Astro older than 7.3. If it goes ahead, your pages, layout and configuration stay as they are, and editor pages are served on routes that don't exist yet, or wherever you tell it. Your existing pages stay in code: to edit one of their sections in the editor, it has to become a block.

What it will ask you

• Which Sanity organization the project goes in, or the project ID if you've already created one.
• For an existing project: which routes come from the editor, and whether the home page comes from the editor or stays yours.
• Which modules you want: slider, 3D logo, reusable components and the AI chat. What you don't pick isn't installed.
• Who will edit, using Sanity's role names: only Administrator (your team), plus Editor (a client who publishes), plus Contributor (someone who only leaves drafts).
• Whether to load example content to see the editor working right away.

Before changing anything, it shows you the plan (which blocks go, which dependencies are removed, which roles stay) and waits for your OK. The chat and components can be switched on or off later in src/okapi.config.json.

What you do yourself

Anything that needs your account. The agent gives you the exact command or steps:

• Log in to Sanity and, if you want, import the example page.
• Invite the client.
• On your host: environment variables (including the AI key, if you use the chat), the domain in CORS and the publish webhook.
• The logged-in editor test (Before you hand off).

With your agent

What to ask for next

Once Okapi is installed, these are the most common requests. They work with any agent: the rules it follows are in the AGENTS.md left in your project.

With your agent

How to ask

The split that keeps the work organized:

Product

Architecture

The core idea: the same PageBuilder component draws the page in the editor and on the site. What you see while editing is the real site, with its styles.

Why an iframe

The canvas lives on its own route (/edit-canvas), separate from the Studio:

• Isolated CSS: the site's CSS doesn't mix with the Studio's.
• Real breakpoints: desktop, tablet and mobile change the iframe's width.
• No exposed drafts: the route is public but has no data of its own. It only draws what an already authenticated editor sends it, over same-origin postMessage.

Block paths

Every block carries data-sanity-path on its root, holding its GROQ path inside the document, for example:

Product

The public site

Pages are static (output: "static"). If the AI chat is on and the host runs functions (Vercel, Netlify, Cloudflare Pages), Astro adds one server function, /api/editor-chat; everything else is still prerendered. With the chat off there is no adapter at all. At build time, each page requests its document from Sanity, and loadSite() fetches settings, navigation, the route map and the component library. Build reads bypass Sanity's CDN on purpose, and a production build stops if Sanity can't be reached or the env is missing, so a failed fetch never deploys an empty site.

HTML first, JavaScript only where needed

PageBuilder renders on the server. Every top-level section that contains a block with js in the registry is wrapped as an island:

Base.astro includes a minimal script. If the page has at least one island, it imports core/render/hydrate.tsx, which runs hydrateRoot on each island with the same props. If there are none, the page doesn't load React.

npm run verify checks this on every build: no public HTML references editor or Studio code, and the home page doesn't exceed 250 KB of JS.

SEO included

• Titles and description: every page has metaTitle, metaDescription, ogImage and noindex. When they're empty, they fall back to the values in Settings, and if those are empty too, to the defaults in code.
• Generated tags: absolute canonical, og:*, Twitter card, sitemap.xml, robots.txt and JSON-LD Organization on the home page.
• URLs: all of them come from pageHref() and resolveLink(). Internal links are references to pages, not hand-typed paths. Adding languages later means changing those two functions.

Product

Okapi Editor

It's the Studio's first tab. It has three columns: pages and layers, canvas and properties. Along the top are undo and redo, + Add, the device selector and Publish. The right column has two tabs, Properties and ✦ Chat. Both side columns resize by dragging their edge (double-click resets).

What you can do

• In-place text. Double-click headings, paragraphs, eyebrows, buttons, and card titles and bodies. Rich text has a floating toolbar with bold, italic, link and unlink.
• Layers. A tree with drag and drop (before, after or inside), insert, duplicate, delete, move, and copy and paste between pages.
• Dragging on the canvas. The selected block shows a ⠿ handle. A blue line shows where it will land, and the move is validated with the same rules as the layers.
• Multi-select. ⇧ or ⌘ + click on the canvas or in the layers. Delete, duplicate, copy and move apply to all of them.
• Images. Drag a file onto an image, card or section background, or upload it from the panel.
• Properties generated from the schema. Every field of every block has its own control; verify fails if any field is left without one.
• ✦ Chat. Ask for changes in your own words and attach up to 3 images. Only what your role allows; changes are drafts that undo in one step. See Permissions and AI chat.

Shortcuts

Saving and publishing

Everything you do is saved automatically as a draft. Nobody sees it until you press Publish. After publishing, the site updates on the next build: a couple of minutes if the project has the webhook set up.

How it saves

The editor uses the Studio's own document store, with no additional SDK. Changes apply locally right away and are saved as a draft. Publish publishes the document. Since the site is static, publishing triggers a rebuild (see Hosting and publishing).

Text editing without caret jumps

While you type, the canvas holds back the renders coming from the editor. When you finish, it restores the exact DOM React expects, and only then applies the new value. Rich text is converted between Portable Text and editable HTML in core/editor/richtext.ts, which keeps the targets of existing links by their key.

Editor ⇄ canvas protocol

Same-origin postMessage messages, typed in core/editor/protocol.ts.

Product

Styles and tokens

All of the design comes from src/theme/tokens.css, the first file you change in every project. It holds the colors per theme (light, dark, brand), the radii, the type scale, spacing and page width. Tailwind 4 exposes them as utilities (bg-ok-surface text-ok-fg gap-ok-md rounded-ok-main), and since colors read the section's data-ok-theme, every block adapts to the theme on its own. Tailwind's default palette is removed on purpose: a new color is added as a token. Everything Okapi defines carries a prefix (--ok-* variables, ok-* classes, ok- utilities), so it never clashes with the project's own Tailwind, shadcn or DaisyUI.

Style panel

Every block has a design field that the editor shows as the style panel. It offers tokens only, no free-form CSS, and each value can be set for all screens, tablet and mobile.

Box

The free-form container: it stacks, lays out in a row or builds a grid, with token gaps, alignment and wrapping. It can be nested. On tablet, grids drop to 2 columns and on mobile to 1; rows stack on mobile.

Product

Components

A component is a component document that holds sections. A page uses it through a componentRef block (an instance). If you edit the component, all of its instances change.

In the editor

• Make component: saves the selected section to the library and replaces it with an instance.
• + Add: lists the library's components so you can insert them as instances.
• Edit component: opens the original component for editing.
• Detach: turns the instance into a standalone, editable copy.
• The canvas selects an instance as a single block.

Per-instance overrides

If you double-click a text or drop an image inside an instance, the change is saved on that instance only, in its overrides list. The original is untouched. Each override targets "<blockKey>.<field>", is applied at render time (core/render/overrides.ts), and the panel lists them with a Reset button.

Product

Permissions and AI chat

Each project decides who can do what in src/okapi.policy.ts: every Sanity role gets a list of permissions and, optionally, the block types it may add. The editor and the chat follow it. The chat can never do more than the person using it.

Roles and invitations

The role is set in Sanity, not in Okapi. Invite people in sanity.io/manage → your project → Members → Invite and pick the role there (you can change it later from the same list), or from a terminal: npx sanity users invite ana@client.com --role editor.

How the chat works

• The editor sends the request, with the person's Sanity session, to the site's own function /api/editor-chat.
• The function checks the session with Sanity, works out the person's permissions, reads the page from Sanity and asks the model with the project's key, stored in the host. The key never reaches the browser.
• The model only proposes changes. The editor checks each one against the permissions, the block registry and the schema, and applies the valid ones as one undo step, saved as a draft. The chat never publishes.
• Images: attach up to 3 (📎, paste or drop). The original is uploaded to Sanity; the model sees a smaller copy.
• Model picker: every provider with a key on the host appears (Anthropic, OpenAI, OpenRouter). AI_MODELS limits the list; the first is the default.

Cost and privacy

• One key per project, with its own spend limit at the provider. Every request has a token cap and a per-person rate limit; the drafts-only role has no chat by default.
• The page being edited and any attached images are sent to the chosen provider. Say so to the client.
• The chat is optional: with features.chat: false in src/okapi.config.json the site stays fully static.

Product

Blocks

Okapi ships with these example blocks. At install, npm run okapi:setup removes the optional ones you don't want (Slider, 3D Logo); each project then adds its own. The single registry is src/blocks/meta.ts. It defines which types exist, what they can contain, which ones need JS and what the editor offers in each place. schemas.ts and components.tsx are typed against the registry: if something is missing, the compiler flags it.

Integration

Installation

The full guide is INSTALL.md, at the root of the repo, written for any agent to follow. There are two paths, and both end with the same shared steps: Sanity, .env, first run, roles, production and verify.

Path A: new project

The Okapi repo is already a complete Astro project: clone it, remove its .git and run npm install.

Path B: existing project

First the agent analyzes the project and shows a report with ✅, ⚠️ and 🛑. 🛑 means it doesn't install: Astro older than 7.3, Preact or Solid (Okapi sets the project's JSX to React), Tailwind 3 (Okapi needs Tailwind 4 and a project can't have both), or Sanity already set up. ⚠️ means it goes on only if you accept it: Vue or Svelte, several languages, dynamic routes at the root. Okapi's [slug] outranks a blog's or Starlight's [...slug], so the project's slugs go in reservedSlugs, or editor pages move to /p/<slug> with pagesBase. A project without Tailwind is fine: Okapi's Tailwind has no preflight and only loads in its own layouts. The project's trailingSlash stays as it is: Okapi's routes, links, canonicals and sitemap follow it.

Then pieces are copied into the project without overwriting anything that already exists. If a route collides, the agent stops and asks.

Tested on Astro's official blog template: build and verify pass, the blog is untouched and src/core is unchanged.

Choosing what to install

Before installing, the agent asks which modules the person wants and runs npm run okapi:setup with the answers: first with --dry-run to show the plan, then with --yes. If an answer is missing, the script does nothing and says which one. Run in a terminal without flags, it asks the questions itself. It refuses to run inside the Okapi repo.

Blocks are deleted, so the site ships less code. Chat and components are flags that core reads (core/config.ts), so core stays the same in every project and they can be switched later. Checks pass with any combination: tested with everything off, the page JS dropped and a Vercel build came out fully static.

Configuration that gets merged

• package.json: the Sanity, React 19 and Tailwind 4 dependencies (plus Embla and three if the slider and the 3D logo stay, and the host adapters if the chat is on), engines: node >=22.12 and the okapi:setup script. Sanity at its current versions: sanity ^6.19, @sanity/client 8, @sanity/ui 4, @sanity/icons 5. If the project has newer ones, they stay; older ones are raised within the same major.
• astro.config: nothing is pasted. It imports okapi(), okapiSanity(), okapiAdapter() and okapiSite() from src/core/astro/okapi.ts and adds them next to react() and the Tailwind plugin. okapi() brings the chat route, the project's final trailingSlash, Sanity's image CDN and the optimizeDeps list, merged with the project's own. The project's output and site are kept.
• tsconfig: React JSX and the @/* → ./src/* alias.

Integration

The contract with your project

What your code has to respect for the editor to work. Everything else is up to you.

Working with it

The code

The rule the product rests on: src/core is the same in every project. A fix in core is made in the Okapi repo and then pulled into each project. What's specific to each project lives in blocks, theme and its layouts. Once there are 3 or more projects in production, core becomes a private package and fixes arrive with npm update.

Rules most often broken

• Blocks receive everything as props and carry {...editable(…)} on their root. They never fetch: the canvas draws them with the document it receives.
• Style with Tailwind utilities built on the tokens. No literal colors.
• Design assets (logos, textures) are code; they don't go in the CMS.
• macOS is case-insensitive: never put Foo.tsx and foo.ts in the same folder.

Working with it

Adding a block

Working with it

Hosting and publishing

Any host works. Build with npm run build, output dist, Node 22.12+ and npm. With the AI chat on, use Vercel or Netlify (built in) or Cloudflare Pages (npm i @astrojs/cloudflare wrangler once): Okapi picks the adapter from where the build runs and adds the chat's single function. On any other host the site works and the chat shows as unavailable.

Working with it

Quality and testing

npm run verify

Run it before every handoff and after any change to core. It checks the things that break silently:

• The installed Sanity version has its patch.
• Links and routes resolve correctly (routes.check).
• Every field of every block has a control in the panel (check-editor-schema).
• Insert, move, delete and duplicate keep the document valid, and island detection is correct (ops.check).
• Tokens produce the expected CSS, with no selector injection (stylesheet.check).
• Overrides apply to the right block and never touch the original (overrides.check).
• Each role's permissions gate every change the chat proposes, and provider requests have the right shape (chat.check).
• Rich text round-trips to editable HTML without breaking out of attributes (richtext.check).
• The build passes, the public HTML contains no editor or Studio code, and the home page stays at or under 250 KB of JS.
• The home page has real content, an absolute canonical, a sitemap and robots.txt.
• Given a URL (npm run verify -- https://your-domain), it also checks that /, /studio and /edit-canvas respond.

Logged-in smoke test

Flows that need a login can't be automated without credentials. Test them by hand, on a throwaway page, before handing off a site:

1. Type into a heading on the page, reload, and check that the text is still there.
2. Bold, italic and a link in a paragraph. Insert, duplicate, delete and drag a layer. Undo and redo.
3. Drop an image on an Image block: it uploads and shows up.
4. Make component on a section. Edit text on an instance: only that one changes. Reset. Edit component: all of them change.
5. Publish, then npm run build, and the change is on the static page.
6. Log in as a client-role user: they don't see styles or structure actions.
7. With View as each role, only what okapi.policy.ts allows shows up; the chat refuses the rest.
8. ✦ Chat: "make the selected heading shorter" is applied, and Undo reverts it.

Working with it

Known issues

Each of these has come up before and has a known fix.

Context

Decisions

Why it's built this way. Before changing any of these, read the reasoning.

Context

History

The milestones, grouped. The details are in the repo's commits.

With your agent

If something breaks

Tell your agent exactly what you see. Each of these has happened before and has a known fix.

With your agent

Before you hand off

Ask your agent to "run verify". Then, logged in with your own user, on a throwaway page:

1. Type into a heading on the page, reload, and check that the text is still there.
2. Bold, italic and a link in a paragraph. Insert, duplicate, delete and drag a block. Undo and redo.
3. Drop an image on an Image block: it uploads and shows up.
4. Create a component, change the text on one instance (only that one changes) and edit the original (all of them change).
5. Publish and see the change on the site after the build.
6. Log in as the client: they don't see styles or structure actions.
7. With View as each role, only what okapi.policy.ts allows shows up; the chat refuses the rest.
8. ✦ Chat: "make the selected heading shorter" is applied, and Undo reverts it.
9. Settings filled in: site name, description and social sharing image.
10. The domain is in CORS and the publish webhook works.

With your agent

Glossary

Block

A piece of the page: a heading, paragraph, image, card, slider…

Section

A horizontal band of the page that holds blocks. It has a theme (light, dark or brand), spacing and a background.

Box

A free-form container for laying out blocks in a column, a row or a grid.

Component

A section saved to the library so it can be reused across pages.

Instance

Each use of a component on a page. If you change the component, every instance changes.

Override

A text or image changed on a single instance, without touching the component.

Token

A named design value: a color, a spacing step, a radius. Changing it changes the whole site.

Draft

What you've edited but haven't published yet. Only the team sees it.

Publish

Put content live. With the webhook, the site rebuilds within minutes.

Build

When the site is generated from the published content. It takes a few seconds, plus install time.

Webhook

The notification Sanity sends on publish so your host runs a build.

Studio

Sanity's admin panel, at /studio. The editor lives inside it.

Canvas

The view of the page inside the editor, where you click and type.

verify

The project's automated check: if it passes, the important parts work.

INSTALL.md

The guide any agent follows to add Okapi to a project.

AGENTS.md

The rules the agent reads before working on the project. Claude Code reads them through CLAUDE.md.

Skill

A Claude Code shortcut: okapi-astro fetches INSTALL.md and follows it.

Core

src/core, the editor's code. It's the same in every project and gets fixed in the Okapi repo.

okapi:setup

The install script: keeps only the modules you chose.

okapi.config.json

What the project uses: the chat and components, on or off.

Role

Administrator, Editor, Contributor or Viewer: set in Sanity when you invite someone. Okapi uses the same names.

okapi.policy.ts

Who can do what in the editor and the chat, per Sanity role.

✦ Chat

The editor's AI assistant. It proposes changes; you keep or undo them.

Context

What's next

Ordered by impact. None of these blocks current use.