docs(sw): Popup guidance, example comments, package README and link check

packages/sw/tests/ai-docs.check.mjs

@@ -48,6 +48,10 @@ for (const doc of [...docs.map(name => path.join("ai", name)), "README.md"]) {
   const links = [...text.matchAll(/\]\((\.\/[^)#\s]+)/g)].map(match => match[1])
   const broken = links.filter(link => !existsSync(path.resolve(root, path.dirname(doc), link)))
   check(`${doc}: package-relative links resolve`, broken.length === 0, { links: links.length, broken })
+  // Any other relative link (e.g. ../../docs/...) points outside the published package and breaks once installed.
+  const relative = [...text.matchAll(/\]\(([^)\s]+)\)/g)].map(match => match[1]).filter(link => !/^(?:[a-z][a-z0-9+.-]*:|#|\/|\.\/)/i.test(link))
+  const outside = relative.filter(link => path.relative(root, path.resolve(root, path.dirname(doc), link.split("#")[0])).startsWith(".."))
+  check(`${doc}: no links outside the package`, outside.length === 0, { links: relative.length, outside })
 }
 console.log(`${results.filter(Boolean).length}/${results.length} PASS`)
 process.exitCode = results.every(Boolean) ? 0 : 1