From dfdb7452f65bdcceed7e1aba735889dc3b2168c7 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 26 Dec 2025 22:34:25 +0100
Subject: [PATCH] docs: add undocumented API disclaimer

---
 README.md            |  5 +++++
 docs/assets/site.css | 41 ++++++++++++++++++++++++++++++++++++++++-
 docs/index.html      | 12 +++++++++++-
 3 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f6ad167..ada3730 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,11 @@
 
 `bird` is a fast X CLI for tweeting, replying, and reading via X/Twitter GraphQL (cookie auth).
 
+## Disclaimer
+
+This project uses X/Twitter’s **undocumented** web GraphQL API (and cookie auth). X can change endpoints, query IDs,
+and anti-bot behavior at any time — **expect this to break without notice**.
+
 ## Install
 
 ```bash
diff --git a/docs/assets/site.css b/docs/assets/site.css
index fc26576..4c7e732 100644
--- a/docs/assets/site.css
+++ b/docs/assets/site.css
@@ -395,6 +395,46 @@ main { position: relative; z-index: 1; }
 .tiny--muted { color: rgba(244, 241, 233, 0.52); }
 .sep { opacity: 0.5; }
 
+.notice {
+  margin-top: 18px;
+  border-radius: var(--radius);
+  border: 1px solid rgba(244, 241, 233, 0.12);
+  background: rgba(0, 0, 0, 0.22);
+  padding: 14px 14px;
+  display: grid;
+  grid-template-columns: 34px 1fr;
+  gap: 12px;
+  align-items: start;
+  box-shadow: 0 18px 70px rgba(0, 0, 0, 0.26);
+}
+.notice__icon {
+  width: 34px;
+  height: 34px;
+  border-radius: 12px;
+  display: grid;
+  place-items: center;
+  font-family: var(--mono);
+  font-weight: 600;
+  border: 1px solid rgba(244, 241, 233, 0.14);
+  background: rgba(0, 0, 0, 0.18);
+  color: rgba(244, 241, 233, 0.86);
+}
+.notice__title {
+  margin: 0 0 4px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+}
+.notice__text { margin: 0; color: var(--muted); line-height: 1.6; }
+.notice--warn {
+  border-color: rgba(183, 255, 106, 0.18);
+  background: linear-gradient(180deg, rgba(183, 255, 106, 0.10), rgba(0, 0, 0, 0.22));
+}
+.notice--warn .notice__icon {
+  border-color: rgba(183, 255, 106, 0.28);
+  background: rgba(183, 255, 106, 0.08);
+  color: rgba(183, 255, 106, 0.92);
+}
+
 .bottom {
   position: relative;
   z-index: 1;
@@ -437,4 +477,3 @@ body.is-ready [data-reveal]:nth-child(6) { transition-delay: 420ms; }
   .steps { grid-template-columns: 1fr; }
   .nav { display: none; }
 }
-
diff --git a/docs/index.html b/docs/index.html
index d372cdd..9f1b08c 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -194,6 +194,17 @@ bun add -g @steipete/bird</code></pre>
             </article>
           </div>
 
+          <aside class="notice notice--warn" role="note" aria-label="Disclaimer">
+            <div class="notice__icon" aria-hidden="true">!</div>
+            <div class="notice__body">
+              <p class="notice__title">Undocumented API.</p>
+              <p class="notice__text">
+                bird uses X/Twitter’s private web GraphQL endpoints and rotating query IDs. X can change things anytime —
+                expect breakage without notice.
+              </p>
+            </div>
+          </aside>
+
           <div class="footerline">
             <a class="tiny" href="https://github.com/steipete/bird#authentication-graphql">
               Authentication details
@@ -219,4 +230,3 @@ bun add -g @steipete/bird</code></pre>
     <script src="./assets/site.js" type="module"></script>
   </body>
 </html>
-