Add maintainer guide

Author: ookyet

MAINTAINING.md

@@ -0,0 +1,67 @@
+# Maintaining this repository
+
+Documentation repo — structured data / entity SEO for ENS-based identities.
+No build system, no runtime: Markdown docs + shell/JS tooling in `scripts/`. English only.
+
+> Companion of a **private reference implementation** (ookyet.com). Knowledge flows **one way**:
+> lessons are validated on the reference site first, then ported here in batch "port windows"
+> (see CHANGELOG v3.1.x–v3.3.x for the pattern). Never publish guidance here that the reference
+> implementation has not field-tested, and never copy site-private material (API keys, GSC
+> screenshots, non-public URLs) into this repo.
+
+This repo is also a **subjectOf asset in the author's own entity graph** (SoftwareSourceCode
+node + CITATION.cff with ORCID). Treat public-facing text as entity corpus: byline is
+`Qifeng Huang (ookyet)`, the real name in CITATION.cff is deliberate, and the wallet
+address appearing in examples is public by design.
+
+## Honesty rules (the repo's soul — never trade away)
+
+1. **No "KP trigger" framing.** A Knowledge Panel is notability-driven and cannot be forced
+   by markup. The v3.2.1 "honesty pass" retired `READY FOR KP` / trigger-score language from
+   the tooling; do not reintroduce it in docs, scripts, or release notes. Heuristics must be
+   labeled "not a Google metric".
+2. **Timestamp every claim.** Field data over promises: outcomes carry dates and measurement
+   methods (see README Results table). Never put a Knowledge Panel on a calendar.
+3. **Negative results stay.** Retired strategies (FAQPage, HowTo, active-trigger, phantom
+   press JSON-LD) are kept as documented failures with dates — they are load-bearing teaching
+   content. **Do not "clean up" `~~RETIRED~~` sections.**
+4. **Markup must reflect reality.** Never document or exemplify structured data for content
+   that does not exist (no phantom articles, no dead selectors, no fabricated credentials).
+5. Do not re-add retired schema types: `FAQPage` / `HowTo` (Google removed the rich results);
+   `QAPage` only for genuine single-question + user-submitted-answers pages; no
+   `potentialAction/SearchAction` without a real search results page.
+
+## Versioning & release protocol (every release, in order)
+
+Semantic mapping (documentation SemVer): **MAJOR** = stance reversal (e.g. 3.0.0 retired the
+active-trigger strategy) · **MINOR** = new guidance/sections · **PATCH** = corrections and
+repo hygiene. Skipping versions is allowed (SemVer only requires monotonic increase; v2.x
+never existed — do not backfill tags for CHANGELOG-only versions 3.0.0/3.0.1).
+
+Release checklist:
+1. `CHANGELOG.md` entry (Keep a Changelog: Added/Changed/Fixed, dated, why not just what).
+2. `CITATION.cff` — bump `version` + `date-released`.
+3. Commit, push, then tag `vX.Y.Z` and push the tag.
+4. `gh release create vX.Y.Z` — title `vX.Y.Z — <short human phrase>`; body is a **narrative
+   summary** (headline sentence + context + Added/Changed), not a changelog copy-paste;
+   end with a link to the CHANGELOG section.
+
+## Commit rules
+
+- Author/committer: `ookyet <ookyet.mid@gmail.com>`; messages ASCII English.
+- `core.hooksPath=.githooks` runs `scripts/commit-message-guard.sh` — it strips tool
+  watermarks and co-author trailers; empty-after-strip blocks the commit. Never `--no-verify`.
+- CI gates (`.github/workflows/`): commit-guard (message contract on push/PR), shellcheck
+  (`-S warning` over `scripts/*.sh`), kg-monitor (scheduled KG API check). Keep them green.
+
+## Editing discipline
+
+- Docs must stay self-consistent: if guidance changes in one file, grep for the old claim in
+  README / `docs/faq.md` / `docs/implementation-guide.md` / `docs/troubleshooting.md` and
+  `examples/` — stale cross-references are this repo's main defect class (e.g. FAQ once
+  promised retired FAQ rich results while Step 3 documented the retirement).
+- Monitoring guidance baseline: **weekly** KG API cadence; growth staircase reading order
+  `url` → `image` → `resultScore` → `detailedDescription`; "no change" is the normal case.
+- Google's docs drift: when citing them, keep the "as of <date>" qualifier and verify the
+  linked page still says what we claim during any port window.
+- Never commit API keys (KG Search API keys expire and get rotated — they live outside git).