openvibers/openvibe.tools Commits

Agent layer: /.well-known/agent.json and Markdown twins of the directory and tool pages (#135)

OP OpenVibers committed 15 days ago · a8c385f090 · 6 files, +372 −21

openvibe-shared v4.34.0 in the gateway (was v4.33.0). server/agent-descriptor.js describes what openvibe.tools
really serves: the directory and tool pages, the run API /api/v1, its published OpenAPI 3.1 document, /developers
as documentation, auth none + Network OIDC + bearer app tokens, and the real tool quotas. server/pages/agent-pages.js
twins /, /all-tools, every family path and /tool/:id through the same pageIndex/pageFamily/pageTool/pageAll
renderers the browser gets, including the reworked design-pass markup that has landed on main. The site router
passes twin requests through to the mount after it; twin pages carry both discovery <link> tags, their HTML the
Link header, and robots.txt the manifest comment.

Changes

ddiff --git a/apps/gateway/package-lock.json b/apps/gateway/package-lock.json
iindex b5d994f..6e137f8 100644
---- a/apps/gateway/package-lock.json
++++ b/apps/gateway/package-lock.json
@@@ -19,13 +19,19 @@
          "helmet": "^8.1.0",
          "iovalkey": "^0.4.0",
          "jsonwebtoken": "^9.0.0",
--        "openvibe-contracts": "https://codeload.github.com/OpenVibers/OpenVibe.Contracts/tar.gz/refs/tags/v0.213.0",
--        "openvibe-sdk": "https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.64.0",
--        "openvibe-shared": "https://codeload.github.com/OpenVibers/OpenVibe.Shared/tar.gz/refs/tags/v4.12.0",
++        "openvibe-contracts": "https://codeload.github.com/OpenVibers/OpenVibe.Contracts/tar.gz/refs/tags/v0.222.0",
++        "openvibe-sdk": "https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.67.0",
++        "openvibe-shared": "https://codeload.github.com/OpenVibers/OpenVibe.Shared/tar.gz/refs/tags/v4.34.0",
          "pg": "^8.23.0",
          "zxing-wasm": "3.1.5"
        }
      },
++    "node_modules/@acemir/cssom": {
++      "version": "0.9.32",
++      "resolved": "https://registry.npmjs.org/@acemir/cssom/-/cssom-0.9.32.tgz",
++      "integrity": "sha512-OijrAUu7rrJhSIoHNg6LMPS5e344nwUHA+1EFYYjrh64D+GmytUsfBQjci45TjT+rd5Spsp8B5xsZDT+TgyXXQ==",
++      "license": "MIT"
++    },
      "node_modules/@electric-sql/pglite": {
        "version": "0.5.8",
        "resolved": "https://registry.npmjs.org/@electric-sql/pglite/-/pglite-0.5.8.tgz",
@@@ -120,6 +126,19 @@
          "npm": "1.2.8000 || >= 1.4.16"
        }
      },
++    "node_modules/boolbase": {
++      "version": "2.0.0",
++      "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-2.0.0.tgz",
++      "integrity": "sha512-DkVaaQHymRhpYEYo9x1oo7Q7B0Y6KJUsjm3c9eTyFDby4MHLBTwZ6ZDWBel5zrYxj1WsZgC5oLpiz+93MluXeA==",
++      "license": "ISC",
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "type": "github",
++        "url": "https://github.com/sponsors/fb55"
++      }
++    },
      "node_modules/buffer-equal-constant-time": {
        "version": "1.0.1",
        "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz",
@@@ -248,6 +267,39 @@
          "url": "https://opencollective.com/express"
        }
      },
