From 4db9aabe70ec26f2680ac4c4bdd288a8f1e2ae98 Mon Sep 17 00:00:00 2001 From: azghr Date: Sat, 1 Aug 2026 00:09:47 +0500 Subject: [PATCH] docs: add community and discord setup guides and improve docs formatting --- CONTRIBUTING.md | 66 +++++++------- README.md | 90 +++++++++++-------- docs/community.md | 90 +++++++++++++++++++ docs/discord-setup.md | 202 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 378 insertions(+), 70 deletions(-) create mode 100644 docs/community.md create mode 100644 docs/discord-setup.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 079700bf5..37cdb9ded 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,8 @@ WebBrain's agent loop is generic — `click`, `type_text`, `scroll`, even a frontier model struggles to navigate without prior knowledge. The "site adapter" mechanism injects 5-15 lines of hand-written guidance into the agent's first message when it lands on a known site, telling it things like: -*"the body editor is a CodeMirror, not a textarea"* or *"the file upload -input is `input#releases-upload`, not the generic `input[type='file']`"*. +_"the body editor is a CodeMirror, not a textarea"_ or _"the file upload +input is `input#releases-upload`, not the generic `input[type='file']`"_. We have decent coverage for English-first global sites: GitHub, GitLab, Stack Overflow, Hacker News, Gmail, Google Docs/Calendar, Slack, Notion, @@ -29,18 +29,18 @@ What we don't have, and what causes user-facing failures every day, is **adapters for the sites people in non-US markets actually use**. Examples of the kind of thing we'd love a PR for: -| Region | High-priority sites | -|--------|---------------------| -| **Türkiye** | sahibinden.com, hepsiburada.com, trendyol.com, n11.com, yemeksepeti.com, getir.com, gittigidiyor.com | -| **LATAM** | mercadolibre.com.ar / .com.mx / .com.br, olx.com.br, despegar.com, rappi.com | -| **Brasil** | mercadolivre.com.br, americanas.com, magazineluiza.com.br, ifood.com.br | -| **Russia / CIS** | wildberries.ru, ozon.ru, yandex.market, avito.ru, vk.com | -| **India** | flipkart.com, snapdeal.com, swiggy.in, zomato.com, irctc.co.in, paytm.com | -| **SE Asia** | shopee.com, lazada.com, tokopedia.com, traveloka.com, gojek.com, grab.com | -| **East Asia** | rakuten.co.jp, mercari.com, yahoo.co.jp, naver.com, coupang.com | -| **MENA / Gulf** | noon.com, souq.com, hepsiburada (also TR), careem.com, talabat.com | -| **Africa** | jumia.com, takealot.com, kilimall.com | -| **Europe (non-en)** | allegro.pl, leboncoin.fr, bol.com, otto.de, marktplaats.nl, willhaben.at | +| Region | High-priority sites | +| ------------------- | ---------------------------------------------------------------------------------------------------- | +| **Türkiye** | sahibinden.com, hepsiburada.com, trendyol.com, n11.com, yemeksepeti.com, getir.com, gittigidiyor.com | +| **LATAM** | mercadolibre.com.ar / .com.mx / .com.br, olx.com.br, despegar.com, rappi.com | +| **Brasil** | mercadolivre.com.br, americanas.com, magazineluiza.com.br, ifood.com.br | +| **Russia / CIS** | wildberries.ru, ozon.ru, yandex.market, avito.ru, vk.com | +| **India** | flipkart.com, snapdeal.com, swiggy.in, zomato.com, irctc.co.in, paytm.com | +| **SE Asia** | shopee.com, lazada.com, tokopedia.com, traveloka.com, gojek.com, grab.com | +| **East Asia** | rakuten.co.jp, mercari.com, yahoo.co.jp, naver.com, coupang.com | +| **MENA / Gulf** | noon.com, souq.com, hepsiburada (also TR), careem.com, talabat.com | +| **Africa** | jumia.com, takealot.com, kilimall.com | +| **Europe (non-en)** | allegro.pl, leboncoin.fr, bol.com, otto.de, marktplaats.nl, willhaben.at | This list is not exhaustive — if you use a site that WebBrain handles badly, you're probably the right person to write its adapter. **A PR adding one @@ -80,25 +80,25 @@ Each adapter needs four things: Adapter notes are **not documentation for humans**. They're prompt fragments for an LLM that's about to drive the page. The bar is: -- **Imperative voice.** *"Click ``"* not *"You should click ``"*. +- **Imperative voice.** _"Click ``"_ not _"You should click ``"_. - **Names actual selectors, URL patterns, or visible button text** — not vague - guidance. *"The login button is labeled 'Giriş Yap', not 'Login'"* is - useful. *"Be careful with the login flow"* is useless. + guidance. _"The login button is labeled 'Giriş Yap', not 'Login'"_ is + useful. _"Be careful with the login flow"_ is useless. - **Mentions traps the model would otherwise fall into.** That's the whole point. If the search field looks like a normal `` but actually opens a typeahead modal, **say so**. -- **Names the success indicators.** *"After posting, the new listing appears +- **Names the success indicators.** _"After posting, the new listing appears at the top of /ilanlarim with a 'Yayında' (Published) badge — not in - /ilanlar."* -- **Says what NOT to do.** *"Don't click the green 'Hemen Al' button unless - you actually want to buy — there is no confirm dialog."* Anti-patterns + /ilanlar."_ +- **Says what NOT to do.** _"Don't click the green 'Hemen Al' button unless + you actually want to buy — there is no confirm dialog."_ Anti-patterns matter as much as patterns. - **Stays short.** 5-15 bullets. The notes ride along with every first-turn request on that site, so they cost tokens. If your adapter is approaching 20 bullets, split common patterns into shorter sentences or trim the least-likely scenarios. -- **Is dated when the UI is volatile.** If you write *"As of 2026-04, the - listing form is at /ilan-ver/step-1"*, future contributors know how stale +- **Is dated when the UI is volatile.** If you write _"As of 2026-04, the + listing form is at /ilan-ver/step-1"_, future contributors know how stale the note is. A canonical example to imitate is the **github** adapter — it tells the model @@ -109,9 +109,9 @@ the Pull Requests link). ### What bad adapter notes look like -- *"GitHub is a code hosting site."* (Tells the model nothing useful.) -- *"Be careful when posting comments."* (Vague — what specifically goes wrong?) -- *"The site has many features."* (Filler.) +- _"GitHub is a code hosting site."_ (Tells the model nothing useful.) +- _"Be careful when posting comments."_ (Vague — what specifically goes wrong?) +- _"The site has many features."_ (Filler.) - 30+ bullets covering every page on the site. (Exceeds the budget; the model will skim.) - Quoting screenshots or ASCII art. (Tokens you can't afford.) @@ -123,7 +123,7 @@ the Pull Requests link). 2. Open the WebBrain side panel on the target site. 3. **Settings → Display → Site adapters** must be on (it is by default). 4. Run a representative task in Act mode — for sahibinden, something like - *"find me 5 listings under 35,000 TL for X"*. Watch what the agent does. + _"find me 5 listings under 35,000 TL for X"_. Watch what the agent does. 5. Toggle **Settings → Display → Record traces** before the run. After the run, open the Traces page and inspect the timeline. Did the agent hit any of the dead-ends your adapter is meant to prevent? Did it follow @@ -135,7 +135,7 @@ the Pull Requests link). - One adapter per PR is ideal. If you've got two unrelated adapters, two PRs. - Title: `agent: add adapter for `. -- Body: a one-liner of *what real failure mode this adapter prevents*, plus +- Body: a one-liner of _what real failure mode this adapter prevents_, plus one or two trace-based examples if you have them. We don't need a long rationale; we trust your judgment if you've actually used the site. - Mirror to both `src/chrome/` and `src/firefox/` so neither browser regresses. @@ -204,8 +204,8 @@ want a code task. It explains what counts as untrusted page content, the two registries that must stay exhaustive (`UNTRUSTED_CONTENT_TOOLS` and the capability map), and the rule that page-derived bytes must go through `_wrapUntrusted` — not a - prose label. The unit tests check that tools are *listed*, not that you - classified them *correctly*. + prose label. The unit tests check that tools are _listed_, not that you + classified them _correctly_. --- @@ -221,4 +221,8 @@ the commit history, forever. Open a [GitHub Discussion](https://github.com/webbrain-one/webbrain/discussions) or file an issue. Don't email Emre directly with code questions; the -conversation is more useful in public. +conversation is more useful in public. For quick help and community discussion, +join the [WebBrain Discord](https://discord.gg/cgC325ssfw) — see +[`docs/community.md`](docs/community.md) for the channel layout and rules. +Questions that turn into bugs or features should be moved back to a GitHub issue +so they stay tracked. diff --git a/README.md b/README.md index 54212281b..79e8d9a9c 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ Français · Docs · Website · + Discord · MIT License

