openvibers/openvibe.zone Commits

Agent layer: /.well-known/agent.json and Markdown twins of the public pages (#75)

OP OpenVibers committed 15 days ago · 0f1f0934d3 · 10 files, +369 −22

openvibe-shared v4.34.0 (was v4.33.0). The descriptor names what openvibe.zone really serves: the zone API at
/api/v1, the usage guide at /docs, and the three ways in (none, Network OIDC, a zone access key over S3
Signature Version 4). The public pages keep their own builders and server/agent-pages.js renders their twins
through the same ones (createPageRoutes().publicViews), so a twin cannot drift from its page: the home, the
docs and the update log. /projects and /p/:project are a signed-in person's and have no twin. Only the
manifest and twin requests reach the mount, even though it sits before the page routes, so signed-in pages
keep their account bar and forms; each public page advertises its twin with both discovery links and the Link
header. robots.txt gains the manifest comment.

Changes

ddiff --git a/README.md b/README.md
iindex 60a0200..3f5fcc5 100644
---- a/README.md
++++ b/README.md
@@@ -123,5 +123,5 @@ AGPL-3.0, see LICENSE.
  <!-- versions:start -->
  - openvibe-contracts: v0.222.0
  - openvibe-sdk: v0.67.0
--- openvibe-shared: v4.33.0
++- openvibe-shared: v4.34.0
  <!-- versions:end -->
ddiff --git a/STATUS.json b/STATUS.json
iindex fdd9f02..e1b40b4 100644
---- a/STATUS.json
++++ b/STATUS.json
@@@ -9,11 +9,11 @@
    "domain": "openvibe.zone",
    "contracts": "openvibe-contracts v0.222.0",
    "sdk": "openvibe-sdk v0.67.0",
--  "shared": "openvibe-shared v4.33.0",
++  "shared": "openvibe-shared v4.34.0",
    "packages": [
      "openvibe-contracts v0.222.0",
      "openvibe-sdk v0.67.0",
--    "openvibe-shared v4.33.0"
++    "openvibe-shared v4.34.0"
    ],
    "summary": "OpenVibe.Zone — private S3-compatible storage zones for OpenVibe projects (ADR-031 amendment). Zone owns the zone record and its control API; OpenVibe.Media owns the objects, bytes, keys, quotas and the S3 surface at s3.openvibe.media.",
    "works": [
ddiff --git a/package-lock.json b/package-lock.json
iindex 9dbfddd..ad14bcf 100644
---- a/package-lock.json
++++ b/package-lock.json
@@@ -18,7 +18,7 @@
          "iovalkey": "^0.4.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",
          "pg": "^8.23.0"
        },
        "devDependencies": {
@@@ -28,6 +28,12 @@
          "node": ">=22.0.0"
        }
      },
++    "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.10",
        "resolved": "https://registry.npmjs.org/@electric-sql/pglite/-/pglite-0.5.10.tgz",
@@@ -117,6 +123,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",
@@@ -219,6 +238,39 @@
        "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==",
        "license": "MIT"
      },
++    "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",
@@@ -256,6 +308,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",
@@@ -306,6 +425,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",
@@@ -564,6 +695,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",
@@@ -709,6 +944,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",
@@@ -847,6 +1106,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-inspect": {
        "version": "1.13.4",
        "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
