From 66957c34dba5398474323606001e09da5380ca3d Mon Sep 17 00:00:00 2001
From: David Keane <david@davidtkeane.com>
Date: Tue, 9 Jun 2026 02:24:53 +0100
Subject: [PATCH] wiki: initial 5 pages (Home / Architecture / Roadmap /
 Privacy / FAQ / Family)

Mirrors the rangerhq-tuner wiki pattern so the RangerHQ family
stays coherent across surfaces. Each page written specifically to
make the wp.org reviewer's verification job easy:

- Home: overview, status table, source layout, install
- Architecture: per-user wp_usermeta storage, inline-SVG renderer,
  CSS-only animations, the four load-bearing decisions, Tier-1
  admin discipline notes (esc_html, no inline styles, etc.)
- Roadmap: Phase A done -> B (interactions) -> C (decay) ->
  D (species) -> E (site health, the headline feature) -> F (Pro)
- Privacy: per-user wp_usermeta inventory, zero outbound requests,
  GDPR notes, how-to-wipe runbook
- FAQ: 13 common questions
- Family: positions Buddy against Radio + Tuner + future Logbook
  with the 'RangerHQ promise' (GPL, no telemetry, etc.)
---
 Architecture.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++
 FAQ.md          |  65 ++++++++++++++++++++++++++++
 Family.md       |  60 ++++++++++++++++++++++++++
 Home.md         |  70 ++++++++++++++++++++++++++++++
 Privacy.md      |  76 ++++++++++++++++++++++++++++++++
 Roadmap.md      |  94 ++++++++++++++++++++++++++++++++++++++++
 6 files changed, 477 insertions(+)
 create mode 100644 Architecture.md
 create mode 100644 FAQ.md
 create mode 100644 Family.md
 create mode 100644 Home.md
 create mode 100644 Privacy.md
 create mode 100644 Roadmap.md

