MacroPrimer manual

MacroPrimer writes and runs your product's help center. It reads your code to learn what the product does — its screens, features, workflows and terms — and keeps that understanding as a knowledge base. From the knowledge base it drafts help articles, organises them into collections, and checks existing articles against what the code actually does. A browser agent can walk through your live product and capture screenshots or video for each article. You review, edit and publish; readers get a fast, searchable help center on your own subdomain or domain.

You can use as much or as little of this as you like. Two common ways to work:

• Generate it from your code — connect a repository, build the knowledge base, review the suggested articles and publish. This is the fastest way to a complete help center.
• Write it yourself — create collections and articles by hand, or import them from Intercom, and use MacroPrimer for hosting, search, translation and walkthroughs.

1. Create an account with your email or Google. Signing up creates your first workspace — one help center with its own articles, settings, team and plan.
2. Open Articles. The Get your help center live checklist shows the next step on each path and ticks steps off as you complete them; its button takes you straight to the right page.
3. To generate from code: connect a repository, add an AI key, build the knowledge base, suggest articles, review them and publish — each step is explained below.

The dashboard sidebar has your content (Articles, Collections, Assets, Suggestions, Knowledge Bases, Walkthroughs) and Settings, which configures the open workspace for everyone in it. Account, at the bottom left, holds your profile, the workspaces you belong to, and billing.

MacroPrimer reads your repository through a GitHub access token. It only ever reads; it never writes to your repository.

Create a token

1. In GitHub, go to Settings → Developer settings → Personal access tokens → Fine-grained tokens and generate a new token.
2. Under Repository access, select the repositories MacroPrimer should read (or all of them).
3. Under Permissions, give Contents read-only access. Nothing else is needed.
4. Copy the token straight from the confirmation page — GitHub shows it only once.

Connect a repository

In Settings → GitHub, enter the repository as owner/repo, optionally a branch (the default branch otherwise), and the token. Connecting checks the token and syncs the repository straight away. A workspace can connect several repositories — for example a web app and a separate workflow engine — and they feed one knowledge base.

Keep it in sync

• Resync (Knowledge Bases page) re-reads the repository at its latest commit. Do this after significant code changes, then rebuild the knowledge base.
• Check for updates compares the latest commit with the last sync and proposes article updates for what changed, without a full rebuild.
• File filters choose which files are read. The defaults read your source and docs and skip dependencies, build output, tests, data files and binaries; adjust them if part of your product lives somewhere unusual.

A sync downloads the repository as a single archive, so even a large repository costs one request against your GitHub token's hourly limit.

Rather not give MacroPrimer access to your code? Add the MacroPrimer GitHub Action (github.com/SakamotoLabs/macroprimer-action) to the repository instead: it reads the code on your own GitHub runner and sends MacroPrimer only what it learns, never the files. The repository then shows as updated by the GitHub Action.

AI is included on every plan: there is no AI account to set up and no key to add. Every plan builds and refreshes the knowledge base from your code. Pro and higher also suggest new articles, keep your articles up to date as the code changes, check them against it and translate them.

Each workspace has a monthly AI allowance, shown with what is left in Settings → AI; it renews on the 1st. When it is used up, AI work stops until then with a message saying so, and everything else keeps working. Building a typical knowledge base uses well under a dollar, and updates after code changes only re-read what changed.

AI house style (same page) is guidance the AI follows when drafting: tone, audience, the words to use for things, and what to avoid.

The knowledge base is MacroPrimer's map of your product: an overview, how the product is navigated, its features, the workflows people complete with it (with steps), and a glossary. Everything else — suggestions, quality checks, the API — works from it.

Product profile

Before the first build, choose who the knowledge base is written for in Settings → GitHub → Product profile. After a sync MacroPrimer suggests a profile based on what it found in the code.

• Audience: End users (people using screens in a web or mobile app), Developers (people calling a library, SDK, API or command-line tool) or Data practitioners (people running pipelines, notebooks and models). For developers and data practitioners, code names, paths and snippets are kept; for end users they are removed.
• Granularity: Consolidated (a few substantial capabilities, related options folded together) or One per surface (an entry for each screen, endpoint, command or function found in the code).

Build

On the Knowledge Bases page, click Build knowledge base. A build first reads the code area by area, then writes a detail sheet for each screen (or, for developer audiences, each endpoint, command and function), then combines everything into the knowledge base. Progress shows under the button and survives page reloads; your previous knowledge base stays live until the new one is complete. A first build of a large repository can take a while.

A detail sheet records what one screen looks like and does, from its own code: how to get there, its layout and fields, every action with its confirmation and result messages, its empty, loading and error states, and who may use it. Sheets are rewritten only when the code behind them changes, so rebuilding an unchanged product costs nothing; up to 300 are kept per workspace, labelled screens first. They are included in the API, the MCP tools and exports, and suggested articles are drafted from them. Which code a sheet is read from is decided when a repository is synced, so a repository last synced before detail sheets existed needs a Resync before the next build writes its sheets.

• View KB shows the result. Each feature and workflow is labelled with the repository it was found in; expand one and click a screen under Detail sheets to read its sheet.
• Rebuild knowledge base after a resync or a profile change. If nothing it depends on has changed since the last build, it finishes at once as already up to date; Rebuild anyway forces a fresh pass.
• If the AI provider refuses a request (for example, no credit left), the build stops and shows the provider's reason. Fix the cause and start the build again — it continues where it stopped.

The Suggestions page turns the knowledge base into proposed changes for you to review. Nothing is published until you accept it.

• Suggest articles groups the knowledge base into help topics and drafts one comprehensive article per topic, skipping topics your existing articles already cover. Choose whether drafts are tagged with your public collections only, with all collections including hidden ones, or with none.
• Suggest collections proposes collections to organise your articles.
• Suggested reorganization proposes new sections and article moves for collections that have grown too large.
• Quality review checks existing articles against the knowledge base and flags weak or unverified ones.

Open a suggestion to preview it, then accept or dismiss it — individually or in bulk. Accepted articles arrive as drafts on the Articles page.

• Articles lists every article with filters for status, collection, origin and open comments. + New article opens the editor; select several articles to publish, unpublish, move or delete them together.
• Articles are drafts until published. Only published articles appear in your help center.
• The editor keeps a history of every saved version, which you can restore, and a comments panel for review notes between teammates.
• Collections organise articles into a tree; a collection can also act as a section inside another. Collections can be hidden from the public help center.
• Assets is the library of images and files used in your articles.

A walkthrough is a recording of a feature in your live product: a browser agent signs in, performs the steps of an article, and captures screenshots — or a video — that are inserted into the article.

1. Add your product in Settings → Platforms: its address, and optional instructions for the agent (for example, a panel to close first).
2. Give the agent a way to sign in: either capture a login session, or import one from your own browser (this works with Google and other single sign-on). By default the agent works read-only: it won't click buttons that delete or destroy things, or fill in billing or credential forms. It is still acting in your real product, so use a test account where possible.
3. From an article, run a walkthrough for it, or use Run walkthroughs for all missing drafts on the Articles page. Screenshots only is faster and cheaper than video.

A video walkthrough is a short narrated clip: a pointer glides to each element before it is used, a voice reads each step, and every step stays on screen until its sentence is finished. Each video also comes with a preview GIF (for emails, where videos don't play) and a poster image, which is shown before the video plays when you insert it from Insert from walkthrough. Screenshots stay clean — the pointer only appears in the video.

Each plan includes a number of walkthrough runs per month (see Account → Billing). If a saved login expires, queued walkthroughs pause until you capture it again.

• Address. Your help center lives at your-handle.help.macroprimer.com. Change the handle in Settings → Basic — existing links to the old address stop working. A handle that's already taken or reserved can't be used; the page tells you which.
• Custom domain (Business plan). Enter a subdomain you own, such as help.yourcompany.com, then add the CNAME record shown on the page at your DNS provider. Once the record resolves, a secure certificate is issued automatically, which can take up to an hour.
• Branding (Settings → Branding): logo, colours and the hero message, with a preview.
• Languages (Settings → Languages): choose a default language and the languages your help center offers. Articles can be translated with AI; translations are linked to the original and flagged when the original changes.
• Readers get full-text search across everything you publish.

• Roles. A workspace has owners and editors. Editors write and publish content. Owners also manage the team, API keys and billing.
• Inviting. An owner adds an editor by email in Settings → Users; the editor signs in with Google using that address. The number of editors depends on the plan.
• Several workspaces. One login can belong to several workspaces — for different products or clients. Switch with the selector at the top of the sidebar, and create one with + New workspace. Account → Workspaces lists each workspace you belong to, your role in it, and who owns it.

• Import from Intercom (Articles page, Pro plan and up) brings over your Intercom help center — collections, articles and their images — keeping the original article addresses where possible. Images are copied to MacroPrimer so they keep working if the Intercom account goes away.
• Export & backup (Settings → Basic → Migrate content) downloads a full backup of your content.

Everything in your workspace is also available programmatically, with keys you create in Settings → API keys (owners only). Each key has only the permissions you give it.

• The REST API manages articles, collections, translations, assets and walkthroughs, and reads the knowledge base. See the API reference.
• The MCP server at https://api.macroprimer.com/mcp lets AI assistants and agents read your knowledge base directly. Connect it with a key that has the knowledge:read permission.

• “GitHub request failed: Bad credentials” — GitHub doesn't accept the token: it may be mistyped, expired or revoked. Create a new one and check it has read access to the repository's contents.
• “GitHub's API rate limit … is used up” — the GitHub account behind the token has spent its hourly allowance (it is shared with everything else using that account). Try again after the time shown.
• “… AI for the month is used up” — the workspace has spent this month's AI allowance. AI work continues on the 1st; Settings → AI shows what is left.
• “MacroPrimer's AI provider refused the request” — usually brief: start the job again and it continues where it stopped.
• The knowledge base looks thin — check that every repository is connected and synced, that the file filters include where your product lives, and that the product profile matches your audience. Then Resync and rebuild.
• “Not saved” when changing the handle — the handle is taken or reserved; the message says which. Choose another.

Still stuck? Write to hello@macroprimer.com.