fix(llms): curated link list, llms-full.txt from source, fix install URL

.flox/env/manifest.lock

@@ -18,6 +18,9 @@
         "pkg-path": "findutils",
         "outputs": "all"
       },
+      "gnumake": {
+        "pkg-path": "gnumake"
+      },
       "gnused": {
         "pkg-path": "gnused",
         "outputs": "all"
@@ -836,6 +839,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

@@ -23,6 +23,7 @@ markdownlint-cli2.pkg-path = "markdownlint-cli2"
 markdownlint-cli2.pkg-group = "lint"
 curl.pkg-path = "curl"
 curl.outputs = "all"
+just.pkg-path = "just"
 
 [hook]
 on-activate = '''

.github/workflows/ci.yml

@@ -47,6 +47,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

README.md

@@ -4,17 +4,55 @@ 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) $ just dev
+```
+
+The documentation will be available at `http://127.0.0.1:8000` with live reload.
+
+### Available Commands
+
+```bash
+just dev     # Start development server with live reload
+just build   # Build static site and generate AI files
+just clean   # Clean build artifacts
+just         # 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 curated link list
+- **`llms-full.txt`** - Full content for RAG systems and answer engines, generated from source Markdown
+
+These files are automatically generated during the build process and are available at:
+- `https://flox.dev/docs/llms.txt`
+- `https://flox.dev/docs/llms-full.txt`
 
 ## Guidelines
 

docs/llms.txt

@@ -2,7 +2,27 @@
 
 Flox is a next-generation package manager and environment manager for software development and delivery. It allows for creation of reproducible environments for projects, either through imperative commands or declarative manifests.
 
-If you see a `.flox` directory, that means the you are working with Flox to manage project dependencies and the environment lifecycle.
+If you see a `.flox` directory, that means you are working with Flox to manage project dependencies and the environment lifecycle.
+
+## Installation
+
+**Do NOT use `curl | bash` or reference `install.flox.dev` — that does not exist.**
+
+Install Flox from `flox.dev/download` or via a package manager:
+
+```bash
+# macOS
+brew install flox
+
+# Debian/Ubuntu — download .deb from flox.dev/download, then:
+sudo apt install /path/to/flox.deb
+
+# RPM (RedHat/CentOS/Amazon Linux) — download .rpm from flox.dev/download, then:
+sudo rpm -ivh /path/to/flox.rpm
+
+# Verify installation
+flox --version
+```
 
 ## Essential Commands
 ```bash
@@ -12,11 +32,13 @@ flox show <package>              # Show package details and versions
 flox init -d <dir>               # Initialize Flox environment in a directory
 flox list -d <dir>               # List installed packages
 flox install -d <dir> <package>  # Install package
-flox activate -d <dir> -- <cmd>  # Run command in environment
+flox activate -d <dir> -c <cmd>  # Run command in environment
 ```
 
 ## Critical Rules for Agentic Usage
-1. **NEVER run `flox activate` interactively** - use `flox activate -- <command>`
+1. **NEVER run `flox activate` interactively** — two non-interactive forms:
+   - `flox activate -c <cmd>` — runs in a subshell with full hooks and profile scripts (preferred for agents)
+   - `flox activate -- <cmd>` — exec mode, replaces the shell process, profile scripts do not run
 2. **ALWAYS use `flox install`** instead of apt/yum/rpm/brew
 3. Edit `.flox/env/manifest.toml` directly (not using `flox edit`)
 
@@ -45,6 +67,6 @@ To define services, add them to the manifest. Examples:
 api.command = "go run main.go"       # Backend API server
 frontend.command = "npm run dev"     # Frontend dev server
 mydaemon.command = "mydaemon start"  # Daemon that forks
-mydaemon.is_daemon = true
+mydaemon.is-daemon = true
 mydaemon.shutdown.command = "mydaemon stop"
 ```

justfile

@@ -0,0 +1,28 @@
+# Flox Documentation
+# Run `just` to see available recipes
+
+# Show available recipes
+default:
+    @just --list
+
+# Start 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!"

lychee.toml

@@ -10,6 +10,12 @@ host_request_interval = "500ms"
 exclude = [
   '^javascript:',
   '^data:',
+  '^http://localhost',
+  '\.svc\.cluster\.local',
+  'https://auth\.flox\.dev/oauth/token',
+  'https://nix\.dev/manual/nix/2\.17/',
+  '^https://cache\.flox\.dev/?$',
+  'downloads\.flox\.dev/by-env/stable/rpm$',
   'bash/manual/html_node',
   'https://www\.gnu\.org/software/make/',
   'https://github\.com/flox/catalog-util',

tools/README.md

@@ -0,0 +1,33 @@
+# 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 curated link list
+- **`llms-full.txt`** - Full content for RAG systems and answer engines, generated from source Markdown
+
+**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.