{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/seo-brief",
  "slug": "adapters/domain/seo-brief",
  "kind": "capabilities",
  "bucket": "package",
  "title": "seo-brief — SEO content-brief & keyword-planning microservice",
  "name": "seo-brief",
  "eyebrow": "SEO content-brief & keyword-planning microservice",
  "chip": null,
  "summary": "SEO content-brief & keyword-planning microservice: turn a target keyword into a ready-to-write brief — a heading outline (H1/H2/H3), semantic entities to cover, People-Also-Ask style questions, a...",
  "keywords": [
    "seo-brief",
    "content-brief",
    "keyword-planning",
    "people-also-ask",
    "internal-link",
    "leumas seo brief",
    "pixel-safe",
    "content-gap"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# seo-brief — SEO content-brief & keyword-planning microservice\n\nTurns a **target keyword** into everything you need before you write: an outline, semantic entities,\nPeople-Also-Ask questions, a target word count, internal-link ideas, title-tag and meta-description\ndrafts, FAQ JSON-LD, content-gap analysis, and related/long-tail keyword expansion. A paid\n\"intelligent microservice\": every tool has a **deterministic keyword-expansion + template core that\nruns fully offline**, and the generative tools **optionally** call an LLM (via `../_shared/llm.js`) to\nenrich, silently falling back. Every result is tagged `mode: 'heuristic' | 'llm'`.\n\n## Tools\n\n| tool | output |\n|---|---|\n| `brief` | keyword → outline (H1/H2/H3), entities, PAA questions, target word count, internal-link ideas, related keywords. |\n| `titleTags` | N SERP title tags within pixel-safe length (≤60 chars), brand-suffixed, intent-flavored. |\n| `metaDescription` | Meta descriptions within pixel-safe length (≤155 chars), keyword-front-loaded + CTA. |\n| `faqSchema` | FAQPage JSON-LD (schema.org) from `{question,answer}` pairs — or synthesized from the keyword — plus a ready `<script>` tag. |\n| `contentGaps` | Compares your draft `text` to the topic model → missing entities, questions, keywords + a coverage score. |\n| `relatedKeywords` | Expanded related / long-tail keyword list, each tagged with its own search intent. |\n\nIntent is auto-detected (`informational · commercial · transactional · navigational`) or can be forced\nvia `intent`. Word-count targets scale with intent.\n\n## Usage\n\n```js\nimport seoBrief from './index.js';\n\nawait seoBrief.adapters.brief({ keyword: 'email marketing', count: 8 });\nawait seoBrief.adapters.titleTags({ keyword: 'email marketing', brand: 'Leumas' });\nseoBrief.adapters.faqSchema({ faqs: [{ question: 'What is X?', answer: 'X is …' }], url: 'https://ex.com/x' });\nseoBrief.adapters.contentGaps({ keyword: 'email marketing', text: myDraft });\nseoBrief.adapters.relatedKeywords({ keyword: 'email marketing', count: 20 });\n```\n\nEach call takes ONE args object (maps 1:1 to an HTTP POST body). `brief`/`titleTags`/`metaDescription`/\n`contentGaps`/`relatedKeywords` require `keyword`; `contentGaps` also requires `text`; `faqSchema`\nrequires either `faqs` or `keyword`. Missing inputs throw `TypeError`.\n\n## Hybrid intelligence\n\nTemplates + keyword expansion always produce output. When an LLM is reachable, `brief` (richer\nentities/questions via JSON), `titleTags`, and `metaDescription` enrich the result and keep the\nheuristic as `fallback`. A down/absent model never throws — the pack works 100% offline.\n\n## DRY boundary — distinct from `seo`\n\n- **`seo`** *audits* content that already exists: it takes provided HTML/meta/text and analyzes it\n  (meta tags, OpenGraph, JSON-LD from a data payload, sitemap, keyword density, SERP preview).\n- **`seo-brief`** *plans* content that does not exist yet, starting from a keyword. Different input\n  (a keyword, not HTML) and a different job (planning vs. auditing). `faqSchema` here builds FAQPage\n  JSON-LD for planning; `seo.jsonLd` still serves arbitrary schema from a data payload.\n- No cross-pack imports except `../_shared/llm.js`. Pure ESM, Node built-ins only, zero npm deps.\n",
  "source": {
    "path": "shared/engines/adapters/domain/seo-brief/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 3495,
    "hash": "a2ffdb3d0042b8dda59fb438cc744c01380a8445"
  },
  "urls": {
    "html": "/p/adapters/domain/seo-brief",
    "json": "/docs/adapters/domain/seo-brief.json",
    "md": "/docs/adapters/domain/seo-brief.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}