Refino, described precisely.

Status

Requirements

Today, Refino can be added to a site that meets all of these:

• Built with React. Next.js and Vite projects are supported directly. A plain React project can be integrated by hand. Sites produced by Claude Code, Cursor, Codex, v0, Lovable, Bolt and Replit are usually React sites.
• Code kept in a GitHub repository you own or administer. Saving an edit commits to that repository.
• Deployed from that repository, so that a commit becomes a live change without anyone uploading files by hand. Vercel, Netlify and Cloudflare all work this way.

If your site is not one of these, it is not a lost cause. The underlying design is not tied to React or to GitHub. Other frameworks and other code hosts are planned. Tell us what you have.

If you are not sure whether your site meets them, the ownership guides explain what a GitHub repository is and how hosting connects to it, in plain language.

Concepts

There are only four.

The copy file

A flat JSON object. Keys are IDs, values are strings. Key order is preserved so diffs stay readable.

{
  "home.hero.title": "Architecture for people who plan to stay.",
  "home.hero.body": "We design houses and small buildings for clients who want something that lasts.",
  "home.hero.cta": "See our work",
  "footer.note": "Now taking on projects for next spring."
}

The rules the file obeys:

• IDs are dotted segments of letters, digits, hyphens and underscores. No spaces, no slashes.
• Values are plain text. Line breaks are allowed. HTML is not interpreted.
• The editor changes values. It never adds, removes or renames a key. Adding a new piece of copy to the site is a code change: add the key to the file and reference it from the page in the same commit. Your coding agent does this as part of building a new section.
• There is exactly one copy file per site, and it is the only place editable copy lives.

Because the file is ordinary JSON in your repository, every tool you already use can read and write it. A coding agent changing a headline and the owner changing it in the browser are making the same edit to the same file.

Editing

In the page code, each piece of editable copy is an element that carries its ID. Outside edit mode it renders as the plain element, with nothing extra: no attributes, no handlers, no editor code.

<EditableText id="home.hero.title" as="h1" className="hero__title" />

In edit mode the same element becomes editable in place. The interaction:

Links and buttons that are editable do not navigate or submit while in edit mode, so you can change their labels without triggering them. Pasted content is reduced to plain text.

Saving and conflicts

Save sends only the IDs that changed, together with the revision of the copy file those changes were based on. The server applies them to the file and commits it to your repository. A one-word change is a one-line diff, and the commit appears in your history like any other.

If the file has changed since you loaded it, the save is refused as a conflict rather than applied on top of the newer version. This is what makes it safe to have a coding agent and a person editing the same site. Reload, see the current text, and edit again.

If nothing actually changed, nothing is committed.

What the browser can and cannot do

• It can send changed values and the revision they are based on. That is the whole request.
• It cannot name a file, repository or branch. Those are configured on the server.
• It cannot introduce a new ID. Unknown IDs are rejected.
• It never holds a repository credential. Authentication is a server-side session.

Onboarding a site

Adding Refino to an existing site is a one-time code change: move the visible text into the copy file and make the page read from it. You do not have to make that change yourself.

To start, open your website’s repository in your coding agent and ask it to install Refino on this site. It runs npx @getrefino/cli@latest init --agent, which prints a link: open it, sign in, and connect the repository with the Refino GitHub App. You do not create a token or copy any settings between tools. You can also start from Connect a website in your dashboard; both end at the same site.

The setup tool does this in stages, and each stage can be inspected:

1. Inspect. Identify the framework (Next.js, Vite, plain React), the package manager and the entry points.
2. Scan. Find the text a visitor can see on the homepage and in shared parts like the header and footer, and propose an ID for each.
3. Plan. Write out what will change, file by file, before anything changes.
4. Generate instructions. Produce a set of steps specific to this repository, written for a coding agent. Any agent will do: Claude Code, Cursor, Codex, or another.
5. Apply the safe parts. Create the copy file and the isolated setup files that do not touch existing code.
6. Verify. Check that the agent’s work is complete and correct, and say exactly what is missing if it is not. The agent fixes it, and verification runs again, until it passes, including your site’s production build. It reports which pages are editable.

Then commit, merge into the branch your site deploys from, and deploy as usual. Your dashboard follows each step from what it can see, and offers Open editor once your live site’s editor works. A saved edit shows as live only when your host’s production deployment includes it.

The result is a site whose visible copy lives in one file and whose code, design, hosting and deployment are otherwise unchanged.

What is not included

These are deliberate, and they are what keep the product simple and out of your coding agent’s way:

• No rich text: no bold, links or lists inside a single value. Text that mixes formatting with copy is split into separate pieces, or stays as code.
• No images, layout, colours or components.
• No page creation.
• No content database, content store or sync.
• No collaboration, approvals or roles. One owner, editing their own site.

We are interested in helping with the words themselves, such as suggesting rewrites in your own voice or learning which wording works better. None of that exists yet, and this page will say so plainly when it does.

For the plain-language version of all this, see how it works.