@@@ -916,12 +1191,13 @@
        }
      },
      "node_modules/openvibe-shared": {
--      "version": "4.33.0",
--      "resolved": "https://codeload.github.com/OpenVibers/OpenVibe.Shared/tar.gz/refs/tags/v4.33.0",
--      "integrity": "sha512-t9XvhrQ+lQebOrFTjMCzI6/7/i4iQn9dmMr/8HVTNW1XoV1exyJa7IH/HfyyKuLxjA8xaowrDfD28LwKIibBNg==",
++      "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"
@@@ -1364,6 +1640,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/package.json b/package.json
iindex 9c63cff..c3b7bcd 100644
---- a/package.json
++++ b/package.json
@@@ -25,7 +25,7 @@
      "iovalkey": "^0.4.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",
      "pg": "^8.23.0"
    },
    "engines": {
ddiff --git a/server/agent-descriptor.js b/server/agent-descriptor.js
nnew file mode 100644
iindex 0000000..1f0b709
---- /dev/null
++++ b/server/agent-descriptor.js
@@@ -0,0 +1,16 @@
++'use strict';
++// What openvibe.zone tells an agent about itself (openvibe-shared/agent-layer): /.well-known/agent.json.
++// Every field is something this site really serves: the zone API at /api/v1 and the usage guide at /docs.
++// Sign-in is OpenVibe's Network OIDC; the S3 endpoint takes a zone access key, not a Network token.
++module.exports = {
++    id: 'zone',
++    name: 'OpenVibe.Zone',
++    purpose: 'Private S3-compatible storage zones for OpenVibe projects: create zones, issue access keys scoped to them, and use the AWS SDKs, rclone or any S3 tool.',
++    home: 'https://openvibe.zone',
++    site: 'openvibe.zone',
++    api: '/api/v1',
++    docs: '/docs',
++    policy: {
++        auth: ['none', 'Network OIDC', 'zone access key (S3 Signature Version 4)'],
++    },
++};
ddiff --git a/server/agent-pages.js b/server/agent-pages.js
nnew file mode 100644
iindex 0000000..eefec7e
---- /dev/null
++++ b/server/agent-pages.js
@@@ -0,0 +1,20 @@
++'use strict';
++// The Markdown twins of openvibe.zone's public pages (openvibe-shared/agent-layer), rendered by the same page
++// builders the routes use (createPageRoutes().publicViews + render/layout.js's renderPage), so a twin cannot
++// drift from its page. Anonymous only: /projects and /p/:project are a signed-in person's, and get no twin.
++const { renderPage } = require('./render/layout');
++
++function createAgentPages(ctx, publicViews) {
++    const twin = (page, path) => (page ? { html: renderPage({ ...page, viewer: { kind: 'anonymous' }, config: ctx.config, path }) } : null);
++
++    async function renderPublicPage(path) {
++        if (path === '/') return twin(await publicViews.home({ signed: false }), path);
++        if (path === '/docs') return twin(await publicViews.docs(), path);
++        if (path === '/updates') return twin(publicViews.updates(), path);
++        return null;
++    }
++
++    return { renderPublicPage };
++}
++
++module.exports = { createAgentPages };
ddiff --git a/server/app.js b/server/app.js
iindex 32c9cc5..edc465a 100644
---- a/server/app.js
++++ b/server/app.js
@@@ -142,7 +142,21 @@ async function createApp(opts = {}) {
  
      // ── Pages ───────────────────────────────────────────────
      app.use(rateLimit({ windowMs: 60_000, limit: Number(process.env.ZONE_RATE_LIMIT_PER_MIN) || 300, standardHeaders: true, legacyHeaders: false }));
--    app.use(createPageRoutes(ctx));
++    const pageRoutes = createPageRoutes(ctx);
++    // The agent layer (openvibe-shared/agent-layer): /.well-known/agent.json and the Markdown twins of the public
++    // pages. The pages keep their own routes — a signed-in person's projects and forms are theirs — so only the
++    // manifest and twin requests reach this mount; the pages advertise the twin themselves.
++    const agentLayer = express();
++    require('openvibe-shared/agent-layer').mount(agentLayer, {
++        descriptor: require('./agent-descriptor'),
++        render: require('./agent-pages').createAgentPages(ctx, pageRoutes.publicViews).renderPublicPage,
++    });
++    app.use((req, res, next) => {
++        const twin = req.path.endsWith('.md') || req.query.format === 'markdown' || String(req.headers.accept || '').includes('text/markdown');
++        if (req.path !== '/.well-known/agent.json' && !twin) return next();
++        return agentLayer(req, res, next);
++    });
++    app.use(pageRoutes);
      app.use((req, res) => send(res, 404, { viewer: req.viewer, config, path: req.originalUrl, title: 'Not found', body: html`<h1>Not found</h1><p>No page here. Try <a href="/">the home page</a> or <a href="/updates">the update log</a>.</p>` }));
  
      // eslint-disable-next-line no-unused-vars
ddiff --git a/server/http/discovery.js b/server/http/discovery.js
iindex f3ab79b..10281df 100644
---- a/server/http/discovery.js
++++ b/server/http/discovery.js
@@@ -52,6 +52,7 @@ function createDiscoveryRoutes(ctx) {
      r.get('/robots.txt', (_req, res) => {
          res.type('text/plain').set('Cache-Control', TEXT).send(
              '# openvibe.zone: the public pages are for search and AI crawlers; sign-in, projects and the API are not.\n'
++            + '# Agent manifest: https://openvibe.zone/.well-known/agent.json; every public page has a .md twin.\n'
              + seo.robotsTxt({ sitemaps: [abs('/sitemap.xml')], disallow: DISALLOW }));
      });
  
ddiff --git a/server/http/pages.js b/server/http/pages.js
iindex 535d63b..95b5c24 100644
---- a/server/http/pages.js
++++ b/server/http/pages.js
@@@ -68,8 +68,8 @@ function createPageRoutes(ctx) {
      }, 401);
  
      // ── Home ─────────────────────────────────────────────────
--    r.get('/', async (req, res) => {
--        const me = person(req);
++    async function homePage({ signed = false } = {}) {
++        const me = signed;
          const L = await limitsOf();
          const prod = L.get('storage_bytes'), sandbox = L.get('storage_bytes');
          const stats = [];
@@@ -96,8 +96,8 @@ function createPageRoutes(ctx) {
              note: prod ? `Each project includes ${bytes(prod.production)} in production and ${bytes(prod.sandbox)} in its sandbox at no charge.` : 'Each project includes storage in production and in its sandbox at no charge.',
              html: stats.length ? `<dl class="zn-stats">${stats.map(([dt, dd]) => `<div><dt>${dt}</dt><dd>${dd}</dd></div>`).join('')}</dl>` : undefined,
          });
--        page(req, res, {
--            index: true, cache: me ? null : PUBLIC_CACHE, styles: [showcase.STYLESHEET],
++        return {
++            agent: true, index: true, cache: me ? null : PUBLIC_CACHE, styles: [showcase.STYLESHEET],
              jsonLd: [...homeJsonLd(config), { '@context': 'https://schema.org', '@type': 'FAQPage', mainEntity: faq.map((f) => ({ '@type': 'Question', name: f.q, acceptedAnswer: { '@type': 'Answer', text: f.a } })) }],
              description: 'Private S3 buckets for your OpenVibe projects: create zones, issue access keys scoped to them, and use the AWS SDKs, rclone or any S3 tool.',
              body: html`${raw(hero)}
@@@ -159,8 +159,9 @@ ${L.size ? raw(showcase.limits({
                  source: 'https://openvibe.media/limits.json',
              })) : ''}
  <section class="zn-section zn-home zn-faq" aria-labelledby="zn-faq-h"><h2 id="zn-faq-h">Questions</h2>${faq.map((f) => html`<details><summary>${f.q}</summary><p>${f.a}</p></details>`)}</section>`,
--        });
--    });
++        };
++    }
++    r.get('/', async (req, res) => page(req, res, await homePage({ signed: !!person(req) })));
  
      // ── A person's projects ──────────────────────────────────
      r.get('/projects', async (req, res) => {
@@@ -319,8 +320,8 @@ ${keysSection}
      }));
  
      // ── Docs ─────────────────────────────────────────────────
