Overview

VentureKit CMS is an AI-native, headless content platform. Instead of a blank editor, it runs a team of configurable AI personas that research, write, translate, illustrate, optimize for SEO and schedule your content. You stay in control at every step: nothing is published without your approval.

There are two surfaces you work with:

• The CMS workspace — the admin app (where you are signed in) under /app. This is where you configure everything and review & approve content.
• Your website — a separate Next.js project that you own. It renders your published content through the @venturekit/cms-next SDK. The CMS is headless: it never serves your public pages, it gives your site the data and the SEO emissions.

This guide covers three things, in order:

1. Connect your website to the CMS with the SDK.
2. Configure your workspace so the editorial team can start producing content.
3. The validation flow — how AI drafts become reviewed, approved and published content.

Connect your website

Your site stays entirely yours. The SDK mounts the blog routes and emits SEO (canonical URLs, hreflang alternates, sitemaps, robots, JSON-LD and OpenGraph) directly from CMS data — so there is no blog code for you to write or maintain.

Prerequisites

• A Next.js website using the App Router.
• Node.js 18 or newer.
• A CMS API key (a cms_sk_… secret) — issued in the next step.

Step 1 — Set your site origin & base path

In the workspace, open Strategy → Public site (this is also step 2 of onboarding). Set your public site origin (for example https://acme.com, no trailing slash) and the base path under which your blog mounts (usually /). These two values drive every absolute URL the CMS emits — canonical, hreflang, sitemap and OG. Until they are set, those URLs are blank.

Step 2 — Issue an API key

On the same page, click Generate. The plaintext cms_sk_… secret is shown once — copy it immediately and paste it into your website's CMS_SECRET_KEY environment variable. It is a server-side secret: never expose it to the browser (never prefix it with NEXT_PUBLIC_). You can revoke or rotate keys at any time; revoking one immediately cuts off any deployment using it.

Step 3 — Install the SDK

npm install @venturekit/cms-next

Step 4 — Add the integration files

The Strategy → Public site page generates these files pre-filled with your origin and API host — copy them straight into your repo. They are shown here for reference (replace the placeholder origin and API URL with your own):

cms.config.ts

import { defineCmsConfig } from '@venturekit/cms-next';

export const cmsConfig = defineCmsConfig({
  apiUrl: 'https://api.cms.your-tenant.com',
  publicSiteOrigin: 'https://acme.com',
  publicSiteBasePath: '/',
  // Loaded from .env — NEVER prefix with NEXT_PUBLIC_.
  secretKey: process.env.CMS_SECRET_KEY!,
});

app/blog/[[...slug]]/page.tsx

import { BlogRouteHandler } from '@venturekit/cms-next/app';
import { cmsConfig } from '@/cms.config';

export default BlogRouteHandler({ config: cmsConfig });
export const generateMetadata = BlogRouteHandler.generateMetadata({ config: cmsConfig });
export const generateStaticParams = BlogRouteHandler.generateStaticParams({ config: cmsConfig });

app/blog/sitemap-blog.xml/route.ts

import { blogSitemapHandler } from '@venturekit/cms-next/app';
import { cmsConfig } from '@/cms.config';

export const dynamic = 'force-dynamic';
export const GET = blogSitemapHandler({ config: cmsConfig });

app/sitemap.xml/route.ts

import { sitemapIndexHandler } from '@venturekit/cms-next/app';
import { cmsConfig } from '@/cms.config';

// A sitemap-index. One submission URL covers the blog sub-sitemap
// plus any of your own sub-sitemaps you add later.
export const dynamic = 'force-dynamic';
export const GET = sitemapIndexHandler({
  config: cmsConfig,
  children: ['/blog/sitemap-blog.xml'],
});

app/robots.ts

import { robotsHandler } from '@venturekit/cms-next/app';
import { cmsConfig } from '@/cms.config';

export default robotsHandler({ config: cmsConfig });

.env

# Server-side only. Paste the value from the "Generate" dialog.
CMS_SECRET_KEY=cms_sk_replace_with_your_key

That is the whole integration. Every published post now resolves at its localized URL, with hreflang alternates, a blog sub-sitemap rolled into your sitemap index, a robots response, plus JSON-LD and OpenGraph tags — all kept in sync with what you approve in the workspace.

Configure your workspace

The first time you sign in, a five-step wizard walks you through the minimum needed to start producing content. You can revisit and expand every one of these later.

1. Brand & locales — name your site and pick its primary content locale (English, Français or العربية). New posts default to this canonical locale.
2. Public website — save your site origin and base path, then issue the API key (see Connect your website).
3. First author — add at least one byline (human or AI persona). Bylines drive E-E-A-T signals and JSON-LD on rendered posts.
4. First cluster — create one topical pillar with a few seed keywords. This is what the strategist mines for topic suggestions.
5. AI keys — confirm your Anthropic and Google API keys are provisioned (entered under Settings → Secrets). These power the personas, so the wizard will not finish until they resolve.

Once the wizard is complete you land in the Inbox. The rest of your configuration lives in Settings and Strategy and is covered in the next three sections.

AI & social credentials

All credentials live under Settings → Secrets and are encrypted at rest. Two categories matter:

AI providers

The personas call large language models. Anthropic and Google keys are required; OpenAI is optional. Keys are per workspace — you bring your own — and usage is metered so you can see the cost of every post (see Audit & cost).

Social connections

To let the CMS publish on your behalf, connect your accounts via OAuth. Four platforms are supported: LinkedIn, X, Facebook and Instagram. You authorize once; the CMS stores the resulting tokens (encrypted) and uses them only to publish content you have approved. A few platform specifics worth knowing:

• LinkedIn posts as the connected member (scopes openid, profile, w_member_social).
• X uses a rotating refresh token (access tokens are short-lived), so publishing keeps working without you re-connecting.
• Facebook publishes to a Facebook Page you manage — connect with an account that administers at least one Page.
• Instagram publishes to the Instagram Business account linked to that Page, through the Meta Graph API.

You can disconnect any platform at any time, which revokes the stored tokens immediately. See the Privacy Policy for exactly what is stored and how it is used.

Your editorial team

The editorial team is a set of configurable personas. Each one has its own provider and model, a system prompt, and taboos. You can fork the platform defaults per workspace, swap models as better ones ship, and pause optional roles. The roles are:

• Editor-in-chief — owns publication voice, brand and taboos.
• Strategist — picks topics and owns coverage and the calendar.
• Researcher — pulls primary sources and returns verifiable facts.
• Writer — drafts from a brief, in your configured voice.
• Line editor — tightens prose and removes clichés.
• SEO editor — keyword placement, metadata bounds, schema and internal links.
• Critic — scores each draft against a rubric and sends weak work back.
• Art director — briefs and generates on-brand cover and inline imagery.
• Sub-editor — final polish: titles, deks and headline variants.
• Translator — transcreates approved articles between your locales.

Several roles (writer, line editor, SEO editor, critic, sub-editor and translator) are locale-bound — you configure one persona per locale so voice and rules can differ by language. A workflow is simply an ordered list of steps, each performed by one of these personas, and each step can be flagged as requiring your review.

Content strategy

The Strategy area is the content map your team produces against. You set it up once and adjust it occasionally:

• Clusters — topical pillars with keywords and per-platform eligibility. The strategist mines these to suggest topics that fit your goals.
• Authors — bylines (human or AI persona) that drive E-E-A-T and JSON-LD on rendered posts.
• Internal & related links — contextual and related-article links the SEO editor weaves into drafts.
• Locales — enable the languages you ship (fr / en / ar). When you approve a canonical article, it is auto-translated into every enabled locale.
• Cadence — blog and social cadence targets that pace topic suggestions and how much lands in your Inbox.

With clusters, authors and cadence in place, the strategist starts proposing topics — and approving one kicks off an editorial run. That is the validation flow.

The validation flow

The core principle: the AI does the work, you hold the approve button. No content reaches your website or social accounts without a human decision.

The content lifecycle

Every post — blog or social — moves through a small set of statuses: pending → approved → scheduled → publishing → published. A post you turn down becomes declined, and anything that errors during publishing is marked failed with a reason and a retry count.

Editorial runs

Producing a post is an editorial run: a sequence of persona steps — for example research → draft → critic (scores against a rubric) → line edit → SEO → sub-edit. A run is queued, then running. When it reaches a step you flagged as requiring review, it pauses at awaiting_review and waits for you. When all steps are done it is completed; a rejected run is cancelled.

The Inbox

The Inbox is your command center. It gathers everything that needs a decision: runs awaiting review, posts pending approval, and the strategist's topic suggestions. Working the Inbox to zero is the daily loop.

Your three actions at a review gate

• Approve — accept the step's output; the run advances to the next step.
• Edit — override the step's output with your own version, then advance. Downstream steps use your edit.
• Reject — stop the run with a note explaining why. The work is sent back rather than published; you can regenerate or re-queue the topic.

What happens after you approve

Approving a canonical article fans the work out automatically: it is translated into every enabled locale, one social variant per platform and locale is drafted, and cover and inline images are generated — each going through the same lightweight review loop before it can ship.

Scheduling & publishing

Approved content is scheduled to each channel's best times, spread for angle diversity, and published server-side on a schedule. There is no human at publish time — you already made the decision at the review gate. If a publish fails, the post surfaces the error and is retried.

Audit & cost

Every meaningful action is recorded. Saves, publishes, review decisions, failures and each AI call land in a per-workspace audit log with actor attribution, so you always know who (or which persona) did what, and when.

Per-post cost is tracked across a post's whole lineage — the canonical article, its images, its translations and its social variants — broken down by provider and model, with call and token counts. You always know what a post cost to produce.

Need a hand? Email hello@venturekit.dev or sign in to your workspace to get started.