From 2a85346613e780c3b337872e9642d5dbdd7ed339 Mon Sep 17 00:00:00 2001
From: Andrey Avtomonov <andreybavt@gmail.com>
Date: Thu, 28 May 2026 12:51:17 +0200
Subject: [PATCH] fix(docs-site): disable Geist Mono ligatures on every
 font-mono surface (#228)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Geist Mono fuses `--` into an em-dash glyph that visually swallows the
adjacent space, so prompts like `npx skills add Kaelio/ktx --skill ktx`
rendered as `Kaelio/ktx--skill ktx` on the quickstart page. The existing
ligature-off rule only covered <code>/<pre> and the .ktx-code wrapper —
quickstart.mdx puts the prompt in a plain <div className="font-mono">,
so the rule didn't apply. Extend the selector to also match the
.font-mono Tailwind utility and any inline-style opt-in via the mono
font CSS variable.

Document the convention in AGENTS.md so future docs additions keep
ligatures off on any new monospace container.
---
 AGENTS.md                | 16 ++++++++++++++++
 docs-site/app/global.css |  8 ++++++--
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b5eccd67..3d8c1725 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -375,6 +375,22 @@ that do not change user-facing behavior. When you do update docs, follow the
 warrants docs but you are out of scope, call it out in your final summary
 rather than silently skipping it.
 
+#### Monospace ligatures in `docs-site/`
+
+- **MUST**: Disable monospace ligatures on every surface that uses the
+  `var(--font-mono)` family (Geist Mono). Geist Mono fuses `--` into an
+  em-dash glyph that visually eats the adjacent space, so prompts like
+  `npx skills add Kaelio/ktx --skill ktx` render as `Kaelio/ktx--skill ktx`.
+- **MUST**: When adding a new container that renders user-visible monospace
+  text outside `<code>` / `<pre>` (e.g. a styled `<div className="font-mono">`
+  for a copyable prompt), verify the global ligature-off rule in
+  `docs-site/app/global.css` covers its selector. Either use Tailwind's
+  `font-mono` utility (already covered) or extend the rule to match the new
+  class — do not silently rely on Geist Mono's defaults.
+- **SHOULD**: Prefer `<code>` / `<pre>` (or a `font-mono` wrapper) for any
+  string that contains CLI flags, paths, or other tokens with `--`, `->`,
+  `>=`, `!=`, `==`, `//` so ligatures never alter intent.
+
 ## LLM and Prompt Development
 
 When creating or modifying agent prompts, system prompts, tool descriptions, or
diff --git a/docs-site/app/global.css b/docs-site/app/global.css
index a4cebc55..929e06b4 100644
--- a/docs-site/app/global.css
+++ b/docs-site/app/global.css
@@ -166,12 +166,16 @@ pre {
 }
 
 /* Disable monospace ligatures so `--flag` keeps a visible space and double
-   dashes don't fuse into an em-dash glyph. */
+   dashes don't fuse into an em-dash glyph. Covers every monospace surface:
+   raw <code>/<pre>, the ktx-code wrapper, Tailwind's `font-mono` utility,
+   and anything that opts in via the `var(--font-mono)` family directly. */
 code,
 pre,
 pre code,
 .ktx-code,
-.ktx-code code {
+.ktx-code code,
+.font-mono,
+[style*="--font-mono"] {
   font-variant-ligatures: none !important;
   font-feature-settings: "liga" 0, "calt" 0 !important;
 }