++    "node_modules/css-select": {
++      "version": "7.0.0",
++      "resolved": "https://registry.npmjs.org/css-select/-/css-select-7.0.0.tgz",
++      "integrity": "sha512-snmjEVXy+1LnwXdxhYvTMj1d9tOh4HxkA1YmoayVBeeyR2C14Pum7fcxJIm4SswYspVy866eYNwlH6xC3/VH5g==",
++      "license": "BSD-2-Clause",
++      "dependencies": {
++        "boolbase": "^2.0.0",
++        "css-what": "^8.0.0",
++        "domhandler": "^6.0.1",
++        "domutils": "^4.0.2",
++        "nth-check": "^3.0.1"
++      },
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "type": "github",
++        "url": "https://github.com/sponsors/fb55"
++      }
++    },
++    "node_modules/css-what": {
++      "version": "8.0.0",
++      "resolved": "https://registry.npmjs.org/css-what/-/css-what-8.0.0.tgz",
++      "integrity": "sha512-DH0Bqq3DNp5tdOReuNyAA+Ev4Y2GS5FMbZpeTLP6C4CDi0h5nL0BmUPChXw3o/qbHLDWHl49sbNqQVY7bMSDdw==",
++      "license": "BSD-2-Clause",
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "type": "github",
++        "url": "https://github.com/sponsors/fb55"
++      }
++    },
      "node_modules/debug": {
        "version": "2.6.9",
        "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz",
@@@ -285,6 +337,73 @@
          "npm": "1.2.8000 || >= 1.4.16"
        }
      },
++    "node_modules/dom-serializer": {
++      "version": "3.1.1",
++      "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-3.1.1.tgz",
++      "integrity": "sha512-4MEa38/QexBob6gFNwu+EGdWvhJ1OKuNwdYY3Y3NyeWDQfnGeDYQUDfIRzWu5B5gsv03so2Uxd28YC6zrsx3Lw==",
++      "license": "MIT",
++      "dependencies": {
++        "domelementtype": "^3.0.0",
++        "domhandler": "^6.0.0",
++        "entities": "^8.0.0"
++      },
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "type": "github",
++        "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1"
++      }
++    },
++    "node_modules/domelementtype": {
++      "version": "3.0.0",
++      "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-3.0.0.tgz",
++      "integrity": "sha512-umCQid3jKbDmVjx8jGaW7uUykm4DEUeyV21hPxNMo2nV955DhUThwqyOIDtreepP31hl84X7G5U9ZfsWvIB3Pg==",
++      "funding": [
++        {
++          "type": "github",
++          "url": "https://github.com/sponsors/fb55"
++        }
++      ],
++      "license": "BSD-2-Clause",
++      "engines": {
++        "node": ">=20.19.0"
++      }
++    },
++    "node_modules/domhandler": {
++      "version": "6.0.1",
++      "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-6.0.1.tgz",
++      "integrity": "sha512-gYzvtM72ZtxQO0T048kd6HWSbbGCNOUwcnfQ01cqIJ4X2IYKFFHZ5mKvrQETcFXxsRObZulDaKmy//R7TPtsBg==",
++      "license": "BSD-2-Clause",
++      "dependencies": {
++        "domelementtype": "^3.0.0"
++      },
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "type": "github",
++        "url": "https://github.com/fb55/domhandler?sponsor=1"
++      }
++    },
++    "node_modules/domutils": {
++      "version": "4.0.2",
++      "resolved": "https://registry.npmjs.org/domutils/-/domutils-4.0.2.tgz",
++      "integrity": "sha512-qI4JLRKnSzqFqr7hAlS5xQDusBCjKSEG4t4+7aNrIQMHBcsC2TGEhuyABJdYkgSewL57PNLYEiibY2iPKhKpaA==",
++      "license": "BSD-2-Clause",
++      "dependencies": {
++        "dom-serializer": "^3.0.0",
++        "domelementtype": "^3.0.0",
++        "domhandler": "^6.0.0"
++      },
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "type": "github",
++        "url": "https://github.com/fb55/domutils?sponsor=1"
++      }
++    },
      "node_modules/dotenv": {
        "version": "16.6.1",
        "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
@@@ -335,6 +454,18 @@
          "node": ">= 0.8"
        }
      },
++    "node_modules/entities": {
++      "version": "8.1.0",
++      "resolved": "https://registry.npmjs.org/entities/-/entities-8.1.0.tgz",
++      "integrity": "sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA==",
++      "license": "BSD-2-Clause",
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "url": "https://github.com/fb55/entities?sponsor=1"
++      }
++    },
      "node_modules/es-define-property": {
        "version": "1.0.1",
        "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
@@@ -593,6 +724,110 @@
          "url": "https://github.com/sponsors/EvanHahn"
        }
      },
