# MAINTAINERS  -  Barkday(TM) (PRIVATE)

> **Confidential.** Do not share outside the core team.
> This document describes internal governance, release workflow, data versioning, and distribution
> for the Barkday(TM) app
> and datasets.

## 1) Purpose & Scope

This file is the single source of truth for:

- Release governance (major vs. minor)
- Data file ownership and versioning
- Staging -> production workflow
- Play Store (TWA) packaging steps
- Security, IP protection, and trademark usage
- Incident response & rollback

## 2) Contacts & Ownership

- **Product/Brand:** Owner (Trademark)
- **Tech Lead:** [Name]
- **Data Steward (Breeds/Rules):** [Name]
- **Release Manager (Play/TWA):** [Name]
- **Security/Access Control:** [Name]

> Maintain a separate private contact sheet with phone/email + recovery methods.

---

## 3) Repos & Environments

### Repositories

- **Public app host (static):** `candidquality.github.io/Barkday` (public, minimal; no IP-heavy docs)
- **Private ops/docs repo:** `barkday-internal` (PRIVATE) - holds: this file, data governance docs,
  release checklists, packaging scripts, keys/secrets (via GitHub Environments),
  and staging artifacts.
- **Optional local-only archive:** Encrypted drive or DMS (e.g., Google Drive w/ client-side encryption, or
  1Password Documents).

### Environments

- **Local dev:** developer machines; never commit secrets
- **Staging:** private preview build (same origin-path as prod; different branch/URL)
- **Production:** `candidquality.github.io/Barkday` (Pages)

> **Rule:** No private docs, keys, or internal scripts in the public repo. The public README stays marketing-level only.

---

## 4) Data Model  -  Files & Responsibility

> Keep all schema & file details **out of public READMEs**. This section is PRIVATE.

- `breed_aliases.json`  -  Data Steward
- `breed_taxonomy.json`  -  Data Steward
- `breed_groups.json`  -  Data Steward
- `reco-breed.json`  -  Data Steward
- `reco-banded.json`  -  Data Steward
- `rules_library.json`  -  Data Steward
- `barkday_expansion_breeds_v1.json`  -  Data Steward (expansion sets)
- External feed (read-only): Gift suggestions (affiliate-safe list)

## Principles

- Defaults live in `rules_library.json`; overrides only where justified.
- Avoid deletions that reduce guidance richness; replace with better specifics.
- Localization-neutral; no brand names in core guidance.

---

## 5) Versioning & Cache Busting

**Why:** GitHub Pages + service worker caching require explicit busting.

## Policy

- Every change to any data file requires bumping its `?v=` query in `app.js` (e.g.,
  `data/breed_aliases.json?v=3` -> `v=4`).
- Bundle related changes (aliases + taxonomy + groups + reco) in **one major** release to avoid transient mismatches.
- Minor typo/alias additions may ship alone but still require a `?v=` bump for the touched file(s).
- Update `app version` log line in `app.js` console (e.g., `[Barkday] vYYYY-MM-DD-n`).

## Cache-bust checklist

- [ ] Increment `?v=` on each changed data file
- [ ] Increment `app.js` version banner
- [ ] Invalidate SW: bump a comment hash in `service-worker.js`
- [ ] Test: hard-refresh and first-run load on Android + desktop

---

## 6) Release Types

## Major (coordinated)

- Adds/refactors multiple breeds or structural metadata
- Changes umbrella group definitions or cluster logic
- Requires: full data QA + cross-file alignment + coordinated `?v=` bumps

## Minor

- Typos, single alias additions, small bullet fixes
- Single-file `?v=` bump + smoke test

---

## 7) Staging -> Production Workflow

1. **Feature branch** in private repo (`barkday-internal`) with data edits + unit checks.
2. **Staging sync** to a staging branch of the public repo (or a separate staging site if needed).
3. **QA Checklist**
   - [ ] Aliases resolve to canonical names (no orphan breeds)
   - [ ] Taxonomy groups/clusters exist and are spelled consistently
   - [ ] No empty lanes when an override exists (inherit or fill)
   - [ ] Console shows all data files loaded without 404/parse errors
   - [ ] Birthday calc sanity tests (rounding, edge dates)
   - [ ] Gift panel hidden by default; disclosure visible **in-app** after clicking to open the gift links,
     and before first affiliate interaction
