matrix-page-edit

name	matrix-page-edit
description	Safely change a generated <agent>/<app> matrix page: which source file owns which section, the per-page override keys, how to regenerate without dragging 2,188 unrelated pages into the diff, and how to verify the render and schema. Use whenever editing integration page copy, FAQs, troubleshooting, prompts, or adding a new page section.

Editing a matrix page

The 2,188 content/**/*.mdx files are generated. Hand edits are lost on the next npm run preview:build. Everything below is about editing the sources.

⚠️ Section order is load-bearing — steps before persuasion

Before moving anything in renderPage, or adding an intro / extraSections / accessModels block: nothing goes above ## Setup except the title and one lead paragraph. Extractive engines quote whichever source reaches the procedure first, so every paragraph you add above the steps is measurable citation loss across all 2,188 pages at once.

Measured 2026-08-03: our first step sat at word 419–587 while Composio's sat at 252 on every toolkit page. Perplexity listed claw-link.dev in 76% of "how do I connect X" runs but quoted it in only 30%, and on the 105 runs where both were listed Composio took the answer body without us 54 times to our 5. The steps-first reorder (lead → SkillInstallPrompt → ## Setup → positioning) moved the first step to 141–171 words on all 2,188 pages.

If a page needs more argument, put it after Setup, or on an evaluative page — do not buy it with lead time. Rationale, measurement method, and the verify commands: openspec/specs/answer-engine-page-structure/spec.md.

Who owns which section

Section	Source
Page template, section order, new section renderers	scripts/build-preview-pages.mjs (renderPage)
Lead, tool list, comparison, generic troubleshooting, generic prompts	src/lib/agent-provider-content.ts
FAQ assembly (visible accordion and FAQPage JSON-LD)	buildAgentProviderFaq in the same file
Per-page researched copy	config/matrix-cornerstone-overrides.mjs, keyed <agent>/<slug>
Tool names and counts	src/data/integrations.ts
dateModified in JSON-LD	config/matrix-content-dates.json (hash-based, auto)

Prefer the override file. It keeps one page's researched content out of the shared template, and every key there is already wired to render.

Available override keys

"<agent>/<slug>": {
  intro,            // paragraph appended after the lead
  faqs,             // [{title, description}] -> accordion AND FAQPage JSON-LD
  troubleshooting,  // [{title, description}] -> extra accordions, after the
                    //   generic cards, before the auth-scheme card
  promptExamples,   // [{label, prompt}] -> REPLACES the generated prompt tabs
  toolNotes,        // {heading, intro, points[]} -> plain-markdown section
                    //   after Example prompts
  video,            // {url, title, description} -> "Watch the setup" after Setup
}

Conventions that matter:

• Troubleshooting titles are literal error strings, not paraphrases. Verbatim match is what gets the section retrieved and cited; ChatGPT lifted one of these cards near-verbatim in the Gmail pilot.
• toolNotes points must be checkable against the live tool schema (backend.composio.dev/api/v3/tools/<TOOL_SLUG>). Defaults drift; re-verify rather than trusting a note.
• video renders as a markdown link, not an embed, so the .md and llms-full.txt variants keep it. Confirm whose channel it is before linking.
• Comment every entry with the evidence and date. Future edits need to know which claims were researched and which were template defaults.

New structural sections go in renderPage as plain markdown, gated on the override existing so they appear on one page only. Never emit a section to all 2,188 pages for one page's research.

FAQ and schema

FAQ answers go through buildAgentProviderFaq only. It feeds the visible accordion and the FAQPage JSON-LD from the same array, so they cannot diverge. Google ignores schema that disagrees with visible text; never hand-write FAQPage JSON-LD.

Regenerate without wrecking the diff

⚠️ npm run preview:build rewrites all 460 pages. If the tree has any uncommitted source edits (integrations.ts, content builders, tool data), it materializes those pending changes too. In the Gmail pilot the first run produced ~230 unrelated .mdx diffs.

Check git status first. If the tree is dirty, narrow the diff afterwards:

git status --porcelain          # know what was dirty BEFORE generating
npm run preview:pages

# keep only the pages you meant to change
KEEP=/tmp/keep && mkdir -p $KEEP
cp apps/content/content/<agent>/<cat>/<slug>.mdx $KEEP/mine.mdx
cp config/matrix-content-dates.json $KEEP/dates-new.json
git checkout HEAD -- apps/content/content/ config/matrix-content-dates.json
cp $KEEP/mine.mdx apps/content/content/<agent>/<cat>/<slug>.mdx
python3 - <<'EOF'
import json
new=json.load(open('/tmp/keep/dates-new.json'))
cur=json.load(open('config/matrix-content-dates.json'))
for k in ["<agent>/<slug>"]: cur[k]=new[k]
json.dump(cur,open('config/matrix-content-dates.json','w'),indent=2)
open('config/matrix-content-dates.json','a').write('\n')
EOF
git status --porcelain          # should now be your files only

Tell Hithesh the unrelated pages are still pending regeneration; do not silently ship 230 files he did not ask for, and do not silently drop them either.

Shared copy leaks across pages. A string edited in a builder used by several slugs (e.g. the Hermes gmail/outlook access-models block) changes every one of them. Check which pages moved and confirm the new wording is true for each.

Verify

npx tsc --noEmit                       # ignore pre-existing test-file errors
npx next dev -p 3411                   # then curl the page
curl -s localhost:3411/<agent>/<app> -o /tmp/r.html -w "%{http_code}\n"

Confirm from the rendered HTML, not the MDX:

• HTTP 200, canonical unchanged
• JSON-LD block types still present (TechArticle, BreadcrumbList, FAQPage, HowTo) and the FAQ count moved as expected
• Every new string is server-rendered (present in raw HTML, not injected by a client component)
• Any claim you removed is genuinely gone

public/<agent>/<app>.md and llms-full.txt are gitignored and regenerate at prebuild:web, so they do not need a manual run before deploy. If you want to eyeball them: node scripts/build-llms-md.mjs.

Deploy is npm run deploy:web (matrix pages are a static export from apps/content that rides inside the web build since 2026-08-29), and it is Hithesh's call, not part of an edit run.

Watch for

• The ToolExplorer widget generates one prompt per tool from a shared template, so generic filler can survive on a page whose prompt tabs you just rewrote. Check the rendered page, not just the tabs.
• matrix-content-dates.json bumps dateModified only on real content change, and freshness is a live ranking edge. Do not fabricate dates, and do not revert this file after a genuine edit.
• Claims about a provider or agent change over time. Re-verify against their docs in the session you write them; do not trust a claim inherited from an older note.