++    "node_modules/html-escaper": {
++      "version": "3.0.3",
++      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-3.0.3.tgz",
++      "integrity": "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ==",
++      "license": "MIT"
++    },
++    "node_modules/htmlparser2": {
++      "version": "10.1.0",
++      "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-10.1.0.tgz",
++      "integrity": "sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ==",
++      "funding": [
++        "https://github.com/fb55/htmlparser2?sponsor=1",
++        {
++          "type": "github",
++          "url": "https://github.com/sponsors/fb55"
++        }
++      ],
++      "license": "MIT",
++      "dependencies": {
++        "domelementtype": "^2.3.0",
++        "domhandler": "^5.0.3",
++        "domutils": "^3.2.2",
++        "entities": "^7.0.1"
++      }
++    },
++    "node_modules/htmlparser2/node_modules/dom-serializer": {
++      "version": "2.0.0",
++      "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz",
++      "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==",
++      "license": "MIT",
++      "dependencies": {
++        "domelementtype": "^2.3.0",
++        "domhandler": "^5.0.2",
++        "entities": "^4.2.0"
++      },
++      "funding": {
++        "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1"
++      }
++    },
++    "node_modules/htmlparser2/node_modules/dom-serializer/node_modules/entities": {
++      "version": "4.5.0",
++      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
++      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
++      "license": "BSD-2-Clause",
++      "engines": {
++        "node": ">=0.12"
++      },
++      "funding": {
++        "url": "https://github.com/fb55/entities?sponsor=1"
++      }
++    },
++    "node_modules/htmlparser2/node_modules/domelementtype": {
++      "version": "2.3.0",
++      "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz",
++      "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==",
++      "funding": [
++        {
++          "type": "github",
++          "url": "https://github.com/sponsors/fb55"
++        }
++      ],
++      "license": "BSD-2-Clause"
++    },
++    "node_modules/htmlparser2/node_modules/domhandler": {
++      "version": "5.0.3",
++      "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz",
++      "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==",
++      "license": "BSD-2-Clause",
++      "dependencies": {
++        "domelementtype": "^2.3.0"
++      },
++      "engines": {
++        "node": ">= 4"
++      },
++      "funding": {
++        "url": "https://github.com/fb55/domhandler?sponsor=1"
++      }
++    },
++    "node_modules/htmlparser2/node_modules/domutils": {
++      "version": "3.2.2",
++      "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.2.2.tgz",
++      "integrity": "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==",
++      "license": "BSD-2-Clause",
++      "dependencies": {
++        "dom-serializer": "^2.0.0",
++        "domelementtype": "^2.3.0",
++        "domhandler": "^5.0.3"
++      },
++      "funding": {
++        "url": "https://github.com/fb55/domutils?sponsor=1"
++      }
++    },
++    "node_modules/htmlparser2/node_modules/entities": {
++      "version": "7.0.1",
++      "resolved": "https://registry.npmjs.org/entities/-/entities-7.0.1.tgz",
++      "integrity": "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==",
++      "license": "BSD-2-Clause",
++      "engines": {
++        "node": ">=0.12"
++      },
++      "funding": {
++        "url": "https://github.com/fb55/entities?sponsor=1"
++      }
++    },
      "node_modules/http-errors": {
        "version": "2.0.1",
        "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
@@@ -738,6 +973,30 @@
          "safe-buffer": "^5.0.1"
        }
      },
++    "node_modules/linkedom": {
++      "version": "0.18.14",
++      "resolved": "https://registry.npmjs.org/linkedom/-/linkedom-0.18.14.tgz",
++      "integrity": "sha512-BRUnkOm4YR5vo+qI3j0EbungB0vZPSCue5AdnTQRaxAGSbsOZiBFRO0rh4zlo8qXUhli8pxvnpEXDklMnlq2Rg==",
++      "license": "ISC",
++      "dependencies": {
++        "@acemir/cssom": "^0.9.32",
++        "css-select": "^7.0.0",
++        "html-escaper": "^3.0.3",
++        "htmlparser2": "^10.1.0",
++        "uhyphen": "^0.2.0"
++      },
++      "engines": {
++        "node": ">=16"
++      },
++      "peerDependencies": {
++        "canvas": ">= 2"
++      },
++      "peerDependenciesMeta": {
++        "canvas": {
++          "optional": true
++        }
++      }
++    },
      "node_modules/lodash.defaults": {
        "version": "4.2.0",
        "resolved": "https://registry.npmjs.org/lodash.defaults/-/lodash.defaults-4.2.0.tgz",
@@@ -876,6 +1135,22 @@
          "node": ">= 0.6"
        }
      },
