Add a curated llms.txt generated from the docs.json nav

.github/workflows/check-llms-txt.yml

@@ -0,0 +1,42 @@
+name: Check llms.txt is current
+
+# llms.txt is generated from the docs.json nav by scripts/generate-llms-txt.sh
+# and committed, because Mintlify serves it from the repo rather than building
+# it. Fail PRs where the committed file no longer matches what the generator
+# produces — otherwise adding a page silently leaves it out of the index.
+on:
+  pull_request:
+    paths:
+      # '**.mdx', not '**/*.mdx' — '**' matches any character including '/',
+      # so the '/' in '**/*.mdx' is literal and the root-level nav pages
+      # (index.mdx, flox-5-minutes.mdx) would not match. Both feed llms.txt.
+      - '**.mdx'
+      - 'docs.json'
+      - 'llms.txt'
+      - 'llms.txt.header'
+      - 'scripts/generate-llms-txt.sh'
+  workflow_dispatch:
+
+jobs:
+  check-llms-txt:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout docs
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Regenerate llms.txt
+        run: ./scripts/generate-llms-txt.sh
+
+      # Stage before diffing, and diff the index. A PR that DELETES llms.txt
+      # would otherwise pass: the step above recreates the file as untracked,
+      # and `git diff` cannot see untracked files, so the drift comes back
+      # empty and the one outcome this workflow exists to prevent — handing
+      # /docs/llms.txt back to Mintlify's generated version — merges green.
+      - name: Check for drift
+        run: |
+          git add llms.txt
+          if ! git diff --cached --exit-code --stat llms.txt; then
+            echo "::error::llms.txt is out of date. Run ./scripts/generate-llms-txt.sh and commit the result."
+            git diff --cached llms.txt
+            exit 1
+          fi

.github/workflows/sync-man-pages.yml

@@ -30,19 +30,29 @@ jobs:
         run: |
           flox activate -- ./scripts/sync-man-pages.sh "$GITHUB_WORKSPACE/flox-src" ./man
 
+      # llms.txt takes each man page's description from its `## NAME` line, so
+      # a reworded NAME upstream puts the committed file out of date. Regenerate
+      # here rather than let check-llms-txt.yml fail this PR: the job that
+      # causes the drift is the one that can fix it without a human.
+      # Deliberately outside `flox activate` — this environment ships node,
+      # vale and pandoc, and the generator needs python3 from the runner.
+      - name: Regenerate llms.txt
+        run: ./scripts/generate-llms-txt.sh
+
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8
         with:
           token: "${{ secrets.MANAGED_FLOXBOT_GITHUB_ACCESS_TOKEN_REPO_SCOPE }}"
           add-paths: |
             man
+            llms.txt
           commit-message: "chore(man): sync man pages from flox/flox"
           committer: "FloxBot <bot@flox.dev>"
           author: "FloxBot <bot@flox.dev>"
           branch: "chore-sync-man-pages"
           delete-branch: true
           title: "chore(man): sync man pages from flox/flox"
-          body: "This PR was automatically created by the [Sync man pages workflow](https://github.com/flox/docs/actions/workflows/sync-man-pages.yml). `man/*.mdx` is generated from flox/flox `cli/flox/doc` — please spot-check the rendered pages before merging."
+          body: "This PR was automatically created by the [Sync man pages workflow](https://github.com/flox/docs/actions/workflows/sync-man-pages.yml). `man/*.mdx` is generated from flox/flox `cli/flox/doc` — please spot-check the rendered pages before merging. `llms.txt` is regenerated in the same job, so any change to it here follows from an added, removed, renamed or reworded man page — spot-check it alongside the pages themselves."
           # Routing is via the label, matching the sibling
           # update-flox-version.yml workflow.
           labels: "team-developer-support"

.mintignore

@@ -8,3 +8,6 @@
 # Draft content
 drafts/
 *.draft.mdx
+
+# Build input for llms.txt, not a page (see scripts/generate-llms-txt.sh)
+llms.txt.header

AGENTS.md

@@ -59,6 +59,29 @@ Everything under `man/` is generated from the man page sources in the
   `man/` or `docs.json`); pages deliberately left out of the sidebar go
   in that script's `ALLOWLIST`.
 
