feat: improve AEO/GEO — structured data, answer-readiness, and heading hygiene

[yjkellyjoo]

What does this PR resolve? 🚀

Improves the docs site's AEO/GEO (Answer / Generative Engine Optimization) — how well search and AI answer engines can discover, parse, and extract correct answers from the documentation.

• Machine-readable signals: adds site-wide + per-page JSON-LD structured data, a Sitemap: directive and llms.txt pointers in robots.txt, an llms.txt head <link>, and fixes stale homepage OG/Twitter URLs.
• Answer-readiness: rewrites buried ledes to be answer-first, converts key headings to question form, and rewrites weak frontmatter descriptions into factual snippets (these feed the JSON-LD + llms.txt slices).
• Heading hierarchy: removes duplicate page H1s, fixes heading-level skips, and de-duplicates colliding headings.
• Conventions: documents the answer-engine writing rules in CODING.md so new content stays consistent.

Details 📝

Three layers, applied in sequence and committed separately:

1. Structured data & discovery

• docusaurus.config.mjs: site-wide Organization + WebSite JSON-LD (with a SearchAction) via headTags, plus an llms.txt <link>.
• src/theme/DocItem/Layout/index.js: a wrapper swizzle emitting per-doc TechArticle JSON-LD from existing frontmatter. It deliberately does not emit BreadcrumbList — the Docusaurus theme already does. The #organization / #website @ids are a shared contract with the config block.
• static/img/logo-512.png: new 512×512 Organization logo.
• static/robots.txt: Sitemap: + llms.txt comment (crawler policy left open).
• static/llms.txt: corrected the concepts/DISC/ slug (clears the validator's stale-link warning) and aligned the GSOC / DISC entry descriptions.
• src/pages/index.js: homepage OG/Twitter URLs repointed from stale GitHub-branch / netlify-test URLs to docs.ethswarm.org. themeConfig.image intentionally deferred until a purpose-built 1200×630 card exists.

2. Content answer-readiness

• Answer-first ledes on ~7 pages (e.g. what-is-swarm — definition promoted above the citation paragraph; duplicate H1 removed), preserving on-brand voice after the factual sentence.
• Question-shaped headings on 5 pages, with original slugs pinned via {#slug} so no anchors break.
• ~16 frontmatter description rewrites (all 9 desktop/ pages + generic develop/reference ones).
• Correctness fix: gsoc.md description said "Group Send Over Content"; the page defines GSOC as "Graffiti Several Owner Chunk".

3. Heading hierarchy hygiene

• Removed duplicate body H1s (frontmatter title is the H1); retitled the two generic "Introduction" pages (Contribute to Bee Development, Tools & Features) with sidebar_label: Overview.
• Promoted first-heading and mid-page level skips so no page skips a level; scoped node-types.md's repeated Recommended Specifications/Configuration headings per node type (staking's deep-link updated to the new anchor).
• Normalized ## bee.yaml YAML comments to # in code examples.

Follow-ups (not in this PR): a Tier-3 "extraction aids" pass (key-facts callouts, comparative-prose → tables, de-deictic prose) is planned but deferred pending content-expert review; plus FAQPage JSON-LD, agent-card.json org realignment, and a real 1200×630 OG image.

Checklist ✅

• Merged latest master and resolved conflicts
• npm run build succeeds
• Links checked (npm run check:links) where relevant
• static/llms.txt updated if pages were added / renamed / deleted
• Content follows CODING.md conventions (Swarm vs swarm, ..)
• Self-reviewed the diff
• Commits are signed off (git commit -s)

[netlify]

✅ Deploy Preview for test-twitter-preview-testing-3 ready!

Name	Link
🔨 Latest commit	785f7d2
🔍 Latest deploy log	https://app.netlify.com/projects/test-twitter-preview-testing-3/deploys/6a67629ce76def0008b97baf
😎 Deploy Preview	https://deploy-preview-831--test-twitter-preview-testing-3.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[crtahlin]

Approving — clean, well-structured AEO/GEO pass. Site-wide + per-doc JSON-LD, llms.txt/sitemap discovery, answer-first ledes, heading hygiene, and a CODING.md convention to keep it consistent. The config JSON-LD, DocItem/Layout swizzle, and OG fixes are correct and thoughtfully documented; build + Netlify deploy are green. One small consistency nit worth fixing (non-blocking).

Should fix (nit)

• static/llms.txt — DISC expansion doesn't match the page. This changes it to "Distributed Immutable Storage for Chunks", but docs/concepts/DISC/DISC.mdx (title, description, and body) says "Distributed Immutable Storage of Chunks". Since these strings feed answer engines, they should match — suggest "Storage of Chunks."
  • Separately (broader editorial call, not for this PR): both now diverge from the Book-of-Swarm canonical "Distributed Immutable Store for Chunks (DiSC)", where "Store" was chosen deliberately for the acronym.

Nice work

• GSOC fixed to the correct expansion — "Graffiti Several Owner Chunk", now consistent across the page frontmatter, body, and llms.txt (verified against docs.ethswarm.org + bee-js).
• OG/Twitter URL fixes — stale raw.githubusercontent.com/.../set-meta-tags/... and test-twitter-preview-testing-3.netlify.app repointed to docs.ethswarm.org; both target images confirmed present.
• Swizzle done right — wraps rather than ejects, deliberately avoids re-emitting BreadcrumbList (the theme already does), documents the shared #organization/#website @id contract and the "swizzles don't auto-upgrade" caveat.
• JSON-LD SearchAction target correctly matches Docusaurus + Algolia's /search?q= page.

Checklist

• Correctness (GSOC verified correct; DISC for/of nit above)
• Security — none (static docs/meta)
• Breaking changes — none (anchors preserved via {#slug}; additive JSON-LD)
• Tests — N/A for docs; build + deploy/netlify green in CI