++    "node_modules/nth-check": {
++      "version": "3.0.1",
++      "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-3.0.1.tgz",
++      "integrity": "sha512-GX0gsdbGVCgnRgbeGaubfjpBXyYRWOOCVeYh08bSQvDZqxz5ndXs1OTfAt/h36G1xvI94YIspsI0sVFqAV9+RQ==",
++      "license": "BSD-2-Clause",
++      "dependencies": {
++        "boolbase": "^2.0.0"
++      },
++      "engines": {
++        "node": ">=20.19.0"
++      },
++      "funding": {
++        "type": "github",
++        "url": "https://github.com/fb55/nth-check?sponsor=1"
++      }
++    },
      "node_modules/object-assign": {
        "version": "4.1.1",
        "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
@@@ -910,9 +1185,9 @@
        }
      },
      "node_modules/openvibe-contracts": {
--      "version": "0.213.0",
--      "resolved": "https://codeload.github.com/OpenVibers/OpenVibe.Contracts/tar.gz/refs/tags/v0.213.0",
--      "integrity": "sha512-QeJamMrqMoGyvPoD80pyGZepF3GTaKJYVWBVeFsigVulZBmt8zeQOeJZ3TMwtUydT0bPje3kUt98/czwXvR7sg==",
++      "version": "0.222.0",
++      "resolved": "https://codeload.github.com/OpenVibers/OpenVibe.Contracts/tar.gz/refs/tags/v0.222.0",
++      "integrity": "sha512-wdUQCilq9glRMwfxEswbIj3l0QQqKDXZAi2+CR5Mlh34rZjI1Q+7GlAoR0UtNwZAgtLwXhPxFyJ/aPk8lcDG1Q==",
        "license": "AGPL-3.0-only",
        "dependencies": {
          "ajv": "^8.17.1",
@@@ -926,9 +1201,9 @@
        }
      },
      "node_modules/openvibe-sdk": {
--      "version": "0.64.0",
--      "resolved": "https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.64.0",
--      "integrity": "sha512-m7Xey0eclm7RUyEjI9NVTLXqKwgnuCYqY0poX17hDezF9vKRwBB8Xh+WqHh5aZN7QHmM16CKG8GPKS5FUcKg4w==",
++      "version": "0.67.0",
++      "resolved": "https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.67.0",
++      "integrity": "sha512-s7NzjaNcowVcOIiup2z0ze+xsq/qnr++3pHSI8JzirqJPQ5JsBSUF5RkjOHyfk9bRKlmhY0fsNS6x4dsYylyqw==",
        "license": "MIT",
        "bin": {
          "openvibe-download": "bin/openvibe-download.js"
@@@ -954,12 +1229,13 @@
        }
      },
      "node_modules/openvibe-shared": {
--      "version": "4.12.0",
--      "resolved": "https://codeload.github.com/OpenVibers/OpenVibe.Shared/tar.gz/refs/tags/v4.12.0",
--      "integrity": "sha512-k0i63sCPfHtz1KF5MJSI+CGv5VwBf4ISRzxJRQdorkeMKOTtABlAQfiH1uf9kJsd5/Wn7VUTTHlhhOLSX6ZTzw==",
++      "version": "4.34.0",
++      "resolved": "https://codeload.github.com/OpenVibers/OpenVibe.Shared/tar.gz/refs/tags/v4.34.0",
++      "integrity": "sha512-Rj5uRO3MbWkyIYAm+vK4Y94ugDNYEjEgGkYnPjSej4yMqhalpaPCkU96dzphMGiOUGP1PNWsiKhwaBj8tewgBg==",
        "license": "MIT",
        "dependencies": {
--        "jsonwebtoken": "^9.0.0"
++        "jsonwebtoken": "^9.0.0",
++        "linkedom": "^0.18.13"
        },
        "bin": {
          "openvibe-build-assets": "scripts/build-assets.js"
@@@ -1425,6 +1701,12 @@
          "node": ">= 0.6"
        }
      },
