Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(growth): enrich standalone mirrors with docs, llms.txt, AGENTS.md and Pages, and publish the MCP server card at /.well-known/mcp/server-card.json

nirholasacc753227aa6
diff --git a/public/.well-known/mcp/server-card.json b/public/.well-known/mcp/server-card.json
new file mode 100644
index 000000000..6377d2002
--- /dev/null
+++ b/public/.well-known/mcp/server-card.json
@@ -0,0 +1,20 @@
+{
+ "$schema": "https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json",
+ "serverInfo": {
+ "name": "three.ws",
+ "title": "three.ws",
+ "version": "1.0.0"
+ },
+ "description": "The 3D agent economy: generate, rig, and animate 3D avatars and worlds; pay and get paid per call with x402 (USDC on Solana and Base); read live crypto market and on-chain intelligence.",
+ "websiteUrl": "https://three.ws",
+ "documentationUrl": "https://three.ws/docs/mcp",
+ "transport": {
+ "type": "streamable-http",
+ "url": "https://three.ws/api/mcp"
+ },
+ "authentication": {
+ "required": true,
+ "schemes": ["oauth2.1", "api-key", "x402"]
+ },
+ "directory": "https://three.ws/.well-known/mcp.json"
+}
diff --git a/scripts/export-standalone-repos.mjs b/scripts/export-standalone-repos.mjs
index af9a22ff7..76abda055 100644
--- a/scripts/export-standalone-repos.mjs
+++ b/scripts/export-standalone-repos.mjs
@@ -7,13 +7,17 @@
// node scripts/export-standalone-repos.mjs --target glb-tools one repo
// node scripts/export-standalone-repos.mjs --publish also create/push/configure on GitHub
//
-// The monorepo stays the source of truth: the export is one-way and a rebuild
-// overwrites the repository's main branch with the regenerated tree. Config is
+// The monorepo stays the source of truth. A repository that does not exist yet
+// is created from the regenerated tree. A repository that already has history is
+// never force-pushed: the export is cloned, the generated discovery files are
+// added on top as one ordinary commit (existing files such as the README are
+// kept), and the push must fast-forward. Config is
// data/standalone-repos.json. --publish reads the token from GITHUB_TOKEN or the
// file named by GITHUB_TOKEN_FILE; the token is passed per command and never
// written to a remote URL or git config.
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
import { execFileSync } from 'node:child_process';
import { dirname, join, posix, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -39,7 +43,7 @@ function meta(target) {
slug,
repoUrl: `https://github.com/${slug}`,
pagesUrl: `https://${config.owner}.github.io/${target.repo}/`,
- topics: [...new Set([...target.topics, ...config.baseTopics, ...(pkg.keywords || []).map((k) => String(k).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''))])].filter(topicOk).slice(0, 20),
+ topics: [...new Set([...target.topics, ...config.baseTopics, ...(Object.keys(pkg.dependencies || {}).length ? [] : ['zero-dependencies']), ...(pkg.keywords || []).map((k) => String(k).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, ''))])].filter(topicOk).slice(0, 20),
};
}
@@ -362,14 +366,38 @@ async function publish(target, m, dest, tok) {
if (made.status !== 201) throw new Error(`create ${m.slug} failed: ${made.status} ${made.json?.message}`);
} else if (exists.status !== 200) throw new Error(`lookup ${m.slug} failed: ${exists.status}`);
- const git = (args) => execFileSync('git', args, { cwd: dest, stdio: 'pipe' }).toString();
- rmSync(join(dest, '.git'), { recursive: true, force: true });
- git(['init', '-b', 'main']);
- git(['add', '--all']);
- git(['-c', 'user.name=three.ws release builder', '-c', '[email protected]', 'commit', '-m', `feat: publish ${m.pkg.name} ${m.pkg.version} as a standalone repository with docs site and agent discovery files`]);
- git(['remote', 'add', 'origin', `${m.repoUrl}.git`]);
const auth = `Authorization: Basic ${Buffer.from(`x-access-token:${tok}`).toString('base64')}`;
- git(['-c', `http.extraheader=${auth}`, 'push', '--force', '-u', 'origin', 'main']);
+ const identity = ['-c', 'user.name=three.ws release builder', '-c', '[email protected]'];
+ const hasHistory = exists.status === 200 && (await gh('GET', `/repos/${m.slug}/commits?per_page=1`, null, tok)).status === 200;
+ let mode = 'created';
+ if (!hasHistory) {
+ const git = (args) => execFileSync('git', args, { cwd: dest, stdio: 'pipe' }).toString();
+ rmSync(join(dest, '.git'), { recursive: true, force: true });
+ git(['init', '-b', 'main']);
+ git(['add', '--all']);
+ git([...identity, 'commit', '-m', `feat: publish ${m.pkg.name} ${m.pkg.version} as a standalone repository with docs site and agent discovery files`]);
+ git(['remote', 'add', 'origin', `${m.repoUrl}.git`]);
+ git(['-c', `http.extraheader=${auth}`, 'push', '-u', 'origin', 'main']);
+ } else {
+ const work = mkdtempSync(join(tmpdir(), 'standalone-'));
+ try {
+ const git = (args) => execFileSync('git', args, { cwd: work, stdio: 'pipe' }).toString();
+ execFileSync('git', ['-c', `http.extraheader=${auth}`, 'clone', '--depth', '1', `${m.repoUrl}.git`, work], { stdio: 'pipe' });
+ // Add-only: files the repository already has (README, AGENTS.md, src) are kept.
+ // The docs site is regenerated whole because it is a build product.
+ rmSync(join(work, 'docs', 'index.html'), { force: true });
+ cpSync(dest, work, { recursive: true, force: false, errorOnExist: false, filter: (p) => !p.endsWith('/.git') });
+ for (const f of readdirSync(join(dest, 'docs'))) cpSync(join(dest, 'docs', f), join(work, 'docs', f), { recursive: true, force: true });
+ git(['add', '--all']);
+ if (git(['status', '--porcelain']).trim()) {
+ git([...identity, 'commit', '-m', `docs: add docs site, llms.txt, security policy, citation and issue templates for ${m.pkg.name} discovery`]);
+ git(['-c', `http.extraheader=${auth}`, 'push', 'origin', 'HEAD']);
+ mode = 'overlay';
+ } else mode = 'unchanged';
+ } finally {
+ rmSync(work, { recursive: true, force: true });
+ }
+ }
await gh('PATCH', `/repos/${m.slug}`, { description: String(m.pkg.description).slice(0, 350), homepage: m.pagesUrl, has_discussions: true }, tok);
const topics = await gh('PUT', `/repos/${m.slug}/topics`, { names: m.topics }, tok);
@@ -377,19 +405,61 @@ async function publish(target, m, dest, tok) {
for (const [name, color, description] of [['good first issue', '7057ff', 'Good for newcomers'], ['help wanted', '008672', 'Extra attention is needed']]) {
await gh('POST', `/repos/${m.slug}/labels`, { name, color, description }, tok);
}
- return { topics: topics.status, pages: pages.status === 409 ? 'already enabled' : pages.status };
+ return { mode, topics: topics.status, pages: pages.status === 409 ? 'already enabled' : pages.status };
+}
+
+function topicsFor(pkg, dir) {
+ const t = new Set();
+ const text = `${pkg.name} ${pkg.description || ''}`.toLowerCase();
+ if (pkg.mcpName || /mcp/.test(pkg.name)) ['mcp', 'mcp-server', 'model-context-protocol', 'claude'].forEach((x) => t.add(x));
+ if (pkg.bin) t.add('cli');
+ if (/solana/.test(text)) t.add('solana');
+ if (/x402/.test(text)) ['x402', 'payments'].forEach((x) => t.add(x));
+ if (/glb|gltf|3d|avatar|three\.js|webgl|mesh/.test(text)) ['3d', 'gltf', 'webgl'].forEach((x) => t.add(x));
+ if (/agent/.test(text)) ['ai-agents', 'llm-tools'].forEach((x) => t.add(x));
+ return [...t].filter(topicOk);
+}
+
+function autoTargets() {
+ const auto = config.auto;
+ if (!auto) return [];
+ const listed = new Set(config.targets.map((t) => t.source));
+ const out = [];
+ for (const root of auto.roots) {
+ const dirs = root.endsWith('/*') ? readdirSync(join(REPO, root.slice(0, -2))).map((d) => `${root.slice(0, -2)}/${d}`) : [root];
+ for (const source of dirs) {
+ const pj = join(REPO, source, 'package.json');
+ if (!existsSync(pj) || listed.has(source)) continue;
+ const pkg = JSON.parse(readFileSync(pj, 'utf8'));
+ if (pkg.private || !existsSync(join(REPO, source, 'README.md'))) continue;
+ const dir = source.split('/').pop();
+ const repo = auto.rename?.[source] || (dir.includes('-') ? dir : `three-ws-${dir}`);
+ const hold = auto.hold?.[source];
+ out.push({ repo, source, topics: topicsFor(pkg, dir), ...(hold ? { hold } : {}) });
+ }
+ }
+ return out;
}
+config.targets = [...config.targets, ...autoTargets()];
+
const targets = config.targets.filter((t) => (value('--target') ? t.repo === value('--target') : !t.hold));
if (!targets.length) throw new Error(`unknown target: ${value('--target')}`);
mkdirSync(OUT, { recursive: true });
const tok = flag('--publish') ? token() : null;
const report = [];
for (const target of targets) {
- const { m, dest } = await buildTree(target);
- if (!flag('--skip-tests')) verify(target, dest);
- const row = { repo: m.slug, version: m.pkg.version, topics: m.topics.length, files: readdirSync(dest).length, site: m.pagesUrl };
- if (tok) Object.assign(row, await publish(target, m, dest, tok));
- report.push(row);
+ try {
+ const { m, dest } = await buildTree(target);
+ if (!flag('--skip-tests')) verify(target, dest);
+ const row = { repo: m.slug, version: m.pkg.version, topics: m.topics.length, files: readdirSync(dest).length, site: m.pagesUrl };
+ if (tok) Object.assign(row, await publish(target, m, dest, tok));
+ report.push(row);
+ } catch (err) {
+ const secrets = tok ? [tok, Buffer.from(`x-access-token:${tok}`).toString('base64')] : [];
+ const detail = [String(err.message).split('\n')[0], err.stderr ? String(err.stderr).trim().split('\n').pop() : ''].filter(Boolean).join(' | ');
+ report.push({ repo: `${config.owner}/${target.repo}`, error: secrets.reduce((text, secret) => text.split(secret).join('***'), detail).slice(0, 300) });
+ }
}
console.table(report);
+if (report.some((r) => r.error)) process.exitCode = 1;
diff --git a/scripts/lib/standalone-enrich.mjs b/scripts/lib/standalone-enrich.mjs
new file mode 100644
index 000000000..5f82a7bc7
--- /dev/null
+++ b/scripts/lib/standalone-enrich.mjs
@@ -0,0 +1,497 @@
+// Discovery layer for the standalone package mirrors (scripts/sync-standalone-repos.mjs).
+//
+// A bare snapshot of a package dir is a repo nobody finds. This module adds what
+// makes a repo findable and trustworthy to both humans and agents, entirely from
+// facts already in the package (package.json, server.json, README.md):
+//
+// - community health files (CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, CITATION.cff,
+// issue + PR templates)
+// - agent discovery files (AGENTS.md, llms.txt, llms-full.txt, glama.json)
+// - a static docs site under docs/ (the README rendered, with OG/Twitter tags,
+// JSON-LD, sitemap.xml, robots.txt, 404.html) served by GitHub Pages from main:/docs
+// - repository settings applied over the API (topics, description, homepage, Pages)
+//
+// Every file is generated, never hand-edited in the mirror. A file the package
+// already ships is kept, so a package can override any of them in the monorepo.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { marked } from 'marked';
+
+const OWNER_HANDLE = 'nirholas';
+const SITE = 'https://three.ws';
+
+const esc = (s) =>
+ String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+function put(dir, rel, body, { overwrite = false } = {}) {
+ const path = join(dir, rel);
+ if (!overwrite && existsSync(path)) return false;
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, body.endsWith('\n') ? body : body + '\n');
+ return true;
+}
+
+export function pagesUrl(slug) {
+ const [owner, repo] = slug.split('/');
+ return `https://${owner.toLowerCase()}.github.io/${repo}/`;
+}
+
+/** GitHub topics: lowercase, [a-z0-9-], <=50 chars, <=20 total, most specific first. */
+export function topicsFor(pkg, kind) {
+ const base = kind === 'mcp'
+ ? ['mcp', 'model-context-protocol', 'mcp-server', 'ai-agents']
+ : ['ai-agents', 'sdk'];
+ const raw = [...(pkg.keywords || []), ...base, 'three-ws', 'threejs', 'nodejs'];
+ const out = [];
+ for (const k of raw) {
+ const t = String(k).toLowerCase().replace(/\./g, '-').replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50);
+ if (t && !/^\d+$/.test(t) && !out.includes(t)) out.push(t);
+ }
+ return out.slice(0, 20);
+}
+
+function installCommand(pkg) {
+ return pkg.bin ? `npx -y ${pkg.name}` : `npm install ${pkg.name}`;
+}
+
+function agentsMd(pkg, slug, kind) {
+ const scripts = Object.entries(pkg.scripts || {}).map(([k, v]) => `- \`npm run ${k}\`: \`${v}\``).join('\n');
+ const what = kind === 'mcp'
+ ? 'A Model Context Protocol server. Run it over stdio from any MCP client.'
+ : 'A JavaScript library. Import it from ESM.';
+ return `# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+\`${pkg.name}\` v${pkg.version}. ${pkg.description || ''}
+
+${what}
+
+## Use it
+
+\`\`\`bash
+${installCommand(pkg)}
+\`\`\`
+
+Full usage, tool list and configuration are in [README.md](README.md). Machine-readable summaries: [llms.txt](llms.txt) and [llms-full.txt](llms-full.txt).
+
+## Develop
+
+\`\`\`bash
+npm install
+${pkg.scripts?.test ? 'npm test' : 'node --check src/index.js'}
+\`\`\`
+
+${scripts ? `Scripts:\n${scripts}\n` : ''}
+## Conventions
+
+- ES modules, Node ${pkg.engines?.node || '>=20'}.
+- Read-only by default. Anything that signs, spends or sends must be an explicit, separately named tool or option, and must never be inferred from untrusted text (token names, memos, listings).
+- Never commit credentials. Configuration comes from environment variables documented in the README.
+- Keep changes small and covered by a test next to the code they change.
+
+## Source of truth
+
+This repository is a generated mirror of \`${pkg.repository?.directory || 'packages'}\` in https://github.com/${OWNER_HANDLE}/three.ws. Open issues here; send substantial changes as a pull request here or upstream.
+`;
+}
+
+function llmsTxt(pkg, slug, kind, site) {
+ return `# ${pkg.name}
+
+> ${pkg.description || pkg.name}
+
+${pkg.name} is ${kind === 'mcp' ? 'a Model Context Protocol server' : 'a JavaScript library'} from three.ws. Install: \`${installCommand(pkg)}\`.
+
+## Docs
+
+- [README](https://github.com/${slug}/blob/main/README.md): install, configuration, full reference
+- [Documentation site](${site}): the README as a web page
+- [Full text for LLMs](${site}llms-full.txt): README inlined
+- [AGENTS.md](https://github.com/${slug}/blob/main/AGENTS.md): guidance for coding agents
+
+## Project
+
+- [Source](https://github.com/${slug})
+- [npm](https://www.npmjs.com/package/${pkg.name})
+- [three.ws](${SITE}): the platform this is part of
+- [Issues](https://github.com/${slug}/issues)
+${kind === 'mcp' ? `- [MCP Registry](https://registry.modelcontextprotocol.io/?q=${encodeURIComponent(pkg.mcpName || pkg.name)})\n` : ''}`;
+}
+
+function contributing(pkg, slug) {
+ return `# Contributing to ${pkg.name}
+
+Thanks for helping. Small, focused changes land fastest.
+
+## Ways to contribute
+
+- **Report a bug** with the [bug form](https://github.com/${slug}/issues/new?template=bug.yml). Include the version, your Node version and the smallest reproduction you can.
+- **Propose a feature** with the [feature form](https://github.com/${slug}/issues/new?template=feature.yml). Describe the problem first, then the change.
+- **Fix something** with a pull request. Run the tests before you open it.
+
+## Local setup
+
+\`\`\`bash
+git clone https://github.com/${slug}.git
+cd ${slug.split('/')[1]}
+npm install
+${pkg.scripts?.test ? 'npm test' : 'node --check src/index.js'}
+\`\`\`
+
+## Pull requests
+
+- One change per pull request, with a test where the change is testable.
+- Describe what changed and why in plain language.
+- Do not add dependencies for something a few lines of code can do.
+- Security-sensitive reports go through [SECURITY.md](SECURITY.md), not a public issue.
+
+By contributing you agree that your work is licensed under ${pkg.license || 'Apache-2.0'}, the license of this project.
+`;
+}
+
+function security(pkg, slug) {
+ return `# Security Policy
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability.
+
+Use GitHub's private reporting: https://github.com/${slug}/security/advisories/new
+
+You will get an acknowledgement within 3 business days and a status update within 10. Fixes ship as a patch release of \`${pkg.name}\` with credit to the reporter unless you prefer otherwise.
+
+## Scope
+
+In scope: this package's code, its published npm artifact, and its documented configuration. Out of scope: third-party services it talks to, and findings that need a compromised machine or a leaked key.
+
+## Supported versions
+
+The latest published minor version of \`${pkg.name}\` receives fixes.
+`;
+}
+
+function codeOfConduct() {
+ return `# Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful, assume good faith, keep feedback about the work, and do not harass anyone. Maintainers may remove comments, commits or contributions that break these rules and may block repeat offenders.
+
+Report conduct concerns privately to [email protected]. Reports are handled in confidence.
+`;
+}
+
+function citation(pkg, slug) {
+ return `cff-version: 1.2.0
+message: If you use this software, please cite it as below.
+title: "${String(pkg.name).replace(/"/g, '')}"
+abstract: "${String(pkg.description || '').replace(/"/g, "'").replace(/\n/g, ' ')}"
+version: ${pkg.version}
+license: ${pkg.license || 'Apache-2.0'}
+repository-code: "https://github.com/${slug}"
+url: "${SITE}"
+authors:
+ - name: three.ws
+ website: "${SITE}"
+`;
+}
+
+const BUG_FORM = (pkg) => `name: Bug report
+description: Something does not work as documented
+labels: [bug]
+body:
+ - type: input
+ id: version
+ attributes:
+ label: ${pkg.name} version
+ placeholder: ${pkg.version}
+ validations:
+ required: true
+ - type: input
+ id: node
+ attributes:
+ label: Node version and OS
+ placeholder: Node 22, macOS 15
+ - type: textarea
+ id: what
+ attributes:
+ label: What happened, and what did you expect?
+ validations:
+ required: true
+ - type: textarea
+ id: repro
+ attributes:
+ label: Smallest reproduction
+ render: shell
+`;
+
+const FEATURE_FORM = `name: Feature request
+description: Suggest a change or addition
+labels: [enhancement]
+body:
+ - type: textarea
+ id: problem
+ attributes:
+ label: What problem are you trying to solve?
+ validations:
+ required: true
+ - type: textarea
+ id: proposal
+ attributes:
+ label: What would you like to see?
+`;
+
+const ISSUE_CONFIG = (slug) => `blank_issues_enabled: false
+contact_links:
+ - name: three.ws platform support
+ url: ${SITE}
+ about: Questions about the hosted platform rather than this package.
+ - name: Security report
+ url: https://github.com/${slug}/security/advisories/new
+ about: Report a vulnerability privately.
+`;
+
+const PR_TEMPLATE = `## What changed and why
+
+## How it was checked
+
+- [ ] Tests pass locally
+- [ ] Docs updated where behavior changed
+`;
+
+/** Rewrite README-relative links so they resolve on the docs site. */
+function absolutizeLinks(md, slug) {
+ const blob = `https://github.com/${slug}/blob/main/`;
+ const raw = `https://raw.githubusercontent.com/${slug}/main/`;
+ return md
+ .replace(/(!\[[^\]]*\]\()(?!https?:|#|\/\/|data:)\.?\/?([^)\s]+)/g, `$1${raw}$2`)
+ .replace(/(\[[^\]]*\]\()(?!https?:|#|\/\/|mailto:|data:)\.?\/?([^)\s]+)/g, `$1${blob}$2`)
+ .replace(/(src=")(?!https?:|\/\/|data:)\.?\/?([^"]+)/g, `$1${raw}$2`)
+ .replace(/(href=")(?!https?:|#|\/\/|mailto:)\.?\/?([^"]+)/g, `$1${blob}$2`);
+}
+
+function slugify(text) {
+ return text.toLowerCase().replace(/<[^>]+>/g, '').replace(/&[a-z]+;/g, '').replace(/[^a-z0-9\s-]/g, '').trim().replace(/\s+/g, '-');
+}
+
+function renderBody(md, slug) {
+ let html = marked.parse(absolutizeLinks(md, slug), { gfm: true });
+ const seen = new Set();
+ html = html.replace(/<h([2-4])>([\s\S]*?)<\/h\1>/g, (_, lvl, inner) => {
+ let id = slugify(inner) || 'section';
+ for (let n = 2; seen.has(id); n++) id = `${slugify(inner)}-${n}`;
+ seen.add(id);
+ return `<h${lvl} id="${id}"><a class="anchor" href="#${id}" aria-label="Link to this section">#</a>${inner}</h${lvl}>`;
+ });
+ return html;
+}
+
+function tocFrom(html) {
+ const items = [...html.matchAll(/<h2 id="([^"]+)">[\s\S]*?<\/a>([\s\S]*?)<\/h2>/g)];
+ if (items.length < 3) return '';
+ return `<nav class="toc" aria-label="On this page"><p>On this page</p><ul>${items
+ .map(([, id, label]) => `<li><a href="#${id}">${label.replace(/<[^>]+>/g, '')}</a></li>`)
+ .join('')}</ul></nav>`;
+}
+
+const SITE_CSS = `:root{--bg:#fff;--fg:#111418;--mut:#586069;--line:#e3e6ea;--acc:#2563eb;--code:#f4f6f8;--card:#fafbfc}
+@media(prefers-color-scheme:dark){:root{--bg:#0b0d10;--fg:#e8eaed;--mut:#9aa3ad;--line:#232830;--acc:#6ea0ff;--code:#14181d;--card:#10141a}}
+*{box-sizing:border-box}html{scroll-behavior:smooth}
+body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.65 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
+a{color:var(--acc)}a:focus-visible,button:focus-visible{outline:2px solid var(--acc);outline-offset:2px;border-radius:4px}
+header.bar{position:sticky;top:0;z-index:5;background:color-mix(in srgb,var(--bg) 88%,transparent);backdrop-filter:blur(10px);border-bottom:1px solid var(--line)}
+.bar-in{max-width:1100px;margin:0 auto;padding:12px 16px;display:flex;align-items:center;gap:16px;flex-wrap:wrap}
+.brand{font-weight:700;text-decoration:none;color:var(--fg)}
+.bar nav{margin-left:auto;display:flex;gap:16px;font-size:14px}
+.bar nav a{color:var(--mut);text-decoration:none;transition:color .15s}.bar nav a:hover{color:var(--fg)}
+.hero{max-width:1100px;margin:0 auto;padding:48px 16px 24px}
+.hero h1{font-size:clamp(28px,5vw,44px);line-height:1.15;margin:0 0 12px;letter-spacing:-.02em}
+.hero p{color:var(--mut);max-width:70ch;font-size:18px;margin:0 0 24px}
+.install{display:flex;align-items:center;gap:8px;max-width:620px;background:var(--code);border:1px solid var(--line);border-radius:10px;padding:6px 6px 6px 14px}
+.install code{flex:1;overflow-x:auto;white-space:nowrap;font:14px ui-monospace,SFMono-Regular,Menlo,monospace}
+.install button{border:0;background:var(--acc);color:#fff;border-radius:7px;padding:8px 14px;font:600 13px system-ui;cursor:pointer;transition:transform .12s,opacity .12s}
+.install button:hover{opacity:.9}.install button:active{transform:scale(.96)}
+.cta{display:flex;gap:10px;margin-top:16px;flex-wrap:wrap}
+.cta a{padding:9px 16px;border:1px solid var(--line);border-radius:8px;text-decoration:none;font-weight:600;font-size:14px;color:var(--fg);transition:border-color .15s,transform .15s}
+.cta a:hover{border-color:var(--acc);transform:translateY(-1px)}.cta a.pri{background:var(--fg);color:var(--bg);border-color:var(--fg)}
+.layout{max-width:1100px;margin:0 auto;padding:8px 16px 64px;display:grid;grid-template-columns:minmax(0,1fr) 220px;gap:40px}
+@media(max-width:860px){.layout{grid-template-columns:minmax(0,1fr)}.toc{display:none}}
+.toc{position:sticky;top:76px;align-self:start;font-size:14px;border-left:1px solid var(--line);padding-left:16px}
+.toc p{margin:0 0 8px;font-weight:700;color:var(--mut);text-transform:uppercase;font-size:12px;letter-spacing:.06em}
+.toc ul{list-style:none;margin:0;padding:0}.toc li{margin:6px 0}.toc a{color:var(--mut);text-decoration:none}.toc a:hover{color:var(--fg)}
+main{min-width:0;overflow-wrap:anywhere}main pre code{overflow-wrap:normal}main img{max-width:100%;height:auto}
+main h2{margin-top:2.2em;padding-bottom:.3em;border-bottom:1px solid var(--line)}
+.anchor{margin-left:-1.1em;padding-right:.4em;text-decoration:none;opacity:0;color:var(--mut)}h2:hover .anchor,h3:hover .anchor,h4:hover .anchor{opacity:1}
+pre{background:var(--code);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow-x:auto;font-size:14px;line-height:1.5}
+code{font:0.9em ui-monospace,SFMono-Regular,Menlo,monospace;background:var(--code);padding:.15em .35em;border-radius:5px}pre code{background:none;padding:0}
+table{border-collapse:collapse;display:block;overflow-x:auto;max-width:100%}th,td{border:1px solid var(--line);padding:8px 12px;text-align:left}th{background:var(--card)}
+blockquote{margin:1em 0;padding:.2em 1em;border-left:4px solid var(--line);color:var(--mut)}
+footer{border-top:1px solid var(--line);color:var(--mut);font-size:14px}
+.foot-in{max-width:1100px;margin:0 auto;padding:24px 16px;display:flex;gap:16px;flex-wrap:wrap}
+@media(prefers-reduced-motion:reduce){*{transition:none!important;scroll-behavior:auto!important}}`;
+
+const SITE_JS = `document.querySelectorAll('[data-copy]').forEach(function(b){b.addEventListener('click',function(){
+var t=b.getAttribute('data-copy');var done=function(){var o=b.textContent;b.textContent='Copied';setTimeout(function(){b.textContent=o},1400)};
+if(navigator.clipboard&&navigator.clipboard.writeText){navigator.clipboard.writeText(t).then(done,function(){})}
+else{var a=document.createElement('textarea');a.value=t;document.body.appendChild(a);a.select();try{document.execCommand('copy');done()}catch(e){}a.remove()}})});`;
+
+/** Trim to `max` characters at a sentence end, else a word boundary, never mid-word. */
+function clampText(text, max) {
+ const flat = String(text).replace(/\s+/g, ' ').trim();
+ if (flat.length <= max) return flat;
+ const cut = flat.slice(0, max);
+ const sentence = cut.match(/^[\s\S]*[.!?](?=\s)/);
+ if (sentence && sentence[0].length > max * 0.4) return sentence[0];
+ return cut.replace(/\s+\S*$/, '').replace(/[,;:\s]+$/, '') + '...';
+}
+
+function siteIndex(pkg, slug, kind, readme, site) {
+ const body = renderBody(readme.replace(/^\s*(?:<p[^>]*>[\s\S]*?<\/p>\s*)?<h1[\s\S]*?<\/h1>/i, ''), slug);
+ const lead = (pkg.description || '').split(/\s[\u2014\u2013-]\s|[.:]\s/)[0].slice(0, 70);
+ const title = lead ? `${pkg.name}: ${lead}` : pkg.name;
+ const desc = clampText(pkg.description || pkg.name, 300);
+ const cmd = installCommand(pkg);
+ const ld = {
+ '@context': 'https://schema.org',
+ '@type': 'SoftwareSourceCode',
+ name: pkg.name,
+ description: desc,
+ codeRepository: `https://github.com/${slug}`,
+ programmingLanguage: 'JavaScript',
+ license: `https://spdx.org/licenses/${pkg.license || 'Apache-2.0'}.html`,
+ version: pkg.version,
+ url: site,
+ author: { '@type': 'Organization', name: 'three.ws', url: SITE },
+ keywords: (pkg.keywords || []).join(', '),
+ };
+ return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${esc(title)}</title>
+<meta name="description" content="${esc(desc)}">
+<link rel="canonical" href="${site}">
+<meta property="og:type" content="website">
+<meta property="og:site_name" content="three.ws">
+<meta property="og:title" content="${esc(pkg.name)}">
+<meta property="og:description" content="${esc(desc)}">
+<meta property="og:url" content="${site}">
+<meta property="og:image" content="https://opengraph.githubassets.com/1/${slug}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="${esc(pkg.name)}">
+<meta name="twitter:description" content="${esc(desc)}">
+<meta name="twitter:image" content="https://opengraph.githubassets.com/1/${slug}">
+<meta name="keywords" content="${esc((pkg.keywords || []).join(', '))}">
+<link rel="alternate" type="text/plain" href="llms.txt" title="llms.txt">
+<link rel="icon" href="${SITE}/three-ws-mcp-icon.svg" type="image/svg+xml">
+<script type="application/ld+json">${JSON.stringify(ld)}</script>
+<style>${SITE_CSS}</style>
+</head>
+<body>
+<header class="bar"><div class="bar-in">
+<a class="brand" href="${site}">${esc(pkg.name)}</a>
+<nav aria-label="Project links"><a href="https://github.com/${slug}">GitHub</a><a href="https://www.npmjs.com/package/${esc(pkg.name)}">npm</a><a href="llms.txt">llms.txt</a><a href="${SITE}">three.ws</a></nav>
+</div></header>
+<section class="hero">
+<h1>${esc(pkg.name)}</h1>
+<p>${esc(desc)}</p>
+<div class="install" role="group" aria-label="Install command"><code>${esc(cmd)}</code><button type="button" data-copy="${esc(cmd)}">Copy</button></div>
+<div class="cta"><a class="pri" href="https://github.com/${slug}">View on GitHub</a><a href="https://github.com/${slug}/stargazers">Star the repo</a>${kind === 'mcp' ? `<a href="https://registry.modelcontextprotocol.io/?q=${encodeURIComponent(pkg.mcpName || pkg.name)}">MCP Registry</a>` : ''}</div>
+</section>
+<div class="layout">
+<main id="content">${body}</main>
+${tocFrom(body)}
+</div>
+<footer><div class="foot-in"><span>${esc(pkg.license || 'Apache-2.0')} licensed</span><a href="https://github.com/${slug}/issues">Issues</a><a href="https://github.com/${slug}/blob/main/CONTRIBUTING.md">Contributing</a><a href="https://github.com/${slug}/security/policy">Security</a><a href="${SITE}">Part of three.ws</a></div></footer>
+<script>${SITE_JS}</script>
+</body>
+</html>
+`;
+}
+
+function notFound(pkg, site) {
+ return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Page not found - ${esc(pkg.name)}</title><meta name="robots" content="noindex"><style>${SITE_CSS}</style></head><body><section class="hero"><h1>Page not found</h1><p>That page does not exist. The documentation for ${esc(pkg.name)} is on the home page.</p><div class="cta"><a class="pri" href="${site}">Go to the docs</a></div></section></body></html>
+`;
+}
+
+/** Write every discovery file into the mirror working tree. Returns the list written. */
+export function enrichMirror(workDir, { pkg, slug, kind }) {
+ const site = pagesUrl(slug);
+ const written = [];
+ const w = (rel, body, opts) => { if (put(workDir, rel, body, opts)) written.push(rel); };
+
+ w('AGENTS.md', agentsMd(pkg, slug, kind));
+ w('CONTRIBUTING.md', contributing(pkg, slug));
+ w('SECURITY.md', security(pkg, slug));
+ w('CODE_OF_CONDUCT.md', codeOfConduct());
+ w('CITATION.cff', citation(pkg, slug));
+ w('.github/ISSUE_TEMPLATE/bug.yml', BUG_FORM(pkg));
+ w('.github/ISSUE_TEMPLATE/feature.yml', FEATURE_FORM);
+ w('.github/ISSUE_TEMPLATE/config.yml', ISSUE_CONFIG(slug));
+ w('.github/PULL_REQUEST_TEMPLATE.md', PR_TEMPLATE);
+ if (kind === 'mcp') {
+ w('glama.json', JSON.stringify({ $schema: 'https://glama.ai/mcp/schemas/server.json', maintainers: [OWNER_HANDLE] }, null, '\t'));
+ }
+
+ const readmePath = join(workDir, 'README.md');
+ const readme = existsSync(readmePath) ? readFileSync(readmePath, 'utf8') : `# ${pkg.name}\n\n${pkg.description || ''}\n`;
+ w('llms.txt', llmsTxt(pkg, slug, kind, site));
+ w('llms-full.txt', `${llmsTxt(pkg, slug, kind, site)}\n---\n\n${readme}`);
+
+ w('docs/index.html', siteIndex(pkg, slug, kind, readme, site), { overwrite: true });
+ w('docs/404.html', notFound(pkg, site), { overwrite: true });
+ w('docs/llms.txt', llmsTxt(pkg, slug, kind, site), { overwrite: true });
+ w('docs/llms-full.txt', `${llmsTxt(pkg, slug, kind, site)}\n---\n\n${readme}`, { overwrite: true });
+ w('docs/robots.txt', `User-agent: *\nAllow: /\n\nSitemap: ${site}sitemap.xml\n`, { overwrite: true });
+ const today = new Date().toISOString().slice(0, 10);
+ w('docs/sitemap.xml', `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>${site}</loc><lastmod>${today}</lastmod></url></urlset>`, { overwrite: true });
+ w('docs/.nojekyll', '', { overwrite: true });
+ return written;
+}
+
+/** Make package.json discoverable: keywords, homepage, bugs. Preserves everything else. */
+export function enrichPackageJson(workDir, { slug, kind }) {
+ const path = join(workDir, 'package.json');
+ if (!existsSync(path)) return;
+ const pkg = JSON.parse(readFileSync(path, 'utf8'));
+ const kw = new Set((pkg.keywords || []).map(String));
+ for (const k of kind === 'mcp' ? ['mcp', 'model-context-protocol', 'mcp-server', 'ai-agents'] : ['ai-agents']) kw.add(k);
+ kw.add('three.ws');
+ pkg.keywords = [...kw];
+ pkg.homepage = pagesUrl(slug);
+ pkg.bugs = { url: `https://github.com/${slug}/issues` };
+ writeFileSync(path, JSON.stringify(pkg, null, '\t') + '\n');
+}
+
+/**
+ * Apply repository settings over the API using the supplied `gh` runner:
+ * topics, description, homepage, issues, discussions and GitHub Pages from main:/docs.
+ */
+export function applyRepoSettings(gh, { pkg, slug, kind }) {
+ const site = pagesUrl(slug);
+ const steps = [];
+ const attempt = (label, fn) => {
+ try { fn(); steps.push(`${label}: ok`); } catch (e) { steps.push(`${label}: ${String(e.message).split('\n')[0].slice(0, 120)}`); }
+ };
+ attempt('settings', () => gh(['api', '-X', 'PATCH', `repos/${slug}`,
+ '-f', `description=${(pkg.description || '').replace(/\s+/g, ' ').slice(0, 350)}`,
+ '-f', `homepage=${site}`, '-F', 'has_issues=true', '-F', 'has_discussions=true', '-F', 'has_wiki=false']));
+ attempt('topics', () => gh(['api', '-X', 'PUT', `repos/${slug}/topics`, '--input', '-'],
+ { input: JSON.stringify({ names: topicsFor(pkg, kind) }) }));
+ attempt('pages', () => {
+ try {
+ gh(['api', '-X', 'POST', `repos/${slug}/pages`, '--input', '-'],
+ { input: JSON.stringify({ build_type: 'legacy', source: { branch: 'main', path: '/docs' } }) });
+ } catch (e) {
+ if (!/already|409|422/i.test(String(e.stderr || e.message))) throw e;
+ gh(['api', '-X', 'PUT', `repos/${slug}/pages`, '--input', '-'],
+ { input: JSON.stringify({ build_type: 'legacy', source: { branch: 'main', path: '/docs' } }) });
+ }
+ });
+ attempt('vulnerability-alerts', () => gh(['api', '-X', 'PUT', `repos/${slug}/vulnerability-alerts`]));
+ return steps;
+}
diff --git a/scripts/lib/standalone-kit.mjs b/scripts/lib/standalone-kit.mjs
new file mode 100644
index 000000000..e2b946f36
--- /dev/null
+++ b/scripts/lib/standalone-kit.mjs
@@ -0,0 +1,147 @@
+// Standalone mirror boost: the layers that sit on top of standalone-enrich.mjs.
+//
+// standalone-enrich.mjs writes the community files, agent files (AGENTS.md,
+// llms.txt) and the rendered docs site. This module adds what makes a mirror
+// shareable and credible on top of that:
+//
+// - a real 1200x630 Open Graph card (docs/og.png), wired into the site's
+// og:image and twitter:image tags in place of the generic GitHub card
+// - a robots.txt that names the AI crawlers explicitly, plus security.txt
+// - a README footer that links the mirror back to the platform, and a LICENSE
+// file when the package ships none or an "all rights reserved" one
+//
+// Pure functions are exported for tests. boostMirror is the only writer.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import sharp from 'sharp';
+import { pagesUrl } from './standalone-enrich.mjs';
+
+const SITE = 'https://three.ws';
+const MONOREPO = 'https://github.com/nirholas/three.ws';
+const SUPPORT_EMAIL = '[email protected]';
+
+/** Replace the dash glyphs the house style bans, in text this module generates. */
+export function plain(text = '') {
+ return String(text).replace(/\s[\u2014\u2013]\s/g, ': ').replace(/[\u2014\u2013]/g, '-');
+}
+
+export function escapeHtml(s = '') {
+ return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+}
+
+/** Wrap text to lines of at most `max` characters, capped at `maxLines` (for the SVG card). */
+export function wrapLines(text, max, maxLines) {
+ const words = plain(text).split(/\s+/).filter(Boolean);
+ const lines = [];
+ let cur = '';
+ for (const w of words) {
+ if ((cur + ' ' + w).trim().length > max && cur) {
+ lines.push(cur);
+ cur = w;
+ } else cur = (cur + ' ' + w).trim();
+ }
+ if (cur) lines.push(cur);
+ if (lines.length > maxLines) {
+ lines.length = maxLines;
+ lines[maxLines - 1] = lines[maxLines - 1].replace(/[\s.,;:]*$/, '') + '...';
+ }
+ return lines;
+}
+
+export function installCommand(pkg) {
+ return pkg.bin ? `npx -y ${pkg.name}` : `npm install ${pkg.name}`;
+}
+
+export function fixLicenseFooter(readme) {
+ return readme.replace(/^.*all rights reserved.*$/gim, 'Licensed under the [Apache License 2.0](./LICENSE).');
+}
+
+export function ecosystemFooter({ pkg, slug, dir }) {
+ const site = pagesUrl(slug);
+ return [
+ '<!-- three.ws:ecosystem -->',
+ '## Part of three.ws',
+ '',
+ `[three.ws](${SITE}) is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. \`${pkg.name}\` is one package from it.`,
+ '',
+ `- Documentation site: ${site}`,
+ `- npm: https://www.npmjs.com/package/${pkg.name}`,
+ `- Canonical source: ${MONOREPO} (this repository is a generated mirror of \`${dir}\`)`,
+ '- Agent-readable summary: [llms.txt](./llms.txt) and [AGENTS.md](./AGENTS.md)',
+ `- Issues and ideas: https://github.com/${slug}/issues`,
+ '<!-- /three.ws:ecosystem -->',
+ '',
+ ].join('\n');
+}
+
+export function decorateReadme(readme, ctx) {
+ const stripped = fixLicenseFooter(readme).replace(/<!-- three\.ws:ecosystem -->[\s\S]*?<!-- \/three\.ws:ecosystem -->\n?/g, '');
+ return stripped.replace(/\s*$/, '\n\n') + ecosystemFooter(ctx);
+}
+
+const AI_CRAWLERS = ['GPTBot', 'ChatGPT-User', 'OAI-SearchBot', 'ClaudeBot', 'Claude-User', 'Claude-SearchBot', 'PerplexityBot', 'Google-Extended', 'Applebot-Extended', 'CCBot'];
+
+export function robotsTxt(slug) {
+ const blocks = AI_CRAWLERS.map((b) => `User-agent: ${b}\nAllow: /\n`).join('\n');
+ return `User-agent: *\nAllow: /\n\n${blocks}\nSitemap: ${pagesUrl(slug)}sitemap.xml\n`;
+}
+
+/** A 1200x630 social card: package name, one-line pitch and the install command. */
+export async function ogCard({ pkg, install }) {
+ const tagline = (pkg.description || '').split(/(?<=[.!?])\s/)[0];
+ const title = wrapLines(pkg.name, 26, 2);
+ const desc = wrapLines(tagline, 58, 3);
+ const text = (lines, x, y, size, lh, fill, weight = 400) =>
+ lines.map((l, i) => `<text x="${x}" y="${y + i * lh}" font-size="${size}" font-weight="${weight}" fill="${fill}" font-family="Helvetica,Arial,sans-serif">${escapeHtml(l)}</text>`).join('');
+ const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+<defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#0b0e14"/><stop offset="1" stop-color="#1b1f4a"/></linearGradient>
+<radialGradient id="r" cx="0.85" cy="0.1" r="0.7"><stop offset="0" stop-color="#6d5dfc" stop-opacity="0.55"/><stop offset="1" stop-color="#6d5dfc" stop-opacity="0"/></radialGradient></defs>
+<rect width="1200" height="630" fill="url(#g)"/><rect width="1200" height="630" fill="url(#r)"/>
+<rect x="72" y="72" width="64" height="64" rx="16" fill="#6d5dfc"/><text x="104" y="118" text-anchor="middle" font-size="40" font-weight="700" fill="#fff" font-family="Helvetica,Arial,sans-serif">3</text>
+<text x="154" y="116" font-size="34" font-weight="600" fill="#cfd5ff" font-family="Helvetica,Arial,sans-serif">three.ws</text>
+${text(title, 72, 280, 72, 84, '#ffffff', 700)}
+${text(desc, 72, 280 + title.length * 84 + 24, 34, 46, '#b8c0dc')}
+<rect x="72" y="540" width="${Math.min(1056, 60 + install.length * 17)}" height="56" rx="14" fill="#000" fill-opacity="0.45" stroke="#3a4170"/>
+<text x="96" y="577" font-size="26" fill="#e6ebf5" font-family="Menlo,Consolas,monospace">$ ${escapeHtml(install)}</text>
+</svg>`;
+ return sharp(Buffer.from(svg)).png({ compressionLevel: 9 }).toBuffer();
+}
+
+function put(dir, rel, content) {
+ const full = join(dir, rel);
+ mkdirSync(dirname(full), { recursive: true });
+ writeFileSync(full, content);
+}
+
+/** Point the site's social tags at the generated card instead of GitHub's generic one. */
+export function useOgCard(html, slug) {
+ const card = `${pagesUrl(slug)}og.png`;
+ return html
+ .replace(/(<meta property="og:image" content=")[^"]*(")/, `$1${card}$2`)
+ .replace(/(<meta name="twitter:image" content=")[^"]*(")/, `$1${card}$2`);
+}
+
+/**
+ * Layer the shareability extras onto a mirror working tree that enrichMirror has
+ * already populated. `monorepoLicense` is the text of the monorepo LICENSE.
+ */
+export async function boostMirror(dir, { pkg, slug, kind, sourceDir, monorepoLicense }) {
+ const install = installCommand(pkg);
+ const readmePath = join(dir, 'README.md');
+ const readme = existsSync(readmePath) ? readFileSync(readmePath, 'utf8') : `# ${pkg.name}\n\n${pkg.description || ''}\n`;
+ put(dir, 'README.md', decorateReadme(readme, { pkg, slug, dir: sourceDir }));
+
+ const licensePath = join(dir, 'LICENSE');
+ if (!existsSync(licensePath) || /all rights reserved/i.test(readFileSync(licensePath, 'utf8'))) put(dir, 'LICENSE', monorepoLicense);
+ if (!existsSync(join(dir, '.gitignore'))) put(dir, '.gitignore', 'node_modules/\n.env\n.env.*\n!.env.example\n*.log\ndist/\n.DS_Store\n');
+
+ put(dir, 'docs/og.png', await ogCard({ pkg, install }));
+ put(dir, 'docs/robots.txt', robotsTxt(slug));
+ put(dir, 'docs/.well-known/security.txt', `Contact: mailto:${SUPPORT_EMAIL}\nPreferred-Languages: en\nCanonical: ${pagesUrl(slug)}.well-known/security.txt\nExpires: ${new Date(Date.now() + 365 * 864e5).toISOString()}\n`);
+ for (const page of ['docs/index.html', 'docs/404.html']) {
+ const f = join(dir, page);
+ if (existsSync(f)) writeFileSync(f, useOgCard(readFileSync(f, 'utf8'), slug));
+ }
+ if (kind === 'mcp' && existsSync(join(dir, 'server.json'))) put(dir, 'docs/server.json', readFileSync(join(dir, 'server.json')));
+}