--    r.get('/docs', async (req, res) => { const L = await limitsOf(); page(req, res, {
--        index: true, cache: PUBLIC_CACHE, title: 'Using OpenVibe.Zone',
++    async function docsPage() { const L = await limitsOf(); return {
++        agent: true, index: true, cache: PUBLIC_CACHE, title: 'Using OpenVibe.Zone',
          description: 'Create zones, issue S3 access keys and reach your buckets with the AWS SDKs, rclone and any S3 tool: the OpenVibe.Zone guide and API.',
          body: html`<h1>Using OpenVibe.Zone</h1>
  <p class="zn-lede">A zone is an S3 bucket of one project environment. You make zones here or with the API, issue access keys, and point any S3 tool at <code>${s3}</code>.</p>
@@@ -358,14 +359,19 @@ ${keysSection}
  <li><code>GET /zones/:zone_id/usage</code> (<code>zone.usage.read</code>): Media's live snapshot, and this month's metered series (requests, egress, byte-hours) as Media reports each closed hour.</li>
  </ul>
  <p>The objects of a zone are OpenVibe.Media objects. Media's own API (<code>/api/v2/:project_id/objects</code>, with <code>namespace</code> set to the zone's id) reads and writes the same objects.</p>`,
--    }); });
++    }; }
++    r.get('/docs', async (req, res) => page(req, res, await docsPage()));
  