++    "node_modules/uhyphen": {
++      "version": "0.2.0",
++      "resolved": "https://registry.npmjs.org/uhyphen/-/uhyphen-0.2.0.tgz",
++      "integrity": "sha512-qz3o9CHXmJJPGBdqzab7qAYuW8kQGKNEuoHFYrBwV6hWIMcpAmxDLXojcHfFr9US1Pe6zUswEIJIbLI610fuqA==",
++      "license": "ISC"
++    },
      "node_modules/unpipe": {
        "version": "1.0.0",
        "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz",
ddiff --git a/apps/gateway/package.json b/apps/gateway/package.json
iindex 0e4beeb..35131bb 100644
---- a/apps/gateway/package.json
++++ b/apps/gateway/package.json
@@@ -23,7 +23,7 @@
      "jsonwebtoken": "^9.0.0",
      "openvibe-contracts": "https://codeload.github.com/OpenVibers/OpenVibe.Contracts/tar.gz/refs/tags/v0.222.0",
      "openvibe-sdk": "https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.67.0",
--    "openvibe-shared": "https://codeload.github.com/OpenVibers/OpenVibe.Shared/tar.gz/refs/tags/v4.33.0",
++    "openvibe-shared": "https://codeload.github.com/OpenVibers/OpenVibe.Shared/tar.gz/refs/tags/v4.34.0",
      "bwip-js": "4.11.4",
      "zxing-wasm": "3.1.5"
    }
