[anttiviljami]

Summary

This PR makes docs.epilot.io easier to find for search engines and AI agents, and fixes a live bug in the .md pages and llms-full.txt. Each change is its own commit.

1. Descriptions (81036c3, e2591dd)
   • Adds a short description that leads with what the page covers to 60 hand-written pages. Each one is drawn from the page's own intro.
   • The SDK and CLI generators now write a description for each generated page; the committed SDK and CLI pages are updated to match.
   • Weak descriptions drop from 176 to 40. Before, many were link labels such as [API Docs], or  .
2. Trailing slashes (36f6451)
   • Sets trailingSlash: true in the Docusaurus config.
   • Amplify already sends /docs/x to /docs/x/ with a 301, so the canonical URLs, og:url and all 877 sitemap URLs pointed at redirects. No public URL changes.
   • Fixes 87 relative links in the SDK and CLI overview pages that would otherwise break, and updates the generator scripts to match.
3. llms.txt and Markdown output (f01dcdb)
   • Bug fix: the .md pages and llms-full.txt had every {…} and import line removed, including inside code blocks. Live example: /docs/sdk/overview.md is missing import { epilot } from '@epilot/sdk'.
   • llms.txt now follows the llmstxt.org format:
     • a > summary line;
     • one H2 per sidebar section;
     • descriptions on 332 of 363 links, up from 79 of 340 live;
     • "Documentation sets" and "Optional" sections.
   • llms-full.txt now has a Source: URL for each page.
   • Each section also gets its own docs/<section>/llms-full.txt.
4. Metadata and structured data (e8f233f)
   • The home page gets a title and description, plus WebSite and Organization JSON-LD.
   • Every doc page gets TechArticle JSON-LD and a text/markdown alternate link to its Markdown version.
   • API reference pages:
     • each gets its own description;
     • each links to its OpenAPI spec with a rel=alternate link;
     • the static HTML now contains the API name, description and spec URL (before, it was empty until Redoc rendered).
   • Also:
     • the default og:image is the logo;
     • /api is titled "REST API Reference";
     • changelog entries use their excerpt as the description;
     • "Energy XRM" is now written "energy XRM".

Test plan

• npm run build passes.
• Lint and tsc report the same problems as main, none in changed files.
• Checked in the build output:
  • All 293 doc pages have a trailing-slash canonical, a .md alternate and TechArticle JSON-LD that parses.
  • All sitemap URLs end in /.
  • Every local link in llms.txt points to a file that exists in the build.
  • Code blocks in the generated .md files match the source.
• Check an API reference page (its loading state) and a doc page in a browser on the Amplify preview. Both were only checked in the build output.

Follow-ups (not in this PR)

• Amplify console: unknown URLs return 404 but show the home page, with a canonical pointing to /. The rewrite should point at /404.html.
• Social image: a proper 1200×630 og:image should be designed; the logo is a stopgap.
• lastmod and last-updated dates: these need showLastUpdateTime and a full git clone in the Amplify build.
• llms-full.txt size: it grows from 3.1 MB to 4.8 MB because code blocks are no longer stripped. The per-section files run from 5 KB to 914 KB.
• Changelog URLs: they repeat the path (/api/changelog/api/changelog/…). Left as is, because changing URLs is out of scope here.

---

Generated by Claude Code