✨ feat: enhance project setup and architecture documentation

- Updated `tibi-project-setup` skill to clarify project initialization goals and steps.
- Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms.
- Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions.
- Refined `AGENTS.md` to provide a structured roadmap for project development phases.
- Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning.
- Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`.
- Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`.
- Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.

esbuild.config.js

@@ -2,6 +2,36 @@ const fs = require("fs")
 const { execSync } = require("child_process")
 const postcssPlugin = require("esbuild-postcss")
 
+function upsertEnvVar(filePath, key, value) {
+    const nextLine = `${key}=${value}`
+    const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : ""
+    const lines = content ? content.split(/\r?\n/) : []
+    const nextLines = []
+    let replaced = false
+
+    for (const line of lines) {
+        if (!line || line.startsWith(`${key}=`)) {
+            if (line.startsWith(`${key}=`)) {
+                nextLines.push(nextLine)
+                replaced = true
+            } else {
+                nextLines.push(line)
+            }
+            continue
+        }
+        nextLines.push(line)
+    }
+
+    if (!replaced) {
+        if (nextLines.length && nextLines[nextLines.length - 1] !== "") {
+            nextLines.push("")
+        }
+        nextLines.push(nextLine)
+    }
+
+    fs.writeFileSync(filePath, `${nextLines.join("\n").replace(/\n*$/, "")}\n`)
+}
+
 // Resolve version at build time via git describe (tag + hash), fallback to env var or "dev"
 let gitHash = "dev"
 try {
@@ -15,16 +45,18 @@ function writeBuildInfo() {
     const info = {
         gitHash,
         buildTime: new Date().toISOString(),
+        assetVersion: `${gitHash}-${Date.now()}`,
     }
     fs.writeFileSync(
         __dirname + "/frontend/src/lib/buildInfo.ts",
-        `// AUTO-GENERATED by esbuild.config.js \u2013 do not edit\nexport const gitHash = ${JSON.stringify(info.gitHash)}\nexport const buildTime = ${JSON.stringify(info.buildTime)}\n`
+        `// AUTO-GENERATED by esbuild.config.js \u2013 do not edit\nexport const gitHash = ${JSON.stringify(info.gitHash)}\nexport const buildTime = ${JSON.stringify(info.buildTime)}\nexport const assetVersion = ${JSON.stringify(info.assetVersion)}\n`
     )
     // Write same buildInfo for backend hooks (X-Build-Time / X-Release headers)
     fs.writeFileSync(
         __dirname + "/api/hooks/lib/buildInfo.js",
-        `// AUTO-GENERATED by esbuild.config.js \u2013 do not edit\nmodule.exports = { gitHash: ${JSON.stringify(info.gitHash)}, buildTime: ${JSON.stringify(info.buildTime)} }\n`
+        `// AUTO-GENERATED by esbuild.config.js \u2013 do not edit\nmodule.exports = { gitHash: ${JSON.stringify(info.gitHash)}, buildTime: ${JSON.stringify(info.buildTime)}, assetVersion: ${JSON.stringify(info.assetVersion)} }\n`
     )
+    upsertEnvVar(__dirname + "/api/config.yml.env", "ADMIN_ASSET_VERSION", info.assetVersion)
 }
 // NOTE: writeBuildInfo() is NOT called here at top-level.
 // It is called by esbuild-wrapper.js before each build.