docs: add high-level overview of regzbot

CONTRIBUTING.md

@@ -1,3 +1,29 @@
+Codebase overview
+=================
+
+| Area | Files | Role |
+|------|-------|------|
+| Core + DB | `__init__.py` | Regression model, `GitTree`/`GitBranch`, `ReportThread`, `run()`/`generate_web()`/`report()` |
+| Bot commands | `_rbcmd.py` | Parse and execute `#regzbot` subcommands |
+| CLI | `commandl.py` | argparse-based subcommands |
+| Web export | `export_web.py` | Static HTML generation |
+| Mail reports | `export_mail.py` | Weekly text/mail report layout |
+| CSV export | `export_csv.py` | CSV-oriented export (tests) |
+| Lore ingestion | `_repsources/_lore.py` | NNTP and HTTPS access to lore archives |
+| Tracker sources | `_bugzilla.py`, `_gitlab.py`, `_github.py`, `_generic.py` | Tracker-specific API integrations |
+| Tests | `testing_online.py`, `testing_offline.py`, `testing_trackers.py`, `testdata/*` | Offline/online/tracker tests/expected results |
+
+Report sources (pluggable backends):
+
+| Source | Implementation | Notes |
+|--------|----------------|-------|
+| **lore** (NNTP/HTTPS) | `_repsources/_lore.py` | Primary source; kernel mailing list archives |
+| **bugzilla.kernel.org** | `_repsources/_bugzilla.py` | REST API with API key |
+| **GitLab** | `_repsources/_gitlab.py` | Issue tracker integration |
+| **GitHub** | `_repsources/_github.py` | Issue tracker integration |
+
+Tracker polling logic lives in `_repsources/_trackers.py`.
+
 Sign-off Process
 ================
 

README.md

@@ -5,6 +5,24 @@ driven Linux kernel development process. It's actually used in the field, but
 still in a alpha stage: more adjustments are needed to make it better suite the
 its intended purpose.
 
+Regzbot is now part of [KernelCI](https://kernelci.org/), where it contributes
+to coordinated regression tracking across the kernel ecosystem. It monitors
+mailing lists, bug trackers, and Git repositories so reported regressions do
+not slip between first report and a fix in the appropriate kernel tree.
+Reporters and developers interact with it through special lines in emails
+(`#regzbot` commands) or existing conventions (`Link:` / `Closes:` tags in
+commits), keeping overhead minimal.
+
+Kernel development treats regressions with high urgency — fixing them takes
+priority over new features. Before automated tracking, regression reports on
+mailing lists could disappear in the traffic. Regzbot automates the
+bookkeeping: open regressions appear on a public dashboard, periodic mail
+summaries list outstanding issues ahead of releases, and `Link:` tags in fix
+commits tie into tracked regressions without extra manual steps. See the
+kernel documentation for
+[reporting regressions](https://docs.kernel.org/admin-guide/reporting-regressions.html) and
+[handling regressions](https://docs.kernel.org/process/handling-regressions.html).
+
 To get an impression how regression tracking with regzbot is performed in
 practice, see the
 [about page for the Linux kernel regression tracking efforts](https://linux-regtracking.leemhuis.info/about/)
@@ -16,6 +34,22 @@ If you want to interact with regzbot, check out
 
 To install or develop for regzbot, see the [installation documentation](docs/installation.md).
 
+### Public dashboards
+
+| Resource | URL |
+|----------|-----|
+| Tracked regressions (mainline) | https://linux-regtracking.leemhuis.info/regzbot/mainline/ |
+| All views (index) | https://linux-regtracking.leemhuis.info/regzbot/ |
+| About the effort | https://linux-regtracking.leemhuis.info/about/ |
+| Weekly reports (lore search) | [lore.kernel.org](https://lore.kernel.org/lkml/?q=%22Linux+regressions+report%22+f%3Aregzbot) |
+
+### Documentation
+
+* [Getting started](docs/getting_started.md) — report or fix a tracked regression
+* [Reference](docs/reference.md) — full `#regzbot` command syntax
+* [Installation](docs/installation.md) — run your own instance
+* [Contributing](CONTRIBUTING.md) — codebase layout and development
+
 ## Licensing
 
 Rezbot is available under the LGPL 2.1; see the file COPYING for details.

docs/getting_started.md

@@ -3,6 +3,35 @@
 [[_TOC_]]
 
 
+## Background
+
+A **regression** is a change in the kernel that breaks something that previously
+worked — degraded performance, a feature that stops working, or hardware that is
+no longer recognized. Regressions are treated with higher urgency than ordinary
+bugs; see the kernel documentation on
+[reporting regressions](https://docs.kernel.org/admin-guide/reporting-regressions.html) and
+[handling regressions](https://docs.kernel.org/process/handling-regressions.html).
+
+Linux kernel development happens primarily over **email**. A few pieces of this
+infrastructure are relevant to regzbot:
+
+* **Mailing lists** — developers communicate through lists organized by
+  subsystem. `regressions@lists.linux.dev` is specifically for regression
+  reports.
+* **lore.kernel.org** — the public archive of all kernel mailing lists, where
+  every email has a permanent URL.
+* **Message-ID / In-Reply-To / References** — standard email headers that
+  define threading. Regzbot uses these to tie replies, patches, and fixes to the
+  original report.
+* **`Link:` and `Closes:` tags** — conventions in Git commit messages that
+  reference mailing list discussions. Regzbot watches these to detect fixes.
+
+Regzbot tracks three Git trees because fixes arrive at different times:
+**mainline** (`torvalds/linux.git`), **linux-next** (subsystem work before
+mainline), and **stable** (already-shipped kernels). A fix present only in
+linux-next shows as "fix incoming" until it reaches the relevant tree.
+
+
 ## Why and how to make regzbot track a Linux kernel regression
 
 When reporting a Linux kernel regression it is in your interest to make [regzbot](https://gitlab.com/knurd42/regzbot/) aware of the issue, as that ensures the report won't accidentally fall though the cracks; it also makes sure leading developers see the issue via the tracked regression website [or the weekly reports, which are not sent yet, but soon will be].

docs/installation.md

@@ -42,3 +42,23 @@ Now you are ready to run regzbot
     ./regzbot.sh run
 
 It will generate web reports at `~/.cache/regzbot/websites/`
+
+## available commands
+
+| Command | Purpose |
+|---------|---------|
+| `setup` | Initialize database, register sources, first Git tree sync |
+| `run` | Full update cycle (sources → git → web) |
+| `pages` | Regenerate web output only |
+| `report` | Build interactive mail reports (operator sends manually) |
+| `recheck` | Reprocess specific message IDs |
+| `test` | Run offline/online test suites |
+
+## data paths
+
+| Path | Contents |
+|------|----------|
+| `~/.local/share/regzbot/database.db` | SQLite database (tracked regressions, processed message IDs, repository metadata) |
+| `~/.cache/regzbot/gittrees/` | Local Git clones (mainline, next, stable) |
+| `~/.cache/regzbot/websites/` | Generated static HTML output |
+| `~/.config/regzbot/regzbot.cfg` | Configuration file (API keys) |