docs(api): align examples with exported signatures

website/src/content/docs/features/audit.mdx

@@ -8,12 +8,18 @@ description: Audit your AEO setup and measure your site's citability score.
 The `auditSite` function checks your site for AEO best practices and returns a detailed report:
 
 ```ts
-import { auditSite, formatAuditReport, getGrade } from 'aeo.js';
+import { auditSite, formatAuditReport, getGrade, resolveConfig } from 'aeo.js';
 
-const result = await auditSite('https://mysite.com');
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
+const result = auditSite(config);
 
 console.log(formatAuditReport(result));
-console.log('Grade:', getGrade(result));
+console.log('Grade:', getGrade(result.score));
 ```
 
 The audit checks for:
@@ -35,14 +41,24 @@ npx aeo.js check
 Measure how likely AI engines are to cite your content:
 
 ```ts
-import { scorePageCitability, scoreSiteCitability, formatPageCitability } from 'aeo.js';
+import { formatPageCitability, resolveConfig, scorePageCitability, scoreSiteCitability } from 'aeo.js';
 
 // Score a single page
-const pageScore = await scorePageCitability(url, html);
+const pageScore = scorePageCitability({
+  pathname: '/',
+  title: 'Home',
+  content: '# Home\n\nMy site publishes practical guides for AI-ready content.',
+});
 console.log(formatPageCitability(pageScore));
 
 // Score the whole site
-const siteScore = await scoreSiteCitability('https://mysite.com', pages);
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
+const siteScore = scoreSiteCitability(config);
 ```
 
 The citability score evaluates:
@@ -58,9 +74,15 @@ The citability score evaluates:
 Generate a comprehensive AEO report:
 
 ```ts
-import { generateReport, formatReportMarkdown, formatReportJson } from 'aeo.js';
+import { formatReportJson, formatReportMarkdown, generateReport, resolveConfig } from 'aeo.js';
 
-const report = await generateReport(config);
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
+const report = generateReport(config);
 
 // Get as markdown
 console.log(formatReportMarkdown(report));
@@ -74,8 +96,16 @@ console.log(formatReportJson(report));
 Get platform-specific optimization suggestions:
 
 ```ts
-import { generatePlatformHints } from 'aeo.js';
-
-const hints = generatePlatformHints('next');
-// Returns hints specific to Next.js optimization
+import { auditSite, generatePlatformHints, resolveConfig, scoreSiteCitability } from 'aeo.js';
+
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
+const audit = auditSite(config);
+const citability = scoreSiteCitability(config);
+const hints = generatePlatformHints(audit, citability);
+// Returns platform-specific optimization hints for ChatGPT, Perplexity, Google AI, and Bing Copilot
 ```

website/src/content/docs/features/schema-og.mdx

@@ -63,21 +63,45 @@ This generates meta tags like:
 
 ## Programmatic API
 
+The lower-level helpers expect a resolved config and a page entry.
+
 ```ts
-import { generateSchema, generateSchemaObjects, generateJsonLdScript } from 'aeo.js';
-import { generateOGTags, generateOGTagsHtml } from 'aeo.js';
+import {
+  generateJsonLdScript,
+  generateOGTags,
+  generateOGTagsHtml,
+  generateSchemaObjects,
+  resolveConfig,
+} from 'aeo.js';
+
+const page = {
+  pathname: '/page',
+  title: 'Page Title',
+  description: 'Page description',
+  content: 'Page content',
+};
+
+const resolvedConfig = resolveConfig({
+  title: 'My Company',
+  description: 'My company website',
+  url: 'https://mysite.com',
+  pages: [page],
+});
 
 // Get schema objects
-const schemas = generateSchemaObjects(config);
+const schemas = generateSchemaObjects(resolvedConfig);
 
 // Get a <script> tag string
-const script = generateJsonLdScript(config);
+const script = generateJsonLdScript([
+  ...schemas.site,
+  ...(schemas.pages[page.pathname] ?? []),
+]);
 
 // Get OG meta tag objects
-const tags = generateOGTags(config, page);
+const tags = generateOGTags(page, resolvedConfig);
 
 // Get OG meta tags as HTML string
-const html = generateOGTagsHtml(config, page);
+const html = generateOGTagsHtml(page, resolvedConfig);
 ```
 
 <Aside type="tip">

website/src/content/docs/reference/api.mdx

@@ -43,6 +43,8 @@ const resolved = resolveConfig({ title: 'My Site' });
 // All fields now have defaults
 ```
 
+The examples below use `resolvedConfig` for a config object returned by `resolveConfig`.
+
 ### `validateConfig(config)`
 
 Validate a config object and return any errors:
