SEOMANTIK
Choose a plan
Documentation

seomantik-topic

Last updated: September 14, 2026

It turns your domain and one seed keyword into a complete build plan: the exact pages to create or fix, in the order to do them, each traced back to live search data.

It maps everything people search for around your topic, checks what your site already covers and how well, finds the questions worth answering and who holds the answer today, designs the pages your site should have, and sorts all of it into waves. Blogs, SaaS, online shops and local service businesses each get a plan shaped for their kind of site.

What to expect

Starting

Type one line in your project folder:

Run seomantik-topic on yourdomain.com with the seed keyword "your main keyword"

The first thing it prints is your allowance: sites, briefs, data used and the reset date.

The questions it asks you

It asks once at the start, all in one message, then works through the plan and only stops where your judgement matters.

  • What kind of site this is (blog, SaaS, shop or local service). It reads your homepage first and shows what it found; you confirm or correct it.
  • Whether the site sells what it writes about (bookings, products, a service). This decides who your articles may name later.
  • The seed keyword. Give the broad subject of your site, not a full question. If you give several, it explains that one run takes one seed and helps you pick.
  • The market: the country and language your plan is for.
  • That the site is yours to change, since the plan includes edits and redirects.

It also offers to connect your CMS (WordPress is the common case). That is optional: without it, your site is read by a free crawler instead.

Where it stops for you

  • The topic map, once built: the groups of subjects it found. You know your niche better than the data does, so correcting the grouping here is normal.
  • Before the first paid loop of a step: it tells you how many calls it is about to make and waits for your go.
  • The page structure: which pages become hubs and which sit under them.
  • Any check that fails: it says what failed and why, and stops.

How long it takes

A plan runs in phases, and a long plan spans several Claude Code sessions. That is by design: every phase saves its work to the folder, so a new session picks up exactly where the last one stopped and pays for nothing twice. At the end of each phase it tells you the sentence to paste into the next session.

The phases, in plain words

The session names phases by number, so they are numbered here the same way.

  1. Setup. Confirms your site, market and seed, and writes project.config.
  2. The topic map. Everything people search for around your seed: keywords, the pages that rank for them, the entities they mention and what AI answers say. Your site plays no part yet, so a brand new site gets the same quality map.
  3. Your site against the map. Reads every page of your site and grades how well each subject is covered: strong, adequate, thin or not at all. It also finds pages that are off topic, orphaned (nothing links to them) or too weak to count.
  4. The questions. The questions worth answering, ranked by how much your site needs them. For each one it records what Google's AI Overview answers in your market and which sites it cites, and whether yours is one of them. ChatGPT is measured alongside when it is available.
  5. The page structure. Every page your site should have, arranged in hubs and the pages under them, every internal link that should exist, and what to do with each existing page that is in the wrong shape.
  6. The build list. Every action scored and put in order: wave 1 fixes what already exists, wave 2 builds one complete cluster, wave 3 holds the rest. Unclear items are deferred, with the reason.
  7. Every month afterwards, the monthly progress pass (below).