--    r.get('/updates', (req, res) => page(req, res, {
--        index: true, cache: PUBLIC_CACHE,
++    const updatesPage = () => ({
++        agent: true, index: true, cache: PUBLIC_CACHE,
          title: `What shipped on ${SITE_NAME}`,
          description: 'Every change deployed to OpenVibe.Zone, newest first, from the OpenVibe network\'s shared update log.',
          body: raw(frame.updatesBody({ service: 'zone', siteName: SITE_NAME }) + `<script src="${ovServe.url('shipped.js')}" defer></script>`),
--    }));
++    });
++    r.get('/updates', (req, res) => page(req, res, updatesPage()));
++
++    // The public pages the agent layer's Markdown twins (server/agent-pages.js) render with the same builders.
++    r.publicViews = { home: homePage, docs: docsPage, updates: updatesPage };
  
      // ── Discovery: robots.txt, sitemap.xml, llms.txt, llms-full.txt ──
      r.use(createDiscoveryRoutes(ctx));
ddiff --git a/server/render/layout.js b/server/render/layout.js
iindex da06a05..c6f10b1 100644
---- a/server/render/layout.js
++++ b/server/render/layout.js
@@@ -84,6 +84,10 @@ function renderPage(o) {
          description: o.description || `${SITE_NAME} — ${TAGLINE}`,
          canonical,
          robots: o.index ? 'index, follow' : 'noindex, nofollow',
++        // A page with a Markdown twin (o.agent) advertises it in the head and the Link header; the twin itself
++        // is server/agent-pages.js.
++        agentLayer: o.agent === true,
++        llms: `${String(o.config.baseUrl).replace(/\/+$/, '')}/llms.txt`,
          jsonLd: (o.jsonLd || []).filter(Boolean),
          home: '/',
          navLinks: NAV,
@@@ -121,6 +125,10 @@ function send(res, status, o) {
      const personal = o.viewer && o.viewer.kind === 'user';
      if (!res.get('Cache-Control')) res.set('Cache-Control', !personal && o.cache ? o.cache : cache.htmlHeaders({ private: true }));
      res.set('Vary', 'Cookie');
++    if (o.agent) {
++        const site = String(o.config.baseUrl).replace(/\/+$/, '');
++        res.set('Link', require('openvibe-shared/agent-layer').linkHeaderTags(`${site}${String(o.path || '/').split('?')[0]}`, `${site}/llms.txt`).header);
++    }
      res.status(status).type('html').send(renderPage(o));
  }