@@ -65,10 +66,10 @@ Click the WebBrain icon to open the side panel, then type something like: Three modes control what the agent is allowed to do: -| Mode | What it can do | -|---|---| -| **Ask** | Read-only. Reads the page, answers questions, fetches URLs. | -| **Act** | Clicks, types, navigates, uploads, downloads, fills forms. | +| Mode | What it can do | +| ------- | ---------------------------------------------------------------------- | +| **Ask** | Read-only. Reads the page, answers questions, fetches URLs. | +| **Act** | Clicks, types, navigates, uploads, downloads, fills forms. | | **Dev** | Adds page source, styles, console, network, and reversible page edits. | ## Pick a model @@ -138,18 +139,18 @@ The full tool-by-tier matrix, WebMCP notes, and Dev-mode diagnostics are in Type `/help` in the panel for full signatures and flags. The most useful ones: -| Command | What it does | -|---------|--------------| -| `/ask` · `/act` · `/dev` · `/plan` | Switch mode before sending | -| `/schedule [prompt]` | Create a scheduled task | -| `/watch [--keep] [--secs <30-120>] [--long \| --short] [/beep]` | Poll the current page and act when a condition is met | -| `/workflow --save ` | Compile the last successful run into a reusable workflow | -| `/memory --add ` | Save a user preference | -| `/screenshot [--full-page]` | Capture the tab, or the full scrollable page | -| `/record [--transcribe]` | Record the current tab, optionally saving a transcript | -| `/export [--traces \| --config]` | Download the conversation, tool chain, or a Settings snapshot | -| `/compact` · `/reset` · `/verbose` | Compact context, clear the conversation, toggle tool detail | -| `/allow-api` | Per-conversation override letting `fetch_url` mutate when the UI is failing | +| Command | What it does | +| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `/ask` · `/act` · `/dev` · `/plan` | Switch mode before sending | +| `/schedule [prompt]` | Create a scheduled task | +| `/watch [--keep] [--secs <30-120>] [--long \| --short] [/beep]` | Poll the current page and act when a condition is met | +| `/workflow --save ` | Compile the last successful run into a reusable workflow | +| `/memory --add ` | Save a user preference | +| `/screenshot [--full-page]` | Capture the tab, or the full scrollable page | +| `/record [--transcribe]` | Record the current tab, optionally saving a transcript | +| `/export [--traces \| --config]` | Download the conversation, tool chain, or a Settings snapshot | +| `/compact` · `/reset` · `/verbose` | Compact context, clear the conversation, toggle tool detail | +| `/allow-api` | Per-conversation override letting `fetch_url` mutate when the UI is failing | `/watch` runs its first check immediately, then polls every 60 seconds (`--secs` accepts 30–120). Relative conditions like "when a new commit appears" @@ -163,34 +164,45 @@ suffixes: [slash commands](docs/slash-commands.md). Chrome side panel shortcuts work when the WebBrain side panel has focus. -| Shortcut | What it does | -|----------|--------------| -| `Ctrl+/` or `Cmd+/` | Focus the input | -| `Ctrl+Shift+A` or `Cmd+Shift+A` | Switch to Ask mode | -| `Ctrl+Shift+X` or `Cmd+Shift+X` | Switch to Act mode | -| `Ctrl+Shift+D` or `Cmd+Shift+D` | Switch to Dev mode | -| `Escape` | Stop the active run, unless it is only dismissing slash-command autocomplete | -| `Escape` twice | Stop an active recording from WebBrain or browser pages | +| Shortcut | What it does | +| ------------------------------- | ---------------------------------------------------------------------------- | +| `Ctrl+/` or `Cmd+/` | Focus the input | +| `Ctrl+Shift+A` or `Cmd+Shift+A` | Switch to Ask mode | +| `Ctrl+Shift+X` or `Cmd+Shift+X` | Switch to Act mode | +| `Ctrl+Shift+D` or `Cmd+Shift+D` | Switch to Dev mode | +| `Escape` | Stop the active run, unless it is only dismissing slash-command autocomplete | +| `Escape` twice | Stop an active recording from WebBrain or browser pages | ## Documentation -| | | -|---|---| -| [Architecture](docs/architecture.md) | System overview, turn flow, subsystems | -| [Agent tools](docs/agent-tools.md) | Tiers, modes, and the full tool matrix | -| [Slash commands](docs/slash-commands.md) | Every command and flag | -| [Providers and models](docs/providers-and-models.md) | All 104 provider cards, local setup, tiers | -| [Skills](docs/skills.md) | Bundled skills, importing, skill tools | -| [Security model](docs/security-model.md) | Permissions, credentials, trust boundaries | -| [Prompt-injection defense](docs/prompt-injection-defense.md) | Defense layers and known gaps | -| [Privacy and data flow](docs/privacy-and-data-flow.md) | What leaves the browser, and what doesn't | -| [Accessibility tree and refs](docs/accessibility-tree-and-refs.md) | How pages are read and targeted | -| [Site adapters](docs/site-adapters.md) | Per-site guidance | -| [Export and workflow formats](docs/export-and-workflow-formats.md) | `webbrain-config/1`, `webbrain-workflow/1` | -| [Adding a tool](docs/adding-a-tool.md) · [Localization](docs/localization.md) · [Test scenarios](docs/test-scenarios.md) | Contributor guides | +| | | +| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | +| [Architecture](docs/architecture.md) | System overview, turn flow, subsystems | +| [Agent tools](docs/agent-tools.md) | Tiers, modes, and the full tool matrix | +| [Slash commands](docs/slash-commands.md) | Every command and flag | +| [Providers and models](docs/providers-and-models.md) | All 104 provider cards, local setup, tiers | +| [Skills](docs/skills.md) | Bundled skills, importing, skill tools | +| [Security model](docs/security-model.md) | Permissions, credentials, trust boundaries | +| [Prompt-injection defense](docs/prompt-injection-defense.md) | Defense layers and known gaps | +| [Privacy and data flow](docs/privacy-and-data-flow.md) | What leaves the browser, and what doesn't | +| [Accessibility tree and refs](docs/accessibility-tree-and-refs.md) | How pages are read and targeted | +| [Site adapters](docs/site-adapters.md) | Per-site guidance | +| [Export and workflow formats](docs/export-and-workflow-formats.md) | `webbrain-config/1`, `webbrain-workflow/1` | +| [Adding a tool](docs/adding-a-tool.md) · [Localization](docs/localization.md) · [Test scenarios](docs/test-scenarios.md) | Contributor guides | +| [Community](docs/community.md) | Discord server guide: channels, roles, rules, escalation | Also available in [中文](docs/zh-CN/) and [Français](docs/fr/). +## Community + +Chat about everything WebBrain — help, local and cloud model setups, site +adapters, show-and-tell, and contributor coordination — on the +[WebBrain Discord](https://discord.gg/cgC325ssfw). See +[community](docs/community.md) for how the server is organized, and +[discord-setup](docs/discord-setup.md) for the channel, role, and welcome-screen +configuration. Bug reports and feature requests belong in +[GitHub issues](https://github.com/webbrain-one/webbrain/issues), not Discord. + ## Repository layout ``` @@ -216,7 +228,7 @@ SPA-navigation-aware retry, and no CDP screenshots. It uses `tabs.captureTab` for viewport screenshots, including inactive run tabs, but still cannot provide Chrome's pixel-perfect or full-page CDP capture. Site adapters, vision detection, loop detection, the auto-screenshot loop, and the Compact prompt/tool -set *are* mirrored to Firefox. Some single-page apps may also fail to trigger +set _are_ mirrored to Firefox. Some single-page apps may also fail to trigger content-script re-injection after client-side navigation. ## Contributing diff --git a/docs/community.md b/docs/community.md new file mode 100644 index 000000000..9ba63e0ab --- /dev/null +++ b/docs/community.md @@ -0,0 +1,90 @@ +# WebBrain Community + +WebBrain runs a Discord server as the informal home for users, contributors, and +maintainers to discuss everything WebBrain: how to use it, which models and +providers work well, site adapters, feature ideas, show-and-tell, and +coordination between contributors. + +- **Invite:** https://discord.gg/cgC325ssfw +- **Server setup and copy-paste content:** [`discord-setup.md`](discord-setup.md) +- **Rules:** the project [Code of Conduct](../CODE_OF_CONDUCT.md) applies in full. + +Discord is a _support and discussion_ channel. Bug reports, feature requests, +and contributions still belong on +[GitHub](https://github.com/webbrain-one/webbrain) so they stay tracked and +searchable. If a Discord discussion turns into an actionable bug, feature, or +PR, move it to a GitHub issue so it does not get lost in chat. + +## Channel Structure + +| Channel | Purpose | +| ------------------ | ----------------------------------------------------------------------- | +| `#welcome` | One-time welcome message with the rules and a "getting started" pointer | +| `#rules` | Server rules (read-only) | +| `#announcements` | Releases and project news (read-only) | +| `#general` | Anything WebBrain: questions, ideas, conversation | +| `#introductions` | Say hi, tell us what you use WebBrain for | +| `#show-and-tell` | Traces, workflows, adapters, and runs you are proud of | +| `#help` | Getting started, side panel, modes, slash commands | +| `#local-models` | llama.cpp, Ollama, LM Studio, Jan, vLLM, and local provider setups | +| `#providers` | Cloud providers, API keys, context windows, model recommendations | +| `#traces-and-bugs` | Trace debugging and triage. Take confirmed bugs to GitHub issues | +| `#contributing` | Getting started as a contributor, first issues, PR reviews | +| `#site-adapters` | The highest-leverage contribution — see `CONTRIBUTING.md` | +| `#roadmap` | Proposed features and design discussion, mirroring GitHub Discussions | +| `#github-feed` | GitHub bot stream of issues, PRs, and releases | +| `#off-topic` | Non-WebBrain conversation, clearly marked safe space for casual chat | + +## Roles + +| Role | Grant | What it means | +| ------------- | ---------------------------------------------------------- | ----------------------------------------------------------- | +| `Member` | Default | Can read and post in most channels | +| `Contributor` | After a merged PR, issue triage, or sustained support help | Acknowledges contribution; can post in contributor channels | +| `Maintainer` | Maintainers listed in `OWNERS.md` | Project authority, per `GOVERNANCE.md` | +| `Moderator` | Appointed by maintainers | Enforces the Code of Conduct, moves/cleans channels | + +`Contributor`, `Maintainer`, and `Moderator` are granted by maintainers, matching +the roles in [`GOVERNANCE.md`](../GOVERNANCE.md). Being a Discord `Contributor` +does not grant repository rights; merge rights are a separate, GitHub-only +decision. + +## Rules + +1. Be civil. Disagree with the code, not with the person. +2. No spam, self-promotion, or unsolicited DMs. The only exception is show-and-tell + of your own WebBrain workflows in `#show-and-tell`. +3. Do not post credentials, API keys, or traces containing personal data. Traces + should be scrubbed before sharing — see `CONTRIBUTING.md`. +4. Keep security-sensitive discussions in DMs with a maintainer, or file a + private report via `SECURITY.md`. Do not discuss active vulnerabilities publicly. +5. Follow maintainer direction in this server. Escalation paths are below. +6. The project Code of Conduct applies everywhere, including here. + +## Escalation + +- **Channel or thread issues:** ping a `Moderator`. +- **Code of Conduct violations:** message a `Moderator` or `Maintainer` + privately. Maintainers are responsible for enforcing the Code of Conduct + fairly, per `GOVERNANCE.md`. +- **Security vulnerabilities:** report privately, never in a public channel. + Follow `SECURITY.md`. +- **Moderator or maintainer disputes:** the Lead Maintainer makes the final + call, per `GOVERNANCE.md`. + +## Discord vs GitHub + +| You want to... | Where | +| ----------------------------- | ----------------------------------------------------------------- | +| Get quick help using WebBrain | Discord `#help`, `#local-models`, `#providers` | +| Report a bug with a trace | GitHub issue (see `CONTRIBUTING.md`) | +| Ask for a feature | GitHub Discussion, or Discord `#roadmap` for discussion first | +| Contribute an adapter / PR | GitHub, coordinated in Discord `#site-adapters` / `#contributing` | +| Chat about WebBrain casually | Discord `#general` | + +## Setup and Maintenance + +Maintainers (and anyone recreating the server) follow +[`discord-setup.md`](discord-setup.md) for the exact channel list, roles, +welcome-screen copy, and bot configuration. The setup doc is the single source +of truth for server configuration; keep it in sync when the server changes. diff --git a/docs/discord-setup.md b/docs/discord-setup.md new file mode 100644 index 000000000..696cde7e1 --- /dev/null +++ b/docs/discord-setup.md @@ -0,0 +1,202 @@ +# WebBrain Discord Server — Setup Guide + +This is the single source of truth for configuring the WebBrain Discord server +(invite: https://discord.gg/cgC325ssfw). It exists so the server can be +(re)created from scratch quickly, and so channel, role, and copy changes are +reviewable like code. When the live server changes, update this file in the same +PR. + +The community-facing reference (rules, escalation, Discord-vs-GitHub guidance) is +[`community.md`](community.md). Server structure and copy here should stay in +sync with it. + +--- + +## 1. Server Basics + +| Setting | Value | +| -------------------------- | ---------------------------------------------------------------------------------------------- | +| Server name | WebBrain | +| Server description | Official community for the WebBrain AI browser agent — chat, help, adapters, and contributions | +| Invite | `https://discord.gg/cgC325ssfw` | +| Verification level | Low (email verified) | +| Explicit content filter | Keep it enabled at the default | +| Community / welcome screen | On, with the onboarding copy below | +| Rules screening | On — new members must accept `#rules` | + +Recommended settings under **Server Settings → Overview**: + +- Enable **Community** features (enables welcome screen and rules screening). +- Set the **System Messages Channel** to `#announcements`. + +--- + +## 2. Channel Structure + +Create channels in this order, under four categories. + +### Category: Info + +| Channel | Type | Topic | +| ---------------- | ---------------- | ----------------------------------------- | +| `#welcome` | text (read-only) | Landing message with invite reminder | +| `#rules` | text (read-only) | Server rules, accepted by all new members | +| `#announcements` | text (read-only) | Releases, store updates, community news | + +### Category: Community + +| Channel | Type | Topic | +| ---------------- | ---- | -------------------------------------------------- | +| `#general` | text | Anything WebBrain: questions, ideas, conversation | +| `#introductions` | text | Say hi, tell us what you use WebBrain for | +| `#show-and-tell` | text | Traces, workflows, adapters, runs you are proud of | + +### Category: Support + +| Channel | Type | Topic | +| ------------------ | ---- | ----------------------------------------------------------- | +| `#help` | text | Getting started, side panel, modes, slash commands | +| `#local-models` | text | llama.cpp, Ollama, LM Studio, Jan, vLLM and local providers | +| `#providers` | text | Cloud providers, API keys, context windows, model picks | +| `#traces-and-bugs` | text | Trace debugging and triage before a GitHub issue | + +### Category: Development + +| Channel | Type | Topic | +| ---------------- | ---------------- | --------------------------------------------------------- | +| `#contributing` | text | First issues, PR reviews, contributor onboarding | +| `#site-adapters` | text | The highest-leverage contribution — see `CONTRIBUTING.md` | +| `#roadmap` | text | Feature proposals and design discussion | +| `#github-feed` | text (read-only) | GitHub bot stream of issues, PRs, releases | + +### Category: Lounge + +| Channel | Type | Topic | +| ------------ | ---- | ------------------------- | +| `#off-topic` | text | Non-WebBrain conversation | + +`#help` is a good candidate for Discord **Forums** (per-topic threads) once +traffic justifies it; start as a text channel to keep moderation simple. + +--- + +## 3. Roles + +Create roles in this order. Suggested colors keep roles readable in the member +list. + +| Role | Color | Permission baseline | +| ------------- | -------------- | ------------------------------------------------------------------------------------ | +| `Member` | default (grey) | Default `@everyone` permissions | +| `Contributor` | green | `Member` + can post in `#contributing` when it is otherwise gated | +| `Moderator` | orange | `Member` + Manage Messages, Move/Manage Threads, timeout members | +| `Maintainer` | red | `Moderator` + Manage Roles, Manage Channels, Mention Everyone (for `#announcements`) | + +Notes: + +- **`Contributor`** is a thank-you, not a repository right. Grant it to anyone + with a merged PR, sustained support help, or useful issue triage. Granting is a + maintainer decision. +- Keep `#announcements`, `#github-feed`, `#rules`, and `#welcome` **read-only** + for `Member` (Send Messages denied) so announcements stay clean. +- `@everyone` should be able to read everything except nothing-sensitive. Do not + create private channels; if a conversation is sensitive it belongs in DMs. + +--- + +## 4. Rules Message (paste into `#rules`) + +Use Discord's **Rules Screening** with the text below so new members must accept +it before posting. Reuse the same text as a pinned message in `#rules`. + +```text +1. Be civil. Disagree with the code, not with the person. +2. No spam, self-promotion, or unsolicited DMs. The only exception is sharing + your own WebBrain workflows in #show-and-tell. +3. Never post credentials, API keys, or traces containing personal data. + Scrub traces before sharing. +4. Report security issues privately to a maintainer (see SECURITY.md). + Never discuss active vulnerabilities in public channels. +5. Respect maintainer and moderator direction in this server. +6. The project Code of Conduct applies here in full: + https://github.com/webbrain-one/webbrain/blob/main/CODE_OF_CONDUCT.md +``` + +--- + +## 5. Welcome Screen (paste into `#welcome`) + +This is the pinned welcome message and the landing copy for the welcome screen. + +```text +Welcome to the WebBrain community. + +WebBrain is an open-source AI browser agent for Chrome and Firefox. It chats +with web pages, automates multi-step tasks, and runs on your choice of LLM — +local (llama.cpp, Ollama, LM Studio) or cloud (OpenAI, Anthropic, Google, +OpenRouter, and 100+ others). + +Getting started +- Install: https://webbrain.one +- Repo: https://github.com/webbrain-one/webbrain +- Docs: https://webbrain.one/docs + +Where to go +- #help — questions about using WebBrain +- #local-models / #providers — which models work, and how to set them up +- #site-adapters — write guidance for a site you use; it is our highest-value + contribution (see CONTRIBUTING.md) +- #show-and-tell — share traces and workflows +- #general — anything else + +Please read #rules before posting. +``` + +--- + +## 6. Onboarding Flow + +1. Member joins via the invite and lands on the **welcome screen** (rules + + welcome copy above). +2. Rules screening requires accepting `#rules`. +3. A maintainer greets them in `#introductions` when they post there. +4. First merged PR or sustained support help → `Contributor` role. +5. Occasional triage of the GitHub feed → `Contributor`. + +Optional: a bot like _Carl-bot_ or _MEE6_ can auto-assign `Member` on join and +post the welcome message; the plain pinned message works equally well and avoids +an extra bot dependency. + +--- + +## 7. GitHub Bot Feed (optional) + +Post repository activity to `#github-feed` using a bot such as the official +**GitHub** Discord app, or a self-hosted webhook: + +1. Repository: `webbrain-one/webbrain` +2. Events worth posting: issues, pull requests, releases. +3. Keep the channel read-only so the feed stays clean. +4. Point people from the feed back to the repo; Discord is for discussion, GitHub + is where issues and PRs live. + +The webhook secret must not be committed to the repository. Configure it in +Discord's integration settings only. + +--- + +## 8. Moderation Playbook + +- **Spam / abuse:** `Moderator` deletes the message, warns, then timeout as + needed. The project prefers warnings over bans for first offenses. +- **Off-topic:** gently redirect to `#general` or `#off-topic`; move threads when + Discord threads are in use. +- **Bug reports:** help the reporter produce a scrubbed trace and a GitHub issue + in `#traces-and-bugs`; link `CONTRIBUTING.md`. +- **Security reports:** take to DMs with a maintainer immediately; never leave + the details in a public channel. +- **Maintainer disputes:** follow `GOVERNANCE.md` — lazy consensus, then the Lead + Maintainer's call. + +Moderators act for the project per the Code of Conduct. They do not make product +or roadmap decisions; those follow `GOVERNANCE.md`.