ddiff --git a/apps/gateway/server/agent-descriptor.js b/apps/gateway/server/agent-descriptor.js
nnew file mode 100644
iindex 0000000..58325c2
---- /dev/null
++++ b/apps/gateway/server/agent-descriptor.js
@@@ -0,0 +1,18 @@
++'use strict';
++// What openvibe.tools tells an agent about itself (openvibe-shared/agent-layer): /.well-known/agent.json.
++// The directory and tool pages are public; the run API is /api/v1 (an OpenAPI 3.1 document is published at
++// /api/v1/openapi.json) and /developers documents it. Auth is none + Network OIDC (bearer for app tokens).
++module.exports = {
++    id: 'tools',
++    name: 'OpenVibe.Tools',
++    purpose: 'The OpenVibe network\'s tool suite: converters, file and PDF tools, developer utilities and network checks, open in the browser or callable through one JSON API.',
++    home: 'https://openvibe.tools',
++    site: 'openvibe.tools',
++    api: '/api/v1',
++    openapi: '/api/v1/openapi.json',
++    docs: '/developers',
++    policy: {
++        auth: ['none', 'Network OIDC', 'bearer'],
++        rateLimit: 'Anonymous tool runs follow the per-address tool quota; signing in or an app token raises the tier, and every answer carries RateLimit-* headers',
++    },
++};
ddiff --git a/apps/gateway/server/index.js b/apps/gateway/server/index.js
iindex e0d2215..26caa0a 100644
---- a/apps/gateway/server/index.js
++++ b/apps/gateway/server/index.js
@@@ -506,6 +506,13 @@ app.get('/openvibe-sw.js', (req, res) => {
  // not fall through to the SPA/static handlers. Unset INDEXNOW_KEY → off, nothing mounted (404).
  const indexnow = createToolsIndexNow(config.baseUrl, config.indexnow.key);
  if (indexnow.enabled) app.use(indexnow.keyFile);
++// The agent layer (openvibe-shared/agent-layer): /.well-known/agent.json and the Markdown twins of the directory and
++// tool pages. Mounted after the site routes, so a browser gets the page's own head and cache and only a twin request
++// reaches it; before the static files and the catch-all, so an unknown .md is a 404.
++require('openvibe-shared/agent-layer').mount(app, {
++    descriptor: require('./agent-descriptor'),
++    render: require('./pages/agent-pages').createAgentPages({ opens: toolOpens }).renderPublicPage,
++});
  app.use(express.static(path.join(__dirname, '..', 'public'), {
      setHeaders(res, filePath) {
          if (filePath.endsWith('.js') || filePath.endsWith('.css')) {
ddiff --git a/apps/gateway/server/pages/agent-pages.js b/apps/gateway/server/pages/agent-pages.js
nnew file mode 100644
iindex 0000000..69e24e4
---- /dev/null
++++ b/apps/gateway/server/pages/agent-pages.js
@@@ -0,0 +1,27 @@
++'use strict';
++// The Markdown twins of openvibe.tools' public pages (openvibe-shared/agent-layer): the directory, every family,
++// /all-tools and each tool's page. They are the same pageIndex/pageFamily/pageTool/pageAll renderers the site serves,
++// so a twin cannot drift from its page. The noindex search page and the API pages have no twin.
++const site = require('./site');
++const registry = require('../registry');
++
++function createAgentPages({ opens = null } = {}) {
++    async function renderPublicPage(path) {
++        const p = String(path || '/').replace(/\/+$/, '') || '/';
++        if (p === '/') {
++            const top = opens ? await opens.top(7, 12).catch(() => []) : [];
++            return { html: site.pageIndex(top) };
++        }
++        if (p === '/all-tools') return { html: site.pageAll() };
++        if (p.startsWith('/tool/')) {
++            const t = registry.get().tools.find((x) => x.id === p.slice('/tool/'.length));
++            return t ? { html: site.pageTool(t) } : null;
++        }
++        const f = registry.get().families.find((x) => x.path === p);
++        return f ? { html: site.pageFamily(f) } : null;
++    }
++
++    return { renderPublicPage };
++}
++
++module.exports = { createAgentPages };
ddiff --git a/apps/gateway/server/pages/site.js b/apps/gateway/server/pages/site.js
iindex 6d7b1bc..afe6215 100644
---- a/apps/gateway/server/pages/site.js
++++ b/apps/gateway/server/pages/site.js
@@@ -183,7 +183,12 @@ function networkLinks() {
      return NETWORK_COPY.filter(([id]) => up.has(id)).map(([id, d]) => [id, up.get(id).name, d, `${up.get(id).origin}/`]);
  }
  
--function shell({ head, body, families }) {
++function shell({ head, body, families, agent = false }) {
++    // A page with a Markdown twin names it and llms.txt in the head (openvibe-shared/agent-layer).
++    if (agent) {
++        const canonical = (head.match(/<link rel="canonical" href="([^"]+)"/) || [])[1];
++        if (canonical) head += '\n' + seo.linkHeaderTags(canonical, `${SITE}/llms.txt`).head;
++    }
      // Every icon on the page once, as a sprite; the markup above only references them.
      const NETWORK = networkLinks();
      const spriteSvg = icons.sprite([..._used, ...NETWORK.map(n => n[0])]); _used = new Set();
@@@ -356,7 +361,7 @@ ${frame.shipped({ service: 'tools', title: 'Recently shipped on OpenVibe.Tools'
  <div><b>Signed in</b><p>Results keep for 24 hours, your recent tools follow you across devices, and your theme and notifications come along from the rest of OpenVibe.</p></div>
  <div><b>For developers</b><p>Run any tool from code: see <a href="/developers">the Tools API</a> (<a href="/api/v1/openapi.json">OpenAPI</a>). The catalog is public JSON at <a href="/api/catalog.json">/api/catalog.json</a>, with a plain-text map at <a href="/llms.txt">/llms.txt</a>.</p></div></div></details></section>
  <section aria-labelledby="faq-h"><div class="sec-h"><h2 id="faq-h">Questions</h2></div>${HOME_FAQ.map(([q, a]) => `<details><summary>${esc(q)}</summary><p>${esc(a)}</p></details>`).join('')}</section>`;
--    return shell({ families, body, head: head({
++    return shell({ families, agent: true, body, head: head({
          title: 'Online Tools for Files, Text, Code & Networks', description: `${tools.length} online tools in one place: video and audio converters, image and PDF tools, developer utilities and network diagnostics. Open source and community-run.`,
          canonical: SITE + '/', keywords: 'online tools, converter, pdf tools, image converter, developer tools, network tools, youtube downloader',
          jsonLd: [seo.jsonLd.organization(), seo.jsonLd.website({ name: NAME, url: SITE + '/', description: 'Online tools for files, text, code and networks.', searchUrl: SITE + '/search?q={search_term_string}' }),
@@@ -373,7 +378,7 @@ function pageFamily(f) {
  ${f.hosts ? `<a class="cta" href="${esc(f.url)}">Open ${esc(f.name)}</a>` : ''}
  <section><div class="sec-h"><h2>${list.length} tools</h2></div><p class="sec-p">${esc(f.intro || '')}</p><div class="grid">${list.map(toolCard).join('')}</div></section>
  ${f.faq && f.faq.length ? `<section><div class="sec-h"><h2>Questions</h2></div>${f.faq.map(([q, a]) => `<details><summary>${esc(q)}</summary><p>${esc(a)}</p></details>`).join('')}</section>` : ''}`;
--    return shell({ families, body, head: head({ title: `${f.name}: ${f.tagline}`, description: f.description, canonical: url, keywords: list.slice(0, 12).map(t => t.name.toLowerCase()).join(', '),
++    return shell({ families, agent: true, body, head: head({ title: `${f.name}: ${f.tagline}`, description: f.description, canonical: url, keywords: list.slice(0, 12).map(t => t.name.toLowerCase()).join(', '),
          jsonLd: [seo.jsonLd.breadcrumbs([{ name: 'Tools', url: SITE + '/' }, { name: f.name, url }]), seo.jsonLd.itemList(f.name, list.map(t => ({ name: t.name, url: t.url, description: t.tagline }))),
              ...(f.faq && f.faq.length ? [seo.jsonLd.faq(f.faq.map(([q, a]) => ({ q, a })))] : [])] }) });
  }
@@@ -392,7 +397,7 @@ ${t.status === 'unavailable' ? `<p class="lead"><strong>Not available yet.</stro
  ${t.keywords && t.keywords.length ? `<section><div class="sec-h"><h2>People also call this</h2></div><ul class="kw">${t.keywords.map(k => `<li>${esc(k)}</li>`).join('')}</ul></section>` : ''}
  ${apiSection(t)}
  ${related.length ? `<section><div class="sec-h"><h2>Related tools</h2>${f && f.path ? `<a class="more" href="${esc(f.path)}">All ${esc(f.name)}</a>` : ''}</div><div class="grid">${related.map(toolCard).join('')}</div></section>` : ''}`;
--    return shell({ families, body, head: head({ title: `${t.name}: ${t.tagline}`, description: t.description, canonical: url, keywords: (t.keywords || []).join(', '),
++    return shell({ families, agent: true, body, head: head({ title: `${t.name}: ${t.tagline}`, description: t.description, canonical: url, keywords: (t.keywords || []).join(', '),
          jsonLd: [seo.jsonLd.breadcrumbs([{ name: 'Tools', url: SITE + '/' }, ...(f && f.path ? [{ name: f.name, url: SITE + f.path }] : []), { name: t.name, url }]),
              seo.jsonLd.softwareApp({ name: t.name, url: t.url, description: t.description, category: 'UtilitiesApplication', keywords: t.keywords })] }) });
  }
@@@ -402,7 +407,7 @@ function pageAll() {
      const sorted = [...tools].sort((a, b) => a.name.localeCompare(b.name));
      const body = `<nav class="crumbs" aria-label="Breadcrumb"><a href="/">Tools</a> › All tools</nav><div class="page-h">${icon('tools', 56)}<h1>All ${tools.length} tools, A to Z</h1></div>
  ${searchForm('')}<section><ul class="az">${sorted.map(t => `<li><a href="${esc(t.url)}">${esc(t.name)}</a> <small><a href="/tool/${esc(t.id)}" aria-label="About ${esc(t.name)}">about</a></small></li>`).join('')}</ul></section>`;
--    return shell({ families, body, head: head({ title: `All ${tools.length} Online Tools, A to Z`, description: 'The complete list of tools on OpenVibe.Tools: converters, downloaders, PDF and image tools, text utilities, developer tools and network diagnostics.', canonical: SITE + '/all-tools',
++    return shell({ families, agent: true, body, head: head({ title: `All ${tools.length} Online Tools, A to Z`, description: 'The complete list of tools on OpenVibe.Tools: converters, downloaders, PDF and image tools, text utilities, developer tools and network diagnostics.', canonical: SITE + '/all-tools',
          jsonLd: [seo.jsonLd.breadcrumbs([{ name: 'Tools', url: SITE + '/' }, { name: 'All tools', url: SITE + '/all-tools' }])] }) });
  }
  
@@@ -482,6 +487,11 @@ const done = await job.wait();   // any tool, sync or job`)}
  
  function send(req, res, key, render, type, extra) {
      const e = cached(key, render, extra);
++    if (!type || /^text\/html/.test(type)) {
++        const isAgentPage = key === '/' || key === '/all-tools' || key.startsWith('/tool/')
++            || registry.get().families.some((f) => f.path === key);
++        if (isAgentPage) res.set('Link', seo.linkHeaderTags(`${SITE}${key === '/' ? '/' : key}`, `${SITE}/llms.txt`).header);
++    }
      res.set('Content-Type', type || 'text/html; charset=utf-8');
      res.set('Cache-Control', 'public, max-age=300, stale-while-revalidate=86400');
      res.set('ETag', e.etag);
@@@ -530,6 +540,13 @@ function llmsFullBody() {
  
  function createSiteRouter({ opens = null } = {}) {
      const router = express.Router();
++    // Markdown twin and agent manifest requests go to openvibe-shared/agent-layer, mounted after this router.
++    router.use((req, res, next) => {
++        const p = String(req.path || '');
++        if (p.endsWith('.md') || p.startsWith('/.well-known/') || (req.query && req.query.format === 'markdown')
++            || req.accepts(['html', 'text/markdown']) === 'text/markdown') return next('router');
++        return next();
++    });
      const apexOnly = (req, res, next) => (!req.ovHost || req.ovHost.kind === 'apex' || (req.ovHost.kind === 'unknown' && !req.ovHost.inZone) ? next() : next('router'));
      router.use(apexOnly);
      router.get('/api/v1/openapi.json', (req, res) => { res.set('Access-Control-Allow-Origin', '*'); send(req, res, 'openapi', () => JSON.stringify(require('../openapi').openapi(require('../registry/descriptors').snapshot(), SITE)), 'application/json; charset=utf-8'); });
@@@ -547,7 +564,7 @@ function createSiteRouter({ opens = null } = {}) {
      router.get('/search', (req, res) => { res.set('Cache-Control', 'no-store'); res.type('html').send(pageSearch(String(req.query.q || '').slice(0, 80))); });
      router.get('/tool/:id', (req, res, next) => { const t = registry.get().tools.find(x => x.id === req.params.id); return t ? send(req, res, '/tool/' + t.id, () => pageTool(t)) : next(); });
      router.get('/sitemap.xml', (req, res) => send(req, res, 'sitemap', () => seo.sitemapXml(sitemapEntries()), 'application/xml; charset=utf-8'));
--    router.get('/robots.txt', (req, res) => send(req, res, 'robots', () => seo.robotsTxt({ sitemaps: [SITE + '/sitemap.xml'], disallow: ['/api/', '/auth/'], allow: ['/api/catalog.json'], allowAI: true }), 'text/plain; charset=utf-8'));
++    router.get('/robots.txt', (req, res) => send(req, res, 'robots', () => seo.robotsTxt({ sitemaps: [SITE + '/sitemap.xml'], disallow: ['/api/', '/auth/'], allow: ['/api/catalog.json'], allowAI: true }) + `# Agent manifest: ${SITE}/.well-known/agent.json\n`, 'text/plain; charset=utf-8'));
      router.get('/llms.txt', (req, res) => send(req, res, 'llms', llmsTxtBody, 'text/plain; charset=utf-8'));
      // The same document with every public page's text: what /llms.txt lists, readable whole.
      router.get('/llms-full.txt', (req, res) => send(req, res, 'llms-full', llmsFullBody, 'text/plain; charset=utf-8'));
@@@ -557,4 +574,4 @@ function createSiteRouter({ opens = null } = {}) {
  
  const renderNotFound = () => pageSearch('').replace('<h1>Search tools</h1>', '<h1>That page is not here</h1>').replace(/<title>[^<]*<\/title>/, '<title>Page not found | OpenVibe.Tools</title>');
  
--module.exports = { createSiteRouter, search, sitemapEntries, renderNotFound };
++module.exports = { createSiteRouter, pageIndex, pageFamily, pageTool, pageAll, search, sitemapEntries, renderNotFound, SITE, NAME };