diff --git a/Architecture.md b/Architecture.md
new file mode 100644
index 0000000..e2e1119
--- /dev/null
+++ b/Architecture.md
@@ -0,0 +1,112 @@
+# Architecture
+
+RangerHQ Buddy is hand-rolled PHP — no frameworks, no Composer dependencies, no build step. The whole plugin is ~6 PHP files, one stylesheet, and zero JavaScript. Currently ~28 KB packaged.
+
+## High-level component map
+
+```
+   wp-admin
+   ┌────────────────────────────────────────────────────────────────┐
+   │  WP Dashboard                                                  │
+   │  ┌──────────────────────────────────┐                          │
+   │  │  Buddy Dashboard Widget          │  inc/dashboard-widget.php│
+   │  │  - sprite (sm)                   │                          │
+   │  │  - name + mood                   │                          │
+   │  │  - four stat bars (h/h/h/e)      │                          │
+   │  └──────────────────────────────────┘                          │
+   │                                                                │
+   │  Sidebar: 🐾 Buddy ▾                                           │
+   │  ├─ My Buddy       inc/admin-page.php                          │
+   │  ├─ Settings       inc/settings.php   (rename Buddy)           │
+   │  └─ About          inc/about.php      (roadmap + version)      │
+   └────────────────────────────────────────────────────────────────┘
+                            │
+                            │ buddy_get_state / buddy_update_state
+                            ▼
+   ┌────────────────────────────────────────────────────────────────┐
+   │  inc/state.php — per-user storage in wp_usermeta               │
+   │  Key: 'buddy_state'                                            │
+   │  Shape: { name, species, hunger, happiness, health, energy,    │
+   │           born_at, last_tick }                                 │
+   └────────────────────────────────────────────────────────────────┘
+                            │
+                            │ values feed → mood label + tone selection
+                            ▼
+   ┌────────────────────────────────────────────────────────────────┐
+   │  inc/sprite.php — inline-SVG renderer                          │
+   │  buddy_render_sprite( $tone, $size )                           │
+   │  - tones: happy / neutral / sad / wink (cheeky surprise)       │
+   │  - sizes: sm / md / lg                                         │
+   │  - no image files, no GIFs — every pixel is SVG                │
+   │  - CSS keyframes drive bobbing + blinking, NOT JS              │
+   └────────────────────────────────────────────────────────────────┘
+```
+
+## The four load-bearing decisions
+
+### 1. Per-user state in `wp_usermeta` (not `wp_options`)
+
+Each WP admin user gets their own Buddy. Storage is `update_user_meta( $user_id, 'buddy_state', $state )`. This means multi-admin sites work perfectly — Alice's Buddy is independent of Bob's. Nothing is shared between accounts.
+
+The alternative (a single `wp_options` row for the whole site) would have meant either everyone shares one Buddy or a complex multi-row schema. `wp_usermeta` makes per-user a one-liner.
+
+### 2. Inline-SVG character (no GIFs, no sprite sheets, no PNGs)
+
+`inc/sprite.php` outputs an `<svg>` element directly into the page HTML. Eye shapes, mouth curves, cheek dots — all paths/circles in SVG, all parameterised by the `$tone` and `$size` arguments. Switching mood doesn't change the image; it changes a couple of SVG element attributes.
+
+Why: zero asset weight, zero HTTP requests for the character, infinite scalability, easy to extend (add a new mood by adding a few SVG elements, not by drawing a new sprite sheet).
+
+### 3. CSS-only animations (no JavaScript)
+
+Bobbing motion and periodic blinking are CSS keyframes in `assets/css/buddy.css`. The wink animation that landed in v0.1.3 is also a CSS animation, not a JS timer. The plugin ships **zero JavaScript** for the character itself.
+
+The only JS in the whole plugin is the WP-native admin form scaffolding (the rename form on the Settings page uses standard WordPress nonces and a POST submission — no AJAX).
+
+### 4. Tier-1 admin discipline
+
+Carried forward from the broader RangerHQ family submission discipline (see [[Family]]):
+
+- Single `<h1>` per admin page (accessibility + WordPress conventions)
+- No nested toggle boxes
+- No duplicate sections
+- Output escaping on every user-facing string (`esc_html_e`, `esc_attr_e`, etc.)
+- Text-domain alignment across every translation call (`'rangerhq-buddy'`)
+- `wp_rand()` instead of `mt_rand()` for any randomness
+- All CSS in enqueued stylesheets — **no inline `<style>` blocks, no inline `style="..."` attributes** (lesson hard-won in v0.1.5 after wp.org reviewer flagged it)
+
+## File-by-file walkthrough
+
+If you've cloned the repo and want to understand the flow, read these files in order:
+
+1. **`buddy.php`** — the entry point WordPress sees. Plugin header (Plugin Name, version, text domain), constants (`BUDDY_VERSION`, paths), `require_once` for the `inc/*.php` files, `admin_menu` registration, `admin_enqueue_scripts` enqueue, activation hook.
+2. **`inc/state.php`** — `buddy_default_state()`, `buddy_get_state()`, `buddy_update_state()`. The data layer.
+3. **`inc/sprite.php`** — `buddy_render_sprite( $tone, $size )`. The SVG character renderer.
+4. **`inc/dashboard-widget.php`** — registers the WP Dashboard widget via `wp_add_dashboard_widget()`. Calls `buddy_get_state()` + `buddy_render_sprite('happy', 'sm')` + renders stat bars.
+5. **`inc/admin-page.php`** — the dedicated "My Buddy" page in the sidebar. Larger sprite + same data.
+6. **`inc/about.php`** — the About page (intro, "what Buddy does today", roadmap, version history). All inline styles removed in v0.1.5.
+7. **`inc/settings.php`** — the rename-Buddy form. Nonce + POST handling.
+
+Total reading time end-to-end: about 15 minutes.
+
+## Permission profile (deliberately narrow)
+
+Buddy is a wp-admin-only plugin. It:
+
+- ❌ **Does NOT** register front-end shortcodes
+- ❌ **Does NOT** enqueue assets on the public site
+- ❌ **Does NOT** create custom post types, taxonomies, or REST API endpoints
+- ❌ **Does NOT** call any external service (no API requests, no telemetry, no CDN fonts)
+- ✅ Only loads its CSS on the four admin pages it owns (Dashboard, My Buddy, Settings, About)
+- ✅ Stores everything in `wp_usermeta` on the user's own WP site
+
+## What's coming (Phase B onwards)
+
+See [[Roadmap]] for the full phase plan. Architectural changes anticipated:
+
+- **Phase B (Interactions):** Feed / Play / Clean / Sleep buttons — will add a small `inc/actions.php` with cooldown timer logic, AJAX endpoints, and a single new JS file (the first JS the plugin will ever ship).
+- **Phase C (Decay):** WP-cron event that lowers stats over time when the user is away. Pure server-side, no JS.
+- **Phase D (Species):** Multi-species sprite renderer. `inc/sprite.php` will grow species-specific path libraries.
+- **Phase E (Site health):** `wp_get_site_health()` results feed into mood/stat calculations. Pure server-side hook.
+- **Phase F (Pro):** Custom skins, multi-pet farm, social visits.
+
+The core architecture (per-user state, inline-SVG, CSS animations) is locked and won't change across phases.
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..8394a73
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,65 @@
+# FAQ
+
+## Is each user's Buddy private?
+
+Yes. Buddy is stored per-user in `wp_usermeta` under the `buddy_state` key. Other admins on the same site cannot see your Buddy, and you cannot see theirs. WordPress's user-meta API enforces this — there is no shared site-wide state.
+
+## Does Buddy send any data off my site?
+
+No. RangerHQ Buddy makes zero outbound HTTP requests. No telemetry, no analytics, no fonts from a CDN, no third-party JavaScript. Everything stays on your own WordPress installation. See [[Privacy]] for the full audit.
+
+## Will Buddy slow down my site?
+
+No. The plugin only loads on the four admin pages it owns (Dashboard, My Buddy, Settings, About). It does not enqueue assets on the public-facing site, doesn't run on every admin page, and uses inline SVG (no image files, no extra HTTP requests) for the character. The CSS file is small. There is no JavaScript framework involved.
+
+## Can I have more than one Buddy?
+
+Not yet. Phase D will add a species picker (dog, dragon, sprite, robot) but each user will still have one Buddy at a time. Multi-Buddy farming is a Pro-tier consideration (Phase F).
+
+## When will Buddy react to my site's actual health?
+
+That's Phase E on the [[Roadmap]] — the headline feature. For now (Phase A), Buddy's stats just persist at their default values. Phase B will add interactions (Feed / Play / Clean / Sleep) so YOU can directly affect the stats. Phase C will add time-based decay so the stats drift down when you're away. Phase E ties the stats to `wp_get_site_health()` results — outdated plugins make Buddy sick, published posts feed Buddy, cleared spam makes Buddy happy.
+
+## Why does Buddy wink sometimes?
+
+The wink Easter-egg landed in v0.1.1. When Buddy's overall mood is ≥ 75 (which is most of the time on default settings), there's a ~5% chance on each page render that the wink tone fires instead of the standard happy face. The wink is a real CSS keyframe animation as of v0.1.3 — for a brief moment in v0.1.1 and v0.1.2 it would get "stuck" mid-wink, that's been fixed.
+
+## Why is there no JavaScript?
+
+The character renderer is inline SVG, and the animations are CSS keyframes. No JS framework is required to make the Buddy bob, blink, or wink. The first JavaScript file will arrive in Phase B when the Feed / Play / Clean / Sleep AJAX buttons are added.
+
+This is a deliberate architectural choice — see [[Architecture]].
+
+## Is the source code open?
+
+Yes. The plugin is GPL v2 or later and the full source is published on Gitea at <https://git.davidtkeane.com/ranger/rangerhq-buddy>. You can inspect every line.
+
+## Why is it called "RangerHQ Buddy" and not just "Buddy"?
+
+"Buddy" is a one-word brand that's hard to trademark search and easy to confuse with other plugins. "RangerHQ Buddy" places it in the larger RangerHQ family (see [[Family]]), which makes naming, discovery, and family-installs all easier. The plugin slug is still `buddy` internally so file paths and admin URLs stay short; only the user-facing brand and the WordPress text domain are `rangerhq-buddy`.
+
+## I don't want the Buddy on my Dashboard. Can I hide it?
+
+Yes — same as any other Dashboard widget. Click "Screen Options" at the top right of your Dashboard, uncheck "Buddy", and it disappears. Your Buddy still exists in `wp_usermeta` and you can still visit the My Buddy page from the sidebar.
+
+## Will RangerHQ Buddy work on multisite?
+
+Yes. Each user's `buddy_state` is per-user, not per-blog. If you have multiple sites, your Buddy is the same across all of them. (Phase F's "multi-pet farm" idea would add an explicit per-blog mode for those who want it.)
+
+## I removed the plugin. Is my data gone?
+
+WordPress leaves `wp_usermeta` rows in place when a plugin is deactivated — that's by design so reinstalling restores your Buddy. To fully wipe Buddy data:
+
+```sql
+DELETE FROM wp_usermeta WHERE meta_key = 'buddy_state';
+```
+
+A "Reset Buddy" button on the Settings page is on the future roadmap.
+
+## How do I report a bug or request a feature?
+
+Open an issue at <https://git.davidtkeane.com/ranger/rangerhq-buddy/issues> or email <david@davidtkeane.com>.
+
+## Who made this?
+
+David Keane, Dublin, Ireland. <david@davidtkeane.com> · <https://davidtkeane.com>
diff --git a/Family.md b/Family.md
new file mode 100644
index 0000000..3316e44
--- /dev/null
+++ b/Family.md
@@ -0,0 +1,60 @@
+# Family
+
+RangerHQ Buddy is one of several **RangerHQ** projects by David Keane. The family share a name, a visual identity (the helmet logo), a GPL v2+ licence, and a "lightweight, no-telemetry, hand-rolled" ethos. They live on different surfaces because the audiences are genuinely different.
+
+## Current family members
+
+### RangerHQ Buddy — this project
+
+- **Surface:** WordPress admin
+- **Function:** A small virtual pet for every WP admin user, with Phase E (the headline feature) tying its mood to your site's actual health
+- **Repo:** [git.davidtkeane.com/ranger/rangerhq-buddy](https://git.davidtkeane.com/ranger/rangerhq-buddy)
+- **Distribution:** WordPress.org Plugin Directory (in round-2 review at time of writing)
+
+### RangerHQ Radio — WordPress sibling
+
+- **Surface:** WordPress admin
+- **Function:** Plays SomaFM internet radio from your wp-admin sidebar, with the 4-button search-link affordance (Spotify / YouTube / Apple / Bandcamp) on every track
+- **Repo:** [git.davidtkeane.com/ranger/rangerhq-radio](https://git.davidtkeane.com/ranger/rangerhq-radio)
+- **Distribution:** [WordPress.org Plugin Directory](https://wordpress.org/plugins/rangerhq-radio/) (LIVE)
+
+RangerHQ Radio's `inc/history.php` was the file that the Tuner Chrome extension's `src/lib/history.js` mirrored. The 4-button search URL templates (Spotify, YouTube, Apple Music, Bandcamp) are byte-for-byte identical across both.
+
+### RangerHQ Tuner — Chrome sibling
+
+- **Surface:** Chrome browser (toolbar popup + optional New Tab Page override)
+- **Function:** Same idea as Radio, but in the browser instead of wp-admin. Plays SomaFM, logs tracks, 4-button search out to the major services
+- **Repo:** [git.davidtkeane.com/ranger/rangerhq-tuner](https://git.davidtkeane.com/ranger/rangerhq-tuner)
+- **Distribution:** Chrome Web Store (in review at time of writing)
+
+## Coming next
+
+### RangerHQ Logbook
+
+- **Surface:** WordPress admin
+- **Function:** Site-changes audit log for WordPress administrators. Captures who did what when across plugins, themes, options, users — searchable + exportable
+- **Status:** In design
+
+## Family-wide promises (the "RangerHQ promise")
+
+Every plugin or extension in the RangerHQ family commits to:
+
+- ✅ **GPL v2 or later** — open source, audit-able, fork-able
+- ✅ **No telemetry, ever** — nothing leaves your site / browser / device
+- ✅ **No third-party JavaScript SDKs** — the code you install is the code that runs
+- ✅ **No CDN-fetched fonts or images** — assets are bundled, period
+- ✅ **Narrow permissions** — request only what's needed, justify the rest
+- ✅ **Per-user / per-device privacy** — no cross-account leakage, no shared site-wide state where per-user makes more sense
+- ✅ **Hand-rolled, no build step where possible** — vanilla PHP on WordPress, vanilla JS in the browser, ESM where applicable
+- ✅ **Tier-1 admin discipline** — single h1 per admin page, escaped output everywhere, accessibility-respecting, no inline `<style>` blocks
+- ✅ **Keep-a-Changelog format** — every release documented at the file-level detail
+
+If a plugin or extension can't meet all of these, it doesn't ship under the RangerHQ name.
+
+## Identity
+
+- **Logo:** the RangerHQ helmet (the gladiator/Spartan-style silhouette)
+- **Palette:** dark base `#0f1411`, accent green `#6dbf7a` (RangerHQ green), cream `#f4e9b7` (highlights)
+- **Typography:** system fonts, no web fonts
+- **Voice:** matter-of-fact, "what it does today" + "what it doesn't do yet"
+- **Maker:** [David Keane](https://davidtkeane.com), Dublin, Ireland
diff --git a/Home.md b/Home.md
new file mode 100644
index 0000000..6927454
--- /dev/null
+++ b/Home.md
@@ -0,0 +1,70 @@
+# RangerHQ Buddy Wiki
+
+**A small virtual companion that lives in your WordPress dashboard. Adopt a Buddy. Watch them blink, bob, and (eventually) react to your site's health.**
+
+| | |
+|---|---|
+| **Latest tag** | [v0.1.5](https://git.davidtkeane.com/ranger/rangerhq-buddy/src/tag/v0.1.5) |
+| **wp.org status** | Round-2 review at time of writing |
+| **Licence** | GPL v2 or later |
+| **Landing page** | https://davidtkeane.com/rangerhq-buddy |
+| **Family** | Sibling to [RangerHQ Radio](https://wordpress.org/plugins/rangerhq-radio/) (WP) and [RangerHQ Tuner](https://git.davidtkeane.com/ranger/rangerhq-tuner) (Chrome) |
+
+---
+
+## What it does today
+
+RangerHQ Buddy is a WordPress plugin that gives every admin user their own tiny virtual pet living in the WP dashboard. Right now (Phase A), Buddy just **exists** — they bob, they blink, they show a mood, they have four stat bars (hunger / happiness / health / energy). Each WP user gets their own private Buddy stored in `wp_usermeta`; nothing is shared between accounts and nothing leaves your site.
+
+What makes Buddy different from a hundred WP novelty plugins is the **architecture**:
+
+- **Per-user state** in `wp_usermeta` under `buddy_state` — multi-admin sites work perfectly, no cross-talk
+- **Inline-SVG character renderer** with mood tones (happy / neutral / sad / wink) and three sizes (sm / md / lg) — no GIFs, no sprite sheets, no image files for the character
+- **CSS-only animations** — bobbing motion and periodic blinking, no JS animation framework
+- **Tier-1 admin discipline** carried over from the broader RangerHQ WordPress family
+
+## Quick links
+
+- [[Architecture]] — how the per-user `buddy_state` storage, the inline-SVG renderer, the dashboard widget hook, and the four admin pages all fit together
+- [[Roadmap]] — the Phase A→F plan (interactions → decay → species → site health integration → Pro tier)
+- [[Privacy]] — what's stored (locally on your site, per-user), what's not
+- [[FAQ]] — common questions
+- [[Family]] — sibling projects in the RangerHQ family
+
+## Install
+
+### From WordPress.org (when live)
+
+Search for **RangerHQ Buddy** in `Plugins → Add New` → Install → Activate. Look for the paw-print icon in your admin sidebar.
+
+### Developer mode (right now)
+
+```bash
+git clone https://git.davidtkeane.com/ranger/rangerhq-buddy.git
+```
+
+Drop the folder into `wp-content/plugins/` and activate via the WordPress admin.
+
+## Source layout
+
+```
+rangerhq-buddy/
+├── buddy.php                   # plugin header + admin-menu + asset enqueue
+├── LICENSE                     # GPL v2 or later
+├── README.md
+├── CHANGELOG.md                # Keep a Changelog format
+├── readme.txt                  # wp.org-format readme
+├── inc/
+│   ├── state.php               # per-user state CRUD (wp_usermeta)
+│   ├── sprite.php              # inline-SVG character renderer
+│   ├── dashboard-widget.php    # the pet on WP Dashboard
+│   ├── admin-page.php          # dedicated "My Buddy" page
+│   ├── about.php               # About page
+│   └── settings.php            # Settings (rename Buddy)
+└── assets/
+    └── css/buddy.css           # all visual styling, CSS-only animations
+```
+
+## Reporting issues / suggestions
+
+Open an [issue](https://git.davidtkeane.com/ranger/rangerhq-buddy/issues) or email <david@davidtkeane.com>.
diff --git a/Privacy.md b/Privacy.md
new file mode 100644
index 0000000..fdd9e15
--- /dev/null
+++ b/Privacy.md
@@ -0,0 +1,76 @@
+# Privacy
+
+## TL;DR
+
+**RangerHQ Buddy collects nothing and contacts nothing.** Every piece of data the plugin handles lives in your own WordPress database, scoped to the individual user. The plugin makes zero outbound HTTP requests. Nothing leaves your site.
+
+## What is stored
+
+In your WordPress site's `wp_usermeta` table, **one row per admin user**, under the meta key `buddy_state`:
+
+| Field | What it holds | Default |
+|---|---|---|
+| `name`       | The name the user gave their Buddy | `"Buddy"` |
+| `species`    | The species id | `"default"` (Phase D will widen) |
+| `hunger`     | 0-100 | 80 |
+| `happiness`  | 0-100 | 80 |
+| `health`     | 0-100 | 80 |
+| `energy`     | 0-100 | 80 |
+| `born_at`    | Unix timestamp the Buddy was first created | (time of first dashboard visit) |
+| `last_tick`  | Unix timestamp of the last decay tick (Phase C+) | (time of first creation) |
+
+That's it. Eight fields per user. **No tracking IDs, no IP addresses, no browser fingerprints, no behavioural logs.**
+
+## What is NOT stored
+
+- No user-identifying information beyond what WordPress already stores (the `wp_usermeta` link to the user ID is WordPress's normal user system)
+- No browsing history
+- No page-view counters
+- No interaction logs (Phase B's Feed / Play / Clean / Sleep clicks update `last_tick` but don't log a history of individual actions)
+- No site-content snapshots
+- No telemetry of any kind
+
+## What is sent off your site
+
+**Nothing.** The plugin makes zero outbound HTTP requests. There is no API call, no analytics ping, no error-reporting beacon, no font CDN, no image CDN, no third-party JavaScript SDK.
+
+Verify this yourself:
+
+```bash
+grep -rn "wp_remote_\|fetch(\|XMLHttpRequest\|curl_init" inc/ buddy.php
+```
+
+The plugin uses zero `wp_remote_*` functions and no JavaScript beyond the (future Phase B) AJAX endpoint that hits your own site's `admin-ajax.php`.
+
+## Multi-admin sites
+
+Each WordPress user gets their own `buddy_state` row in `wp_usermeta`. Alice's Buddy is completely independent of Bob's. Neither can see the other's Buddy. This is enforced by WordPress's user-meta API — there is no shared site-wide Buddy state.
+
+## How to wipe everything
+
+Three options:
+
+1. **Deactivate + delete the plugin.** WordPress will leave the `wp_usermeta` rows in place (Buddy state survives a reinstall by design). To clean them out manually:
+
+   ```sql
+   DELETE FROM wp_usermeta WHERE meta_key = 'buddy_state';
+   ```
+
+2. **Delete the user.** WordPress automatically removes all `wp_usermeta` for a deleted user via `wp_delete_user()`. Buddy state goes with them.
+
+3. **Future: a "Reset Buddy" button on the Settings page** — planned but not yet shipped. For now, the SQL above is the cleanest path.
+
+## Children's privacy
+
+RangerHQ Buddy is a WordPress administrator-only feature. It doesn't render on the public site. Admin access requires a WordPress account, which means the visitor is an authenticated user of a WordPress installation. No data is collected about anyone of any age.
+
+## Compliance notes
+
+- **GDPR:** No personal data is collected or processed beyond what WordPress already stores. The plugin adds one row to `wp_usermeta` per admin user. WordPress's existing GDPR tools (`wp_export_personal_data`, `wp_erase_personal_data`) will pick up the `buddy_state` rows because they're standard `usermeta`.
+- **CCPA, LGPD, PIPEDA, etc.:** Same logic applies. No data collection, no data sharing, no third-party processors.
+
+## Contact
+
+- Email: <david@davidtkeane.com>
+- Issues / source: <https://git.davidtkeane.com/ranger/rangerhq-buddy>
+- Author: David Keane, Dublin, Ireland
diff --git a/Roadmap.md b/Roadmap.md
new file mode 100644
index 0000000..5803daf
--- /dev/null
+++ b/Roadmap.md
@@ -0,0 +1,94 @@
+# Roadmap
+
+RangerHQ Buddy is built in phases. Each phase is a focused capability addition that ships independently, gets validated, then sets up the next phase. The current release (v0.1.5) sits at the end of Phase A.
+
+## Phase A — Pet exists ✅ (v0.1.0 → v0.1.5)
+
+The Buddy is born. Everything visible today.
+
+- ✅ Dashboard widget at WP Admin → Dashboard
+- ✅ Dedicated admin page at WP Admin → Buddy → My Buddy
+- ✅ Settings page (rename your Buddy)
+- ✅ About page (roadmap + version history)
+- ✅ Per-user state in `wp_usermeta` under `buddy_state`
+- ✅ Inline-SVG sprite renderer with three mood tones (happy / neutral / sad)
+- ✅ Wink mood added in v0.1.1, probability-tuned in v0.1.2, fixed as real CSS animation in v0.1.3
+- ✅ WordPress.org submission prep (v0.1.4) — renamed to RangerHQ Buddy, GPL v2 LICENSE, readme.txt
+- ✅ wp.org reviewer-feedback fix (v0.1.5) — moved inline `<style>` block to enqueued CSS
+
+## Phase B — Interactions (next)
+
+Make the Buddy respond to the user.
+
+- ⏳ **Feed** button → bumps hunger up, cooldown 4 hours
+- ⏳ **Play** button → bumps happiness up, slight energy drain, cooldown 1 hour
+- ⏳ **Clean** button → bumps health up, cooldown 8 hours
+- ⏳ **Sleep** button → restores energy, mood becomes "sleeping", cooldown 6 hours
+
+Architectural addition:
+- `inc/actions.php` (new) — interaction handlers + cooldown logic
+- The first JavaScript in the plugin: a small `assets/js/buddy-actions.js` to handle AJAX clicks without page reloads
+- AJAX endpoint via `admin-ajax.php`, secured with `wp_create_nonce()` + `check_ajax_referer()`
+
+## Phase C — Decay
+
+Stats drift down over time. Your Buddy needs you.
+
+- ⏳ WP-cron event runs hourly, lowers all four stats by 1-3 points each
+- ⏳ Dismissible admin notice "Your Buddy is hungry" / "Your Buddy is sleepy" when a stat drops below 25
+- ⏳ Notice dismissal persists per-user in `wp_usermeta` (port the Logbook pattern)
+- ⏳ Buddy's mood label changes based on the average of the four stats
+
+Architectural addition:
+- `inc/decay.php` (new) — WP-cron handler
+- `inc/notices.php` (new) — admin notice rendering + dismissal
+
+## Phase D — Species
+
+More than one kind of Buddy. Pick the character that fits you.
+
+- ⏳ Dog (loyal, sleeps a lot)
+- ⏳ Dragon (proud, plays a lot)
+- ⏳ Sprite (curious, eats a lot)
+- ⏳ Robot (stoic, doesn't get sick)
+- ⏳ Per-species personality phrases ("Woof!", "Beep boop", etc.)
+- ⏳ Species picker on the Settings page
+
+Architectural addition:
+- `inc/sprites/dog.php`, `inc/sprites/dragon.php`, etc.
+- `inc/sprite.php` becomes a dispatcher that picks the right per-species renderer
+
+## Phase E — Site health integration ⭐ (the headline feature)
+
+Buddy's mood reflects how well you're taking care of your WordPress site. This is the reason the whole plugin exists.
+
+- ⏳ `wp_get_site_health()` results feed into Buddy's stats:
+  - Outdated plugins → drain `health`
+  - Unpublished drafts piling up → drain `energy`
+  - Spam queue length → drain `happiness`
+  - Recently published posts → boost `hunger` (Buddy is fed by content)
+- ⏳ Optional: WooCommerce / EDD integration where sales boost happiness
+- ⏳ Optional: comments approved boost hunger
+
+Architectural addition:
+- `inc/site-health.php` (new) — readers for each WP health signal
+- A daily WP-cron job that recalculates Buddy's stats based on site health
+
+## Phase F — Pro tier (long-term, optional)
+
+If the free plugin finds an audience, a paid tier:
+
+- ⏳ Custom skins (premium SVG art)
+- ⏳ Multi-pet farm (manage several Buddies for a multisite)
+- ⏳ Social visits (anonymously see how other WP admins' Buddies are doing)
+- ⏳ Anonymous leaderboard (most-cared-for Buddy)
+
+## What WILL NOT be added (deliberate non-goals)
+
+- ❌ External account / login
+- ❌ Telemetry / analytics
+- ❌ Third-party JavaScript libraries
+- ❌ CDN-fetched fonts or images
+- ❌ Any feature that requires sending user data off-site
+
+These are non-negotiable across the whole RangerHQ family — see [[Family]].