@@ -66,15 +68,19 @@ const info = detectFramework();
 
 ## HTML Extraction
 
-### `htmlToMarkdown(html)`
+### `htmlToMarkdown(html, pagePath, config)`
 
 Convert HTML to clean markdown:
 
 ```ts
 import { htmlToMarkdown } from 'aeo.js';
 
-const md = htmlToMarkdown('<h1>Hello</h1><p>World</p>');
-// '# Hello\n\nWorld'
+const md = htmlToMarkdown(
+  '<html><head><title>Hello</title></head><body><main><p>World</p></main></body></html>',
+  '/',
+  { url: 'https://mysite.com' }
+);
+// Returns a markdown document with YAML frontmatter
 ```
 
 ### `extractTextFromHtml(html)`
@@ -107,65 +113,79 @@ import { generateSchemaObjects } from 'aeo.js';
 const schemas = generateSchemaObjects(resolvedConfig);
 ```
 
-### `generateJsonLdScript(config)`
+### `generateJsonLdScript(schemas)`
 
 Generate a `<script type="application/ld+json">` tag:
 
 ```ts
-import { generateJsonLdScript } from 'aeo.js';
+import { generateJsonLdScript, generateSiteSchemas } from 'aeo.js';
 
-const script = generateJsonLdScript(resolvedConfig);
+const schemas = generateSiteSchemas(resolvedConfig);
+const script = generateJsonLdScript(schemas);
 ```
 
-### `generateSiteSchemas(config)` / `generatePageSchemas(config, page)`
+### `generateSiteSchemas(config)` / `generatePageSchemas(page, config)`
 
 Generate schemas for the site or individual pages.
 
 ## Open Graph
 
-### `generateOGTags(config, page)`
+### `generateOGTags(page, config)`
 
 Returns an array of `MetaTag` objects:
 
 ```ts
 import { generateOGTags } from 'aeo.js';
 
-const tags = generateOGTags(config, { pathname: '/', title: 'Home' });
+const tags = generateOGTags(
+  { pathname: '/', title: 'Home' },
+  resolvedConfig
+);
 // [{ property: 'og:title', content: 'Home' }, ...]
 ```
 
-### `generateOGTagsHtml(config, page)`
+### `generateOGTagsHtml(page, config)`
 
 Returns OG tags as an HTML string.
 
 ## Audit
 
-### `auditSite(url)`
+### `auditSite(config)`
 
 Audit a site for AEO best practices:
 
 ```ts
-import { auditSite, formatAuditReport, getGrade } from 'aeo.js';
+import { auditSite, formatAuditReport, getGrade, resolveConfig } from 'aeo.js';
 
-const result = await auditSite('https://mysite.com');
+const config = resolveConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  pages: [{ pathname: '/', title: 'Home', content: 'Welcome to my site.' }],
+});
+
+const result = auditSite(config);
 console.log(formatAuditReport(result));
-console.log(getGrade(result)); // 'A', 'B', 'C', etc.
+console.log(getGrade(result.score)); // 'Excellent', 'Good', 'Fair', etc.
 ```
 
 ## Citability
 
-### `scorePageCitability(url, html)`
+### `scorePageCitability(page)`
 
 Score how likely a page is to be cited by AI:
 
 ```ts
 import { scorePageCitability, formatPageCitability } from 'aeo.js';
 
-const score = await scorePageCitability(url, html);
+const score = scorePageCitability({
+  pathname: '/',
+  title: 'Home',
+  content: '# Home\n\nMy site publishes practical guides for AI-ready content.',
+});
 console.log(formatPageCitability(score));
 ```
 
-### `scoreSiteCitability(url, pages)`
+### `scoreSiteCitability(config)`
 
 Score citability across your entire site.
 
@@ -178,10 +198,24 @@ Generate a comprehensive AEO report:
 ```ts
 import { generateReport, formatReportMarkdown } from 'aeo.js';
 
-const report = await generateReport(config);
+const report = generateReport(resolvedConfig);
 console.log(formatReportMarkdown(report));
 ```
 
+## Platform Hints
+
+### `generatePlatformHints(audit, citability)`
+
+Generate platform-specific optimization hints from audit and citability results:
+
+```ts
+import { auditSite, generatePlatformHints, scoreSiteCitability } from 'aeo.js';
+
+const audit = auditSite(resolvedConfig);
+const citability = scoreSiteCitability(resolvedConfig);
+const hints = generatePlatformHints(audit, citability);
+```
+
 ## Types
 
 All types are exported from the main entry: