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.

Building the knowledge base, suggesting articles and translating use AI. Each workspace brings its own AI account, so usage is billed to you directly by the provider and never shared with other workspaces. Set it up in Settings → AI:

• Anthropic API key — create a key at console.anthropic.com and add credit to that account. A Claude Pro or Max subscription is a separate product and can't be used here.
• DeepInfra API key — runs the same work on open models through DeepInfra, typically at a small fraction of the cost. Only the workspace owner can connect it. Connecting it switches the workspace to DeepInfra; if both are connected, the owner can switch between them at any time.

Walkthrough recordings always use Anthropic, because they drive a real browser; keep an Anthropic key connected if you record walkthroughs.

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 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.

• View KB shows the result. Each feature and workflow is labelled with the repository it was found in.
• 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.

Each plan includes a number of walkthrough runs per month (see Plans). 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, AI provider, 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.

Each workspace has its own plan. See and change it in Account → Billing, which shows the plan of the workspace you have open; annual billing gives two months free.

• Free — 25 published articles, 1 editor, 2 walkthrough runs a month, your help.macroprimer.com subdomain and full-text search.
• Pro ($49/month) — 150 published articles, 5 editors, 25 walkthrough runs a month, Intercom import, up to 3 languages, no MacroPrimer branding, basic analytics and email support.
• Business ($149/month) — unlimited articles and editors, 100 walkthrough runs a month, a custom domain, unlimited languages, full analytics and priority support.

AI usage is not part of the plan: it is billed by your AI provider to the account whose key you connect.

• “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.
• “… refused your workspace's … key” — the AI provider turned the request down; the message gives the provider's reason, such as no credit or an invalid key. Fix it in Settings → AI or with the provider, then start the job again.
• 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.