Add FAQ on using AI coding assistants with THEOplayer

[devin-ai-integration]

Summary

Adds a customer-facing FAQ, theoplayer/faq/how-to-use-ai-coding-assistants, that explains how to load the THEOplayer documentation into AI coding assistants (Claude Code, Cursor, GitHub Copilot, Windsurf, ...):

• lists the machine-readable files generated by Generate llms.txt, llms-full.txt and Markdown twins of every docs page (OPTIP-478) #838 (/docs/llms.txt, /docs/<product>/llms.txt, /docs/<product>/llms-full.txt, and the .md twin of every page) and when to use which;
• gives a starter rules block that integrators can copy into CLAUDE.md, AGENTS.md, Cursor rules or Copilot instructions (documentation URLs, package names per platform, and a few integration rules such as reading the license from configuration).

To make the page easy to find, a sparkle icon in the navbar (left of the theme toggle) links to it. The icon is a CSS mask over static/img/ai-sparkle.svg on a normal link navbar item, so the mobile sidebar shows it as a text item ("AI coding assistants").

web-ui is added to the spellcheck dictionary because the FAQ links to the public THEOplayer/web-ui repository.

The earlier version of this PR contained its own llms.txt generator; it was removed in favour of #838, which is now merged.

Link to Devin session: https://dolby.devinenterprise.com/sessions/77e06f6b72b740eeadf0bf3bfe666b92
Open in Devin Desktop: https://dolby.devinenterprise.com/desktop/session/77e06f6b72b740eeadf0bf3bfe666b92?variant=devin
Requested by: @morgandrake-cpu

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[MattiasBuelens]

We already have a draft PR up for this... See #838.

Could you sync up with @Danesz on which approach we want to take?

[devin-ai-integration]

Thanks, I was not aware of #838. I looked at it: it covers everything the generator in this PR does, and more (per-product llms.txt indexes grouped by sidebar, Markdown twins of every page, preview-origin URLs). So the generator in this PR should not be merged.

Proposal, @Danesz: I drop the plugin from this PR and keep only the FAQ page ("How can I use AI coding assistants with THEOplayer?"), which is the part #838 does not have. It links to /docs/llms.txt and /docs/<product>/llms-full.txt, which #838 produces at the same paths, and contains a starter CLAUDE.md / AGENTS.md rules block for integrators. I would rebase it so it lands after #838 and add a link to the per-product llms.txt files as well. Does that work for you, or do you prefer to fold the FAQ into #838?

[devin-ai-integration]

Devin Review found 4 potential issues.

[Danesz]

Fine for me

[devin-ai-integration]

Done: the generator is removed from this PR. It now contains only the FAQ page and is based on feature/OPTIP-478-llms-txt (#838). The FAQ describes the files #838 produces (llms.txt, per-product llms.txt / llms-full.txt, .md page twins).

[Danesz]

@morgandrake-cpu I changed the PR to ready for review. I think it looks ok, it can land.

[Danesz]

Devin I like the FAQ idea, but tbh that page could win a hide-and-seek competition.

Can't we make it more visible? e.g. in the header of the page, to the left of the dark/light theme icon we put the nowadays fancy "AI sparkle" icon that links to this page? Then even if a crazy AI agent would start reading the HTML page itself (instead of llms.txt), could find it on top with a higher chance, and follow it.

[devin-ai-integration]

Done in d951538: a sparkle icon in the navbar, left of the theme toggle, links to the FAQ. On mobile the sidebar shows it as a text item ("AI coding assistants").

[Danesz]

Good stuff!
Can we make a little hidden gem: if someone hovers on the icon, we show a nice gradient on it with the primary color of the page? (I think it is #6569fe)

[devin-ai-integration]

Added in eeb0a97: on hover the icon shows a gradient from --ifm-color-primary-lightest to --ifm-color-primary-darker, so it uses #6569fe in dark mode and #6d19ff in light mode.

Light theme:
Dark theme:

[MattiasBuelens]

Very colorful! However, I think it could use a transition.

Two things to try:

• A simple CSS transition that just goes from the plain color to the hover gradient (and backwards when you stop hovering)
• A CSS transition where we go from the plain color to the gradient by moving the whole gradient along the 45° line, from the bottom right to the top left. When you stop hovering, we go from the gradient back to the plain color, but still moving in the same direction (bottom right to top left). I think you'll need CSS custom properties with @property in order to animate the gradient stops like that?

Can you record a video of these transitions, so we can pick the one we like best?

[devin-ai-integration]

Here are both transitions side by side (each icon is hovered twice; the icons are enlarged for the video):

A: fade (0.3 s). One registered custom property mixed into the gradient stops, transitioned on the existing ::before, no extra layer:

@property --ai-gradient {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 0%;
}
.navbar__items .navbar__ai-link::before {
  background: linear-gradient(135deg,
    color-mix(in srgb, var(--ifm-color-primary-lightest) var(--ai-gradient), currentColor),
    color-mix(in srgb, var(--ifm-color-primary-darker) var(--ai-gradient), currentColor));
  transition: --ai-gradient 0.3s ease;
}
.navbar__items .navbar__ai-link:hover::before { --ai-gradient: 100%; }

B: sweep (0.5 s). The gradient is a band inside a 300% background; on hover it moves in from the bottom right, on mouse leave it continues in the same direction and ends on the plain color. Keyframes are used instead of a transition so that the direction is the same both ways:

.navbar__items .navbar__ai-link::before {
  background: linear-gradient(135deg,
    currentColor 0 30%,
    var(--ifm-color-primary-lightest) 36%,
    var(--ifm-color-primary-darker) 64%,
    currentColor 70% 100%);
  background-size: 300% 300%;
  animation: ai-sweep-out 0.5s ease-out forwards;
}
.navbar__items .navbar__ai-link:hover::before { animation: ai-sweep-in 0.5s ease-out forwards; }
@keyframes ai-sweep-in  { from { background-position: 0 0; }     to { background-position: 50% 50%; } }
@keyframes ai-sweep-out { from { background-position: 50% 50%; } to { background-position: 100% 100%; } }

Both use currentColor for the rest state, so they work in light and dark mode. @property and color-mix() need Chrome 111+, Safari 16.4+ and Firefox 128+; older browsers get the plain icon without the hover effect. Tell me which one you prefer and I will commit it.

[MattiasBuelens]

I like the sweep. However, now I think it's better to make the gradient colors symmetrical when entering and exiting. So add another stop with var(--ifm-color-primary-lightest).

[devin-ai-integration]

Committed the sweep with a symmetric band (lightest, darker, lightest) in 9dbab2d. On the real navbar, light and dark theme:

[Danesz]

Beautiful ❤️