4. **Production publish** by PR/MR with required reviewers (CODEOWNERS).
5. **Post-release**: verify SW update prompt & first-run experience on Android and desktop.

---

## 8) Play Store (TWA) Packaging  -  High Level

- Generate AAB via PWABuilder/Bubblewrap (TWA).
- Host **Digital Asset Links** at `/.well-known/assetlinks.json` with package name + SHA-256.
- Create listing: title, short/long description, category, privacy URL, icon, feature graphic, screenshots.
- Policy forms: Data Safety (no collection), Target Audience, Ads (No), Content rating.
- Upload AAB, accept Play App Signing; note Google's signing certificate SHA-256.
- If SHA-256 changes, update `assetlinks.json` and re-deploy site.
- Roll out to Production after internal testing.

> Keep a separate `DEPLOYMENT.md` (PRIVATE) with exact command invocations, fingerprints, and image specs.

---

## 9) Security & IP Protection

- **License:** (c) 2025 [Owner]. **All Rights Reserved.** (no redistribution/derivatives)
- **Repo visibility:** Public app repo contains **only** the app and public-safe README.
  All internal docs/scripts live in **`barkday-internal` (PRIVATE)** or encrypted local storage.
- **Branch Protection (private repo):** require reviews, signed commits, status checks.
- **Secrets:** never in code; use GitHub Environments/Secrets (private repo only).
- **Data exfiltration risk:** Don't push schemas or internal docs to the public repo, even temporarily.
- **Trademark:** Barkday(TM) name/logo only in approved assets; disallow third-party use.
- **Affiliate disclosure:** in-app, contextually adjacent to gift panels **before** link interaction.

---

## 10) Incident Response & Rollback

### Trigger examples

- Broken data load (404/JSON parse)
- Incorrect birthday math or UI blocker
- SW caching trap or stale data
- Public IP leak (docs or schemas)

### Immediate actions

1. **Revert** to last-known-good commit on public repo.
2. **Purge SW:** bump service worker and `?v=` parameters; post a quick release note.
3. **If IP leak:** remove files, rotate credentials, and invalidate caches; review Git history & purge if necessary.
4. **Log incident** in private repo with root cause + corrective actions.

---

## 11) Governance References (PRIVATE)

- `DATA-GOVERNANCE.md`  -  detailed schemas, editorial standards, curation sources
- `DEPLOYMENT.md`  -  TWA/Bubblewrap commands, fingerprints, image specs, store copy
- `RELEASE-CHECKLIST.md`  -  step-by-step ship list
- `AFFILIATE-POLICY.md`  -  placement language + examples (app-only)
- **Gifts Access Policy** - Gifts are available to all users. Premium tiers may include optional partner perks
  (discounts/coupons), but access to the gifts list itself is never paywalled.

---

## 12) Roadmap Notes (Internal)

- Designer/Companion hybrid breeds (commercial segment)
- Premium add-ons (reminders, widgets, PDF export)
- i18n content pipeline
- Structured feedback capture (opt-in)

---

## Policy  -  Version-Lock (Data Sources)

All core JSON data endpoints must share the same cache-bust query tag.

- Allowed tags: ISO-like date with sequence (YYYY-MM-DD-N), e.g., 2025-10-06-1.
- Required files: BREED_GROUPS_URL, RECO_BANDED_URL, RECO_BREED_URL, BREED_ALIASES_URL, TAXONOMY_URL, GIFT_FEED_URL.
- On change: Update all constants together in app.js and add a matching /docs/CHANGELOG.md entry.

## Policy  -  Free-Tier Limits & A11y Drawer State

Free-tier behavior:

- Max unique dogs per device: **5** (case-insensitive by name).
- Max saved runs per device: **50** (tier-aware).
- Exceeding cap shows a toast; user retains full offline functionality.

Drawer accessibility:

- Any `.bd-drawer` with `.is-open` **must** have `aria-hidden="false"`.
- When closed, set `aria-hidden="true"`.
- Site code includes an observer-based safety net to enforce the attribute automatically.