For everyone
Concepts
The parts of Pectus and how they fit together. Read this first if you want a mental model before you start clicking around.
The whole thing in one minute
Pectus is a content tool that knows you. You tell it once who you are, who you sell to, and what data you have. From then on, every piece of analysis it produces and every page it helps you draft sounds like you and is aimed at your audience.
It does that by separating four things:
- Your stuff — your brand, your customer profile, your private data and notes. This sits in the middle and never leaves your laptop.
- Skills — things Pectus knows how to do. “Plan next week’s content.” “Write a draft.” “Recommend internal links.”
- Apps — places data comes from or goes to. Google Analytics is an app. WordPress is an app. The bundled content-insights site is an app.
- Connectors — the plumbing underneath: Supabase, the Anthropic API, Google auth. You don’t think about these.
When a skill runs, it wraps itself in your stuff before doing the work. So a “draft a blog post” skill doesn’t need to be told your tone of voice — it already knows.
That’s the whole architecture. The rest of this doc explains each piece in more detail.
The core (your stuff)
The core is the part of Pectus that’s specifically you. Three things live here:
- Brands — each brand lives in
brands/<slug>/brand.json(a file you can read, version, and back up) and mirrors to thebrandstable for the CMS to read fast. Pectus is multi-brand: one install can host several brand identities, each with its own slug-prefixed URL space and its own disk directory. A brand profile has 12 colors, three font slots, a corner-radius preference, voice and tonality blocks, and a guidelines markdown file. You can fill it in by hand from the CMS Brand profile page, or import it from a Claude Design URL — the page has an “Import from Claude Design” affordance that fetches a design bundle and pre-fills everything for you to review. - Projects — one per market or audience segment, scoped to a brand. Each has its own customer profile (ICP), seed keywords, locale, and a history of analyses. A UK and a US site of the same brand are two projects sharing one brand. (v0.3 called these “workspaces” — the rename landed in v0.4.2.)
- Knowledge — your data lake, per brand. Drop any text-shaped file into
brands/<slug>/knowledge/raw/(CSVs, BigQuery exports, audience research PDFs, customer interview transcripts). Theknowledge-digestskill turns the pile into a structuredbrands/<slug>/knowledge/insights.mdthat every other skill reads. Refresh it when you add new files.
Everything else in Pectus reads from the core. Skills and apps never define tone, voice, copy, or visual identity — those live in the core. This separation is the rule that keeps the system coherent as more skills and apps land.
Connectors (the plumbing)
Connectors wire Pectus to the underlying services it needs:
supabase— database, authentication, storageanthropic— Claude APIgoogle— shared OAuth and service-account auth for Search Console + Analyticsvercel— optional, for publishing the public hubgithub— optional, used by the publish flow to commit pages to a repo
You never install a connector. They ship with Pectus. They sit at the bottom of the stack and don’t know anything about brands, projects, or skills — they just know how to talk to a service.
If you need a connector that doesn’t exist (a new auth provider, a new data warehouse), the fix is a PR to pectusai/pectus. Skills and apps don’t reach around connectors to talk to services directly; they import from connectors via @pectus/<service> aliases. That keeps your local install identical to every other Pectus install.
Apps (places data flows in or out)
An app is an installable place where data comes in or goes out. Two flavors. They share the same folder shape but the smart parts live in different files.
Inbound apps bring data in. GA4, Search Console, Google Ads, Meta, LinkedIn, seed-keywords. Each sits between an external API (or, for seed-keywords, a CMS form) and a Pectus table. The “fetch” half is dumb plumbing — call the API, paginate, retry. The smart half is an insights skill that reads the raw rows and writes Insights downstream skills consume.
Outbound apps publish things out. The bundled content-insights (an Astro site), WordPress, Storyblok. Each one takes a draft Pectus produced and rewrites it for the target surface using the brand voice that’s already in scope, then ships it.
The insights pipeline is where the smart part lives
Generic API wrappers force every user into the same shape. Two GA4 properties never mean the same thing to two brands — a SaaS company and a publisher want different rollups from the same sessions_engaged number. Most platforms make you re-shape downstream every time you ask a question.
Pectus inverts that. An inbound app can ship an insights/SKILL.md alongside its fetch.ts. After raw rows land in the app’s table, the runner invokes the insights skill with brand voice, ICP, and knowledge insights in scope. The skill produces rows in the per-project insights table that already speak your language: tagged, named, scoped to what your audience cares about.
The Content Insights’s Insights surface is where this lands end-to-end today: Run analysis writes a data_snapshots row (raw GA4 / Search Console / keywords / articles state at the moment of the run), Stage 1 calls Opus to interpret it into data_interpretations, Stage 2 calls Opus to rank ideas into idea_generations. Each idea card has a one-click Draft that opens the article editor with AI Write pre-filled. Other inbound apps land their raw rows now and will gain their own insights skills over time.
File shape
apps/<name>/
├── APP.md manifest
├── fetch.ts (inbound) raw API wrapper
├── insights/ (inbound, optional) skill that interprets raw rows into Insights
│ ├── SKILL.md
│ └── schema.ts
├── schema.ts raw output shape
├── provision.ts credential setup
└── README.mdApps are not themes. They don’t ship colors, fonts, voice, or copy. When an outbound app publishes a post, the visual identity and tone come from your core; the app supplies the structure and the publishing mechanics. This is what makes “one skill, many apps” work — a draft skill produces a post once and it can land in WordPress, Storyblok, or the bundled hub without rewriting.
The content-insights app ships pre-installed but inactive. You activate it per project from /brands/<slug>/projects/<code>/apps, which opens a wizard asking what kind of site you want (brand-new vs adds-a-section), the mount slug, and the GitHub repo Pectus will publish pages to. Activated apps then add their own group to the project sidebar (Pages, Articles, Insights, Sources, Files, Site URL, Redirects, Review policy for Content Insights). Surfaces that need data (Publish, the GA4 dashboard, GSC keyword sync) gate themselves honestly with an inline CTA card pointing at the fix; article and page authoring are never gated. Conceptually it’s no different from wordpress — it just happens to be the one already in your install.
Skills (things Pectus knows how to do)
A skill is a verb — a thing Pectus can do for you. Examples shipped today:
weekly-analysis— looks at the week’s data and produces a ranked content plan.edit-page— applies a chat instruction to a page draft (used in the page builder).plan-sitemap— proposes a site structure for a project.internal-linking— recommends links between pages.knowledge-digest— turns raw uploaded files into a structured insights document.make-it— scaffolds a new skill or app from a one-line description.seo-strategy,jobs-to-be-done— strategy skills carried forward from v0.1.
skills/<name>/
├── SKILL.md manifest + prompt body
├── schema.ts Zod schema for structured output
├── reference/ optional knowledge files the skill loads
└── README.mdA single skill targets many apps. A draft-producing skill emits a post-shaped output that can land in wordpress, storyblok, or content-insights because the post-shaped output is the same; the publishing surface is the app’s job.
When a skill runs, the runner composes the system prompt as a layered envelope:
[1] Brand block voice, name, colors, tagline (from core)
[2] Project block ICP, market, locale, keywords (from core)
[3] Knowledge block digested insights (from core)
[4] Skill block what to do, written core-aware (from skill)
[5] App block where this lands (from app, if outbound)Skill authors write layer 4 in core-aware language. They refer to brand voice as already-in-scope, never “use a friendly tone”. This is the same rule that applies to apps, because skills and apps are both extensions of the core.
The CLI (the terminal)
The pectus CLI is the operator’s seat. You usually don’t run commands by hand — Claude Code reads pectus.md during install and runs them for you. After install, you’ll touch the CLI for things like:
npx pectus brand add— add another brand (or import from Claude Design).npx pectus connect google— re-auth or re-connect a service.npx pectus project create— add another market under a brand. (pectus workspace addstill works as a deprecated alias.)npx pectus knowledge digest— re-digest after dropping new files intobrands/<slug>/knowledge/raw/.npx pectus update— pull updates from upstream.npx pectus doctor— health check.
The CMS (the admin app)
The CMS is the Next.js app at http://localhost:3000. It’s where you actually click around: edit your brand, manage projects, browse analyses, edit page drafts in the builder, review content waiting for sign-off. The CMS doesn’t contain skills or apps itself — it imports the skill runner and renders results. Every skill or app added upstream becomes available in the CMS automatically; you don’t write integration glue.
Notable surfaces:
/brands— every brand in your install. Add a brand from here; switch brands from the brand switcher in the top nav./brands/<slug>/profile— edit brand voice, colors, fonts, example photos, and image-gen API keys. “Import from Claude Design” lives at the top./brands/<slug>/projects/<code>/apps— every app available, with an Activate button per app. This is where you turn Content Insights on for a project./brands/<slug>/projects/<code>— the project home (apps overview). The left sidebar lists every active app’s group (Content Insights when activated, with Pages, Articles, Insights, Sources, Files, Site URL, Redirects, Review policy), plus ICP, Keywords, and Apps at the project level./brands/<slug>/projects/<code>/apps/content-insights/pages/builder/<variantId>— the page builder. Locale chips, slug editor, and an iframe preview at/pectus-preview/<variantId>(same origin — no second dev server) that updates live as the chat-drivenedit-pageskill applies changes./reviews— global cross-brand review inbox (visible when Content Insights is activated for at least one project)./settings— account, users, and the in-CMS migration runner (/settings/updates).
The relationship in one diagram
┌────────────────────────────────────────────┐
│ │
│ CMS (Next.js) CLI │ what the user touches
│ │
├────────────────────────────────────────────┤
│ │
│ skills/ "verbs" │ logic
│ apps/ "surfaces" (in & out) │ I/O
│ │
├────────────────────────────────────────────┤
│ │
│ brands/<slug>/ projects knowledge/ │ the core (you)
│ │
├────────────────────────────────────────────┤
│ │
│ connectors/ supabase, anthropic, ... │ infrastructure
│ │
└────────────────────────────────────────────┘Each layer depends only on layers below it. Skills and apps depend on the core and connectors. The core depends on nothing. Connectors depend on nothing inside Pectus.
The promise this structure makes
A community-authored skill written today still works after the user changes their brand voice tomorrow, because the skill was never holding the voice. The voice was always in the core; the skill was always pointing at it.
A community-authored app installed today still looks like the user’s brand tomorrow, because the app was never setting visual identity. The brand tokens flow into the app’s components from the core; the app supplies structure and the slot, not the content.
This is the inversion of WordPress. In WordPress, the theme dresses the core. In Pectus, the core dresses the apps.
Where to go next
- Authoring a skill: see skills-spec.
- Authoring an app: see apps-spec.
- How the parts wire at the technical level: see architecture.