+## `llms.txt` is generated — do not edit directly
+
+`llms.txt` is the index AI agents read. It is generated from the `docs.json`
+navigation tree by `scripts/generate-llms-txt.sh` and committed, because
+Mintlify serves it from the repo rather than building it.
+
+- **Do not edit `llms.txt` directly** — the whole file, preamble included, is
+  overwritten by the next generator run.
+- Edit the hand-written preamble in `llms.txt.header`; everything below the
+  first `##` heading comes from the nav and from each page's frontmatter
+  `title` and `description` (falling back to a man page's `## NAME` line).
+- After changing `docs.json`, `llms.txt.header`, or any page's `title` or
+  `description`, regenerate and commit the result:
+
+  ```bash
+  ./scripts/generate-llms-txt.sh
+  ```
+
+  The script requires `python3`.
+- `.github/workflows/check-llms-txt.yml` fails PRs where the committed file
+  no longer matches what the generator produces. The daily man-page sync
+  regenerates it too, so bot PRs arrive correct.
+
 ## Content boundaries
 
 This is a **public repository**. Keep that in mind when adding or editing content:

concepts/compatibility.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Compatibility policy"
-description: "Compatibility policy"
+description: "Manifest schema versions, what counts as a backwards incompatible change, and how the CLI migrates environments for you"
 ---
 
 Flox is a rapidly evolving tool, but you should still be able to rely on _some_ things being stable from release to release.

concepts/flox-vs-containers.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Flox vs. container workflows"
+description: "Where Flox environments and container workflows differ, and how teams combine them"
 ---
 
 Containers are everywhere these days.

concepts/organizations.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Understanding Organizations in FloxHub"
+description: "Roles, access control, and shared ownership of environments across a team"
 ---
 
 <Tip>

customer/known-issues.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Known issues"
-description: "Known issues"
+description: "Known Flox limitations and their workarounds, including false-positive build dependencies"
 ---
 
 ## Build

install-flox/ide-extensions.mdx

@@ -4,27 +4,41 @@
 ---
 
 <Tabs>
-  <Tab title="Skills and MCP">
+  <Tab title="Agent skills">
 
-  [Flox Agentic](https://github.com/flox/flox-agentic) provides a skill library and MCP server
-  that give AI coding agents expert knowledge of Flox environments,
-  builds, services, containers, publishing, and CUDA.
+  [Flox Skills](https://github.com/flox/flox-skills) teaches AI coding
+  agents how to use Flox properly: building reproducible environments,
+  onboarding existing repositories, and wiring up services, builds,
+  containers, and package publishing.
 
-  **Skills included:** `flox-environments`, `flox-services`,
-  `flox-builds`, `flox-containers`, `flox-publish`,
-  `flox-sharing`, `flox-cuda`
+  **Skills included:**
+
+  - `flox` — create and manage environments. Installs packages and pins
+    toolchains, sets up services and databases, builds and containerizes
+    applications, publishes to FloxHub, and composes environments across
+    teams.
+  - `floxify` — onboard an existing repository. Detects your runtimes,
+    services, and build tools, then writes `.flox/env/manifest.toml` so
+    `flox activate` becomes the only setup command a new developer needs.
 
   ## Claude Code
 
-  The Flox plugin for Claude Code installs both the skill library
-  and MCP server in one step:
+  ```
+  claude plugin marketplace add flox/flox-skills
+  ```
 
   ```
-  claude plugin marketplace add flox/flox-agentic
+  claude plugin install flox@flox-skills
   ```
 
+  ## Codex
+
+  ```bash
+  codex plugin marketplace add flox/flox-skills
   ```
-  claude plugin install flox@flox-agentic
+
+  ```bash
+  codex plugin add flox@flox-skills
   ```
 
   ## Other agents (skills.sh)
@@ -34,7 +48,7 @@
   ecosystem:
 
   ```
-  npx skills add flox/flox-agentic
+  npx skills add flox/flox-skills
   ```
 
   <Note>
@@ -43,32 +57,11 @@
     skills.sh is not maintained by Flox. It requires Node.js.
     See [skills.sh](https://skills.sh) for supported agents and docs.
   </Note>
-  ## MCP server
-
-  For agents that support the
-  [Model Context Protocol](https://modelcontextprotocol.io) directly, install the MCP server:
-
-  ```
-  flox install flox/flox-mcp-server
-  ```
-
-  Then point your client at the `flox-mcp` command using stdio
-  transport. For Cursor, add to `~/.cursor/mcp.json`:
-
-  ```
-  {
-    "mcpServers": {
-      "flox": {
-        "command": "flox-mcp"
-      }
-    }
-  }
-  ```
 
   ## Learn more
 
   Full documentation and source code:
-  [github.com/flox/flox-agentic](https://github.com/flox/flox-agentic)
+  [github.com/flox/flox-skills](https://github.com/flox/flox-skills)
 
   </Tab>
   <Tab title="VS Code">