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(community): give contributors a front door with channels, a first PR path, and triage

nirholas8298fd98dcab
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 207b463d6..eb1e723d4 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,14 +1,26 @@
blank_issues_enabled: false
contact_links:
- - name: 📧 Private or account-specific help
- url: mailto:[email protected]
- about: Billing, account issues, or anything you would rather not post publicly.
+ - name: 💬 Ask in GitHub Discussions
+ url: https://github.com/nirholas/three.ws/discussions
+ about: Design questions, feature ideas, and anything worth keeping searchable.
+ - name: 🚀 Your first contribution
+ url: https://github.com/nirholas/three.ws/blob/main/docs/first-contribution.md
+ about: Clone to open PR in 15 minutes, with a worked example.
+ - name: ✈️ Telegram community
+ url: https://t.me/three_ws_community
+ about: Real-time chat and quick help from other builders.
+ - name: 𝕏 X community
+ url: https://x.com/i/communities/1923523161230078106
+ about: Demos, avatars people built, and launch chatter.
+ - name: 🔷 IBM Community group
+ url: https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016
+ about: Enterprise and integration discussion with the IBM developer community.
- name: 🔒 Report a security vulnerability
url: https://github.com/nirholas/three.ws/security/advisories/new
about: Privately report a security issue. Please do NOT open a public issue.
- - name: 📣 Follow @trythreews on X
- url: https://x.com/trythreews
- about: Product updates, releases, and announcements.
+ - name: 📧 Private or account-specific help
+ url: mailto:[email protected]
+ about: Billing, account issues, or anything you would rather not post publicly.
- name: 📖 Documentation
url: https://three.ws/docs
about: Guides, API reference, and SDK docs.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b9a5651f7..82c606138 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,6 +4,22 @@ Thanks for your interest in contributing! This guide covers everything you need
---
+## Community
+
+| Where | For what |
+| --- | --- |
+| [GitHub Discussions](https://github.com/nirholas/three.ws/discussions) | Design questions, ideas, show and tell |
+| [Telegram community](https://t.me/three_ws_community) | Real-time chat and quick help |
+| [X community](https://x.com/i/communities/1923523161230078106) | Demos and avatars people built |
+| [IBM Community group](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016) | Enterprise and integration discussion |
+| [Release channel](https://t.me/three_ws) | Every user-visible change, pushed on deploy |
+
+Full list with guidance on which room fits which question: [docs/community.md](docs/community.md).
+
+**New here?** [Your first contribution](docs/first-contribution.md) takes you from clone to open pull request in about 15 minutes, with a complete worked example. How we sort and respond to incoming work, including our response targets, is documented in [Triage](docs/triage.md).
+
+---
+
## Quick Start
```bash
@@ -170,6 +186,12 @@ Use the [Khronos glTF Sample Assets](https://github.com/KhronosGroup/glTF-Sample
Looking for something to work on? Here are areas that welcome contributions:
+**Start here:** [`good first issue`](https://github.com/nirholas/three.ws/labels/good%20first%20issue) is curated, not a dumping ground. Every issue on that list names the file to change and the command that proves the change worked. Comment on one to claim it.
+
+The areas that most need help:
+
+- **Rig support**: teach [`src/glb-canonicalize.js`](src/glb-canonicalize.js) a bone-naming convention it does not know yet, so more uploaded avatars animate instead of falling back to a default body. The single highest-leverage self-contained change in the repo. Walked through step by step in [Your first contribution](docs/first-contribution.md).
+- **Animation quality**: new clips for the shared library, or better retargeting in [`src/animation-retarget.js`](src/animation-retarget.js)
- **Bug fixes** — check the [issues page](https://github.com/nirholas/three.ws/issues)
- **New environment maps** — add more HDR options
- **Accessibility** — improve keyboard navigation and screen reader support
diff --git a/README.md b/README.md
index 7b23b7f84..8e8cefe21 100644
--- a/README.md
+++ b/README.md
@@ -8506,6 +8506,7 @@ endsolid threews_avatar
- [Environment Variables](#environment-variables)
- [Testing](#testing)
- [FAQ & Troubleshooting](#faq--troubleshooting)
+- [Community](#community)
- [Contributing](#contributing)
- [Contributors](#contributors)
- [License](#license)
@@ -11289,6 +11290,25 @@ Increment `JWT_KID` and add the new secret. Existing tokens continue to validate
---
+## Community
+
+three.ws is built in the open. Pick the room that fits what you want to do.
+
+| Where | Best for |
+| --- | --- |
+| [GitHub Discussions](https://github.com/nirholas/three.ws/discussions) | Design questions, feature ideas, show and tell |
+| [Telegram community](https://t.me/three_ws_community) | Real-time chat and quick help |
+| [X community](https://x.com/i/communities/1923523161230078106) | Demos, avatars people built, launch chatter |
+| [IBM Community group](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016) | Enterprise and integration discussion |
+| [Release channel](https://t.me/three_ws) | Every user-visible change, pushed automatically on deploy |
+| [@trythreews on X](https://x.com/trythreews) | Product announcements |
+
+Guidance on which channel suits which question, plus the house rules, lives in [docs/community.md](docs/community.md).
+
+**Want to contribute?** [Your first contribution](docs/first-contribution.md) goes from clone to open pull request in about 15 minutes with a complete worked example, and [`good first issue`](https://github.com/nirholas/three.ws/labels/good%20first%20issue) is a curated list where every entry names the file to change and the command that proves it worked. How we triage and how fast you can expect a response: [docs/triage.md](docs/triage.md).
+
+---
+
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide. Contributors are expected to follow the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md) in every project space — issues, pull requests, discussions, and any community channel that links to this repository.
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 77ef6a94f..1ff2a071c 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -24,7 +24,7 @@ bottom.
| Docs World (immersive 3D docs) | [pages/docs-world.html](pages/docs-world.html) `→ /docs/world`, app [src/docs-world/](src/docs-world) (world/player/controls/overlays), styles [public/docs-world.css](public/docs-world.css), shared manifest [docs/nav.json](docs/nav.json) | Live | The documentation as a walkable place: each section of the docs sidebar is a glowing pavilion on a ring; walk up (WASD / touch joystick, four shared camera modes via [src/game/camera-modes.js](src/game/camera-modes.js)) or tap one to list its pages, and read the live markdown in an in-world DOM reader ([src/shared/markdown.js](src/shared/markdown.js)). One content source: both surfaces read `docs/nav.json` + `/docs/<slug>.md`, so classic and immersive docs cannot drift. Deep links mirror the classic hash routes (`/docs/world#forge`); the classic header's "3D world" button carries the open page across. Avatar is the platform's default rigged body (the same one `/walk` uses, since the agent mannequin ships unskinned and cannot be clip-driven) or any rigged GLB via `?avatar=`, animated by the canonical clip library. No-WebGL devices get a designed fallback routing to `/docs`. Docs: [docs/docs-world.md](docs/docs-world.md). Tests: [tests/docs-world.test.js](tests/docs-world.test.js) |
| React avatar creator | [avatar-sdk/](avatar-sdk) `→ /react` `/creator` | Published as `@three-ws/avatar` | Same package, React subpath |
| Avatar CLI (manifests in the build pipeline) | [packages/avatar-cli/](packages/avatar-cli), landing [pages/avatar-cli.html](pages/avatar-cli.html) `→ /avatar-cli`, styles [public/avatar-cli.css](public/avatar-cli.css), page runtime [src/avatar-cli-page.js](src/avatar-cli-page.js) | Published as `@three-ws/avatar-cli` | The terminal half of the avatar story, and the half that makes an avatar auditable. Four commands over one file: `init` scaffolds a schema-valid manifest from a wallet plus a mesh (reading the GLB once to compute its SHA-256 and size, so the document cannot disagree with the bytes it was built from), `validate` checks it against [packages/avatar-schema/](packages/avatar-schema) and exits non-zero so it works as a build gate, `hash` prints a bare digest that composes in a shell, and `preview` emits a resolver URL, an `<agent-3d>` snippet paired with the loader that registers it, and a zero-install iframe. Offline and deterministic throughout: no account, no API key, no network call, which is what makes it safe in a release script. `preview` warns instead of printing a dead snippet when `mesh.uri` is still a local `file://` path. The landing page proves the emitted markup by rendering it live rather than screenshotting it. Docs: [docs/avatar-cli.md](docs/avatar-cli.md) `→ /docs/avatar-cli`, tutorial [docs/tutorials/ship-an-avatar-manifest.md](docs/tutorials/ship-an-avatar-manifest.md). Tests: [packages/avatar-cli/test/](packages/avatar-cli/test) |
-| Rig Doctor (will this GLB animate?) | [pages/rig-doctor.html](pages/rig-doctor.html) `→ /rig-doctor`, analysis [src/rig-report.js](src/rig-report.js), page runtime [src/rig-doctor-page.js](src/rig-doctor-page.js), styles [public/rig-doctor.css](public/rig-doctor.css) | Live | The answer to the most expensive silent failure on the platform: a rig loads, renders, and never moves, because clips address bones by name and this skeleton calls them something else. Drop a `.glb` and the page reads its glTF JSON chunk in the browser, names the authoring convention (eleven fingerprints, from Mixamo and Ready Player Me to Unreal, VRM, Biped, Rigify, and HumanIK), and scores four limb groups independently against the 52-joint canonical set, because "62% covered" is not actionable and "your legs will not move" is. The verdict mirrors the runtime gate in [src/animation-manager.js](src/animation-manager.js) exactly (a skinned mesh plus 8 mapped joints), so it predicts rather than approximates. It then does two things a report cannot: mounts the real [src/avatar-pose.js](src/avatar-pose.js) stage on a blob URL of the file so the user watches their own rig perform the actual clip library, and runs [src/glb-canonicalize.js](src/glb-canonicalize.js) in-browser to hand back a repaired GLB with canonical joint names. Nothing is uploaded: the only network calls are for the clip library and the sample rigs. Also emits a schema-v1 manifest, an `<agent-3d>` snippet, and the matching [packages/avatar-cli/](packages/avatar-cli) commands. Docs: [docs/rig-doctor.md](docs/rig-doctor.md) `→ /docs/rig-doctor`. Tests: [tests/rig-report.test.js](tests/rig-report.test.js) |
+| Rig Doctor (will this GLB animate?) | [pages/rig-doctor.html](pages/rig-doctor.html) `→ /rig-doctor`, analysis [src/rig-report.js](src/rig-report.js), page runtime [src/rig-doctor-page.js](src/rig-doctor-page.js), styles [public/rig-doctor.css](public/rig-doctor.css) | Live | The answer to the most expensive silent failure on the platform: a rig loads, renders, and never moves, because clips address bones by name and this skeleton calls them something else. Drop a `.glb` and the page reads its glTF JSON chunk in the browser, names the authoring convention (twelve fingerprints, from Mixamo and Ready Player Me to Unreal, VRM, MMD, Biped, Rigify, and HumanIK), and scores four limb groups independently against the 52-joint canonical set, because "62% covered" is not actionable and "your legs will not move" is. The verdict mirrors the runtime gate in [src/animation-manager.js](src/animation-manager.js) exactly (a skinned mesh plus 8 mapped joints), so it predicts rather than approximates. It then does two things a report cannot: mounts the real [src/avatar-pose.js](src/avatar-pose.js) stage on a blob URL of the file so the user watches their own rig perform the actual clip library, and runs [src/glb-canonicalize.js](src/glb-canonicalize.js) in-browser to hand back a repaired GLB with canonical joint names. Nothing is uploaded: the only network calls are for the clip library and the sample rigs. Also emits a schema-v1 manifest, an `<agent-3d>` snippet, and the matching [packages/avatar-cli/](packages/avatar-cli) commands. Docs: [docs/rig-doctor.md](docs/rig-doctor.md) `→ /docs/rig-doctor`. Tests: [tests/rig-report.test.js](tests/rig-report.test.js) |
| Talking page guide | [page-agent-sdk/](page-agent-sdk) | Published as `@three-ws/page-agent` | Drop-in rigged 3D agent that narrates any page + visitor avatar picker. `<page-agent>` web component. Rigged-only catalog. `preset="…"` resolves one of 5 personas (greeting/role/suggested-prompt chips/tool allowlist) — see [page-agent-sdk/README.md#persona-presets](page-agent-sdk/README.md#persona-presets). See [page-agent-sdk/PUBLISHING.md](page-agent-sdk/PUBLISHING.md) |
| Guided site tour | [tour-sdk/](tour-sdk) | Published as `@three-ws/tour` | 3D guide walks a live site, spotlights sections, narrates each. One-tag CDN build + free roam |
| Concierge (embeddable AI support chat) | [concierge-sdk/](concierge-sdk), backend [api/concierge.js](api/concierge.js) `→ /api/concierge`, landing [pages/concierge.html](pages/concierge.html) `→ /concierge`, first-party CDN copy `→ /concierge/concierge.global.js` (mirrored by [concierge-sdk/build.mjs](concierge-sdk/build.mjs)) | Published as `@three-ws/concierge` | An AI concierge for ANY website: floating launcher, chat panel with a rigged 3D avatar bust (blink/idle/viseme lipsync via the page-agent stage lineage), SSE-streamed answers grounded in the live page (ask-time DOM harvest + host `knowledge`, no crawler), speaks while streaming (sentence-level TTS handoff), push-to-talk mic, themes/accent/position, avatar picker or custom GLB. Backend is anonymous + CORS-`*` (third-party origins by design) with its own rate buckets (`limits.conciergeIp`/`conciergeGlobal`), no platform-side content filter on the visitor question, and streaming failover over the shared free-first chain (api/_lib/llm.js). Shopping mode (Shopify): when embedded on a Shopify storefront it auto-detects the store (`window.Shopify` / `shop` config) and becomes a shopping assistant, reading the store's public `/products.json` + `/collections.json` + `/policies/*` at ask-time (no key, no crawler, same-origin), retrieving the relevant products per question via keyword+intent search ([concierge-sdk/src/shopify.js](concierge-sdk/src/shopify.js)), grounding the answer in them, and rendering real product cards (image/live price/link + on-store `/cart/add.js` add-to-cart). The endpoint accepts a bounded `shopping` payload and swaps the system prompt to a store assistant. `<three-concierge>` element, `data-concierge` one-tag auto-init, or `new Concierge({...})`. Also reachable from any AI agent via the MCP server [packages/concierge-mcp/](packages/concierge-mcp) (`@three-ws/concierge-mcp`, registry `io.github.nirholas/concierge-mcp`): `concierge_ask` (ask any site's concierge, grounded in the fetched page), `concierge_embed` (generate the embed), `concierge_avatars`. Examples: [concierge-sdk/examples/](concierge-sdk/examples) (one-tag, web component, imperative, custom avatar, React, self-hosted backend). Docs: [docs/concierge.md](docs/concierge.md), tutorial [docs/tutorials/build-a-site-concierge.md](docs/tutorials/build-a-site-concierge.md). Tests: [concierge-sdk/test/](concierge-sdk/test), [tests/api-concierge.test.js](tests/api-concierge.test.js), [packages/concierge-mcp/test/](packages/concierge-mcp/test) |
@@ -439,5 +439,8 @@ gain.
- [README.md](README.md) — product overview, quickstart, full feature list
- [CONTRIBUTING.md](CONTRIBUTING.md) — how to propose changes
+- [docs/community.md](docs/community.md) `→ /docs/community`: every community channel and which room fits which question
+- [docs/first-contribution.md](docs/first-contribution.md) `→ /docs/first-contribution`: clone to open pull request in 15 minutes, with a worked example
+- [docs/triage.md](docs/triage.md) `→ /docs/triage`: how issues and PRs are sorted, label meanings, response targets
- Attribution for derived code and assets — [character-studio/LICENSE](character-studio/LICENSE) (fork of M3-org/CharacterStudio), [src/scene-studio/vendor/LICENSE](src/scene-studio/vendor/LICENSE) (vendored three.js editor), [public/animations/LICENSES.md](public/animations/LICENSES.md), and the per-asset `LICENSES.md` files under [public/club/](public/club)
- [CLAUDE.md](CLAUDE.md) — operating rules for AI agents working in this repo
diff --git a/docs/community.md b/docs/community.md
new file mode 100644
index 000000000..f9f7b6d30
--- /dev/null
+++ b/docs/community.md
@@ -0,0 +1,38 @@
+# Community
+
+three.ws is built in the open and the conversation happens in public. Pick the room that fits what you want to do.
+
+## Where to find us
+
+| Channel | Best for | Link |
+|---|---|---|
+| **GitHub Discussions** | Design questions, feature ideas, showing off what you built, anything worth keeping searchable | [github.com/nirholas/three.ws/discussions](https://github.com/nirholas/three.ws/discussions) |
+| **Telegram community** | Real-time chat, quick help, "is this thing on?" | [t.me/three_ws_community](https://t.me/three_ws_community) |
+| **X community** | Demos, avatars people made, launch chatter | [x.com/i/communities/1923523161230078106](https://x.com/i/communities/1923523161230078106) |
+| **IBM Community group** | Enterprise and integration discussion with the IBM developer community | [community.ibm.com group](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016) |
+| **Release channel** | Every user-visible change, pushed automatically on deploy | [t.me/three_ws](https://t.me/three_ws) and [/changelog](https://three.ws/changelog) |
+| **Issues** | Bugs and concrete feature requests | [github.com/nirholas/three.ws/issues](https://github.com/nirholas/three.ws/issues) |
+| **Security** | Vulnerabilities, privately | [Report an advisory](https://github.com/nirholas/three.ws/security/advisories/new) |
+
+Announcements also go out on [@trythreews](https://x.com/trythreews).
+
+## Which channel for which question
+
+- **"How do I embed an avatar on my site?"** Discussions, Q&A category. The answer helps the next person who searches it.
+- **"The avatar renders as a T-pose."** Open an [issue](https://github.com/nirholas/three.ws/issues/new/choose) with the GLB or a link to it. Rig problems are almost always reproducible and we want the file.
+- **"Look what I made."** [Show and tell](https://github.com/nirholas/three.ws/discussions/categories/show-and-tell) on Discussions, or the X community. We repost good ones.
+- **"Is anyone working on X? I want to help."** Check [`good first issue`](https://github.com/nirholas/three.ws/labels/good%20first%20issue) first, then say so in the issue thread so nobody duplicates your work.
+- **"I found a security hole."** Never a public issue. Use the [advisory form](https://github.com/nirholas/three.ws/security/advisories/new).
+
+## House rules
+
+The [Code of Conduct](../CODE_OF_CONDUCT.md) applies in every one of these rooms, not just the GitHub ones. It is the Contributor Covenant, and it is enforced.
+
+Two additions specific to this project:
+
+- **No trading talk in the technical channels.** three.ws has on-chain surfaces and there is a token in the ecosystem. Price talk belongs nowhere near a bug thread. Issues and Discussions are for the software.
+- **Share the file.** Rendering and rigging bugs are hard to guess at and trivial to diagnose from the actual GLB. If you can share the model, share it.
+
+## Contributing
+
+New here? Start with [Your first contribution](first-contribution.md), a 15-minute path from clone to open PR. The full guide is [CONTRIBUTING.md](../CONTRIBUTING.md), and how we sort incoming work is documented in [Triage](triage.md).
diff --git a/docs/contributing/discussion-seeds.md b/docs/contributing/discussion-seeds.md
new file mode 100644
index 000000000..879379d70
--- /dev/null
+++ b/docs/contributing/discussion-seeds.md
@@ -0,0 +1,119 @@
+# Discussion seeds
+
+Three ready-to-post GitHub Discussions that turn an empty Discussions tab into a live community front door. Written 2026-08-21 for the Open Source Friday application (see [../open-source-friday-plan.md](../open-source-friday-plan.md)), where a community conversation channel is a preference criterion and an empty tab reads as nobody being home.
+
+**These are not posted yet.** The automation token in this workspace has `issues: write` but not `discussions: write`, so a human has to paste them. Each takes about 20 seconds:
+
+| Post | Category | New-discussion link |
+|---|---|---|
+| Welcome | Announcements | [new](https://github.com/nirholas/three.ws/discussions/new?category=announcements) |
+| Show and tell | Show and tell | [new](https://github.com/nirholas/three.ws/discussions/new?category=show-and-tell) |
+| Roadmap | Ideas | [new](https://github.com/nirholas/three.ws/discussions/new?category=ideas) |
+
+Pin the Welcome post after publishing it. Delete this file once all three are live, or leave it as the record of what was posted.
+
+---
+
+## 1. Welcome (Announcements, pin it)
+
+**Title:** `Welcome to three.ws: start here, and introduce yourself`
+
+```markdown
+Welcome. This is the front door for the three.ws community, so start here and say hello.
+
+**three.ws** is an open framework for 3D AI agents on the web. A text prompt becomes a rigged, animation-ready avatar, and one `<agent-3d>` tag drops it into any page with an LLM brain, memory, and moods behind it. Browser-native: Three.js and glTF, no plugin, no game engine.
+
+## Introduce yourself
+
+Reply with:
+
+- What you build, or what brought you here
+- What you would use a 3D agent for
+- One thing that is currently harder than it should be
+
+That last one is the most useful thing you can give us. The best issues in this repo started as somebody saying a thing felt wrong.
+
+## Where everything is
+
+| | |
+|---|---|
+| Try it | [three.ws](https://three.ws) |
+| Will my avatar animate? | [Rig Doctor](https://three.ws/rig-doctor), drop a `.glb` and find out |
+| First contribution, 15 minutes | [docs/first-contribution.md](https://github.com/nirholas/three.ws/blob/main/docs/first-contribution.md) |
+| Curated starter work | [`good first issue`](https://github.com/nirholas/three.ws/labels/good%20first%20issue) |
+| How we triage and how fast we answer | [docs/triage.md](https://github.com/nirholas/three.ws/blob/main/docs/triage.md) |
+| Every channel we are in | [docs/community.md](https://github.com/nirholas/three.ws/blob/main/docs/community.md) |
+| Real-time chat | [Telegram](https://t.me/three_ws_community) |
+| Demos and avatars people built | [X community](https://x.com/i/communities/1923523161230078106) |
+| Enterprise and integration talk | [IBM Community group](https://community.ibm.com/community/user/usergroup?CommunityKey=e71510cc-d953-408f-9a1c-019f5c0a7016) |
+| Every user-visible change | [changelog](https://three.ws/changelog) and [t.me/three_ws](https://t.me/three_ws) |
+
+## Two house rules
+
+The [Code of Conduct](https://github.com/nirholas/three.ws/blob/main/CODE_OF_CONDUCT.md) applies in every room, not just this one. Beyond it:
+
+- **No trading talk in the technical channels.** There are on-chain surfaces in this project. Price chat still does not belong anywhere near a bug thread.
+- **Share the file.** Rendering and rigging bugs are nearly impossible to guess at and trivial to diagnose from the actual GLB.
+
+Welcome aboard.
+```
+
+---
+
+## 2. Show and tell (Show and tell)
+
+**Title:** `Show and tell: what have you built with three.ws?`
+
+```markdown
+Show us what you built with three.ws. Avatars, embeds, agents, weird experiments, half-finished things you are not sure about. All of it.
+
+**A good post has:**
+
+- A screenshot or a screen recording. This is a 3D project. Pixels or it did not happen.
+- One line on what it is
+- A link, if it is live somewhere
+
+**We will:**
+
+- Repost the good ones from [@trythreews](https://x.com/trythreews) and in the [X community](https://x.com/i/communities/1923523161230078106), with credit
+- Turn anything that broke on the way into a real issue
+
+**Things worth showing even if they feel small:** an avatar embedded in a site you already run, a rig that came from an unusual tool, a mood or animation sequence driven from your own page code, an agent doing something we did not design for.
+
+That last category is the most interesting one. If you found a use we did not anticipate, that is a product direction, not a curiosity.
+
+Broke something instead of building something? That is also worth posting. Open an [issue](https://github.com/nirholas/three.ws/issues/new/choose) and link it here.
+```
+
+---
+
+## 3. Roadmap (Ideas)
+
+**Title:** `Roadmap: what should we build next, and what is in your way?`
+
+```markdown
+What should we build next, and what is currently in your way?
+
+This thread is deliberately open. We ship fast and publish every user-visible change to the [changelog](https://three.ws/changelog), which means the roadmap is genuinely steerable by whoever shows up with a good argument.
+
+## The best kind of reply
+
+Not "add feature X", but:
+
+> I was trying to do **[thing]**. I got as far as **[point]**. Then **[what stopped me]**.
+
+That format tells us the shape of the gap instead of one guess at its solution, and it is how most of the good decisions in this project got made.
+
+## Where we think the sharp edges are
+
+Tell us if we are wrong about any of these. Being wrong here is expensive, so an argument against one of them is more valuable than agreement.
+
+- **Rig coverage.** Every humanoid GLB in the wild names bones differently, and we map them to one canonical skeleton so the shared clip library retargets onto anything. Rigs we do not recognise fall back to a default body. If yours does that, [Rig Doctor](https://three.ws/rig-doctor) will tell you exactly which joints we missed, and that list is a contribution: see [#115](https://github.com/nirholas/three.ws/issues/115).
+- **The embed story.** One `<agent-3d>` tag is meant to be all it takes. If integrating into your framework needed more than that, say what.
+- **The agent runtime.** Memory, moods, tools, brains. What is missing for the agent you actually want to build?
+- **Docs.** If you had to read source to answer something, that is a docs bug and we want the specific question.
+
+## What happens to replies here
+
+Anything concrete becomes an issue, linked back to this thread. Anything shipped shows up in the changelog and gets a reply here saying so. Nothing gets quietly dropped.
+```
diff --git a/docs/first-contribution.md b/docs/first-contribution.md
new file mode 100644
index 000000000..796fe2409
--- /dev/null
+++ b/docs/first-contribution.md
@@ -0,0 +1,141 @@
+# Your first contribution
+
+Clone to open pull request in about 15 minutes. No prior knowledge of the codebase assumed.
+
+If you get stuck at any step, ask in [Discussions](https://github.com/nirholas/three.ws/discussions) or the [Telegram community](https://t.me/three_ws_community). A stuck contributor is a bug in this document and we want to hear about it.
+
+---
+
+## 1. Get it running (5 minutes)
+
+```bash
+git clone https://github.com/nirholas/three.ws.git
+cd three.ws
+npm install
+npm run setup
+npm run dev
+```
+
+Open http://localhost:3000. You should see a 3D avatar you can orbit with the mouse.
+
+`npm run setup` is not optional and not the same as `npm install`. It builds the local `solana-agent-sdk` (linked as a `file:` dependency with no prebuilt `dist/`) and generates the gitignored `data/_generated/*` artifacts that the app, the sitemap, and the test suite read. It is idempotent, so re-running it is always safe.
+
+You do **not** need any API keys, a wallet, or a database to work on the rendering, rigging, animation, or docs layers. Those layers are pure client-side JavaScript and their tests run offline.
+
+## 2. Find something to work on
+
+Browse [`good first issue`](https://github.com/nirholas/three.ws/labels/good%20first%20issue). Every one of them names the file to change and the command that proves the change worked.
+
+**Comment on the issue before you start.** One line ("taking this") is enough. It stops two people doing the same work, and it means a maintainer can hand you context before you have written code rather than after.
+
+## 3. A worked example: teach the retargeter a new rig
+
+This is the highest-value first contribution in the project, so here is the whole thing end to end.
+
+### The problem
+
+three.ws ships one library of pre-baked animation clips and plays them on *any* humanoid avatar a user uploads. That only works because every rig gets rewritten to one canonical skeleton first. The trouble is that no two tools name bones the same way. Mixamo says `LeftArm`, Unreal says `upperarm_l`, VRoid says `J_Bip_L_UpperArm`, Daz says `lShldr`.
+
+[`src/glb-canonicalize.js`](../src/glb-canonicalize.js) is the map that reconciles them. Every convention it knows about is a rig that animates; every convention it does not know about falls back to a default body. Adding a convention is a self-contained, high-leverage change with a fast test loop.
+
+### Check what is missing
+
+```js
+// scratch.mjs
+import { canonicalizeBoneName } from './src/glb-canonicalize.js';
+console.log(canonicalizeBoneName('左腕')); // null → not supported yet
+console.log(canonicalizeBoneName('upperarm_l')); // 'LeftArm' → already supported
+```
+
+```bash
+node scratch.mjs
+```
+
+`null` means the bone would be dropped and the rig would score below the retarget coverage floor.
+
+### Make the change
+
+Bone-name variants live in the `EXTRA_ALIASES` map in [`src/glb-canonicalize.js`](../src/glb-canonicalize.js). Entries are keyed by a separator-stripped, lowercased form, and the `put()` helper does that normalization for you. First spelling wins, so listing order is priority order.
+
+A MikuMikuDance rig, for example, names bones in Japanese with a 左 / 右 side prefix:
+
+```js
+// MikuMikuDance (MMD) skeletons name bones in Japanese, side-prefixed
+// with 左 (left) / 右 (right). Extremely common in the VRM/anime avatar
+// ecosystem, and none of these spellings share a stem with any Latin rig.
+for (const [v, c] of [
+ ['センター', 'Hips'], ['上半身', 'Spine'], ['上半身2', 'Spine1'],
+ ['首', 'Neck'], ['頭', 'Head'],
+]) put(v, c);
+for (const [side, prefix] of [['左', 'Left'], ['右', 'Right']]) {
+ put(`${side}肩`, `${prefix}Shoulder`);
+ put(`${side}腕`, `${prefix}Arm`);
+ put(`${side}ひじ`, `${prefix}ForeArm`);
+ put(`${side}手首`, `${prefix}Hand`);
+ put(`${side}足`, `${prefix}UpLeg`);
+ put(`${side}ひざ`, `${prefix}Leg`);
+ put(`${side}足首`, `${prefix}Foot`);
+ put(`${side}つま先`, `${prefix}ToeBase`);
+}
+```
+
+### Prove it
+
+Add a case to [`tests/glb-canonicalize.test.js`](../tests/glb-canonicalize.test.js) beside the existing per-convention blocks:
+
+```js
+it('maps an MMD (Japanese) skeleton', () => {
+ expect(canonicalizeBoneName('センター')).toBe('Hips');
+ expect(canonicalizeBoneName('左腕')).toBe('LeftArm');
+ expect(canonicalizeBoneName('右ひざ')).toBe('RightLeg');
+});
+
+it('never crosses sides', () => {
+ expect(canonicalizeBoneName('左足首')).toBe('LeftFoot');
+ expect(canonicalizeBoneName('右足首')).toBe('RightFoot');
+});
+```
+
+Run just that file. It takes about a second:
+
+```bash
+npx vitest run tests/glb-canonicalize.test.js
+```
+
+Then run the whole suite before you open the PR:
+
+```bash
+npm test
+```
+
+Two rules that will save you a review round:
+
+- **Never cross sides.** A mapping that sends a left bone to a right canonical name tears the avatar apart in motion, and it is the single most common mistake in this file. Test both sides, always.
+- **Do not map bones that are not skeleton joints.** Constraint-driven control rigs, tracker nodes, and metacarpal scaffolding are deliberately left unmapped. The header comment in `glb-canonicalize.js` explains why in detail. Read it before you widen a match.
+
+## 4. Open the pull request
+
+```bash
+git checkout -b feat/mmd-bone-names
+npx prettier --write src/glb-canonicalize.js tests/glb-canonicalize.test.js
+git add src/glb-canonicalize.js tests/glb-canonicalize.test.js
+git commit -m "feat(rig): map MikuMikuDance Japanese bone names to the canonical skeleton"
+git push origin feat/mmd-bone-names
+```
+
+Then open the PR on GitHub. In the description say what changed, what you tested it against, and paste the test output. If you have a real GLB that exercises the change, link it.
+
+**Commit message format:** `type(scope): what changed and why a reader would care`. Plain language, specific to your diff. `wip`, `update`, and `changes` are rejected.
+
+## 5. What happens next
+
+See [Triage](triage.md) for the full flow and response targets. In short: a maintainer reads it, you get real review comments, and merged work shows up in the [public changelog](https://three.ws/changelog).
+
+---
+
+## Other good places to start
+
+- **Animation.** Add a clip to the shared library, or improve the retarget quality in [`src/animation-retarget.js`](../src/animation-retarget.js).
+- **Docs.** Run `npm run audit:docs`. Anything it reports is a real, mechanically verified defect and a legitimate PR.
+- **MCP tools.** Every package under `packages/*-mcp` follows the same shape. Copy the closest one and you have a working new tool.
+- **Whatever annoyed you.** If something in the product felt wrong the first time you used it, that reaction is worth more than any list we could write. Open an issue describing it.
diff --git a/docs/open-source-friday-plan.md b/docs/open-source-friday-plan.md
new file mode 100644
index 000000000..bfb5fb287
--- /dev/null
+++ b/docs/open-source-friday-plan.md
@@ -0,0 +1,188 @@
+# Open Source Friday: application and stream plan
+
+**Goal:** get three.ws booked on GitHub's Open Source Friday livestream (Twitch/github, Fridays 1:00 PM ET) with Andrea Griffiths (@AndreaGriffiths11 / @acolombiadev), who invited us to open the request issue on 2026-08-21.
+
+**Program page:** https://github.com/githubevents/open-source-friday
+**Criteria:** [admin/project-criteria.md](https://github.com/githubevents/open-source-friday/blob/main/admin/project-criteria.md)
+**Request form:** https://github.com/githubevents/open-source-friday/issues/new?template=osf-guest-invite.yml
+
+---
+
+## 1. Where we stand against the criteria
+
+Verified 2026-08-21 against `gh repo view nirholas/three.ws` and the working tree, not from memory.
+
+| Criterion | Status | Evidence |
+|---|---|---|
+| Code of conduct | PASS | [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md), Contributor Covenant, detected by GitHub |
+| Contributing guide | PASS | [CONTRIBUTING.md](../CONTRIBUTING.md), now opening with the community table and the 15-minute onboarding path |
+| **License** | **FAIL** | [LICENSE](../LICENSE) is proprietary: "All rights reserved... may not be used, copied, modified, distributed". GitHub reports `licenseInfo.key: other`. `package.json` and all 67 `packages/*` declare `SEE LICENSE IN LICENSE`. |
+| **100+ stars, hosted on GitHub** | **FAIL by 2** | 98 stargazers, 24 forks |
+| Open to outside contributions | PASS | 11 contributors, issue and PR templates, CODEOWNERS, and six curated open issues (see below) |
+| *Preferred:* community channel | **PASS** | Telegram community, X community, IBM Community group, GitHub Discussions, release channel. All five documented in [docs/community.md](community.md) and wired into the README, CONTRIBUTING, and the new-issue chooser. |
+| *Preferred:* triage team / contributor onboarding | **PASS** | [docs/triage.md](triage.md) (labels, claiming, published response targets) and [docs/first-contribution.md](first-contribution.md) (clone to PR in 15 minutes, worked example) |
+| Guest available Friday 1:00 PM ET | Owner to confirm | Pre-recording is allowed as an exception |
+| Booked at least two weeks ahead | Plan for it | Earliest realistic slot: **2026-09-11** |
+
+### The one thing that still blocks this
+
+**The license.** Everything else is either already true or is now done. Open Source Friday is a program for open source projects, and our repo is publicly described as "Open-source 3D AI agent framework" while shipping a LICENSE that forbids use, copying, modification, and distribution. A reviewer who opens the file sees the contradiction, and the request stalls there no matter how good the demo is.
+
+It is contradicted inside the repo too: [CONTRIBUTING.md](../CONTRIBUTING.md) ends by telling contributors their work "will be licensed under the Apache License 2.0", which is not what LICENSE says. Whatever the outcome, those two files have to agree.
+
+This is an owner decision, not an agent decision. Two workable paths:
+
+- **Option A (recommended): relicense the repo to MIT or Apache-2.0.** MIT is the lowest-friction read for a JS/Three.js ecosystem project and matches most of our dependency tree. Apache-2.0 buys an explicit patent grant, which matters more if the on-chain contracts stay in-repo, and it is what CONTRIBUTING.md already claims. Mechanically: replace `LICENSE`, set `"license"` in the root `package.json` and every `packages/*/package.json` (67, scriptable), update the README License section, add the changelog entry. Contributors so far are the owner plus a small set of collaborators, so there is no large CLA cleanup problem.
+- **Option B: split out an OSS core.** Keep the platform proprietary and publish a genuinely open subset (the `<agent-3d>` web component, `avatar-sdk`, and the glTF canonicalize/retarget layer) as its own repo, then apply with that. Honest, but expensive: a new repo starts at 0 stars and fails criterion 2 on day one.
+
+Option A is the only path that gets us on air this quarter.
+
+### Clearing the two-star gap
+
+98 to 100 is noise, not a campaign. It closes on its own once the relicense is announced, because a license change is a real postable event and its audience is exactly the audience that stars repos. Do not buy, trade, or ask for stars: reviewers look at the repo, and a suspicious star curve is worse than being two short. If it is still under 100 at submit time, submit anyway and mention the relicense in Additional Information.
+
+---
+
+## 2. Pre-flight work
+
+### Done on 2026-08-21
+
+- **Community channels documented and wired.** [docs/community.md](community.md) lists all five rooms with guidance on which fits which question, plus the house rules. Linked from the README (new Community section, in the table of contents), CONTRIBUTING.md, and the GitHub new-issue chooser (`.github/ISSUE_TEMPLATE/config.yml`).
+- **Contributor onboarding written.** [docs/first-contribution.md](first-contribution.md) goes clone to open PR in about 15 minutes, with a complete worked example: teaching the avatar retargeter a bone-naming convention, the test that proves it, and the two mistakes that cost a review round.
+- **Triage documented.** [docs/triage.md](triage.md) publishes response targets (2 business days for a new issue or a first-time contributor's PR, 24 hours for a security advisory), what every label means, how to claim work, and how someone becomes a maintainer.
+- **Six curated issues opened**, every one with a named file and a verification command:
+ - [#110](https://github.com/nirholas/three.ws/issues/110) Rig: Apple / ARKit `_joint`-suffixed skeletons (verified: 0 of 10 joints map today)
+ - [#111](https://github.com/nirholas/three.ws/issues/111) Rig: Kinect trailing-side bone names (verified: 0 of 10)
+ - [#112](https://github.com/nirholas/three.ws/issues/112) Rig: Reallusion CC3/CC4 numbered spine (verified gap)
+ - [#113](https://github.com/nirholas/three.ws/issues/113) Animation: bake a real `bow` clip (the repo's own tracked `known_issue`)
+ - [#114](https://github.com/nirholas/three.ws/issues/114) Tests: drift guard between supported and documented rig conventions
+ - [#115](https://github.com/nirholas/three.ws/issues/115) Rig: teach the retargeter any convention it does not know (open-ended, `help wanted`)
+- **Labels added:** `area: rig`, `area: animation`, `area: docs`, `area: tests`, `triage`.
+- **MMD rig support shipped**, so the worked example in the onboarding doc points at real merged code rather than a hypothetical. MikuMikuDance names every bone in Japanese and mapped zero joints before; the full PMX skeleton now maps (fingers and toes included), Rig Doctor fingerprints the convention on sight, and the IK and twist bones are deliberately left unmapped. 471 tests pass across the two affected suites.
+
+### Still to do
+
+1. **Relicense** (owner call, section 1). Everything below assumes it landed.
+2. **Post the three seeded Discussions.** Written and ready in [contributing/discussion-seeds.md](contributing/discussion-seeds.md): a Welcome post (pin it), a Show and tell thread, and an open Roadmap thread. The workspace token has `issues: write` but not `discussions: write`, so this is 60 seconds of paste by a human. Zero threads is what reads as nobody being home; three real ones fixes it.
+3. **Trim the README's front door.** It is 401 KB. Nobody evaluating a livestream guest reads 401 KB. The first screen needs what it is, a 10-second demo GIF, and the install line. Everything else moves below the fold or into `docs/`.
+4. **Record a 45-second demo clip** (prompt to rigged avatar to embedded on a page). Reusable: README, the issue body, and every amplification post. Per section 5, video and images are what move GitHub's own numbers.
+
+---
+
+## 3. The issue: exact field-by-field content
+
+The form (`osf-guest-invite.yml`) auto-titles as `Open Source Friday - [PROJECT NAME] - [MM-DD-YYYY]`, labels `open-source-friday, open-source, twitch, pending`, and assigns @AndreaGriffiths11, @KevinCrosby, @marlenezw, @madebygps. A date is not required to submit: check "Not yet" and they send the booking link on approval.
+
+**Title:** `Open Source Friday - three.ws - 09-11-2026`
+
+**Name:** Nich (owner to confirm the name they want on air)
+
+**GitHub Handle:** `@nirholas`
+
+**Tell us about yourself:**
+> I build three.ws, an open source framework for 3D AI agents on the web. Background is full-stack and real-time graphics; most of my work now sits at the seam between Three.js rendering and agent runtimes, which is a place where very little tooling existed until recently. I maintain the project day to day: triage, reviews, releases, and docs.
+
+**Project Name:** `three.ws`
+
+**Project Repo Link:** `github.com/nirholas/three.ws`
+
+**Stream Date:** "Not yet" (unless the owner already booked at https://gh.io/osf-booking)
+
+**Dates:** leave blank unless booked
+
+**Twitter URL:** `@nichxbt`
+
+**LinkedIn URL:** owner to supply, or leave blank
+
+**Additional Information:**
+> three.ws turns a text prompt into a rigged, animation-ready 3D avatar and lets you drop it into any website with a single web component tag. It is browser-native (Three.js, glTF/GLB, no plugin, no game engine), and it ships an MCP server so coding agents can create and control avatars directly.
+>
+> What I would like to show live:
+> 1. Prompt to rigged avatar in about a minute, then the same avatar animated by our retargeting layer.
+> 2. Embedding it on a blank HTML page with one `<agent-3d>` tag, and driving its mood and animation from page JavaScript.
+> 3. The part I most want contributors on: universal rig support. Every humanoid GLB in the wild uses a different bone naming convention (Mixamo, VRM, Daz, MakeHuman, Unreal, MikuMikuDance, plain Blender, and a dozen more). We map them all to one canonical skeleton so a shared clip library retargets onto anything. Adding a convention is a genuinely self-contained first contribution: a mapping entry, a test, and a docs row. We keep a curated list of them open, each naming the file to change and the command that proves it worked, and I would like to do one live on the stream.
+>
+> Community: GitHub Discussions, a Telegram community, an X community, an IBM Community group, and a public changelog that ships to a Telegram channel on every release. Contributor onboarding and our triage process, including the response times we hold ourselves to, are documented at /docs/first-contribution and /docs/triage. Happy to pre-record if a Friday slot is tight, though live is preferred.
+
+**Follow-up:** reply to Andrea's thread on X with the issue link once it is open. She asked for the issue; closing that loop publicly is the point.
+
+---
+
+## 4. Stream runsheet (45 to 60 min, live at 1:00 PM ET)
+
+Demo early, code live, end with a concrete ask.
+
+| Time | Segment | Notes |
+|---|---|---|
+| 0:00-0:05 | Intro, who I am, what three.ws is | One sentence, then get to pixels |
+| 0:05-0:12 | Live demo: prompt to rigged avatar | Real generation, no pre-baked cache. Fallback GLB staged in case a worker is slow |
+| 0:12-0:20 | Embed it: one tag on a blank page | Blank `index.html` in a live editor, add `<agent-3d>`, avatar appears, drive mood from the console |
+| 0:20-0:28 | Under the hood: canonical skeleton and retargeting | The technical spine of the project, and the setup for the contribution ask |
+| 0:28-0:42 | Live contribution: add a rig convention | Take [#110](https://github.com/nirholas/three.ws/issues/110) or [#111](https://github.com/nirholas/three.ws/issues/111) live: write the mapping, write the test, run `npx vitest run tests/glb-canonicalize.test.js`, open the PR on air |
+| 0:42-0:50 | MCP server: an agent creating an avatar | Ties into the AI-agent audience the program has leaned toward in 2026 |
+| 0:50-0:60 | How to contribute, good first issues, Q&A | End on the issue list, on screen, by number |
+
+**Prep checklist:** clean clone on a second machine or a fresh worktree so the demo path is the one a viewer gets; workers warm; fallback GLB staged; browser zoom up for readability; no `.env` and no wallet UI on screen at any point.
+
+**Downplay on stream:** the on-chain and payments surfaces. They are real and they are in the repo, but this audience is maintainers and contributors, and leading with crypto costs credibility with exactly the people we want opening PRs. If it comes up, one honest sentence: agents can hold a wallet and pay for their own compute, it is optional, here is where the code lives.
+
+---
+
+## 5. What GitHub's own account tells us about promotion
+
+Analysis of 500 posts from @GitHubCommunity (`GitHubCommunity_tweets_2026-08-21.json`, scraped 2026-08-21). Engagement scored as likes + 3x retweets + replies.
+
+**Media is the single biggest lever.**
+
+| Format | Posts | Avg engagement | Median |
+|---|---|---|---|
+| Image | 73 | 31.0 | 13 |
+| Link card | 30 | 27.4 | 12 |
+| Video | 37 | 20.6 | 8 |
+| Plain text | 360 | 10.5 | 8 |
+
+An image post averages roughly 3x a plain text post on that account.
+
+**Their own OSF announcements are underpowered, and that is our opening.**
+
+141 posts mention Open Source Friday. 134 are the same bare template: `Open Source Friday with <Project>` plus a broadcast link, averaging 9.9 engagement. The 7 carrying an image or video average 16.4. The yearly trend on OSF posts is straight down: 16.6 (2023), 10.5 (2024), 8.7 (2025), 7.1 (2026 to date). Their whole account fell the same way, 27.5 in 2022 to 6.4 in 2026.
+
+Read: **do not rely on GitHub's post to carry the episode.** Their announcement will be a plain link reaching a few hundred views. Reach has to come from our side, and our post is the one that should have the video.
+
+**What actually broke out for them** (the top of the 500): projects with visible output. Game Off showcases with playable browser games (146 likes, 40 K views), Godot game roundups (126 likes, 73 K views), an open source game launch with a funding pool (90 likes, 23 RTs). Every one is "here is a thing you can look at, and then go run yourself". That is our shape exactly: a 3D avatar is a screenshot that explains itself. The second cluster is calls to action with a deadline (Git Merge CFP, conference booth applications, 30 to 48 engagement each).
+
+**Post plan around the episode** (finals go in `docs/x-posts/`, one file each, per repo convention):
+
+1. **T-14, application:** "We just applied to be on GitHub's Open Source Friday" plus the issue link and the 45-second demo clip. Reply into Andrea's thread rather than posting cold.
+2. **T-7, the ask:** the `good first issue` list as a readable numbered image, CTA to claim one before the stream so we can review it live. This is the Git Merge CFP pattern, their best-performing non-showcase format.
+3. **T-1, reminder:** short, image, exact time in ET plus one converted timezone, Twitch link.
+4. **T-0, live:** quote-post GitHub's announcement the minute it goes up, so our audience gets it with a face on it instead of a bare link.
+5. **T+1, replay:** the best 30 seconds of the stream as a standalone clip, plus the merged PR from the live contribution segment. The replay clip usually outperforms the live post because it is watchable on its own.
+
+Every one carries an image or video. No plain-text posts in this sequence. Cross-post each to the [X community](https://x.com/i/communities/1923523161230078106) and the [Telegram community](https://t.me/three_ws_community); the IBM Community group gets the T-7 and T+1 posts only, since it is an enterprise audience and reminder spam reads badly there.
+
+---
+
+## 6. Timeline
+
+Assumes the license call is made this week.
+
+| Date | Milestone | Owner |
+|---|---|---|
+| 2026-08-21 | Community docs, triage, onboarding, six curated issues, labels, MMD rig support | Done |
+| 2026-08-22 | License decision (MIT / Apache-2.0 / split-repo) | Owner |
+| 2026-08-22 | Post the three seeded Discussions, pin the Welcome post | Owner, 60 seconds |
+| 2026-08-24 | Relicense landed: LICENSE, root plus 67 package manifests, README, CONTRIBUTING, changelog | Agent |
+| 2026-08-26 | README front door trimmed, demo clip recorded | Agent |
+| 2026-08-27 | **Issue submitted**, reply posted to Andrea's X thread | Owner |
+| 2026-08-28+ | Booking link arrives on approval, book the slot | Owner |
+| ~2026-09-11 | Stream (earliest date satisfying the two-week rule) | Owner |
+
+---
+
+## 7. Open questions for the owner
+
+Only two, and both are genuinely yours to call:
+
+1. **License: MIT, Apache-2.0, or keep it proprietary and apply with a split-out OSS core?** This gates everything, and it is the only remaining hard failure against the criteria.
+2. **Fridays 1:00 PM ET: live or pre-recorded?** The form allows either. Live is better for the contributor-pipeline story.
diff --git a/docs/triage.md b/docs/triage.md
new file mode 100644
index 000000000..4e4b41706
--- /dev/null
+++ b/docs/triage.md
@@ -0,0 +1,66 @@
+# Triage
+
+How incoming issues and pull requests get sorted, who does it, and what you can expect back. Written for contributors, so you know where your work stands without having to ask.
+
+## Response targets
+
+These are commitments, not aspirations. If we miss one, ping the thread and we will own it.
+
+| Event | Target | What "handled" means |
+|---|---|---|
+| New issue | 2 business days | Labeled, and either a question back, a reproduction confirmation, or a "not planned" with the reason |
+| New pull request from a first-time contributor | 2 business days | A human has read the diff and left a real comment |
+| Pull request follow-up round | 2 business days | Re-review after you push changes |
+| Security advisory | 24 hours | Acknowledged privately, with a fix window |
+| Discussions question | Best effort | Community-first; maintainers answer what stays unanswered |
+
+Nothing gets closed for staleness by a bot. If an issue is real and open, it stays open.
+
+## The triage pass
+
+A maintainer runs the untriaged queue at least twice a week. Every new issue gets:
+
+1. **A type label.** `bug`, `enhancement`, `documentation`, or `question`.
+2. **A verdict.** Reproduced, needs more information, or not planned. Rig and rendering bugs need the GLB; the first response on those is usually a request for the file.
+3. **A contributor signal, where it applies.** `good first issue` if it is genuinely self-contained with a named file and a verification command. `help wanted` if we want outside help but it is not beginner-shaped.
+4. **A home.** Anything touching a path in [CODEOWNERS](../.github/CODEOWNERS) is routed to that owner automatically on the PR.
+
+## Labels and what they actually mean
+
+| Label | Meaning |
+|---|---|
+| `good first issue` | Self-contained, one or two files, the issue names the file to change and the command that proves it worked. No architecture knowledge needed. |
+| `help wanted` | We want an outside contributor on this. Larger than a first issue, still well-scoped. |
+| `bug` | Reproduced, or has enough detail to reproduce. |
+| `enhancement` | Accepted as a direction. An enhancement issue that is still open has not been rejected. |
+| `documentation` | Docs defect or gap. `npm run audit:docs` findings land here. |
+| `question` | Usually gets converted to a Discussion so the answer is searchable. |
+| `duplicate` / `invalid` / `wontfix` | Closed, always with the reason written in the thread. Never closed silently. |
+
+## Claiming work
+
+Comment on the issue before you start. One line is enough. We assign it to you and nobody else picks it up.
+
+If you claim something and life happens, say so and we will unassign it with zero drama. An unclaimed issue helps the next person; a silently abandoned one blocks them.
+
+## Pull request expectations
+
+- Branch from `main`, one topic per PR.
+- `npm test` passes locally before you push.
+- `npx prettier --write` on the files you touched.
+- Commit subject in the form `type(scope): what changed and why a reader would care`. Subjects that describe the act of committing (`wip`, `sync`, `update`, `changes`) are rejected mechanically.
+- Touched a feature whose docs are now wrong? Fix the docs in the same PR. Stale docs are worse than none.
+- User-visible change? It needs an entry in `data/changelog.json`. A maintainer will help you word it if you are unsure; the changelog is written for users, not for engineers.
+
+## Maintainers
+
+Day-to-day triage, review, and releases are handled by [@nirholas](https://github.com/nirholas), with [CODEOWNERS](../.github/CODEOWNERS) routing high-blast-radius paths (contracts, payment rails, published SDKs, security policy) to a required review.
+
+We are actively looking to grow this. The path is the normal one: land a few good PRs, help answer things in [Discussions](https://github.com/nirholas/three.ws/discussions), and we will hand you triage rights. There is no interview.
+
+## Related
+
+- [Your first contribution](first-contribution.md)
+- [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [Community](community.md)
+- [Security policy](../.github/SECURITY.md)
diff --git a/scripts/audit-docs.mjs b/scripts/audit-docs.mjs
index 653e3e713..0c62bb933 100644
--- a/scripts/audit-docs.mjs
+++ b/scripts/audit-docs.mjs
@@ -293,7 +293,9 @@ const UNPUBLISHED_DOCS = new Map([
['memetic-launcher', 'owner-gated: names a crypto project other than $THREE'],
['meta-allocator', 'owner-gated: names a crypto project other than $THREE'],
['money-map', 'internal: revenue-share and treasury routing'],
+ ['nvidia-nemotron-ask-the-experts-questions', 'internal: paste-ready live-chat copy drafted for an external stream'],
['native-launchpad', 'owner-gated: names a crypto project other than $THREE'],
+ ['open-source-friday-plan', 'internal: program application plan and stream runsheet, not a reader-facing product doc'],
['oracle-trading-mcp-plan', 'internal: build order for the Oracle and trading-agent MCP servers, not a reader-facing product doc'],
['nvidia-apps-catalog-listing', 'internal: paste-ready listing copy and portal steps for the NVIDIA Inception catalog'],
['nvidia-apps-catalog-request', 'internal: outbound email asking NVIDIA to publish the catalog listing'],