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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(growth): bring every public repo to discovery best practice, least-starred first, with a profile catalog and mirror-safe README block
nirholas6ebd71b48515
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0a76e27c1..f5f3233fe 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Docs · Destination Whitelist** (`/docs/destination-whitelist`): Cooldown allowlist for agent wallet payouts: step-up to add, propose-only agents, one-click cancel, instant removal.- **Docs · Developer plans** (`/docs/developer-plans`): Free, Builder, Scale and Enterprise API plans: monthly call quotas, burst and concurrency ceilings enforced on every v1 call with 429 and 402 responses, live usage in the dashboard, upgrades paid in credits, USDC or $THREE on Solana with proration and receipts, immediate key revocation, rotation with an overlap window, IP allowlists and per-key analytics.- **Docs · Funded launch intents** (`/docs/launch-intents`): Launch a coin from a priced quote paid by the agent wallet: quote, paid, submitted, confirmed, indexed. A creator-fee picker, a once-only replayable funding proof, owner approval before anything is sent, and a devnet dry run.+- **Docs · GitHub growth kit** (`/docs/github-growth`): The discovery layer every public repository carries: star and share links, AGENTS.md and llms.txt for AI agents, community health files, tuned settings, and the profile catalog that lists every repo.- **Docs · Importing skills** (`/docs/skill-import`): Install SKILL.md skills from any public GitHub repository or registry manifest: pinned to an exact commit, licence-checked, scanned for hostile instructions, approved by the owner, and run under the spend gate when they ask to spend, sign or message. Includes the fork and publish flow, the MCP tools and the REST API.- **Docs · Launch Lanes** (`/docs/launch-lanes`): Every way to launch a coin on three.ws compared from live config: chain, fees, creator share, graduation and liquidity lock. Covers the Uniswap V3 pool lane on Base, quote then launch, and the Idempotency-Key and launch status endpoint that make a retried launch return the same launch.- **Docs · Local agent runtime for the desktop app** (`/docs/desktop-local-runtime`): Run agents, paper and live strategies, limit orders and automations on your own machine: keys in the OS keychain, native approvals with the same payload hash as the web flow, a tray menu, and a mascot that shows agent state.@@ -43,6 +44,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Coin logos, agent art and IPFS images load again**: Several public IPFS gateways started refusing image and metadata requests from websites this month, which left coin logos, the 3D coin face, agent cards and on-chain agent art blank or broken across the site. Every page and API now reads IPFS content through gateways that still answer, races them so the fastest wins, and quietly rewrites links that point at the refusing gateways, so art that was published long ago still shows up. Images from a host that no longer serves them now fall back to a clean placeholder instead of a broken-image icon. (`/launches`) `[fix, improvement]`- **Developer plans with quotas that are enforced, self-serve upgrades, key rotation, IP allowlists and per-key analytics**: Every API key now sits on a developer plan: Free, Builder, Scale or Enterprise, each with a monthly call quota, a per-minute burst ceiling, a concurrency ceiling and a webhook cap, all enforced on every /api/v1 call rather than only recorded. Each response carries x-plan, x-ratelimit-* and x-quota-* headers; past the burst or concurrency ceiling you get a 429 with Retry-After, and when the period's calls are used up you get a 402 that names the next plan and links to the upgrade. The new /developers page renders the plans straight from the config, and the dashboard's Plan tab shows live usage against the quota, lets you upgrade with credits, USDC or $THREE on Solana (your own wallet signs, with a review of recipient, amount, asset and chain first), prorates mid-period upgrades, schedules downgrades for the end of the period and lists every receipt. Revoking a key now takes effect immediately on every server. Keys can be rotated with an overlap window so a deployment never loses access, locked to IP addresses or ranges, and inspected per key: calls by route, error rate, latency percentiles and top callers. (`/developers`) `[feature, sdk, security, docs]`- **Every MCP tool now has its own page, and the tool counts are measured, not typed**: The MCP tool catalog now shows the real totals for every server, worked out from the live servers with a plain note on how, and a release view that lists which tools each release added. Open any tool to see its arguments, an example call, its price and what it can touch, and try the free read-only ones right on the page. You can filter the catalog by category. Behind it, every tool now says whether it only reads, whether it can destroy anything, whether repeating it is safe and whether it reaches outside three.ws, and every tool says when to use it. Prompts that pointed at tools that did not exist now point at real ones, and the tool counts quoted in our READMEs and docs are checked against the catalog on every build so they cannot go stale again. (`/mcp-tools`) `[feature, improvement]`+- **Every public repo is now easier to find, trust and share**: All public repositories on the nirholas GitHub account now carry the same discovery layer: a star and share section, an AGENTS.md and llms.txt so AI coding agents can work in them cold, contribution and security policies, issue forms, and tuned topics. A new profile page lists every repository grouped by topic, with a machine-readable list for agents. Package mirrors keep the same layer on every sync. (`/docs/github-growth`) `[improvement, docs]`- **Every three.ws package now has its own home, docs site and agent-readable guide**: Each SDK and MCP server is mirrored to its own GitHub repository with a documentation site, install command, topics for search, an AGENTS.md and llms.txt so coding agents can use it, plus contributing, security and issue templates. Find them all in the standalone repositories list. (`/docs/start-here`) `[docs, improvement]`- **Import skills from any registry, safely**: Agents can now take skills from outside three.ws. Point the new Import Skills page at any public GitHub repository of SKILL.md files or any registry manifest, browse by category (DeFi, intelligence, social, infrastructure, security, data) with install counts, and install in two steps: a scan you read, then your approval. Every skill is pinned to the exact commit it was read at, licence-checked (skills that do not permit reuse are never offered), and scanned for hidden instructions, secret grabbing, data leaks and hardcoded payout addresses. Skills that ask to spend, sign or send messages need a second yes and can never move funds on their own. Updates never apply silently: you see the diff and approve it. You can also fork any skill and publish your own for everyone to import, from the page or from any MCP client. (`/skills/import`) `[feature, security]`- **Launch a coin as a Uniswap pool on Base, and retry launches safely**: There is a new launch lane: your agent launches a fixed-supply coin whose whole supply sits in one Uniswap V3 pool on Base. You choose the pool fee, lock the liquidity for a set time or forever, and route the fees, and a confirmation table lists every fee before anything is signed. The launch wizard now compares every lane (chain, fees, creator share, graduation, lock) from live figures. Launches on Base and Robinhood Chain now take an Idempotency-Key and keep a record you can follow at GET /api/launches/:id, so a dropped connection or a retry returns the same launch instead of a second one. Solana stays the default lane. The Base lane opens once its launcher contract is deployed. (`/launch/uniswap`) `[feature]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 4231ee58c..3658c1bc0 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -259,6 +259,7 @@ bottom.| Awesome 3D Agents (curated list) | Source [data/awesome.json](data/awesome.json), generator [scripts/build-awesome.mjs](scripts/build-awesome.mjs) (`npm run build:awesome`, drift-gated by `npm run check:awesome`, publishable mirror via `npm run awesome:standalone`), outputs [awesome/README.md](awesome/README.md) + [public/awesome.json](public/awesome.json), page [pages/awesome.html](pages/awesome.html) `-> /awesome`, link checker [scripts/check-awesome-links.mjs](scripts/check-awesome-links.mjs) (`npm run awesome:links`) | Live | An awesome-list of everything needed to give an AI agent a body: text-to-3D, capture and splatting, avatars, rigging, motion, lipsync and voice, web renderers, asset pipelines, physics and networking, agent frameworks, datasets, free assets, learning. One JSON source produces both the GitHub-facing list and the searchable page, so they cannot disagree. Every url is fetched and classified (ok / moved / bot-filtered / broken) before it ships; the checker stays out of the deploy path so a third-party outage cannot redden someone else's build. The README is written to pass `npx awesome-lint`: badge on the heading line, no License section, no Contributing entry in the contents, and every description capitalised and ended with a period, all enforced by the generator and by [tests/awesome-list.test.js](tests/awesome-list.test.js). Its last two lint rules read GitHub repository topics, which a list inside a product repo cannot satisfy, so `--standalone` emits a ready-to-publish mirror repo (readme, contributing, code of conduct, license) outside this checkout. Contributing: [awesome/CONTRIBUTING.md](awesome/CONTRIBUTING.md) || Agent Skills pack | [.agents/skills/](.agents/skills) (canonical) → manifest [.agents/skills/SKILLS.md](.agents/skills/SKILLS.md), [.agents/skills/skills-pack.json](.agents/skills/skills-pack.json); published 3D subset [public/skills/3d-studio/](public/skills/3d-studio) `→ /skills/3d-studio/` | In-repo; bundled in the `three-ws-core` [plugin](.claude-plugin/marketplace.json); 3D subset live on the site | Portable `SKILL.md` folders (Agent Skills open standard) for any Claude surface, in five categories: 3d/creative (cross-platform-safe), platform/agents (create an agent, author and sell its skills, hire other agents, connect a client to the MCP servers), wallet/payments, intel/trading, ops/production. Counts live in the generated manifest, never here. The 3d/creative ones are also published as a public, downloadable bundle at `/skills/3d-studio/` (`three-ws-3d-skills.zip`), which is what an OpenAI Plugin Directory submission uploads on its Skills tab; a skill referencing a tool [api/_mcp-studio/](api/_mcp-studio) does not declare is dropped rather than shipped as a dead path. Regenerate manifest: `npm run build:skills-pack` (drift gate `npm run check:skills-pack`); regenerate the published bundle: `npm run build:openai-skills` (drift gate `npm run check:openai-skills`, wired into `npm run gate`). Docs: [docs/agent-skills.md](docs/agent-skills.md) || Standalone skill repos | [scripts/build-standalone-skill-repos.mjs](scripts/build-standalone-skill-repos.mjs) → `.data/standalone-repos/<repo>/` (gitignored) | Generated on demand; publishing is owner-gated | Assembles the three.ws-origin skills into small, publishable repos so an external user installs with one `/plugin marketplace add nirholas/<repo>` instead of cloning this monorepo: `three-ws-skills` (everything), `three-ws-3d-skills` (the crypto-free 3d/creative subset), `three-ws-agent-economy-skills` (wallet/payments + platform/agents). Each output is a complete one-plugin marketplace (`.claude-plugin/{marketplace,plugin}.json`, `skills/`, generated `README.md` with every trigger, `LICENSE`). Built from the same `collectSkills()` the manifest uses, so a copy cannot drift; nothing is committed here. `npm run build:skill-repos`, validate with `npm run check:skill-repos` (wired into `npm run gate`). Docs: [docs/agent-skills.md](docs/agent-skills.md) |+| GitHub growth kit | [scripts/lib/repo-growth-kit.mjs](scripts/lib/repo-growth-kit.mjs), [scripts/boost-github-repos.mjs](scripts/boost-github-repos.mjs), [scripts/build-github-profile.mjs](scripts/build-github-profile.mjs) | Live | Brings every public repo on the nirholas account to discovery best practice, least-starred first: star and share block, AGENTS.md and llms.txt, community health files, tuned settings, plus the generated profile catalog repo. The mirror sync reuses the same module so it never erases the block. Repos about other crypto projects are held back until the owner approves. Docs: [docs/github-growth.md](docs/github-growth.md) || Claude Code plugin marketplace | [marketplace/](marketplace) → plugins [three-ws-3d](marketplace/plugins/three-ws-3d), [three-ws-developer](marketplace/plugins/three-ws-developer) | In-repo · installable via `/plugin marketplace add nirholas/three.ws` | 3D generation + rigged avatars inside Claude Code (free lane + paid x402 tools) and developer tooling for building on three.ws. Index: [marketplace/README.md](marketplace/README.md) || SNS naming + pay-by-name | [api/sns.js](api/sns.js), [api/sns-subdomain.js](api/sns-subdomain.js), [api/threews/subdomain.js](api/threews/subdomain.js), [api/x402/pay-by-name.js](api/x402/pay-by-name.js), [src/solana/sns-subdomain.js](src/solana/sns-subdomain.js), [pages/threews-claim.html](pages/threews-claim.html) | In-repo | `*.threews.sol` subdomain mint, x402 payments addressed by name. Env: `THREEWS_SOL_PARENT_SECRET_BASE58` || Self-hosted x402 facilitator + ring economy | [api/x402-facilitator/[action].js](api/x402-facilitator/[action].js), [api/_lib/x402/self-facilitator.js](api/_lib/x402/self-facilitator.js), [api/x402/ring-settle.js](api/x402/ring-settle.js), [api/_lib/x402/pipelines/ring-rebalance.js](api/_lib/x402/pipelines/ring-rebalance.js), [api/x402-ring.js](api/x402-ring.js), [scripts/x402-ring-setup.mjs](scripts/x402-ring-setup.mjs) | In-repo (off by default) | Closed-loop agent-to-agent x402: platform wallets pay platform endpoints, settled in-house (no external facilitator). Fee-minimized, SOL-floor guarded, internal-labeled. Env: `X402_SELF_FACILITATOR_ENABLED`, `X402_FEE_PAYER_SECRET_BASE58`, `X402_TREASURY_SECRET_BASE58`. See [docs/x402-ring-economy.md](docs/x402-ring-economy.md), [docs/x402-settlement-pending.md](docs/x402-settlement-pending.md) |diff --git a/data/changelog.json b/data/changelog.jsonindex 878b98f3e..9cf7f5ea2 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -29640,6 +29640,16 @@"feature"],"link": "/commerce"+ },+ {+ "date": "2026-10-10",+ "title": "Every public repo is now easier to find, trust and share",+ "summary": "All public repositories on the nirholas GitHub account now carry the same discovery layer: a star and share section, an AGENTS.md and llms.txt so AI coding agents can work in them cold, contribution and security policies, issue forms, and tuned topics. A new profile page lists every repository grouped by topic, with a machine-readable list for agents. Package mirrors keep the same layer on every sync.",+ "tags": [+ "improvement",+ "docs"+ ],+ "link": "/docs/github-growth"}]}diff --git a/data/pages.json b/data/pages.jsonindex 6cda1ede2..cf31c0d50 100644--- a/data/pages.json+++ b/data/pages.json@@ -5313,6 +5313,14 @@"priority": 0.6,"changefreq": "monthly"},+ {+ "path": "/docs/github-growth",+ "title": "Docs · GitHub growth kit",+ "description": "The discovery layer every public repository carries: star and share links, AGENTS.md and llms.txt for AI agents, community health files, tuned settings, and the profile catalog that lists every repo.",+ "priority": 0.6,+ "changefreq": "monthly",+ "added": "2026-10-10"+ },{"path": "/docs/agent-skills","title": "Docs · The three.ws Agent Skills pack",diff --git a/docs/github-growth.md b/docs/github-growth.mdnew file mode 100644index 000000000..53d29484a--- /dev/null+++ b/docs/github-growth.md@@ -0,0 +1,58 @@+# GitHub growth kit++Every public repository on the [nirholas](https://github.com/nirholas) GitHub account carries the same discovery layer, so a person or an AI agent landing on any one of them can find the rest. This page explains what that layer is, how it is applied, and how to keep it true.++## What every repo gets++| Layer | What | Why it helps |+|---|---|---|+| README block | A marked "Support the project" section: star call to action, one-click share links (X, Bluesky, LinkedIn, Hacker News, Reddit), an agent entry point, a link to the profile catalog, a contributors wall and a star history chart | Stars and shares are how repositories get found. The block makes both one click |+| README badges | Stars, license, last commit, PRs welcome and an AI-agent-friendly badge, added only when the README has no badges of its own | Signals an active, maintained project |+| Agent discovery | `AGENTS.md`, `llms.txt`, `llms-full.txt` and a `CLAUDE.md` that imports `AGENTS.md` | Coding agents and LLM crawlers can read the repo cold |+| Community health | `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `CITATION.cff`, issue forms, a pull request template and `.github/FUNDING.yml` | GitHub's community profile checklist, so the repo reads as maintained and safe to depend on |+| Repository settings | Topics (up to 20, always including `three-ws`, `ai-agents`, `llms-txt`, `agents-md`), description, homepage, Discussions, delete-branch-on-merge, secret scanning with push protection, Dependabot alerts and security updates | Search ranking on GitHub and the repo health signals |+| Profile catalog | [github.com/nirholas/nirholas](https://github.com/nirholas/nirholas): every public repo grouped by topic, plus `llms.txt`, `AGENTS.md` and a machine-readable `repos.json` | One place to find every repository |++`FUNDING.yml` links to the product, never to a token. A file a repo already ships is never overwritten, and no license is ever invented for a repo that has none: choosing a license is the owner's decision.++## How it is applied++The kit is one pure module, [scripts/lib/repo-growth-kit.mjs](../scripts/lib/repo-growth-kit.mjs), used two ways so the result is the same either way:++1. **Independent repos** are fixed in place by [scripts/boost-github-repos.mjs](../scripts/boost-github-repos.mjs). It walks every public, non-fork, non-archived repo from the least-starred to the most-starred, shallow-clones it, applies the kit, commits with a message describing exactly what was added, pushes the default branch, then sets the repository settings.+2. **Standalone mirrors** (see [Standalone repositories](./standalone-repos.md)) are force-pushed snapshots, so a direct edit would be erased by the next sync. `scripts/lib/standalone-kit.mjs` calls the same module while decorating each mirror README, so a sync reproduces the block instead of wiping it.++```bash+node scripts/boost-github-repos.mjs # plan every repo, write nothing+node scripts/boost-github-repos.mjs --apply # run the whole fleet, lowest stars first+node scripts/boost-github-repos.mjs --apply --only a,b # named repos+node scripts/boost-github-repos.mjs --apply --resume # continue after an interruption+node scripts/boost-github-repos.mjs --only a --keep # keep the clone to inspect the diff+```++The run is idempotent: a repo already carrying the current kit produces no diff and is skipped. It reads the GitHub API quota before every repo and waits for the reset instead of failing. Progress is written to `state.json` in the work directory so `--resume` skips finished repos.++Repos whose subject is another crypto project are held back by default, because committing content that references them needs the owner's approval. Pass `--include-gated` once that approval exists.++### The profile catalog++```bash+node scripts/build-github-profile.mjs --out /tmp/profile # generate only+node scripts/build-github-profile.mjs --out /tmp/profile --publish # create the repo if missing, commit, push+```++The catalog is built from the live GitHub listing, so it cannot drift from what is actually public. Re-run it after adding or renaming repos.++## What GitHub's API cannot do++The repository social preview image can only be uploaded in the web UI (Settings, then Social preview). Standalone mirrors already serve a generated 1200x630 card from their docs site; set the same image as the social preview on the repos you most want shared.++## Tests++`tests/repo-growth-kit.test.js` covers the block (idempotence, no duplicate sections, links only to files that exist), badges, the file set (never overwrites, never invents a license), topic merging and the mirror README decoration.++## Related++- [Standalone repositories](./standalone-repos.md): the generated package mirrors+- [Contributing](./contributing.md#publishing-packages--standalone-mirrors): publishing and syncing mirrors+- [Agent skills](./agent-skills.md): the standalone skill reposdiff --git a/docs/standalone-repos.md b/docs/standalone-repos.mdindex c74b3bb98..d76101a5c 100644--- a/docs/standalone-repos.md+++ b/docs/standalone-repos.md@@ -87,3 +87,7 @@ This table is generated by `scripts/gen-standalone-catalog.mjs` from each packag| [@three-ws/x402-mcp](https://github.com/nirholas/x402-mcp) | Give any AI agent a self-custodial x402 wallet. | `npx -y @three-ws/x402-mcp` | [docs](https://nirholas.github.io/x402-mcp/) || [@three-ws/x402-preflight](https://github.com/nirholas/x402-preflight) | Ask an x402 seller whether it can actually settle, before you sign anything. | `npx -y @three-ws/x402-preflight` | [docs](https://nirholas.github.io/x402-preflight/) || [@three-ws/x402-server](https://github.com/nirholas/x402-server) | The merchant side of x402, turn any HTTP endpoint into a paid one. | `npm install @three-ws/x402-server` | [docs](https://nirholas.github.io/x402-server/) |++## Discovery layer on every mirror++Each mirror README also gets the shared growth block (star and share links, agent entry points, contributors wall, star history) from `scripts/lib/repo-growth-kit.mjs`, applied during `decorateReadme`. A sync therefore reproduces it instead of erasing it. See [GitHub growth kit](./github-growth.md).diff --git a/docs/start-here.md b/docs/start-here.mdindex ebb5f3518..7b80e8d87 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -121,6 +121,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ- **Your agent needs market data?** → [Market Data API](./market-data-api.md) — the live feeds behind every /markets page (prices, TVL, yields, stablecoins, gas, derivatives, exploits) as 17 pay-per-call x402 endpoints from $0.001 USDC, plus the one-call `market-pulse` bundle; start at the free index [/api/x402/market](https://three.ws/api/x402/market)- **Choosing where to launch a coin?** → [Launch lanes](./launch-lanes.md): pump.fun and the three.ws launchpad on Solana (the default), a Uniswap V3 pool on Base and a paired coin on Robinhood Chain, compared on chain, fees, creator share, graduation and liquidity lock from live config. The two EVM lanes take an `Idempotency-Key` so a retried launch is never a second one, and report progress at `GET /api/launches/:id`- **Want one package on its own?** → [Standalone repositories](./standalone-repos.md): every SDK and MCP server has its own repo and docs site, with `AGENTS.md` and `llms.txt` for agents.+- **Want to find every public repo?** → [GitHub growth kit](./github-growth.md): the discovery layer on every repository and the profile catalog.- **Trading Robinhood Chain?** → [Robinhood Chain on three.ws](./robinhood-chain-markets.md): the 24/7 tokenized-equity board (live Chainlink NAV vs. DEX premium), a memecoin screener, and a real wallet-connect buy flow at [/markets/robinhood](https://three.ws/markets/robinhood), backed by 6 free + 1 paid `/api/v1/robinhood/*` endpoints. Your agent can also [launch its own coin there on Pons](./pons-launch.md), or launch a [paired coin](./paired-coins.md) that trades against up to five assets at once (tokenized stocks, WETH, stablecoins) from its own wallet- **Listing our services across the x402 ecosystem?** → [x402 distribution](./x402-distribution.md) — the operating playbook for x402scan, the CDP Bazaar, agentic.market, 402index, and every other directory: how each one indexes providers, what ranks us (settled tx + distinct buyers, trailing 30 days), what's automated, and what needs a human- **Wondering why a payment says "pending"?** → [Pending settlement](./x402-settlement-pending.md): a Solana settle has three outcomes, not two: broadcast-but-unconfirmed is `settlement_pending`, not a failed payment. Covers what a buyer should do with it (retry once, keep the good, watch the signature), how our facilitator guarantees one authorization never produces two transactions, and the reconcile pass that closes the books either waydiff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex 24c8df859..6c03b3329 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,11 +1,11 @@{- "generated_at": "2026-10-10T21:02:24.880Z",+ "generated_at": "2026-10-10T21:47:55.310Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 3940,+ "total": 3942,"complete": false,"full_feed": "/changelog.json","entries": [@@ -89,6 +89,16 @@"launch"]},+ {+ "date": "2026-10-10",+ "type": "launch",+ "title": "Docs · GitHub growth kit",+ "summary": "The discovery layer every public repository carries: star and share links, AGENTS.md and llms.txt for AI agents, community health files, tuned settings, and the profile catalog that lists every repo.",+ "link": "/docs/github-growth",+ "tags": [+ "launch"+ ]+ },{"date": "2026-10-10","type": "launch",@@ -390,6 +400,17 @@"improvement"]},+ {+ "date": "2026-10-10",+ "type": "update",+ "title": "Every public repo is now easier to find, trust and share",+ "summary": "All public repositories on the nirholas GitHub account now carry the same discovery layer: a star and share section, an AGENTS.md and llms.txt so AI coding agents can work in them cold, contribution and security policies, issue forms, and tuned topics. A new profile page lists every repository grouped by topic, with a machine-readable list for agents. Package mirrors keep the same layer on every sync.",+ "link": "/docs/github-growth",+ "tags": [+ "improvement",+ "docs"+ ]+ },{"date": "2026-10-10","type": "update",@@ -1524,26 +1545,6 @@"feature","fix"]- },- {- "date": "2026-09-30",- "type": "update",- "title": "Every platform total in one free API call",- "summary": "GET /api/platform/analytics returns agents, agents with a wallet, coins launched, 3D models generated, LLM tokens processed, x402 settlements and volume, marketplace sales and agent-to-agent hire volume, each with a daily series over 30 days, 90 days or all time and a plain sentence saying exactly which rows were counted. A figure that cannot be read comes back empty with a named reason instead of as zero. It powers the new analytics page and is open to anyone building on three.ws.",- "link": "/analytics",- "tags": [- "feature"- ]- },- {- "date": "2026-09-30",- "type": "update",- "title": "Experiment write-up: can autonomous agents trade new coins at a profit?",- "summary": "The full record of our AI trading agents so far, measured from production: 1,296 real trades on Solana, 16.4% of them winners, and a net loss of 0.5402 SOL on 9.1444 SOL put to work. Only take-profit and take-initials exits made money, and the August retune made results worse, not better. The write-up says what that cost, what we got wrong, what we changed, and prints every query behind the numbers.",- "link": "/docs/experiments-autonomous-trading",- "tags": [- "docs"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex 601792a98..6586091f3 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-10T21:02:24.858Z",+ "generated_at": "2026-10-10T21:47:55.288Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -86,6 +86,16 @@"launch"]},+ {+ "date": "2026-10-10",+ "type": "launch",+ "title": "Docs · GitHub growth kit",+ "summary": "The discovery layer every public repository carries: star and share links, AGENTS.md and llms.txt for AI agents, community health files, tuned settings, and the profile catalog that lists every repo.",+ "link": "/docs/github-growth",+ "tags": [+ "launch"+ ]+ },{"date": "2026-10-10","type": "launch",@@ -387,6 +397,17 @@"improvement"]},+ {+ "date": "2026-10-10",+ "type": "update",+ "title": "Every public repo is now easier to find, trust and share",+ "summary": "All public repositories on the nirholas GitHub account now carry the same discovery layer: a star and share section, an AGENTS.md and llms.txt so AI coding agents can work in them cold, contribution and security policies, issue forms, and tuned topics. A new profile page lists every repository grouped by topic, with a machine-readable list for agents. Package mirrors keep the same layer on every sync.",+ "link": "/docs/github-growth",+ "tags": [+ "improvement",+ "docs"+ ]+ },{"date": "2026-10-10","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 3c87cf053..1c389c274 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -70,6 +70,14 @@<category>launch</category><description>Launch a coin from a priced quote paid by the agent wallet: quote, paid, submitted, confirmed, indexed. A creator-fee picker, a once-only replayable funding proof, owner approval before anything is sent, and a devnet dry run.</description></item>+ <item>+ <title>Docs · GitHub growth kit</title>+ <link>https://three.ws/docs/github-growth</link>+ <guid isPermaLink="false">2026-10-10:Docs · GitHub growth kit</guid>+ <pubDate>Sat, 10 Oct 2026 12:00:00 GMT</pubDate>+ <category>launch</category>+ <description>The discovery layer every public repository carries: star and share links, AGENTS.md and llms.txt for AI agents, community health files, tuned settings, and the profile catalog that lists every repo.</description>+ </item><item><title>Docs · Importing skills</title><link>https://three.ws/docs/skill-import</link>@@ -302,6 +310,14 @@<category>feature</category><description>The MCP tool catalog now shows the real totals for every server, worked out from the live servers with a plain note on how, and a release view that lists which tools each release added. Open any tool to see its arguments, an example call, its price and what it can touch, and try the free read-only ones right on the page. You can filter the catalog by category. Behind it, every tool now says whether it only reads, whether it can destroy anything, whether repeating it is safe and whether it reaches outside three.ws, and every tool says when to use it. Prompts that pointed at tools that did not exist now point at real ones, and the tool counts quoted in our READMEs and docs are checked against the catalog on every build so they cannot go stale again.</description></item>+ <item>+ <title>Every public repo is now easier to find, trust and share</title>+ <link>https://three.ws/docs/github-growth</link>+ <guid isPermaLink="false">2026-10-10:Every public repo is now easier to find, trust and share</guid>+ <pubDate>Sat, 10 Oct 2026 12:00:00 GMT</pubDate>+ <category>improvement</category>+ <description>All public repositories on the nirholas GitHub account now carry the same discovery layer: a star and share section, an AGENTS.md and llms.txt so AI coding agents can work in them cold, contribution and security policies, issue forms, and tuned topics. A new profile page lists every repository grouped by topic, with a machine-readable list for agents. Package mirrors keep the same layer on every sync.</description>+ </item><item><title>Every three.ws package now has its own home, docs site and agent-readable guide</title><link>https://three.ws/docs/start-here</link>diff --git a/public/sitemap/index.html b/public/sitemap/index.htmlindex 025b0c70f..4d3d52c0b 100644--- a/public/sitemap/index.html+++ b/public/sitemap/index.html@@ -96,7 +96,7 @@<main class="sm-wrap"><div class="sm-hero"><h1 data-i18n="sitemap_index.sitemap">Sitemap</h1>- <p><span>1027</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p>+ <p><span>1028</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p><div class="sm-formats"><a href="/sitemap.xml" data-i18n-html="sitemap_index.for_search_engines"><code>sitemap.xml</code> · for search engines</a><a href="/llms.txt" data-i18n-html="sitemap_index.for_ai_agents"><code>llms.txt</code> · for AI agents</a>@@ -108,7 +108,7 @@</div><div class="sm-filter"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>- <input id="sm-filter-input" type="search" placeholder="Filter 1027 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />+ <input id="sm-filter-input" type="search" placeholder="Filter 1028 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" /><kbd id="sm-filter-kbd" aria-hidden="true">/</kbd></div><p class="sm-filter-count" role="status" aria-live="polite"><span id="sm-filter-count"></span><span id="sm-filter-hint" aria-hidden="true"></span></p>@@ -2849,7 +2849,7 @@<section class="sm-section" id="learn"><header>- <h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>479</span></h2>+ <h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>480</span></h2><p class="sm-section-desc" data-i18n="sitemap_index.docs_tutorials_and_reference">Docs, tutorials, and reference.</p></header><ul class="sm-list">@@ -4932,6 +4932,13 @@<span class="sm-desc" data-i18n="sitemap_index.d_docs_agent_shell">Every visitor gets a named agent within five seconds of arriving, and the shell makes that agent the way you use the site: a command palette that runs real commands, and navigation between pages that never unloads your agent.</span></a></li>+ <li>+ <a href="/docs/github-growth">+ <span class="sm-title"><span data-i18n="sitemap_index.t_docs_github_growth">Docs · GitHub growth kit</span></span>+ <span class="sm-path" translate="no">/docs/github-growth</span>+ <span class="sm-desc" data-i18n="sitemap_index.d_docs_github_growth">The discovery layer every public repository carries: star and share links, AGENTS.md and llms.txt for AI agents, community health files, tuned settings, and the profile catalog that lists every repo.</span>+ </a>+ </li><li><a href="/docs/agent-skills"><span class="sm-title"><span data-i18n="sitemap_index.t_docs_agent_skills">Docs · The three.ws Agent Skills pack</span></span>diff --git a/scripts/boost-github-repos.mjs b/scripts/boost-github-repos.mjsnew file mode 100644index 000000000..3ebe7aa5c--- /dev/null+++ b/scripts/boost-github-repos.mjs@@ -0,0 +1,266 @@+#!/usr/bin/env node+// Apply the growth kit (scripts/lib/repo-growth-kit.mjs) to every public,+// non-fork, non-archived repository on the owner's GitHub account, from the+// least-starred to the most-starred so the flagship repos are touched last,+// after the process has been proven on the long tail.+//+// Per repo it: shallow-clones, adds the README growth block and badge row,+// adds whichever agent-discovery and community-health files are missing (never+// overwriting a file that exists), commits with a message describing exactly+// what changed, pushes the default branch, then applies repository settings+// (topics, description, homepage, Discussions, branch hygiene, vulnerability+// alerts and secret scanning).+//+// Dry run unless --apply. Idempotent: a repo already carrying the current kit+// produces no diff and is skipped. Progress is recorded so --resume continues.+//+// node scripts/boost-github-repos.mjs # plan every repo+// node scripts/boost-github-repos.mjs --apply # run the whole fleet+// node scripts/boost-github-repos.mjs --apply --only a,b # named repos+// node scripts/boost-github-repos.mjs --apply --limit 25 # first N in star order+// node scripts/boost-github-repos.mjs --apply --resume # skip repos already done+// node scripts/boost-github-repos.mjs --apply --include-gated # owner-approved set+// node scripts/boost-github-repos.mjs --only a --keep # keep the clone to inspect the diff+//+// Repos whose subject is another crypto project are held back by default (see+// GATED); committing content that references them needs the owner's approval.+//+// Auth: gh must be authenticated as the owner.+import { execFileSync, spawnSync } from 'node:child_process';+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import {+ OWNER,+ applyBadges,+ applyGrowthBlock,+ badgeRow,+ growthBlock,+ mergeTopics,+ missingFiles,+} from './lib/repo-growth-kit.mjs';++const args = process.argv.slice(2);+const flag = (n) => args.includes(`--${n}`);+const opt = (n) => {+ const i = args.indexOf(`--${n}`);+ return i === -1 ? null : args[i + 1];+};+const APPLY = flag('apply');+const RESUME = flag('resume');+const INCLUDE_GATED = flag('include-gated');+const KEEP = flag('keep');+const ONLY = opt('only') ? new Set(opt('only').split(',')) : null;+const LIMIT = opt('limit') ? Number(opt('limit')) : Infinity;+const WORK = opt('workdir') || join(process.env.TMPDIR || '/tmp', 'repo-fleet');+const STATE = opt('state') || join(WORK, 'state.json');++// Repos named for, or built around, a specific third-party crypto project.+const GATED = /agenc|agora-mcp|binance|bnbchain|bitrefill|flock|lyra|memescope|metaplex|sherwood|techdollar|loxley|wisconsin|ucai|kol-quest|three-ws-intel/i;++const COAUTHOR = 'Co-Authored-By: Claude Sonnet 5.5 <[email protected]>';++function gh(args2, input) {+ return execFileSync('gh', args2, { encoding: 'utf8', input, maxBuffer: 1 << 28, stdio: ['pipe', 'pipe', 'pipe'] });+}++/** Seconds until the core REST quota resets, or 0 when there is headroom. rate_limit itself is free. */+function quotaWaitSeconds(need = 40) {+ try {+ const core = ghJson(['api', 'rate_limit']).resources.core;+ return core.remaining >= need ? 0 : Math.max(core.reset - Math.floor(Date.now() / 1000), 1) + 5;+ } catch {+ return 0;+ }+}++function sleepSync(seconds) {+ console.log(` waiting ${seconds}s for the GitHub API quota to reset`);+ spawnSync('sleep', [String(seconds)]);+}++const isRateLimit = (e) => /rate limit|secondary rate|abuse detection/i.test(String(e.message) + String(e.stderr || ''));++function ghJson(args2, input) {+ return JSON.parse(gh(args2, input));+}++function git(cwd, ...a) {+ const r = spawnSync('git', ['-c', 'credential.helper=!gh auth git-credential', ...a], { cwd, encoding: 'utf8', maxBuffer: 1 << 28 });+ if (r.status !== 0) throw new Error(`git ${a.join(' ')} failed: ${(r.stderr || r.stdout).trim().slice(0, 400)}`);+ return r.stdout;+}++function listRepos() {+ const rows = ghJson(['repo', 'list', OWNER, '--limit', '1000', '--json', 'name,stargazerCount,isPrivate,isFork,isArchived']);+ return rows+ .filter((r) => !r.isPrivate && !r.isFork && !r.isArchived)+ .sort((a, b) => a.stargazerCount - b.stargazerCount || a.name.localeCompare(b.name));+}++function describeChange(added, readmeChanged) {+ const parts = [];+ if (readmeChanged) parts.push('star call to action, share links and badges');+ const names = Object.keys(added).filter((p) => !p.startsWith('.github/ISSUE_TEMPLATE/'));+ if (Object.keys(added).some((p) => p.startsWith('.github/ISSUE_TEMPLATE/'))) names.push('issue forms');+ if (names.length) parts.push(names.length > 4 ? `${names.slice(0, 4).join(', ')} and ${names.length - 4} more discovery and community files` : names.join(', '));+ return parts.join(' plus ');+}++function boostOne(repo) {+ const dir = join(WORK, 'clones', repo.name);+ rmSync(dir, { recursive: true, force: true });+ mkdirSync(join(WORK, 'clones'), { recursive: true });+ const meta = ghJson(['api', `repos/${OWNER}/${repo.name}`]);+ git(WORK, 'clone', '--quiet', '--depth', '1', `https://github.com/${OWNER}/${repo.name}.git`, dir);++ const files = new Set(git(dir, 'ls-files').split('\n').filter(Boolean));+ const readmeName = [...files].find((p) => /^readme(\.md)?$/i.test(p));+ if (!readmeName) return { repo: repo.name, status: 'no-readme' };+ const readmePath = join(dir, readmeName);+ const original = readFileSync(readmePath, 'utf8');+ const pkgPath = join(dir, 'package.json');+ let pkg = null;+ try {+ pkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf8')) : null;+ } catch {+ pkg = null;+ }+ const license = meta.license && meta.license.spdx_id && meta.license.spdx_id !== 'NOASSERTION' ? meta.license.spdx_id : null;+ const description = meta.description || pkg?.description || '';+ const homepage = meta.homepage || (meta.has_pages ? `https://${OWNER}.github.io/${repo.name}/` : 'https://three.ws');+ const ctx = { name: repo.name, description, files, readme: original, homepage, pkg, license, language: meta.language };++ const added = missingFiles(ctx);+ for (const [rel, body] of Object.entries(added)) {+ const full = join(dir, rel);+ mkdirSync(join(full, '..'), { recursive: true });+ writeFileSync(full, body);+ }+ const finalFiles = new Set([...files, ...Object.keys(added)]);+ let readme = applyBadges(original, badgeRow({ name: repo.name, hasLicense: Boolean(license) }));+ readme = applyGrowthBlock(readme, growthBlock({ name: repo.name, description, files: finalFiles, readme }));+ const readmeChanged = readme !== original;+ if (readmeChanged) writeFileSync(readmePath, readme);++ const result = { repo: repo.name, stars: repo.stargazerCount, added: Object.keys(added), readmeChanged, pushed: false, settings: [] };+ if (APPLY && (readmeChanged || Object.keys(added).length)) {+ git(dir, 'add', '--', readmeName, ...Object.keys(added));+ const subject = `docs: add ${describeChange(added, readmeChanged)}`;+ const body = [+ 'Makes the repository easier to find and to share, for people and for AI agents.',+ '',+ ...(readmeChanged ? ['- README: star call to action, one-click share links, agent entry points, contributors wall and star history'] : []),+ ...Object.keys(added).map((p) => `- add ${p}`),+ '',+ COAUTHOR,+ ].join('\n');+ git(dir, 'commit', '--quiet', '-m', subject, '-m', body);+ try {+ git(dir, 'push', '--quiet', 'origin', `HEAD:${meta.default_branch}`);+ } catch {+ git(dir, 'pull', '--quiet', '--rebase', 'origin', meta.default_branch);+ git(dir, 'push', '--quiet', 'origin', `HEAD:${meta.default_branch}`);+ }+ result.pushed = true;+ }+ result.settings = applySettings(meta, repo, description, homepage);+ if (!KEEP) rmSync(dir, { recursive: true, force: true });+ return result;+}++function applySettings(meta, repo, description, homepage) {+ const done = [];+ const patch = {};+ if (!meta.has_issues) patch.has_issues = true;+ if (!meta.has_discussions) patch.has_discussions = true;+ if (!meta.delete_branch_on_merge) patch.delete_branch_on_merge = true;+ if (!meta.description && description) patch.description = String(description).replace(/\s+/g, ' ').slice(0, 350);+ if (!meta.homepage) patch.homepage = homepage;+ const sa = meta.security_and_analysis || {};+ if (sa.secret_scanning?.status !== 'enabled' || sa.secret_scanning_push_protection?.status !== 'enabled') {+ patch.security_and_analysis = { secret_scanning: { status: 'enabled' }, secret_scanning_push_protection: { status: 'enabled' } };+ }+ const topics = mergeTopics(meta.topics || [], meta.language);+ const topicsChanged = topics.join() !== (meta.topics || []).join();+ if (!APPLY) return [...Object.keys(patch), ...(topicsChanged ? ['topics'] : [])];+ if (Object.keys(patch).length) {+ try {+ gh(['api', '-X', 'PATCH', `repos/${OWNER}/${repo.name}`, '--input', '-'], JSON.stringify(patch));+ done.push(...Object.keys(patch));+ } catch (e) {+ if (isRateLimit(e)) throw e;+ if (patch.security_and_analysis) {+ const { security_and_analysis: _drop, ...rest } = patch;+ if (Object.keys(rest).length) {+ gh(['api', '-X', 'PATCH', `repos/${OWNER}/${repo.name}`, '--input', '-'], JSON.stringify(rest));+ done.push(...Object.keys(rest));+ }+ done.push('security_and_analysis:unavailable');+ } else throw e;+ }+ }+ if (topicsChanged) {+ gh(['api', '-X', 'PUT', `repos/${OWNER}/${repo.name}/topics`, '--input', '-'], JSON.stringify({ names: topics }));+ done.push('topics');+ }+ if (sa.dependabot_security_updates?.status !== 'enabled') {+ for (const ep of ['vulnerability-alerts', 'automated-security-fixes']) {+ try {+ gh(['api', '-X', 'PUT', `repos/${OWNER}/${repo.name}/${ep}`]);+ done.push(ep);+ } catch (e) {+ if (isRateLimit(e)) throw e;+ done.push(`${ep}:unavailable`);+ }+ }+ }+ return done;+}++function loadState() {+ try {+ return JSON.parse(readFileSync(STATE, 'utf8'));+ } catch {+ return {};+ }+}++mkdirSync(WORK, { recursive: true });+const state = RESUME ? loadState() : {};+let repos = listRepos();+const held = repos.filter((r) => GATED.test(r.name));+if (!INCLUDE_GATED) repos = repos.filter((r) => !GATED.test(r.name));+if (ONLY) repos = repos.filter((r) => ONLY.has(r.name));+repos = repos.slice(0, LIMIT);++console.log(`${APPLY ? 'APPLY' : 'PLAN'}: ${repos.length} repos (${held.length} held for owner approval${INCLUDE_GATED ? ', included' : ''}), ${repos[0]?.stargazerCount ?? '-'} to ${repos.at(-1)?.stargazerCount ?? '-'} stars`);+let ok = 0;+const failures = [];+for (const repo of repos) {+ if (RESUME && state[repo.name]?.ok) continue;+ try {+ let r;+ for (let attempt = 0; ; attempt++) {+ const wait = quotaWaitSeconds();+ if (wait) sleepSync(wait);+ try {+ r = boostOne(repo);+ break;+ } catch (e) {+ if (!isRateLimit(e) || attempt >= 3) throw e;+ sleepSync(Math.max(quotaWaitSeconds(5000), 60));+ }+ }+ state[repo.name] = { ok: true, ...r };+ ok++;+ console.log(`${String(repo.stargazerCount).padStart(5)} ${repo.name} ${r.status || (r.pushed ? 'pushed' : 'unchanged')} +${r.added?.length ?? 0} files${r.readmeChanged ? ' +readme' : ''}${r.settings?.length ? ' settings:' + r.settings.join(',') : ''}`);+ } catch (e) {+ state[repo.name] = { ok: false, error: String(e.message).slice(0, 300) };+ failures.push(repo.name);+ console.log(`${String(repo.stargazerCount).padStart(5)} ${repo.name} FAILED ${String(e.message).slice(0, 200)}`);+ }+ writeFileSync(STATE, JSON.stringify(state, null, 1));+}+console.log(`done: ${ok} ok, ${failures.length} failed${failures.length ? ` (${failures.join(', ')})` : ''}`);+if (held.length) console.log(`held for owner approval (${held.length}): ${held.map((r) => r.name).join(' ')}`);+process.exit(failures.length ? 1 : 0);diff --git a/scripts/build-github-profile.mjs b/scripts/build-github-profile.mjsnew file mode 100644index 000000000..49bab2573--- /dev/null+++ b/scripts/build-github-profile.mjs@@ -0,0 +1,205 @@+#!/usr/bin/env node+// Generate the owner's GitHub profile repository (github.com/<owner>/<owner>):+// a README that lists every public repo grouped by topic, plus the machine+// readable layer for AI agents (llms.txt, AGENTS.md, repos.json).+//+// The catalog is built from the live GitHub listing, so it never drifts from+// what is actually public. Repos about a third-party crypto project are left+// out of the generated text (committing them needs the owner's approval); pass+// --include-gated once that approval exists.+//+// node scripts/build-github-profile.mjs --out /tmp/profile # write files only+// node scripts/build-github-profile.mjs --out /tmp/profile --publish+// # create the repo if missing, commit, push+//+// Auth: gh must be authenticated as the owner.+import { execFileSync, spawnSync } from 'node:child_process';+import { copyFileSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';+import { OWNER, plain } from './lib/repo-growth-kit.mjs';++const args = process.argv.slice(2);+const flag = (n) => args.includes(`--${n}`);+const opt = (n) => {+ const i = args.indexOf(`--${n}`);+ return i === -1 ? null : args[i + 1];+};+const OUT = opt('out') || join(process.env.TMPDIR || '/tmp', 'profile-repo');+const GATED = /agenc|agora-mcp|binance|bnbchain|bitrefill|flock|lyra|memescope|metaplex|sherwood|techdollar|loxley|wisconsin|ucai|kol-quest|three-ws-intel/i;++const gh = (a, input) => execFileSync('gh', a, { encoding: 'utf8', input, maxBuffer: 1 << 28, stdio: ['pipe', 'pipe', 'pipe'] });++const CATEGORIES = [+ ['Robinhood Chain', 'SDKs, bots, alerts and tooling for Robinhood Chain.', (r) => /robinhood|hood-/i.test(r.name)],+ ['x402 payments and agent commerce', 'Pay-per-call APIs and the clients, gates and facilitators that let agents buy.', (r) => /x402/i.test(r.name) || has(r, ['x402'])],+ ['MCP servers for AI agents', 'Model Context Protocol servers that give any MCP client new abilities.', (r) => /mcp/i.test(r.name) || has(r, ['mcp-server', 'model-context-protocol'])],+ ['three.ws platform and 3D agents', 'The platform for 3D AI agents with Solana wallets, its SDKs, CLIs and the avatar toolchain.', (r) => r.name === 'three.ws' || /^three-?ws|^threews|3d|avatar|glb|tty-|agent-(glance|vitals|guards?|memory|runtime)|guardian|witness|shipfeed|retarget|motion|sign-language|viewer/i.test(r.name) || has(r, ['3d', 'avatar', 'glb', 'vrm', 'gltf', 'rigging'])],+ ['Solana and pump.fun tooling', 'Wallets, SDKs, claims, vanity addresses and launch tooling on Solana.', (r) => /pump|solana|spl|wallet|vanity|sniper|launch/i.test(r.name)],+ ['DeFi mechanisms and Uniswap v4 hooks', 'Research-grade mechanism designs: hooks, curves, auctions and fee models.', (r) => has(r, ['uniswap-v4', 'amm', 'defi']) || /hook|swap|perp|curve|oracle|liquidity|fee/i.test(r.name)],+ ['On-chain experiments and collectibles', 'Small, shippable ideas that live fully on-chain: receipts, postcards, mints and byte-level curiosities.', (r) => has(r, ['solana', 'onchain', 'on-chain', 'nft', 'calldata', 'evm', 'meme'])],+ ['Developer tools and everything else', 'Utilities, data tools and side projects.', () => true],+];++function has(r, topics) {+ return (r.topics || []).some((t) => topics.includes(t));+}++const stars = (n) => (n ? ` ★${n}` : '');+const clip = (s = '', n = 140) => {+ const t = plain(s).replace(/\s+/g, ' ').trim();+ if (t.length <= n) return t;+ const cut = t.slice(0, n);+ return `${cut.slice(0, Math.max(cut.lastIndexOf(' '), 20)).replace(/[\s,;:(-]+$/, '')}...`;+};+const line = (r) => `- [${r.name}](https://github.com/${OWNER}/${r.name})${stars(r.stargazerCount)}${r.description ? `: ${clip(r.description)}` : ''}`;++function load() {+ const rows = JSON.parse(gh(['repo', 'list', OWNER, '--limit', '1000', '--json', 'name,description,stargazerCount,isPrivate,isFork,isArchived,repositoryTopics,primaryLanguage,homepageUrl,pushedAt']));+ return rows+ .filter((r) => !r.isPrivate && !r.isFork && !r.isArchived && r.name !== OWNER)+ .map((r) => ({ ...r, topics: (r.repositoryTopics || []).map((t) => t.name), language: r.primaryLanguage?.name || null }))+ .sort((a, b) => b.stargazerCount - a.stargazerCount || a.name.localeCompare(b.name));+}++export function buildProfile(allRepos, { includeGated = false } = {}) {+ const repos = includeGated ? allRepos : allRepos.filter((r) => !GATED.test(r.name) && !GATED.test(r.description || ''));+ const totalStars = repos.reduce((n, r) => n + r.stargazerCount, 0);+ const featured = repos.slice(0, 6);+ const placed = new Set();+ const groups = CATEGORIES.map(([title, blurb, test]) => {+ const items = repos.filter((r) => !placed.has(r.name) && test(r));+ items.forEach((r) => placed.add(r.name));+ return { title, blurb, items };+ }).filter((g) => g.items.length);++ const readme = `<h1 align="center">nirholas</h1>++<p align="center"><b>Open-source tooling for 3D AI agents, agent payments and on-chain builders.</b><br/>${repos.length} public repositories, all documented for people and for AI agents.</p>++<p align="center">+<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/platform-three.ws-6d5dfc?style=for-the-badge"/></a>+<a href="https://github.com/${OWNER}?tab=followers"><img alt="Followers" src="https://img.shields.io/github/followers/${OWNER}?style=for-the-badge&logo=github"/></a>+<a href="https://github.com/${OWNER}/three.ws"><img alt="three.ws stars" src="https://img.shields.io/github/stars/${OWNER}/three.ws?style=for-the-badge&logo=github"/></a>+</p>++## Start here++${featured.map(line).join('\n')}++**Find your way:** use the repository topics on the left of any repo, or jump to a section below. Every repo ships a README, an [AGENTS.md](https://agents.md) and an [llms.txt](https://llmstxt.org) so a coding agent can pick it up cold. The full machine-readable list is [repos.json](./repos.json).++${groups.map((g) => `- [${g.title}](#${g.title.toLowerCase().replace(/[^a-z0-9 -]/g, '').trim().replace(/\s+/g, '-')}) (${g.items.length})`).join('\n')}++${groups+ .map(+ (g, i) => `## ${g.title}++${g.blurb}++<details${i < 2 ? ' open' : ''}>+<summary>${g.items.length} repositories</summary>++${g.items.map(line).join('\n')}++</details>`,+ )+ .join('\n\n')}++## Why star and follow++Stars are how developers and AI agents decide which repositories to trust. If something here helped you, a star takes one click and tells the next person it is worth their time. Follow [@${OWNER}](https://github.com/${OWNER}) to see new releases, and open a Discussion on any repo if you want to build with it.++- Platform: [three.ws](https://three.ws)+- Live site feeds: [changelog](https://three.ws/changelog) and [llms.txt](https://three.ws/llms.txt)+- Contact: [[email protected]](mailto:[email protected])++<p align="center"><sub>Catalog generated from the live GitHub listing by <code>scripts/build-github-profile.mjs</code> in <a href="https://github.com/${OWNER}/three.ws">three.ws</a> (${repos.length} repositories, ${totalStars} stars across them).</sub></p>+`;++ const llms = `# ${OWNER}++> Open-source tooling for 3D AI agents, agent payments and on-chain builders. ${repos.length} public repositories by ${OWNER}, part of the three.ws ecosystem.++## Catalog++- [Full machine-readable list](https://github.com/${OWNER}/${OWNER}/blob/main/repos.json): name, description, topics, language and stars for every repo+- [Human catalog](https://github.com/${OWNER}/${OWNER}#readme): grouped by topic++## Sections++${groups.map((g) => `- ${g.title}: ${g.items.length} repositories`).join('\n')}++## Featured++${featured.map((r) => `- [${r.name}](https://github.com/${OWNER}/${r.name}): ${clip(r.description, 120)}`).join('\n')}++## Platform++- [three.ws](https://three.ws): the platform+- [three.ws llms.txt](https://three.ws/llms.txt)+`;++ const agents = `# AGENTS.md++This repository is the catalog for the public repositories of ${OWNER}. It holds no application code.++## How to use it++- Read [repos.json](repos.json) to find a repository by topic, language or description. Each entry has \`name\`, \`url\`, \`description\`, \`topics\`, \`language\` and \`stars\`.+- Every listed repository carries its own README, AGENTS.md and llms.txt. Open the repository, then read AGENTS.md for how to work in it.+- Do not guess at a repository that is not in repos.json. It may be private or retired.++## Regeneration++\`README.md\`, \`llms.txt\`, \`AGENTS.md\` and \`repos.json\` are generated by \`scripts/build-github-profile.mjs\` in https://github.com/${OWNER}/three.ws. Do not edit them by hand.+`;++ const json = repos.map((r) => ({+ name: r.name,+ url: `https://github.com/${OWNER}/${r.name}`,+ description: clip(r.description, 300),+ topics: r.topics,+ language: r.language,+ stars: r.stargazerCount,+ homepage: r.homepageUrl || null,+ }));+ return { readme, llms, agents, json: `${JSON.stringify(json, null, '\t')}\n`, count: repos.length, groups };+}++if (import.meta.url === `file://${process.argv[1]}`) {+ const all = load();+ const out = buildProfile(all, { includeGated: flag('include-gated') });+ rmSync(OUT, { recursive: true, force: true });+ mkdirSync(OUT, { recursive: true });+ writeFileSync(join(OUT, 'README.md'), out.readme);+ writeFileSync(join(OUT, 'llms.txt'), out.llms);+ writeFileSync(join(OUT, 'AGENTS.md'), out.agents);+ writeFileSync(join(OUT, 'repos.json'), out.json);+ console.log(`wrote ${out.count} repos in ${out.groups.length} sections to ${OUT}`);+ for (const g of out.groups) console.log(` ${String(g.items.length).padStart(3)} ${g.title}`);++ if (flag('publish')) {+ try {+ gh(['api', `repos/${OWNER}/${OWNER}`]);+ } catch {+ gh(['repo', 'create', `${OWNER}/${OWNER}`, '--public', '--description', 'Open-source tooling for 3D AI agents, agent payments and on-chain builders. Catalog of every public repository.']);+ }+ const clone = `${OUT}-clone`;+ rmSync(clone, { recursive: true, force: true });+ const run = (cwd, ...a) => {+ const r = spawnSync('git', ['-c', 'credential.helper=!gh auth git-credential', ...a], { cwd, encoding: 'utf8' });+ if (r.status !== 0) throw new Error(`git ${a.join(' ')}: ${r.stderr}`);+ return r.stdout;+ };+ run(process.cwd(), 'clone', '--quiet', `https://github.com/${OWNER}/${OWNER}.git`, clone);+ for (const f of ['README.md', 'llms.txt', 'AGENTS.md', 'repos.json']) copyFileSync(join(OUT, f), join(clone, f));+ run(clone, 'add', '--', 'README.md', 'llms.txt', 'AGENTS.md', 'repos.json');+ if (!run(clone, 'status', '--porcelain').trim()) {+ console.log('profile repo already up to date');+ process.exit(0);+ }+ run(clone, 'commit', '--quiet', '-m', `docs: publish the profile catalog of ${out.count} public repositories with llms.txt and repos.json`, '-m', 'Co-Authored-By: Claude Sonnet 5.5 <[email protected]>');+ run(clone, 'push', '--quiet', 'origin', 'HEAD');+ console.log(`published https://github.com/${OWNER}/${OWNER}`);+ }+}diff --git a/scripts/lib/repo-growth-kit.mjs b/scripts/lib/repo-growth-kit.mjsnew file mode 100644index 000000000..6cad5e972--- /dev/null+++ b/scripts/lib/repo-growth-kit.mjs@@ -0,0 +1,484 @@+// Growth kit for the public repositories on the owner's GitHub account.+//+// Everything here is a pure function over facts already known about a repo+// (name, description, language, README, root file list), so the same output is+// reproducible by scripts/boost-github-repos.mjs (direct fixes on independent+// repos) and by the standalone mirror sync (scripts/lib/standalone-kit.mjs),+// which keeps a mirror's next force-push from erasing what this adds.+//+// What it produces:+// - a marker-delimited README block (star call to action, one-click share+// links, agent entry points, contributors wall, star history) that is+// replaced in place on re-runs and never duplicated+// - a badge row for READMEs that have none+// - the community and agent discovery files a repo is missing (never overwrites)+// - the repository topics and settings that make a repo findable++export const OWNER = 'nirholas';+const SITE = 'https://three.ws';+const SUPPORT_EMAIL = '[email protected]';+const CATALOG = `https://github.com/${OWNER}/${OWNER}#readme`;++export const GROWTH_START = '<!-- three.ws:growth -->';+export const GROWTH_END = '<!-- /three.ws:growth -->';+const BADGES_START = '<!-- three.ws:badges -->';+const BADGES_END = '<!-- /three.ws:badges -->';++/** The house style bans dash glyphs; strip them from any text we copy in. */+export function plain(text = '') {+ return String(text).replace(/\s[\u2014\u2013]\s/g, ': ').replace(/[\u2014\u2013]/g, '-');+}++const oneLine = (s = '') => plain(s).replace(/\s+/g, ' ').trim();+const enc = encodeURIComponent;++/** First sentence of a description, cut at a word boundary so a share link never ends mid-word. */+export function pitchOf(description = '', max = 100) {+ const first = oneLine(description).split(/(?<=[.!?])\s/)[0].replace(/[.!?]+$/, '');+ if (first.length <= max) return first;+ const cut = first.slice(0, max);+ return cut.slice(0, Math.max(cut.lastIndexOf(' '), 20)).replace(/[\s,;:(-]+$/, '');+}++/** Discovery topics that are always worth having when there is room. */+const DISCOVERY_TOPICS = ['three-ws', 'ai-agents', 'llms-txt', 'agents-md', 'open-source'];+const LANG_TOPIC = {+ JavaScript: 'javascript',+ TypeScript: 'typescript',+ Python: 'python',+ Solidity: 'solidity',+ Rust: 'rust',+ Go: 'golang',+ Shell: 'shell',+ HTML: 'html',+ Svelte: 'svelte',+ 'Jupyter Notebook': 'jupyter-notebook',+};++/** Existing topics first, then discovery topics, capped at GitHub's 20. */+export function mergeTopics(existing = [], language) {+ const out = [...existing];+ const add = (t) => {+ if (t && !out.includes(t) && /^[a-z0-9][a-z0-9-]{0,49}$/.test(t)) out.push(t);+ };+ if (language) add(LANG_TOPIC[language]);+ for (const t of DISCOVERY_TOPICS) add(t);+ return out.slice(0, 20);+}++export function shareLinks({ name, description }) {+ const url = `https://github.com/${OWNER}/${name}`;+ const pitch = pitchOf(description);+ const text = pitch ? `${name}: ${pitch}` : name;+ return [+ ['Post on X', `https://twitter.com/intent/tweet?text=${enc(text)}&url=${enc(url)}`],+ ['Share on Bluesky', `https://bsky.app/intent/compose?text=${enc(`${text} ${url}`)}`],+ ['Share on LinkedIn', `https://www.linkedin.com/sharing/share-offsite/?url=${enc(url)}`],+ ['Submit to Hacker News', `https://news.ycombinator.com/submitlink?u=${enc(url)}&t=${enc(text)}`],+ ['Share on Reddit', `https://www.reddit.com/submit?url=${enc(url)}&title=${enc(text)}`],+ ];+}++/**+ * The README block. `files` is the set of root-relative paths in the repo after+ * the kit's own files are added, so a link is only emitted for a file that exists.+ */+export function growthBlock({ name, description, files, readme }) {+ const url = `https://github.com/${OWNER}/${name}`;+ const share = shareLinks({ name, description }).map(([label, href]) => `[${label}](${href})`).join(' · ');+ const agentLinks = [];+ if (files.has('AGENTS.md')) agentLinks.push('[AGENTS.md](./AGENTS.md)');+ if (files.has('llms.txt')) agentLinks.push('[llms.txt](./llms.txt)');+ if (files.has('llms-full.txt')) agentLinks.push('[llms-full.txt](./llms-full.txt)');+ const own = stripGrowthBlock(readme);+ const hasStarHistory = /star-history\.com/i.test(own);+ const hasContributors = /contrib\.rocks/i.test(own);++ const lines = [+ GROWTH_START,+ '## Support the project',+ '',+ `If ${name} saves you time, **[star it on GitHub](${url})**. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.`,+ '',+ `Know someone who would use it? ${share}`,+ '',+ ];+ if (agentLinks.length) {+ lines.push(+ '## Built for AI agents too',+ '',+ `Coding agents and LLM tooling can read this repo directly: ${agentLinks.join(', ')}. Point an agent at \`${url}\` and it has the context it needs.`,+ '',+ );+ }+ lines.push(+ '## More from the same author',+ '',+ `- [All repositories by ${OWNER}](${CATALOG}): the full catalog, grouped by topic`,+ `- [three.ws](${SITE}): the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments`,+ `- Questions or ideas: [open an issue](${url}/issues) or [start a discussion](${url}/discussions)`,+ '',+ );+ if (!hasContributors) {+ lines.push('## Contributors', '', `[](${url}/graphs/contributors)`, '');+ }+ if (!hasStarHistory) {+ lines.push(+ '## Star history',+ '',+ `[](https://www.star-history.com/#${OWNER}/${name}&Date)`,+ '',+ );+ }+ lines.push(GROWTH_END, '');+ return lines.join('\n');+}++/** The README without our own block, so detection never mistakes the block for author content. */+export function stripGrowthBlock(readme) {+ return readme.replace(new RegExp(`${escapeRe(GROWTH_START)}[\\s\\S]*?${escapeRe(GROWTH_END)}\\n?`), '');+}++/** Replace an existing growth block in place, otherwise insert before the mirror footer or at the end. */+export function applyGrowthBlock(readme, block) {+ const re = new RegExp(`${escapeRe(GROWTH_START)}[\\s\\S]*?${escapeRe(GROWTH_END)}\\n?`);+ if (re.test(readme)) return readme.replace(re, block);+ const footer = readme.indexOf('<!-- three.ws:ecosystem -->');+ if (footer !== -1) return `${readme.slice(0, footer).replace(/\s*$/, '\n\n')}${block}\n${readme.slice(footer)}`;+ return `${readme.replace(/\s*$/, '\n\n')}${block}`;+}++function escapeRe(s) {+ return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+}++export function badgeRow({ name, hasLicense }) {+ const repo = `${OWNER}/${name}`;+ const b = (alt, img, link) => `[](${link})`;+ const row = [+ b('GitHub stars', `https://img.shields.io/github/stars/${repo}?style=flat&logo=github`, `https://github.com/${repo}/stargazers`),+ hasLicense ? b('License', `https://img.shields.io/github/license/${repo}?style=flat`, `https://github.com/${repo}/blob/HEAD/LICENSE`) : null,+ b('Last commit', `https://img.shields.io/github/last-commit/${repo}?style=flat`, `https://github.com/${repo}/commits`),+ b('PRs welcome', 'https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat', `https://github.com/${repo}/pulls`),+ b('AI agent friendly', 'https://img.shields.io/badge/AI%20agents-AGENTS.md%20%2B%20llms.txt-6d5dfc?style=flat', `https://github.com/${repo}/blob/HEAD/AGENTS.md`),+ ].filter(Boolean);+ return `${BADGES_START}\n${row.join(' ')}\n${BADGES_END}\n`;+}++/** Insert the badge row under the first H1 when the README carries no badges at all. */+export function applyBadges(readme, row) {+ if (readme.includes(BADGES_START)) {+ const re = new RegExp(`${escapeRe(BADGES_START)}[\\s\\S]*?${escapeRe(BADGES_END)}\\n?`);+ return readme.replace(re, row);+ }+ if (/img\.shields\.io|badge\.svg|badgen\.net/i.test(readme)) return readme;+ const h1 = readme.match(/^# .+$/m);+ if (h1 && h1.index !== undefined) {+ const at = h1.index + h1[0].length;+ return `${readme.slice(0, at)}\n\n${row}${readme.slice(at)}`;+ }+ return `${row}\n${readme}`;+}++/** Facts about the repo's toolchain, read from the root file list and package.json. */+export function detectToolchain(files, pkg) {+ if (pkg) {+ const scripts = Object.keys(pkg.scripts || {});+ return {+ install: 'npm install',+ test: scripts.includes('test') ? 'npm test' : null,+ build: scripts.includes('build') ? 'npm run build' : null,+ label: 'Node.js',+ scripts: pkg.scripts || {},+ };+ }+ if (files.has('Cargo.toml')) return { install: 'cargo build', test: 'cargo test', build: 'cargo build --release', label: 'Rust', scripts: {} };+ if (files.has('foundry.toml')) return { install: 'forge install', test: 'forge test', build: 'forge build', label: 'Solidity (Foundry)', scripts: {} };+ if (files.has('go.mod')) return { install: 'go mod download', test: 'go test ./...', build: 'go build ./...', label: 'Go', scripts: {} };+ if (files.has('pyproject.toml') || files.has('requirements.txt')) {+ return { install: files.has('requirements.txt') ? 'pip install -r requirements.txt' : 'pip install -e .', test: 'pytest', build: null, label: 'Python', scripts: {} };+ }+ return { install: null, test: null, build: null, label: null, scripts: {} };+}++export function agentsMd({ name, description, language, toolchain, license }) {+ const tc = toolchain;+ const cmds = [tc.install, tc.build, tc.test].filter(Boolean);+ const scripts = Object.entries(tc.scripts).map(([k, v]) => `- \`npm run ${k}\`: \`${oneLine(v)}\``).join('\n');+ return `# AGENTS.md++Guidance for AI coding agents working in this repository.++## What this is++\`${name}\`: ${oneLine(description) || 'see README.md'}++${language ? `Primary language: ${language}.` : ''}++## Where to start++- [README.md](README.md) has install, usage and configuration.+- [llms.txt](llms.txt) is a machine-readable summary; [llms-full.txt](llms-full.txt) inlines the README.+- Part of [three.ws](${SITE}), a platform for 3D AI agents with Solana wallets. Catalog of sibling repositories: ${CATALOG}++## Develop++${cmds.length ? `\`\`\`bash\n${cmds.join('\n')}\n\`\`\`` : 'Follow the setup steps in README.md. There is no build step to run before reading or editing the sources.'}+${scripts ? `\nScripts:\n${scripts}\n` : ''}+## Conventions++- Match the style of the surrounding code before introducing a new pattern.+- Read-only by default. Anything that signs, spends or sends must be an explicit, separately named function or option, and must never be inferred from untrusted text such as token names, memos or 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.${license ? `\n- This project is licensed under ${license}; contributions are accepted under the same terms.` : ''}++## Contributing++See [CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately through [SECURITY.md](SECURITY.md).+`;+}++export function claudeMd() {+ return '@AGENTS.md\n';+}++/** Headings of the README, used to give llms.txt a real table of contents. */+export function readmeSections(readme, max = 8) {+ const out = [];+ let fence = false;+ for (const line of readme.split('\n')) {+ if (/^```/.test(line)) fence = !fence;+ if (fence) continue;+ const m = line.match(/^##\s+(.+?)\s*$/);+ if (!m) continue;+ const title = plain(m[1]).replace(/[`*_[\]]/g, '').replace(/<[^>]+>/g, '').trim();+ if (!title || /^(star history|contributors|support the project|more from the same author|built for ai agents too|part of three\.ws)$/i.test(title)) continue;+ out.push({ title, anchor: title.toLowerCase().replace(/[^a-z0-9 -]/g, '').trim().replace(/\s+/g, '-') });+ if (out.length >= max) break;+ }+ return out;+}++export function llmsTxt({ name, description, homepage, readme, files }) {+ const url = `https://github.com/${OWNER}/${name}`;+ const sections = readmeSections(readme);+ const docs = [+ `- [README](${url}/blob/HEAD/README.md): install, usage and reference`,+ ...sections.map((s) => `- [${s.title}](${url}/blob/HEAD/README.md#${s.anchor})`),+ files.has('AGENTS.md') ? `- [AGENTS.md](${url}/blob/HEAD/AGENTS.md): guidance for coding agents` : null,+ files.has('llms-full.txt') ? `- [Full text for LLMs](${url}/blob/HEAD/llms-full.txt): the README inlined` : null,+ ].filter(Boolean);+ return `# ${name}++> ${oneLine(description) || name}++${name} is an open-source repository by ${OWNER}, part of the three.ws ecosystem.++## Docs++${docs.join('\n')}++## Project++- [Source](${url})+- [Issues](${url}/issues)+- [Discussions](${url}/discussions)+${homepage ? `- [Homepage](${homepage})\n` : ''}- [three.ws](${SITE}): the platform this is part of+- [All repositories by ${OWNER}](${CATALOG})+`;+}++export function llmsFullTxt({ name, description, readme }) {+ return `# ${name}\n\n> ${oneLine(description) || name}\n\n${plain(stripGrowthBlock(readme)).trim()}\n`;+}++export function contributingMd({ name, toolchain, license }) {+ const url = `https://github.com/${OWNER}/${name}`;+ const setup = [toolchain.install, toolchain.test].filter(Boolean);+ return `# Contributing to ${name}++Thanks for helping. Small, focused changes land fastest.++## Ways to contribute++- **Report a bug** with the [bug form](${url}/issues/new?template=bug.yml). Include what you ran, what you expected and the smallest reproduction you can.+- **Propose a feature** with the [feature form](${url}/issues/new?template=feature.yml). Describe the problem first, then the change.+- **Ask a question or share what you built** in [Discussions](${url}/discussions).+- **Fix something** with a pull request.++## Local setup++\`\`\`bash+git clone ${url}.git+cd ${name}+${setup.length ? setup.join('\n') : '# follow the setup steps in README.md'}+\`\`\`++## 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.++${license ? `By contributing you agree that your work is licensed under ${license}, the license of this project.` : 'By contributing you agree that your work is licensed under the terms in this repository\'s LICENSE file.'}+`;+}++export function securityMd({ name }) {+ return `# Security Policy++## Reporting a vulnerability++Please do not open a public issue for a vulnerability.++Use GitHub's private reporting: https://github.com/${OWNER}/${name}/security/advisories/new++You will get an acknowledgement within 3 business days and a status update within 10. Fixes ship in the next release with credit to the reporter unless you prefer otherwise.++## Scope++In scope: this repository's code 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 release (or the default branch when there are no releases) receives fixes.+`;+}++export function codeOfConductMd() {+ 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 ${SUPPORT_EMAIL}. Reports are handled in confidence.+`;+}++export function citationCff({ name, description, license }) {+ const q = (s) => `"${oneLine(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;+ return `cff-version: 1.2.0+message: If you use this software, please cite it as below.+title: ${q(name)}+abstract: ${q(description || name)}+${license ? `license: ${license}\n` : ''}repository-code: "https://github.com/${OWNER}/${name}"+url: "${SITE}"+authors:+ - name: three.ws+ website: "${SITE}"+`;+}++export function fundingYml() {+ return `# Adds a Sponsor button to the repo. Links to the product, not to any token.+custom:+ - ${SITE}+`;+}++export function bugForm({ name }) {+ return `name: Bug report+description: Something does not work as documented+labels: [bug]+body:+ - type: input+ id: version+ attributes:+ label: ${name} version or commit+ placeholder: v1.0.0 or a commit SHA+ validations:+ required: true+ - type: input+ id: env+ attributes:+ label: Runtime 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+`;+}++export function featureForm() {+ return `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?+`;+}++export function issueConfig({ name }) {+ return `blank_issues_enabled: false+contact_links:+ - name: Ask a question or share what you built+ url: https://github.com/${OWNER}/${name}/discussions+ about: Open-ended questions belong in Discussions.+ - name: three.ws platform support+ url: ${SITE}+ about: Questions about the hosted platform rather than this repository.+ - name: Security report+ url: https://github.com/${OWNER}/${name}/security/advisories/new+ about: Report a vulnerability privately.+`;+}++export function prTemplate() {+ return `## What changed and why++## How it was checked++- [ ] Tests pass locally (or the change is documentation only)+- [ ] Docs updated where behavior changed+`;+}++/**+ * The files to add, as {path: content}, given what the repo already has.+ * Existing files are never replaced. `files` is the root-relative path set.+ */+export function missingFiles(ctx) {+ const { name, description, files, readme, homepage, pkg, license, language } = ctx;+ const has = (re) => [...files].some((p) => re.test(p));+ const toolchain = detectToolchain(files, pkg);+ const out = {};+ const base = { name, description, language, toolchain, license, homepage, readme };+ if (!has(/^readme/i)) return out;+ if (!has(/^llms-full\.txt$/i)) out['llms-full.txt'] = llmsFullTxt(base);+ const withFull = new Set([...files, ...(out['llms-full.txt'] ? ['llms-full.txt'] : [])]);+ if (!has(/^agents\.md$/i)) out['AGENTS.md'] = agentsMd(base);+ const withAgents = new Set([...withFull, 'AGENTS.md']);+ if (!has(/^llms\.txt$/i)) out['llms.txt'] = llmsTxt({ ...base, files: withAgents });+ if (!has(/^claude\.md$/i)) out['CLAUDE.md'] = claudeMd();+ if (!has(/^(\.github\/)?contributing/i)) out['CONTRIBUTING.md'] = contributingMd(base);+ if (!has(/^(\.github\/)?security\.md$/i)) out['SECURITY.md'] = securityMd(base);+ if (!has(/^(\.github\/)?code_of_conduct/i)) out['CODE_OF_CONDUCT.md'] = codeOfConductMd();+ if (!has(/^citation\.cff$/i)) out['CITATION.cff'] = citationCff(base);+ if (!has(/^\.github\/funding\.yml$/i)) out['.github/FUNDING.yml'] = fundingYml();+ if (!has(/^\.github\/issue_template/i)) {+ out['.github/ISSUE_TEMPLATE/bug.yml'] = bugForm(base);+ out['.github/ISSUE_TEMPLATE/feature.yml'] = featureForm();+ out['.github/ISSUE_TEMPLATE/config.yml'] = issueConfig(base);+ }+ if (!has(/pull_request_template/i)) out['.github/PULL_REQUEST_TEMPLATE.md'] = prTemplate();+ return out;+}diff --git a/scripts/lib/standalone-kit.mjs b/scripts/lib/standalone-kit.mjsindex e2b946f36..2d25f6513 100644--- a/scripts/lib/standalone-kit.mjs+++ b/scripts/lib/standalone-kit.mjs@@ -16,6 +16,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';import { dirname, join } from 'node:path';import sharp from 'sharp';import { pagesUrl } from './standalone-enrich.mjs';+import { applyBadges, applyGrowthBlock, badgeRow, growthBlock } from './repo-growth-kit.mjs';const SITE = 'https://three.ws';const MONOREPO = 'https://github.com/nirholas/three.ws';@@ -77,7 +78,11 @@ export function ecosystemFooter({ pkg, slug, dir }) {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 name = ctx.slug.split('/')[1];+ const files = new Set(['AGENTS.md', 'llms.txt', 'llms-full.txt']);+ const badged = applyBadges(stripped, badgeRow({ name, hasLicense: true }));+ const grown = applyGrowthBlock(badged, growthBlock({ name, description: ctx.pkg.description || '', files, readme: badged }));+ return grown.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'];diff --git a/tests/repo-growth-kit.test.js b/tests/repo-growth-kit.test.jsnew file mode 100644index 000000000..2687e9465--- /dev/null+++ b/tests/repo-growth-kit.test.js@@ -0,0 +1,139 @@+import { describe, it, expect } from 'vitest';+import {+ applyBadges,+ applyGrowthBlock,+ badgeRow,+ growthBlock,+ mergeTopics,+ missingFiles,+ pitchOf,+ shareLinks,+} from '../scripts/lib/repo-growth-kit.mjs';+import { decorateReadme } from '../scripts/lib/standalone-kit.mjs';++const ctx = (over = {}) => ({+ name: 'demo-repo',+ description: 'Does a useful thing for agents. And a second sentence.',+ files: new Set(['README.md', 'LICENSE']),+ readme: '# demo-repo\n\nText.\n',+ homepage: 'https://three.ws',+ pkg: null,+ license: 'MIT',+ language: 'JavaScript',+ ...over,+});++describe('pitchOf', () => {+ it('keeps the first sentence and drops the terminal period', () => {+ expect(pitchOf('One. Two.')).toBe('One');+ });+ it('cuts at a word boundary when too long', () => {+ const out = pitchOf('word '.repeat(60), 40);+ expect(out.length).toBeLessThanOrEqual(40);+ expect(out.endsWith('word')).toBe(true);+ });+ it('strips banned dash glyphs', () => {+ expect(pitchOf('a \u2014 b')).toBe('a: b');+ });+});++describe('shareLinks', () => {+ it('encodes the repo url into every network', () => {+ const links = shareLinks({ name: 'demo-repo', description: 'x' });+ expect(links.length).toBe(5);+ for (const [, href] of links) expect(href).toContain(encodeURIComponent('https://github.com/nirholas/demo-repo'));+ });+});++describe('growth block', () => {+ it('is idempotent: applying twice yields the same README', () => {+ const c = ctx();+ const once = applyGrowthBlock(c.readme, growthBlock({ ...c, files: c.files }));+ const twice = applyGrowthBlock(once, growthBlock({ ...c, readme: once, files: c.files }));+ expect(twice).toBe(once);+ expect(once.match(/three\.ws:growth -->/g).length).toBe(2);+ });+ it('does not add star history or contributors the README already has', () => {+ const readme = '# x\n\n[](https://star-history.com)\n[c](https://contrib.rocks/image?repo=a/b)\n';+ const block = growthBlock({ ...ctx(), readme });+ expect(block).not.toContain('## Star history');+ expect(block).not.toContain('## Contributors');+ });+ it('links agent files only when they exist', () => {+ expect(growthBlock({ ...ctx(), files: new Set() })).not.toContain('Built for AI agents');+ expect(growthBlock({ ...ctx(), files: new Set(['AGENTS.md']) })).toContain('[AGENTS.md](./AGENTS.md)');+ });+ it('inserts above the mirror footer', () => {+ const readme = '# x\n\n<!-- three.ws:ecosystem -->\nfooter\n<!-- /three.ws:ecosystem -->\n';+ const out = applyGrowthBlock(readme, growthBlock(ctx()));+ expect(out.indexOf('three.ws:growth')).toBeLessThan(out.indexOf('three.ws:ecosystem'));+ });+ it('never emits a dash glyph', () => {+ const out = growthBlock({ ...ctx({ description: 'a \u2014 b' }) });+ expect(out).not.toMatch(/[\u2014\u2013]/);+ });+});++describe('badges', () => {+ it('adds a row under the H1 only when the README has no badges', () => {+ const row = badgeRow({ name: 'demo-repo', hasLicense: true });+ const out = applyBadges('# demo\n\nbody\n', row);+ expect(out.indexOf('img.shields.io')).toBeGreaterThan(out.indexOf('# demo'));+ expect(applyBadges('# demo\n\n\n', row)).toContain('![b]');+ expect(applyBadges('# demo\n\n\n', row)).not.toContain('three.ws:badges');+ });+ it('omits the license badge when the repo has no license', () => {+ expect(badgeRow({ name: 'a', hasLicense: false })).not.toContain('github/license');+ });+});++describe('missingFiles', () => {+ it('generates the full discovery and community set for a bare repo', () => {+ const out = missingFiles(ctx());+ for (const f of ['AGENTS.md', 'llms.txt', 'llms-full.txt', 'CLAUDE.md', 'CONTRIBUTING.md', 'SECURITY.md', 'CODE_OF_CONDUCT.md', 'CITATION.cff', '.github/FUNDING.yml', '.github/PULL_REQUEST_TEMPLATE.md', '.github/ISSUE_TEMPLATE/bug.yml']) {+ expect(out).toHaveProperty([f]);+ }+ });+ it('never overwrites a file the repo already has', () => {+ const out = missingFiles(ctx({ files: new Set(['README.md', 'AGENTS.md', 'llms.txt', 'SECURITY.md', '.github/FUNDING.yml']) }));+ expect(out).not.toHaveProperty(['AGENTS.md']);+ expect(out).not.toHaveProperty(['llms.txt']);+ expect(out).not.toHaveProperty(['SECURITY.md']);+ expect(out).not.toHaveProperty(['.github/FUNDING.yml']);+ expect(out).toHaveProperty(['CLAUDE.md']);+ });+ it('does not invent a license', () => {+ expect(missingFiles(ctx({ license: null }))).not.toHaveProperty(['LICENSE']);+ });+ it('funding links the product, never a token', () => {+ expect(missingFiles(ctx())['.github/FUNDING.yml']).toContain('https://three.ws');+ });+ it('uses the repo toolchain for develop commands', () => {+ const out = missingFiles(ctx({ files: new Set(['README.md', 'Cargo.toml']) }));+ expect(out['AGENTS.md']).toContain('cargo test');+ });+});++describe('mergeTopics', () => {+ it('keeps existing topics first and never exceeds 20', () => {+ const existing = Array.from({ length: 19 }, (_, i) => `t${i}`);+ const out = mergeTopics(existing, 'Rust');+ expect(out.slice(0, 19)).toEqual(existing);+ expect(out.length).toBe(20);+ });+ it('adds the discovery topics when there is room', () => {+ const out = mergeTopics(['mcp'], 'TypeScript');+ expect(out).toEqual(expect.arrayContaining(['typescript', 'three-ws', 'ai-agents', 'llms-txt', 'agents-md']));+ });+});++describe('mirror README decoration', () => {+ it('keeps the growth block above the footer and is stable across re-runs', () => {+ const pkg = { name: '@three-ws/demo', description: 'Demo package.' };+ const c = { pkg, slug: 'nirholas/demo', dir: 'packages/demo' };+ const once = decorateReadme('# demo\n\nbody\n', c);+ const twice = decorateReadme(once, c);+ expect(twice).toBe(once);+ expect(once.indexOf('three.ws:growth')).toBeLessThan(once.indexOf('three.ws:ecosystem'));+ });+});