Areca Docs

Quickstart with an AI agent

Let an AI coding agent set up Areca in a new website project. The agent checks your project, asks a few questions, builds the content model, connects the site SDK and makes a first release.

The areca-quickstart skill lets an AI coding agent set up Areca for you. The agent reads your project, asks you a few questions, creates the content model, wires in the site SDK and makes a first release. You make the decisions. The agent does the work.

This guide is for developers who start a new client website. It explains what to prepare, what the agent asks, what it changes, and how to keep the site up to date.

For client creation, tokens and the complete installation checklist, start with Developer setup with Areca skills.

Prefer to do each step yourself? Follow Installation and setup instead.

Before you start

You need these things first.

  • A site in the CMS. The agent cannot create sites or tokens. Create the client and site in the CMS under Agency › Clients › New site. Use http://localhost:3001 as the Production URL for now. You can change it later.
  • Website credentials. Save the site token when you create the site. For code-first manifest pushes only, obtain a schema-write token separately in Settings › Developer. The CMS shows each one only once. If you lose one, rotate it under Settings › Developer.
  • Connect AI. The agent uses the site's MCP server to create the content model. Connect your AI app first. See Connect AI. If you cannot connect, the agent uses the code-first path instead. See How the content model is created.
  • Node.js 22.18 or newer. The CLI loads areca.config.ts directly. On an older Node version, the agent runs the CLI through tsx.
  • A website project. Use a project with a package.json at its root. The agent works with TanStack Start, Next.js, Astro and other frameworks. If you have no project yet, create one first.
  • A coding agent with a terminal. The agent must read and change files in your project and run commands. Claude Code, Codex, Cursor and similar tools work. Chat apps such as the Claude app or ChatGPT cannot run this skill.

Install the skill

Install the skill in the website project. Pick the method that fits your tools.

Run the installer and select areca-quickstart in the skill list:

npx @areca-cms/skills

To skip the prompts, pass the skill name and the agent:

npx @areca-cms/skills add -a claude-code -s areca-quickstart -y

Run the skill

Open the website project in your agent and run the skill.

  • In Claude Code, type /areca-quickstart. With the plugin, type /areca:areca-quickstart.
  • In other agents, such as Codex or Cursor, ask: "run the areca-quickstart skill".

What the agent asks

The agent first checks your project. It detects the framework, the package manager and whether the project already uses more than one language. It asks only about what it cannot find.

Then it asks in four batches.

  1. Project. What the site is for, and the framework and package manager to use.
  2. Content model. Which content types the site needs. The agent suggests recipes such as blog, vacancies, team and services. You can keep, change or skip any of them.
  3. Languages. Which languages the site uses, and which one is the default.
  4. Build and preview. How the site gets its content at build time, and whether to add a preview route.

After the batches, the agent shows the proposed schema. It makes no changes until you approve it.

How the content model is created

The agent uses one of two paths. MCP-first is the default.

  • MCP-first. The agent creates the collections, sections and languages through the Areca MCP server. Then areca manifest pull writes them into areca.config.ts. This path needs an agency admin connection.
  • Code-first. The agent writes areca.config.ts itself, then runs areca manifest push. The agent uses this path when the MCP server is not connected, or when you are not an agency admin. This path needs the schema-write token in .env.local.

A push removes collections you leave out

A manifest push disables any collection that is missing from areca.config.ts. Check the proposed schema before you approve it. See Syncing the schema.

What the agent creates or changes

The agent works in the website project. These files change.

File or folderWhat changes
areca.config.tsThe collections, fields, sections and languages. Written by the agent (code-first) or by areca manifest pull (MCP-first).
.env.example and .env.localCreated by areca init. You paste the tokens into .env.local yourself. The agent never asks for them in chat.
.gitignoreUpdated by areca init to ignore .env.local and the pulled content files.
package.jsonAdds the content:pull and content:sync scripts, and a prebuild hook that pulls content before the build.
src/generated/content/The pulled content and the areca.gen.ts types file. Commit areca.gen.ts.
Framework filesThe loaders or routes that read content, written for your framework.
LanguagesLocale routing for the languages you chose, through Paraglide or explicit locale routes.
Optional pagesSample pages and a preview route, if you chose them.

The agent installs @areca-cms/site-sdk and runs areca init for you. See Installation and setup for what areca init writes.

Make the first release

A release needs content to show. So the agent makes a first release before it finishes.

  1. For a new site, it asks to use Demo mode. When it is connected as an agency admin, it does this itself with the set_publishing_mode tool. That is refused if the site was ever live in production. For a site that has already been live, use a development environment rather than switching it to Demo.
  2. It creates a few entries with a [Sample] prefix, so you can find and delete them later.
  3. It marks the entries ready.
  4. It asks you before it goes live.
  5. When you agree, it goes live, pulls the content and builds the site. Then it checks that a page renders.

If the connection cannot go live, the agent asks you to press Publish demo in the CMS. To let the agent go live, connect the app again and tick Allow going live. See Connect AI.

Demo releases are not public

Demo releases are never visible to visitors. They are for previews and testing. For a public site, switch the site to Production and set up deployment. See Going live and Go-live builds.

Stay up to date

After setup, one command keeps the site in step with the CMS:

pnpm run content:sync

This command pulls the content model into areca.config.ts, then pulls the published content. Use it on every new machine and before you build.

On a code-first site, run pnpm run content:pull instead. It pulls the content only.

Add or change content later

Run /areca-quickstart again in the same project. The skill sees the existing setup and switches to add or change content mode. It does not repeat the setup.

Work on a live site

Be careful on a live site

Schema changes and go-live actions affect the real site. The agent asks before it goes live. Still, check the proposed schema closely. When the site has a development environment, make the changes there first and push them after review. Without one, ask your agency admin to create one, or test changes on a copy of the site first.

Troubleshooting

SymptomWhat to do
The agent says the Areca MCP is not connected.Connect the app first. See Connect AI. Then start a new agent session, because some apps keep the tool list from the start of a session.
MCP-first setup is refused.Only an agency admin connection can create the content model. Ask an agency admin to connect, or let the agent use code-first setup.
areca pull fails and says there is no release.Make a first release. Run the skill again, or go live from the CMS. areca pull needs a release to read.
The CLI fails while it loads areca.config.ts.Use Node.js 22.18 or newer. Or run the CLI through tsx.
The schema push is refused.Check that ARECA_SCHEMA_TOKEN in .env.local is the current schema-write token. If it was rotated, copy the new one from Settings › Developer.
The build cannot find the site token.Check .env.local. Load env files before the dev server or build starts. See Environment variables.
A schema change you made in the CMS disappeared.The site gets its content types from code. The next manifest push replaces them. Change areca.config.ts instead. See Connect AI.
Demo content does not show to visitors.Demo releases are never public. Switch to Production to publish for visitors.

What the agent will never do

  • Print or paste a token in the chat. You paste tokens into .env.local.
  • Go live without asking you first.
  • Delete a collection, entry or file without your confirmation.
  • Run areca init --force. That command overwrites existing files.
  • Create a site or a token. Only the CMS can do that.

Example site walkthrough

Tour the demo site in the examples/demo-site folder, from its content schema and pull step to rendered articles, the preview route and the health check.

Agent skills

Install the Areca skills so AI coding agents and chat apps know how to use the site SDK and the MCP server.

On this page

Before you startInstall the skillRun the skillWhat the agent asksHow the content model is createdWhat the agent creates or changesMake the first releaseStay up to dateAdd or change content laterWork on a live siteTroubleshootingWhat the agent will never doRelated