Generate richer llms.txt and add doc-content.txt for AI agents

.flox/env/manifest.lock

@@ -12,6 +12,9 @@
       "findutils": {
         "pkg-path": "findutils"
       },
+      "gnumake": {
+        "pkg-path": "gnumake"
+      },
       "gnused": {
         "pkg-path": "gnused"
       },
@@ -662,6 +665,136 @@
       "group": "toplevel",
       "priority": 5
     },
+    {
+      "attr_path": "gnumake",
+      "broken": false,
+      "derivation": "/nix/store/pf71f0ja823aanl6073z3slrpz2hpxr1-gnumake-4.4.1.drv",
+      "description": "Tool to control the generation of non-source files from sources",
+      "install_id": "gnumake",
+      "license": "GPL-3.0-or-later",
+      "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e",
+      "name": "gnumake-4.4.1",
+      "pname": "gnumake",
+      "rev": "8eaee110344796db060382e15d3af0a9fc396e0e",
+      "rev_count": 864002,
+      "rev_date": "2025-09-19T10:20:10Z",
+      "scrape_date": "2025-09-21T05:38:43.319343Z",
+      "stabilities": [
+        "unstable"
+      ],
+      "unfree": false,
+      "version": "4.4.1",
+      "outputs_to_install": [
+        "man",
+        "out"
+      ],
+      "outputs": {
+        "info": "/nix/store/cwx5agxi3ig3gmbk4c4dn7df2krzlddy-gnumake-4.4.1-info",
+        "man": "/nix/store/a4aay80xgirjm8hk1rd142qcd1kkfps8-gnumake-4.4.1-man",
+        "out": "/nix/store/sjxx5p05vzq7xam62h21cyzkbyb1amvd-gnumake-4.4.1"
+      },
+      "system": "aarch64-darwin",
+      "group": "toplevel",
+      "priority": 5
+    },
+    {
+      "attr_path": "gnumake",
+      "broken": false,
+      "derivation": "/nix/store/876aq0p8d0z7sfyjdawn9mrdfnv7n458-gnumake-4.4.1.drv",
+      "description": "Tool to control the generation of non-source files from sources",
+      "install_id": "gnumake",
+      "license": "GPL-3.0-or-later",
+      "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e",
+      "name": "gnumake-4.4.1",
+      "pname": "gnumake",
+      "rev": "8eaee110344796db060382e15d3af0a9fc396e0e",
+      "rev_count": 864002,
+      "rev_date": "2025-09-19T10:20:10Z",
+      "scrape_date": "2025-09-21T06:10:24.182468Z",
+      "stabilities": [
+        "unstable"
+      ],
+      "unfree": false,
+      "version": "4.4.1",
+      "outputs_to_install": [
+        "man",
+        "out"
+      ],
+      "outputs": {
+        "debug": "/nix/store/j8lcp5zjdq0l0ipvji7s13vdc53nzcki-gnumake-4.4.1-debug",
+        "info": "/nix/store/8922q241lh4qbxd2g7jxsnjnkfmgap3z-gnumake-4.4.1-info",
+        "man": "/nix/store/0a4l47b9sqc28ssi5hsq21ivs2hmbzcp-gnumake-4.4.1-man",
+        "out": "/nix/store/9cns3585v908dwbf5nfqqjghv955ndrq-gnumake-4.4.1"
+      },
+      "system": "aarch64-linux",
+      "group": "toplevel",
+      "priority": 5
+    },
+    {
+      "attr_path": "gnumake",
+      "broken": false,
+      "derivation": "/nix/store/xrm5hvv49gd5v31937jmr0vc6m8a1v64-gnumake-4.4.1.drv",
+      "description": "Tool to control the generation of non-source files from sources",
+      "install_id": "gnumake",
+      "license": "GPL-3.0-or-later",
+      "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e",
+      "name": "gnumake-4.4.1",
+      "pname": "gnumake",
+      "rev": "8eaee110344796db060382e15d3af0a9fc396e0e",
+      "rev_count": 864002,
+      "rev_date": "2025-09-19T10:20:10Z",
+      "scrape_date": "2025-09-21T06:39:00.878032Z",
+      "stabilities": [
+        "unstable"
+      ],
+      "unfree": false,
+      "version": "4.4.1",
+      "outputs_to_install": [
+        "man",
+        "out"
+      ],
+      "outputs": {
+        "info": "/nix/store/451pi5y9s89na99pxv6jjvqa44r08dha-gnumake-4.4.1-info",
+        "man": "/nix/store/g7nffhgbmv3r01199lhp0qz741kvnlvf-gnumake-4.4.1-man",
+        "out": "/nix/store/fy063r4nqi1w79bklqhiv7ny0xwdqjp3-gnumake-4.4.1"
+      },
+      "system": "x86_64-darwin",
+      "group": "toplevel",
+      "priority": 5
+    },
+    {
+      "attr_path": "gnumake",
+      "broken": false,
+      "derivation": "/nix/store/riz7jd6hvqpxzxgyhj76ianh96sxhvz4-gnumake-4.4.1.drv",
+      "description": "Tool to control the generation of non-source files from sources",
+      "install_id": "gnumake",
+      "license": "GPL-3.0-or-later",
+      "locked_url": "https://github.com/flox/nixpkgs?rev=8eaee110344796db060382e15d3af0a9fc396e0e",
+      "name": "gnumake-4.4.1",
+      "pname": "gnumake",
+      "rev": "8eaee110344796db060382e15d3af0a9fc396e0e",
+      "rev_count": 864002,
+      "rev_date": "2025-09-19T10:20:10Z",
+      "scrape_date": "2025-09-21T07:10:55.800436Z",
+      "stabilities": [
+        "unstable"
+      ],
+      "unfree": false,
+      "version": "4.4.1",
+      "outputs_to_install": [
+        "man",
+        "out"
+      ],
+      "outputs": {
+        "debug": "/nix/store/7vrxj6zy7y4a83d2q9585sxmcnkfs9ml-gnumake-4.4.1-debug",
+        "info": "/nix/store/m0ijkc5j3wdawh302pns9b45v9n6nq64-gnumake-4.4.1-info",
+        "man": "/nix/store/ha44mgbdcrzgah0dnjd28ax4hrdkc4mm-gnumake-4.4.1-man",
+        "out": "/nix/store/ahxj2q2mrl9z2k77ahqsl9j4zxq1wf84-gnumake-4.4.1"
+      },
+      "system": "x86_64-linux",
+      "group": "toplevel",
+      "priority": 5
+    },
     {
       "attr_path": "gnused",
       "broken": false,

.flox/env/manifest.toml

@@ -15,6 +15,7 @@ lychee.pkg-path = "lychee"
 lychee.pkg-group = "lint"
 markdownlint-cli2.pkg-path = "markdownlint-cli2"
 markdownlint-cli2.pkg-group = "lint"
+gnumake.pkg-path = "gnumake"
 
 [hook]
 on-activate = '''

.github/workflows/ci.yml

@@ -43,6 +43,7 @@ jobs:
         with:
           command: |
             mkdocs build
+            python3 tools/generate_llms_txt.py ./site
             mkdir -p ./public/docs
             cp -R ./site/* ./public/docs/
             chmod -R +w ./public/docs

Makefile

@@ -0,0 +1,43 @@
+# Flox Documentation Makefile
+
+.PHONY: help dev build clean install
+
+# Default target
+help:
+	@echo "Available targets:"
+	@echo "  dev     - Start development server with live reload"
+	@echo "  build   - Build static site and generate AI files"
+	@echo "  clean   - Clean build artifacts"
+	@echo "  install - Install dependencies"
+	@echo "  help    - Show this help message"
+
+# Development server with live reload
+dev:
+	@echo "Starting development server..."
+	@echo "Site will be available at: http://127.0.0.1:8000"
+	@echo "Press Ctrl+C to stop"
+	mkdocs serve
+
+# Build static site and generate AI files
+build:
+	@echo "Building static site..."
+	mkdocs build
+	@echo "Generating AI files..."
+	python3 tools/generate_llms_txt.py ./site
+	@echo "✅ Build complete! Site available in ./site/"
+
+# Clean build artifacts
+clean:
+	@echo "Cleaning build artifacts..."
+	rm -rf site/
+	rm -rf public/
+	@echo "✅ Clean complete!"
+
+# Install dependencies (if needed)
+install:
+	@echo "Installing dependencies..."
+	@if command -v poetry >/dev/null 2>&1; then \
+		poetry install; \
+	else \
+		echo "Poetry not found. Please install dependencies manually."; \
+	fi

README.md

@@ -4,17 +4,53 @@ Live at: [flox.dev/docs](https://flox.dev/docs).
 
 ## Usage
 
+### Quick Start
+
+```bash
+# Activate the Flox environment
+$ flox activate
+✅ You are now using the environment 'floxdocs'.
+
+# Start development server
+λ (floxdocs) $ make dev
+```
+
+The documentation will be available at `http://127.0.0.1:8000` with live reload.
+
+### Available Commands
+
+```bash
+make dev     # Start development server with live reload
+make build   # Build static site and generate AI files
+make clean   # Clean build artifacts
+make help    # Show all available commands
 ```
+
+### Flox Native Usage
+
+You can still use the original Flox services approach:
+
+```bash
 $ flox activate
 ✅ You are now using the environment 'floxdocs'.
 
 λ (floxdocs) $ flox services start mkdocs
 ✅ Service 'mkdocs' started.
-
 ```
+
 Once mkdocs service started you can preview the documentation at
 `https://127.0.0.1:8000`.
 
+## AI-Friendly Documentation
+
+This documentation site automatically generates AI-friendly files for different use cases:
+
+- **`llms.txt`** - Optimized for AI agents with critical rules, workflows, and organized sitemap
+- **`docs-content.txt`** - Comprehensive content for answer engines and RAG systems
+
+These files are automatically generated during the build process and are available at:
+- `https://flox.dev/docs/llms.txt`
+- `https://flox.dev/docs/docs-content.txt`
 
 ## Guidelines
 

tools/README.md

@@ -0,0 +1,31 @@
+# Tools
+
+This directory contains build tools and utilities for the Flox documentation site.
+
+## Scripts
+
+### `generate_llms_txt.py`
+
+Generates AI-friendly documentation files from the built MkDocs site:
+
+- **`llms.txt`** - Agent-focused file with critical rules, workflows, and organized sitemap
+- **`docs-content.txt`** - Answer engine file with comprehensive documentation content
+
+**Usage:**
+```bash
+python3 tools/generate_llms_txt.py <site_directory>
+```
+
+### `generate_llms_txt.sh`
+
+Convenience script for local development. Generates both AI files after a MkDocs build.
+
+**Usage:**
+```bash
+mkdocs build
+./tools/generate_llms_txt.sh
+```
+
+## Integration
+
+These scripts are automatically run during CI builds in `.github/workflows/ci.yml` to ensure the AI files are always up-to-date with the documentation content.