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.

docs(marketing): add product-led growth surfaces

ni3ade91b11cbf79
diff --git a/marketing/growth/README.md b/marketing/growth/README.md
index 864aac76d..212debcab 100644
--- a/marketing/growth/README.md
+++ b/marketing/growth/README.md
@@ -16,6 +16,8 @@ This directory is the operational layer above the repo's deeper source material:
performed, and what can be pushed again.
- [Opportunity register](./opportunities.md): partner-by-partner asks, new relationship
targets, official intake paths, and the big-brand engagement ladder.
+- [GitHub and ecosystem growth surfaces](./github-growth-surfaces.md): the starter-template,
+ Marketplace Action, curated-directory, adopter-story, and startup-program acquisition loops.
- [90-day campaigns](./campaigns.csv): one row per campaign, with channel, CTA, partner ask,
KPI, date, and status.
- [Opportunity tracker](./opportunities.csv): the machine-readable pipeline. This is where
diff --git a/marketing/growth/github-growth-surfaces.md b/marketing/growth/github-growth-surfaces.md
new file mode 100644
index 000000000..b36448798
--- /dev/null
+++ b/marketing/growth/github-growth-surfaces.md
@@ -0,0 +1,191 @@
+# GitHub and ecosystem growth surfaces
+
+This is the product-led expansion of the [opportunity register](./opportunities.md). It
+focuses on places where using three.ws creates a visible artifact, install, badge, link, or
+contribution in somebody else's workflow. Those surfaces can compound; a one-off post
+cannot.
+
+Last verified: **2026-09-15**.
+
+## What the GitHub audit says
+
+| Signal | Current state | Growth implication |
+| ------------------------ | ---------------: | ---------------------------------------------------------------------------- |
+| Stars / forks | 172 / 40 | There is credible early interest, but not yet a repeatable acquisition loop. |
+| Watchers / open issues | 7 / 9 | Release and contributor activation are underused. |
+| Contributors | 12 | A focused contributor campaign can still feel personal and high-touch. |
+| GitHub releases | 1 | Followers have almost no release-driven reason to return. |
+| Discussions | 3 seeded threads | The showcase exists, but it is not yet an active gallery. |
+| Tracked files | 19,546 | The monorepo is intimidating as the first product experience. |
+| Local packed Git history | about 1.8 GiB | Clone cost is a meaningful activation tax. |
+| Root README | about 411 KB | It demonstrates breadth but delays the shortest path to a win. |
+| Community profile | 100% | Basic trust files are not the constraint. |
+
+The conclusion is not "rewrite the README." Keep the monorepo as the source of truth, but
+put smaller doors in front of it. A user should see a live result before they need to
+understand the platform.
+
+## The first four moves
+
+### 1. Publish a tiny starter template
+
+Create a separate public template repository with only:
+
+- one `npm create @three-ws/agent` path;
+- one committed lightweight sample or deterministic test fixture;
+- one page using `<agent-3d>`;
+- `.devcontainer/devcontainer.json` that starts the demo and forwards its port;
+- a **Use this template** button and a **Create codespace** deep link;
+- three next steps: change the prompt, change the mood, deploy the page.
+
+The success event is not a clone. It is **first avatar rendered**. Track template uses,
+Codespaces starts, successful generation, and downstream repositories that retain the
+three.ws attribution link.
+
+GitHub explicitly supports Codespaces-backed template repositories, where starter files and
+development-container configuration open as a ready environment. Use prebuilds only after
+measuring cold-start pain because each retained regional prebuild has a storage cost.
+
+**Official sources:** [Codespaces from a template](https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template),
+[dev containers](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers),
+[prebuilds](https://docs.github.com/en/codespaces/prebuilding-your-codespaces).
+
+### 2. Turn GLB diff into a Marketplace acquisition loop
+
+Create a single-purpose repository for a **three.ws GLB Quality Gate** GitHub Action. The
+existing [`@three-ws/glb-diff`](../../packages/glb-diff/README.md) already provides the core
+contract: compare two models, format a pull-request-sized Markdown report, classify severity,
+and fail CI at a chosen threshold.
+
+The action should:
+
+1. detect changed `.glb` files in a pull request;
+2. retrieve the base and candidate versions;
+3. comment the structural diff and, where practical, a rendered before/after image;
+4. fail only at the configured severity;
+5. add a small, linked "checked by three.ws" footer.
+
+GitHub recommends one action per public repository for Marketplace publication. That is a
+useful constraint here: the focused repository is easier to install, star, release, and
+explain than another feature inside the monorepo. Marketplace actions can be published
+immediately after the repository, root action metadata, and release meet the requirements.
+
+Measure installs, unique repositories, weekly workflow runs, comments created, footer
+referrals, and conversions into `@three-ws/glb-diff` use.
+
+**Official source:** [Publishing actions in GitHub Marketplace](https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace).
+
+### 3. Claim two high-intent curated directories
+
+The current English READMEs for both target lists contain no `three.ws`, `threews`, or
+`agent-3d` match.
+
+| Surface | Audience | Submission | Proof to lead with |
+| ---------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) | Large MCP discovery audience | Add one installable, public server in alphabetical order; one server per line | The narrow open-source 3D server, local install command, tool list, license, and working example |
+| [Awesome Three.js](https://github.com/AxiomeCG/awesome-threejs) | Three.js builders | Add the web component or GLB tooling under the closest existing category | A tiny live demo and one-sentence developer outcome |
+
+Do not submit the whole platform or a list of every server. The first directory line should
+describe one tool somebody can install and verify in minutes. Record accepted PR traffic with
+a dedicated campaign ID.
+
+### 4. Turn existing adopters into proof
+
+GitHub code search already finds third-party use and coverage outside the canonical
+repository. Start with [Bowyer](https://github.com/BowyerApp/bowyer), an active MIT-licensed
+project that imports three.ws avatar/forge functionality. Ask for a 20-minute implementation
+interview, permission to quote the maintainer, and one screenshot or short recording. Offer
+an upstream fix or integration improvement before asking for promotion.
+
+Then run the same audit monthly:
+
+```text
+code search -> verify real use -> open a helpful issue or PR -> document the outcome
+ -> invite to Show and tell -> publish a maintainer-approved case study
+```
+
+The case-study CTA should point to the exact starter used, not the monorepo homepage.
+
+## Activate the GitHub community surface
+
+The repository has only three seeded Discussions. Convert **Show and tell** into a monthly
+ritual:
+
+- Pin a submission template: screenshot/video, live URL, repository, three.ws component used,
+ and one thing learned.
+- Feature one build in the README, release notes, and community social account each month.
+- Attach a small, well-scoped `good first issue` to each monthly theme.
+- During the approved Open Source Friday session, merge a real contribution into the starter
+ or Action rather than navigating the full monorepo.
+
+If the owner is eligible for GitHub Education, make the starter repository a **Learn and
+Collaborate** submission to Community Exchange. A compliant submission needs a description,
+README, license, `CONTRIBUTING.md`, open collaborator issues, and `LEARN.md`. The canonical
+repository is owned by a personal account, which matches the platform's ownership rule, but
+the smaller starter is the better learning experience.
+
+**Official source:** [Submitting to GitHub Community Exchange](https://docs.github.com/en/education/contribute-with-github-community-exchange/submitting-your-repository-to-github-community-exchange).
+
+## Use CloudCredits as a filter, not a shopping list
+
+[CloudCredits](https://cloudcredits.io/) is useful discovery infrastructure: it indexes more
+than 200 startup programs and keeps its data open in
+[t3-sh/cloudcredits.io](https://github.com/t3-sh/cloudcredits.io). Also use the
+[startup-credits registry](https://github.com/sourcey/startup-credits) as a cross-check because
+it records sources and revisions. Neither directory is sufficient evidence for an
+application; re-verify every benefit and eligibility condition on the provider's official
+site.
+
+Prioritize programs only when they supply distribution or customer access in addition to
+credits:
+
+| Program | Why it passes the filter | Gate before applying |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [DigitalOcean Startups](https://www.digitalocean.com/startups) | Official materials offer marketplace reach, co-marketing support, and event partner opportunities in addition to infrastructure support. | Confirm company and product eligibility, then propose one marketplace-ready developer tool and one customer story. |
+| [MongoDB for Startups](https://www.mongodb.com/solutions/startups) | The program advertises technical support and go-to-market opportunities; select startups can receive co-marketing and co-sell access. | Apply only if the production architecture genuinely uses the product and three.ws meets the current stage rules. |
+
+Do not migrate infrastructure to chase credits. Score the value of customer access,
+technical support, migration cost, lock-in, and engineering distraction separately.
+
+There is also a reciprocal idea: create a real **three.ws Creator Grant** with a defined amount of
+3D generation/rigging capacity, transparent eligibility, duration, support level, and public
+terms. Only after the benefit exists should it be submitted to CloudCredits and similar open
+registries. That turns a directory visit into an acquisition channel without making a false
+"credits" claim.
+
+## Three compounding campaigns
+
+### Build an Agent in 10 Minutes
+
+`starter template -> Codespace -> visible avatar -> Show and tell submission -> monthly feature`
+
+The campaign succeeds when newcomers publish something, not when a launch post gets views.
+
+### Model Review Week
+
+`GLB Action install -> useful pull-request comment -> badge/footer referral -> package adoption`
+
+Recruit five design-engineering or game-tool repositories as design partners before the
+Marketplace launch. Their pull requests become the launch evidence.
+
+### Compatibility Lab
+
+Each month, choose one adjacent open-source 3D or agent project. Build the smallest useful
+integration, contribute it upstream, and publish a two-sided demo. Start with maintainers who
+already use or mention three.ws; expand to cold targets only after the format works.
+
+## Decision sequence
+
+| By | Decision or deliverable | Evidence |
+| ---------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| 2026-09-18 | Choose the starter's single use case and repository name | One-sentence job and reserved repository |
+| 2026-09-21 | Open the starter with a dev container and instrumented success event | Fresh-account run reaches a rendered avatar |
+| 2026-09-23 | Open GLB Action design-partner issue | Five named target repositories and install contract |
+| 2026-09-25 | Submit one focused MCP directory PR | External PR URL and campaign ID |
+| 2026-09-28 | Ask the first verified adopter for an interview | Maintainer reply or next checkpoint |
+| 2026-09-30 | Run the first Show and tell feature | Discussion entry and featured-project link |
+| 2026-10-02 | Decide whether a Creator Grant has a funded, supportable benefit | Published terms or explicit no-go |
+
+External directory pull requests, adopter outreach, program applications, grants, and public
+campaigns remain owner-gated. Prepare the artifact and exact copy first; dispatch only after
+the owner approves the external action.
diff --git a/marketing/growth/opportunities.csv b/marketing/growth/opportunities.csv
index 197dfabaf..a6a5295b1 100644
--- a/marketing/growth/opportunities.csv
+++ b/marketing/growth/opportunities.csv
@@ -22,3 +22,13 @@
"P0","18","VS Code Marketplace: three.ws 3D","installable-distribution","ready_to_package","Resolve publisher identity; package, test, inspect, and publish","Engineering+Owner","2026-09-25","packages/vscode-3d","A complete 3D workflow inside a Microsoft-owned developer surface","Live Marketplace URL and activated install","https://code.visualstudio.com/api/working-with-extensions/publishing-extension","2026-09-15"
"P1","17","Comfy Registry and Manager","installable-distribution","metadata_needed","Add pyproject metadata; create publisher identity; package and publish","Engineering+Owner","2026-10-02","integrations/comfyui","Working Forge nodes available through the native manager","Live Registry URL and first completed generation","https://docs.comfy.org/registry/publishing","2026-09-15"
"P1","16","Blender Extensions","installable-distribution","compliance_needed","Honor online-access setting; add manifest; package and submit","Engineering+Owner","2026-10-09","integrations/blender","A working Forge add-on on Blender's own discovery surface","Live Extension URL and first completed generation","https://developer.blender.org/docs/handbook/extensions/addon_guidelines/","2026-09-15"
+"P0","20","three.ws agent starter template and Codespaces","owned-product-loop","not_started","Create a tiny template repository with one command one demo and a dev container","Owner","2026-09-21","packages/create-agent","A first avatar rendered before a newcomer must clone or understand the monorepo","Live template URL plus template uses Codespaces starts and successful first renders","https://docs.github.com/en/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template","2026-09-15"
+"P0","19","three.ws GLB Quality Gate GitHub Action","owned-install-surface","not_started","Create a single-purpose Action repository and recruit five design partners","Owner","2026-09-23","packages/glb-diff","A useful structural and visual model review inside every adopter pull request","Marketplace URL plus unique installing repositories weekly runs and referral sessions","https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace","2026-09-15"
+"P0","19","Awesome MCP Servers listing","new-directory","verified_absent","Submit one narrow installable open-source 3D server in the required format","Owner","2026-09-25","mcp-server","A verifiable public MCP server with concise install and tool documentation","Accepted external PR URL plus referred sessions and installs","https://github.com/punkpeye/awesome-mcp-servers/blob/main/CONTRIBUTING.md","2026-09-15"
+"P0","18","GitHub Show and tell monthly feature","owned-community","seeded_inactive","Publish a submission template and feature the first community build","Community","2026-09-30","GitHub Discussions Show and tell","Recognition README exposure and a direct maintainer feedback loop","Qualified submissions featured project clicks and contributor conversion","https://github.com/nirholas/three.ws/discussions/categories/show-and-tell","2026-09-15"
+"P1","17","Verified adopter case study","organic-adopter","research_complete","Offer Bowyer an upstream improvement then request a short implementation interview","Owner","2026-09-28","GitHub code-search adoption audit","A maintainer-approved implementation story and useful upstream contribution","Merged contribution interview permission and published case-study URL","https://github.com/BowyerApp/bowyer","2026-09-15"
+"P1","16","Awesome Three.js listing","new-directory","verified_absent","Submit one web component or GLB tool with a tiny live demo","Owner","2026-10-02","packages/glb-diff","A focused open-source tool for the existing Three.js builder audience","Accepted external PR URL plus referred sessions and package installs","https://github.com/AxiomeCG/awesome-threejs","2026-09-15"
+"P1","16","GitHub Community Exchange starter listing","education-channel","eligibility_check","Add LEARN.md and collaborator issues to the starter then submit if owner is Education-eligible","Community","2026-10-09","planned starter repository","A complete visual Learn and Collaborate project for students","Accepted listing URL student forks and first-time contributors","https://docs.github.com/en/education/contribute-with-github-community-exchange/submitting-your-repository-to-github-community-exchange","2026-09-15"
+"P2","15","DigitalOcean Startups distribution route","new-program","eligibility_check","Confirm eligibility and product fit then apply with a marketplace and customer-story plan","Owner","2026-10-16","marketplace-ready developer tool","A useful AI developer product and reproducible startup implementation","Acceptance marketplace placement or provider-owned co-marketing URL","https://www.digitalocean.com/startups","2026-09-15"
+"P2","14","MongoDB for Startups GTM route","new-program","architecture_and_eligibility_check","Verify production usage and current stage requirements before applying","Owner","2026-10-16","production data architecture","A genuine production implementation with a visual AI customer outcome","Acceptance assigned support and provider-owned GTM placement","https://www.mongodb.com/solutions/startups","2026-09-15"
+"P2","13","three.ws Creator Grant and CloudCredits listing","owned-acquisition-offer","owner_decision_required","Define a funded generation benefit eligibility support capacity and public terms or record no-go","Owner","2026-10-02","free generation and rigging lanes","A real transparent startup or creator benefit that open registries can verify","Published terms followed by accepted directory listing and activated grantees","https://cloudcredits.io/","2026-09-15"