Document org repository landscape for contributors

CONTRIBUTING.md

@@ -47,6 +47,91 @@ Standard PR workflow described in [CLAUDE.md → Git Workflow](CLAUDE.md):
 - Open a PR against `got-feedback/feedBack:main`.
 - Keep commits scoped and well-described; short imperative subject + `Signed-off-by` trailer.
 
+## Repository landscape
+
+FeedBack is the **hub** of the [got-feedback](https://github.com/got-feedback) organization: a self-hosted FastAPI + vanilla JS app (Docker/NAS) with a plugin runtime. Most sibling repositories either ship inside it, wrap it, extend it, or document/specify what it uses. Knowing which repo to target saves you from opening a PR in the wrong place.
+
+```mermaid
+flowchart TB
+    subgraph core["Core"]
+        FB["feedBack<br/>server + UI + core plugins"]
+    end
+
+    subgraph desktop["Desktop distribution"]
+        FBD["feedBack-desktop<br/>Electron + native audio/VST"]
+    end
+
+    subgraph plugins["Org plugins"]
+        P["feedBack-plugin-*<br/>notedetect, stems, splitscreen, …"]
+    end
+
+    subgraph satellite["Satellite services and assets"]
+        DEM["feedBack-demucs-server"]
+        SF["feedBack-soundfonts"]
+        ACH["feedback-achievements"]
+        SPEC["feedpak-spec"]
+        GUIDE["feedBack-user-guide"]
+    end
+
+    subgraph org["Org infrastructure"]
+        GH[".github<br/>CI, release process, plugin governance"]
+    end
+
+    FBD -->|"bundles clone"| FB
+    FBD -->|"build-time clone"| P
+    P -->|"loaded at runtime"| FB
+    FB -->|"optional HTTP"| DEM
+    FBD -->|"downloads"| SF
+    FB -->|"achievements plugin"| ACH
+    FB -->|"reads/writes"| SPEC
+    GUIDE -.->|"documents"| FB
+    GH -.->|"templates and policy"| FB
+    GH -.->|"templates and policy"| FBD
+    GH -.->|"plugin-lint CI"| P
+```
+
+### Where to contribute
+
+| Repository | What it is | Open your PR here when you are changing… |
+|---|---|---|
+| [**feedBack**](https://github.com/got-feedback/feedBack) (this repo) | Core web app: `server.py`, `static/`, `lib/`, Docker image | Server API, highway/WebSocket, library UI, core data models, bundled plugins under `plugins/`, tests in `tests/` |
+| [**feedBack-desktop**](https://github.com/got-feedback/feedBack-desktop) | Electron shell: native audio, VST hosting, installers | Desktop-only audio/VST, packaging, bundling scripts, platform-specific bugs |
+| [**feedBack-plugin-***](https://github.com/orgs/got-feedback/repositories?q=feedBack-plugin) | One repo per org plugin (`plugin.json`, optional `routes.py` / `screen.js`) | A specific plugin's behavior, settings, or backend — **not** core unless you are promoting it to bundled |
+| [**feedpak-spec**](https://github.com/got-feedback/feedpak-spec) | Open `.feedpak` / `.sloppak` format spec, schemas, validator | Chart package format, wire-format fields, authoring docs for chart files |
+| [**feedBack-user-guide**](https://github.com/got-feedback/feedBack-user-guide) | End-user documentation (MkDocs, GitHub Pages) | User-facing how-to articles, screenshots, launch docs — not developer reference in this repo |
+| [**feedBack-demucs-server**](https://github.com/got-feedback/feedBack-demucs-server) | Optional GPU service for stem separation and lyrics alignment | Demucs/WhisperX pipeline, separation API — not the in-app stems toggle UI (that is `feedBack-plugin-stems`) |
+| [**feedback-achievements**](https://github.com/got-feedback/feedback-achievements) | Hosted multi-user "Feats" wall service | The public feats API and wall — not the local `achievements` plugin in `plugins/achievements/` |
+| [**feedBack-soundfonts**](https://github.com/got-feedback/feedBack-soundfonts) | Public GM soundfont release assets | Soundfont files the desktop app downloads at install time |
+| **[`.github`](https://github.com/got-feedback/.github)** | Org-wide CI templates, branching model, release runbooks | Shared workflows, plugin tier policy, migration runbooks — when a change affects every repo |
+
+**Unsure?** Core engine or something every Docker user should get → **feedBack**. One feature area with its own `plugin.json` → the matching **feedBack-plugin-*** repo. Desktop installer or native audio → **feedBack-desktop**.
+
+### Plugin tiers
+
+Plugins are the main extension point. The org distinguishes three tiers ([full policy](https://github.com/got-feedback/.github/blob/main/docs/plugins.md)):
+
+| Tier | Location | Who gets it | Governance |
+|---|---|---|---|
+| **Core (bundled)** | `plugins/` in **feedBack** | Docker image **and** desktop | Full core CI; ships with core releases |
+| **Org** | `got-feedback/feedBack-plugin-*` repos | Desktop build clones them at compile time | Lighter CI via shared [`plugin-lint`](https://github.com/got-feedback/.github/blob/main/.github/workflows/plugin-lint.yml) workflow; plugin maintainer owns day-to-day workflow |
+| **Community** | Personal GitHub accounts | Desktop only, while awaiting org migration | Transitional; org maintains a `-bak` fork as a disappearance backstop |
+
+Core plugins currently in this repo: `achievements`, `highway_3d`, `drum_highway_3d`, `keys_highway_3d`, `tuner`, `folder_library`, `minigames`, `app_tour_library`, `app_tour_settings`, `capability_inspector`, `input_setup`.
+
+Everything else in the desktop installer — note detection, stems, splitscreen, editor, NAM tone, and the rest — lives in separate `feedBack-plugin-*` repositories and is listed in [`feedBack-desktop/scripts/build-common.sh`](https://github.com/got-feedback/feedBack-desktop/blob/main/scripts/build-common.sh). The desktop build clones each entry at compile time; `SLOPSMITH_REF` selects which core branch or tag to bundle (default `main`), and individual plugin lines can append `@<branch>` to pin a non-default ref for release or feature-branch builds.
+
+To add or change a plugin, read the [Plugin System](CLAUDE.md) and [Plugin Best Practices](CLAUDE.md) sections in `CLAUDE.md`. New org plugins should call the reusable `plugin-lint` workflow from [`.github`](https://github.com/got-feedback/.github).
+
+### Why multi-repo?
+
+The split matches how the product is built and shipped:
+
+1. **Two distributions, one core** — NAS/Docker users get a small, auditable image with only bundled plugins. Desktop bundles the same core plus dozens of org plugins cloned at build time. A single monorepo would either bloat every Docker pull or require awkward desktop-only subtrees.
+2. **Plugins are independent products** — Different maintainers, cadences, and dependencies (ML in note detection, GPU services for stems, VST-adjacent audio plugins). Separate repos keep PR noise and CI blast radius local to the feature.
+3. **Stable runtime contract** — Plugins integrate through `plugin.json`, `routes.py` `setup()`, visualization factories, and capabilities (documented in `CLAUDE.md`). Core can evolve the API while plugins catch up on their own branches; desktop pins known-good commits for releases.
+4. **Clear licensing boundaries** — FeedBack is AGPL-3.0. Plugins are loaded at runtime and may use MIT/BSD/Apache-compatible licenses for the curated list. Separate repos keep that boundary explicit.
+5. **Specs and assets outlive the app** — [feedpak-spec](https://github.com/got-feedback/feedpak-spec) serves chart authors who never run the server; [feedBack-user-guide](https://github.com/got-feedback/feedBack-user-guide) serves end users; [feedBack-soundfonts](https://github.com/got-feedback/feedBack-soundfonts) is a public asset host for the desktop installer.
+
 ## Questions
 
 Open an issue or start a [Discussion](https://github.com/got-feedback/feedBack/discussions) if you're unsure whether a contribution fits — much better to ask early than to find out after the work is done.