sbpp
diff --git a/‎AGENTS.md‎
Lines changed: 194 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 194 additions & 0 deletions
diff --git a/‎ARCHITECTURE.md‎
Lines changed: 1 addition & 0 deletions b/‎ARCHITECTURE.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/astro.config.mjs‎
Lines changed: 6 additions & 0 deletions b/‎docs/astro.config.mjs‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎docs/public/announcements.json‎
Lines changed: 1 addition & 0 deletions b/‎docs/public/announcements.json‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/src/content/docs/configuring/announcements.mdx‎
Lines changed: 138 additions & 0 deletions b/‎docs/src/content/docs/configuring/announcements.mdx‎
Lines changed: 138 additions & 0 deletions
diff --git a/‎docs/src/content/docs/updating/1-8-to-2-0.mdx‎
Lines changed: 69 additions & 1 deletion b/‎docs/src/content/docs/updating/1-8-to-2-0.mdx‎
Lines changed: 69 additions & 1 deletion
diff --git a/‎web/includes/Announce/Announcement.php‎
Lines changed: 45 additions & 0 deletions b/‎web/includes/Announce/Announcement.php‎
Lines changed: 45 additions & 0 deletions
@@ -98,6 +98,7 @@ web/
 │   ├── Upload/               Sbpp\Upload\UploadHandler — shared file-upload handler (perm + CSRF + extension allowlist + filename sanitiser + popup chrome) for the demo / icon / mapimage popup pages (goals#5)
 │   ├── Mail/                 Sbpp\Mail\{Mail,Mailer,EmailType} — Symfony Mailer wrapper + enum
 │   ├── Telemetry/            Sbpp\Telemetry\{Telemetry,Schema1} — anonymous opt-out daily ping (#1126); schema-1.lock.json is the vendored cross-repo contract
+│   ├── Announce/             Sbpp\Announce\{AnnouncementFetcher,Announcement} — anonymous opt-out daily fetch of project news / security advisories from https://sbpp.github.io/announcements.json (source of truth: docs/public/announcements.json); admin-only banner on the home dashboard
 │   ├── SteamID/              SteamID parsing / vanity-URL resolution
 │   ├── PHPStan/              Sbpp\PHPStan\* — custom PHPStan rules (Smarty + SQL prefix)
 │   ├── page-builder.php      route() + build() (the page router; procedural)
 
@@ -125,6 +125,12 @@ export default defineConfig({
             { label: 'Database setup', slug: 'setup/mariadb' },
           ],
         },
+        {
+          label: 'Configuring',
+          items: [
+            { label: 'Project announcements', slug: 'configuring/announcements' },
+          ],
+        },
         {
           label: 'Updating',
           items: [
 
@@ -0,0 +1 @@
+[]
@@ -0,0 +1,138 @@
+---
+title: Project announcements
+description: How the dashboard's "Latest announcement" strip works, where the content comes from, and how to opt out.
+sidebar:
+  order: 1
+  label: Project announcements
+---
+
+import { Aside, Code } from '@astrojs/starlight/components';
+
+The home dashboard surfaces a slim "Latest announcement" strip
+between the stat cards and the recent-activity panels — visible only
+to logged-in administrators. Content is sourced from a JSON feed
+the SourceBans++ maintainers publish at:
+
+<Code lang="text" code="https://sbpp.github.io/announcements.json" />
+
+The panel fetches the feed once per install per day in the
+background, caches it on disk, and renders the freshest non-expired
+entry on every dashboard render thereafter. The fetch uses the same
+opt-out-by-default architecture as the panel's update check (a
+shutdown hook fires after the user's response is flushed; it never
+delays a request and never fails one if the upstream is unreachable).
+
+## What gets fetched
+
+The published feed is a public, anonymous-readable JSON file. You
+can open it in your browser and read it yourself — there's no
+hidden state. A typical entry looks like this:
+
+```json
+[
+  {
+    "id": "2026-05-rc1",
+    "title": "v2.0.0 RC1 is now available",
+    "body_md": "Read the [release notes](https://github.com/sbpp/sourcebans-pp/releases/tag/v2.0.0-rc1).",
+    "url": "https://github.com/sbpp/sourcebans-pp/releases/tag/v2.0.0-rc1",
+    "published_at": "2026-05-15T00:00:00Z",
+    "expires_at": "2026-08-15T00:00:00Z"
+  }
+]
+```
+
+Field-by-field:
+
+- `id` — short stable identifier (≤64 chars). Required.
+- `title` — one-line headline. Required.
+- `body_md` — optional Markdown body. Rendered through CommonMark in
+  safe mode (raw HTML is escaped, `javascript:` / `data:` URLs are
+  stripped). Same renderer your dashboard intro uses.
+- `url` — optional "read more" link. Must be `http://` or `https://`.
+- `published_at` — optional ISO-8601 timestamp; sets the displayed
+  date and the sort order.
+- `expires_at` — optional ISO-8601 timestamp. The panel stops
+  rendering the entry after this time and silently drops it from
+  the cache.
+
+## What's NOT sent
+
+The fetch is a plain HTTP `GET` with no query parameters, no
+cookies, no tracking pixels. The only outbound metadata is the
+`User-Agent` header, which carries your panel's version number
+(parity with the existing update-check call):
+
+<Code lang="text" code="User-Agent: SourceBans++/<version> (announcements)" />
+
+## Why this is opt-out by default
+
+The strip is intentionally narrow — single banner, admin-only
+visibility, low-frequency content (security advisories,
+release announcements, occasional release-blocker heads-up). The
+maintainers want to be able to reach panel operators with one-click
+visibility for things like:
+
+- A critical CVE is published — please update.
+- A backwards-incompatible upgrade just landed — read the upgrade
+  notes before running the updater.
+- A new SourceMod / MariaDB version requirement is shipping.
+
+Operators audit content via the **public diff history** of the
+[`docs/public/announcements.json`](https://github.com/sbpp/sourcebans-pp/blob/main/docs/public/announcements.json)
+file. Every change ships through a pull request with the same
+review process as the rest of the project. There's no separate
+"announcements server" or admin-only API endpoint that could be
+compromised independently — the upstream is just a static file in
+this git repo.
+
+The cost of "always on" is one HTTPS GET per install per day to
+sbpp.github.io, capped at 256 KiB of response body, with a 5-second
+timeout. If the upstream is unreachable, the panel keeps showing
+the previously cached announcement until a successful fetch
+overwrites it.
+
+## How to disable the fetch
+
+If your panel runs in an air-gapped environment, or you don't want
+the outbound network call regardless, define
+`SB_ANNOUNCEMENTS_URL` to the empty string in your `config.php`:
+
+```php
+// In web/config.php (or wherever your install keeps it)
+define('SB_ANNOUNCEMENTS_URL', '');
+```
+
+When the constant is the empty string, the shutdown hook
+short-circuits before flushing the response — no network call ever
+fires, the cache file is never written, and the dashboard simply
+omits the strip. There is no in-panel toggle by design: the JSON
+feed is intentionally low-frequency and audit-friendly, so the only
+sensible "off" position is the air-gap escape hatch above.
+
+<Aside type="note">
+The `define()` must run BEFORE `init.php`'s default define fires —
+`config.php` is loaded first, so this works as written. Don't put it
+in a hook that runs later.
+</Aside>
+
+## How announcements are proposed
+
+If you maintain a fork or care about a specific upcoming
+announcement, the workflow is the same as any other change to the
+docs site:
+
+1. Open a PR against
+   [`sbpp/sourcebans-pp`](https://github.com/sbpp/sourcebans-pp).
+2. Edit `docs/public/announcements.json` to prepend your entry
+   (newest-first ordering — the panel sorts by `published_at` but
+   the file convention is "newest at the top of the array" so
+   reviewers see the most relevant change first).
+3. The maintainers will review and merge. The
+   [docs deploy trigger workflow](https://github.com/sbpp/sourcebans-pp/blob/main/.github/workflows/docs-deploy-trigger.yml)
+   ships the updated file to `https://sbpp.github.io/announcements.json`
+   within a few minutes of merge.
+
+The strict schema, audit history, and one-file source-of-truth are
+the load-bearing properties: any operator with internet access can
+inspect every announcement that has ever been pushed before it
+lands on their dashboard.
@@ -13,12 +13,14 @@ changes between 1.8.x and 2.0.x and the prep work an admin should do
 (back up, upload, visit `/updater/`) is the same as any other version —
 see [Updating SourceBans++](/updating/) for that.
 
-The three things to know about the v2.0 upgrade:
+The four things to know about the v2.0 upgrade:
 
 1. The **PHP version floor moves up** to 8.5. Check your host first.
 2. The **active theme resets** to default. Custom themes need
    porting before re-enabling.
 3. **Anonymous telemetry ships on by default.** Opt-out is one click.
+4. A **daily project-announcements feed** also ships on by default
+   for logged-in admins. Opt-out is a one-line `config.php` define.
 
 <Aside type="caution" title="Back up your database first">
 The updater scripts are idempotent, but a half-completed upload is
@@ -177,3 +179,69 @@ N ms remains N ms regardless of telemetry. The cURL call has
 3-second connect / 5-second total timeouts and is silent on
 failure — telemetry can never hard-fail a panel page or a JSON
 API request.
+
+## Project announcements feed
+
+SourceBans++ 2.0.0 also adds a small **admin-only announcements
+strip** to the home dashboard. Once a day per install, the panel
+fetches `https://sbpp.github.io/announcements.json` (a static file
+the maintainers publish from this repo's `docs/public/` directory)
+and renders the freshest non-expired entry as a slim
+`<details>` strip between the dashboard's stat cards and activity
+panels. Anonymous viewers and non-admin users never see the strip.
+
+This is a **second always-on outbound channel** in addition to
+telemetry. Like telemetry, it ships on by default and is
+opt-out-by-config. The two channels are intentionally separate:
+telemetry is a write-only push (panel → collector), announcements
+is a read-only pull (panel ← static JSON). Neither can affect the
+other; opting out of one leaves the other running.
+
+### What's sent
+
+The GET request carries:
+
+- `User-Agent: SourceBans++/<version> (announcements)` — same
+  shape as the existing `system.check_version` release-check
+  fetch.
+- Standard HTTP headers added by PHP's stream wrapper.
+
+Specifically **not** sent:
+
+- No instance ID, no per-install random.
+- No cookies, no `Referer`, no query string, no POST body.
+- Nothing the panel pulls from `sb_settings` or any other table.
+
+The audit trail is the file in this repo at
+[`docs/public/announcements.json`](https://github.com/sbpp/sourcebans-pp/blob/main/docs/public/announcements.json).
+Every announcement is a git commit before it lands on your
+dashboard, so operators can review the full history before the
+deploy chain ships it to `sbpp.github.io`.
+
+### How to opt out
+
+There's no in-panel toggle. Add this line to your
+`web/config.php`:
+
+```php
+define('SB_ANNOUNCEMENTS_URL', '');
+```
+
+The empty string is the documented air-gap escape hatch. The
+panel skips the daily fetch entirely and the dashboard renders
+without the strip. See the
+[announcements feature page](/configuring/announcements/) for
+the full reference (self-hosted mirror, scheme guard, cache
+behaviour).
+
+### Performance impact
+
+Same shape as telemetry: zero on PHP-FPM.
+
+The announcements tick runs in `register_shutdown_function`.
+`fastcgi_finish_request()` closes the user's TCP socket before
+the upstream fetch runs, so the user-perceived response time
+is unaffected. The fetch has a 5-second total timeout, a 256 KiB
+hard cap on the response body, stale-while-error caching, and
+is silent on failure — a flapping `sbpp.github.io` can never
+hard-fail a panel page.
@@ -0,0 +1,45 @@
+<?php
+// SourceBans++ (c) 2014-2026 SourceBans++ Dev Team
+// Licensed under Creative Commons Attribution-NonCommercial-ShareAlike 3.0.
+// See LICENSE.md for the full license text and THIRD-PARTY-NOTICES.txt for attributions.
+
+declare(strict_types=1);
+
+namespace Sbpp\Announce;
+
+/**
+ * One announcement entry as the home dashboard renders it.
+ *
+ * Constructed by {@see AnnouncementFetcher::latest()} from the cached
+ * upstream JSON feed. Body Markdown is pre-rendered through
+ * {@see \Sbpp\Markup\IntroRenderer} so the template can drop
+ * `body_html` straight in via `{nofilter}` without re-running the
+ * renderer per page paint.
+ *
+ * Rendered fields are deliberately the bare minimum the dashboard
+ * strip needs — anything richer belongs upstream in the JSON feed,
+ * not on the disk cache or the wire format. Adding a field here
+ * means revisiting:
+ *   - {@see AnnouncementFetcher::buildAnnouncement()} (the constructor
+ *     call that maps a raw cache entry onto this DTO).
+ *   - The home page handler's {@see \Sbpp\Announce\Announcement}
+ *     → array conversion in `web/pages/page.home.php`, since Smarty
+ *     consumes the array shape (`{$announcement.title}` etc.).
+ *   - The `Sbpp\View\HomeDashboardView` `?array $announcement`
+ *     property's `@var` shape annotation.
+ *   - The template (`page_dashboard.tpl`) — every new field needs an
+ *     `{if $announcement.<field>}` arm or `SmartyTemplateRule` will
+ *     flag the unused property.
+ */
+final class Announcement
+{
+    public function __construct(
+        public readonly string $id,
+        public readonly string $title,
+        public readonly string $body_html,
+        public readonly string $url,
+        public readonly ?int $published_at,
+        public readonly ?string $published_human,
+    ) {
+    }
+}