How it counts

  • One site. The run opens your site on your subscription before anything is bought. Re-running or resuming it later is free.
  • Data used. Phases 1 to 3 buy search data (the topic map, your site's rankings, the questions). Reading your site is free, and the page structure and the build list cost nothing.
  • No briefs. Building the plan never uses a brief. Briefs are used when pages are written.

Running it again, and on more than one site

Resuming. Type your first line again in the same folder, or paste the sentence the last phase printed. It continues from the first unfinished step.

A second site. Name another domain in the same folder and it creates a subfolder for it, named after the domain. One folder is one site.

A second market for the same site (the United States, then Canada). Ask for it in the same folder: it creates a subfolder like yourdomain.com-canada/, keeps your site's settings and asks only for the market and seed. It reuses the reading of your site and buys the market's research again. It does not use a second site.

A second seed for the same site works the same way, in a subfolder like yourdomain.com-guides/.

Your plan

When the plan is done, open these two files:

  • report/plan.html: the interactive report. Open it in any browser. It holds the wave board (every action, in order, with why it is there), the coverage map, the questions and who holds each answer, and each monthly pass once you run them.
  • PLAN.md: the same plan as a document you can read, work down or send to a client. It opens with the verdict in one paragraph, then wave 1 in full, the wave 2 cluster, a summary of wave 3, what was deferred and why, and three things to review before you start.

Before you start, review three things: read wave 1 end to end and confirm the order; confirm the wave 2 cluster makes sense for your business; and check any page the plan suggests deleting or redirecting in Search Console first. Changing the order costs nothing: the build list can be re-made any time.

Then write the pages with seomantik-content: type Build the next 3 pages.

The monthly progress pass

Once a month, type:

Run the monthly progress pass

It re-reads your site (free), checks which planned pages you published, what your site now covers, what moved in rankings and in the AI answers, and names the next wave. It adds a dated Progress section to PLAN.md and keeps every earlier month, so the file becomes your site's own history.

The first pass sets the starting point, so it has nothing to compare yet. A month with nothing published is reported as exactly that. It never claims that a page caused a ranking change: it reports what was published and what moved over the same period, side by side.

It uses one site you already have and a small amount of data: the rankings read and the AI answer checks.

Every file it writes

In the project folder

  • project.config: the run's settings, written in setup and read by every later phase:
    • DOMAIN: your site.
    • SEED_KEYWORD: the seed this plan is built on. SEEDS_REJECTED lists any others you considered, with why.
    • SITE_TYPE: blog, saas, ecom or local. It shapes every phase.
    • SELLS: yes or no, whether the site sells what it writes about.
    • BRAND_STANCE: one sentence on what you do and who your pages may name. Blank means a sensible default for your site type.
    • LANGUAGE and LOCATION_NAME: the market the plan is for.
    • SITE_SOURCE: how your site is read. crawl (the free crawler), cms (your CMS), or none (a new site with no pages yet).
    • SITE_READ_FROM: only on a second-market or second-seed run, the folder whose site reading it reuses.
    • NODE_OK and RENDERING: technical checks the crawler needs.
  • CLAUDE.md: short ground rules any later session in this folder follows.
  • PLAN.md: your plan as a document (see above).
  • report/plan.html: your plan as an interactive report (see above).

In data/

These are what the content skill reads. You rarely need to open them.

  • universe.json: the topic map: subjects, keywords, entities and questions.
  • entity-map.json: every page of your site matched to those subjects, with how well each subject is covered.
  • questions.json: the ranked questions, each with what the AI answer says, which sites it cites and whether yours is one.
  • architecture.json: the hubs, the pages under them, the internal links and what to do with existing pages.
  • build-list.json: every action with its score, its wave and why it is there.
  • progress-YYYY-MM.json: one per monthly pass.
  • spend.json: a record of every data call the run made, as calls.
  • RESUME.md: where the run stands and the sentence to paste into a new session. Rewritten at the end of every phase.

In data/raw/

Every response the feed returned, saved before anything was read from it, plus the pages of your site as they were read. This is what lets a run resume without paying twice, and it is the evidence behind every number in the plan. Do not edit or delete it.

What it does not do

  • No ranking or traffic promises. It plans coverage and structure. Where anything ranks is decided by search engines.
  • It does not write pages. That is seomantik-content.
  • AI answers are measured, not controlled. It reports what Google's AI Overview (and ChatGPT, when available) says today for your questions, in your market. They change on their own.
  • Counts are what the data returned. Where a source caps its results, the plan says the number is at least that many.

When something goes wrong

It stopped at setup saying the feed is not connected. See Getting started: type /mcp, and seomantik-feed must be connected.

The seed looks wrong halfway through. Tell it. A seed that is a complete question, or too narrow, gives a thin map; it can check a few candidates and recommend one before the map is rebuilt.

Wave 1 is nearly empty. Normal on a site with very few pages: there is little to fix, so the plan is mostly new pages in waves 2 and 3.

It says a check failed. The message names what is wrong. Most are fixed by re-running the step it names; nothing already bought is bought again.

A session ended mid-phase. Open a new session in the same folder and type your first line again.