docs: foundational specs (PRD, architecture, design system, database, security, code style, testing) + AGENTS operational rulebook

PRD.md

@@ -0,0 +1,101 @@
+# PRD — أنور بآي (anwarpy.ai)
+
+> Owner: Ahmed (anwarpy). Maintainer of record: this document. Last revised: 2026-10-11.
+> Status vocabulary in this doc: **MVP** = shipped 2026-10-10 (verified, see `docs/launch/2026-10-10-launch-readiness.md` §11). **Roadmap** = committed, not built. **Out of scope** = we will not build it; do not ask.
+
+## 1. Vision
+
+Anwarpy.ai is an Arabic-first library of practical AI tips and tricks — automation, agentic workflows, models, tooling — whose single goal is: **help the Arabic reader actually use AI and keep discovering new tricks.** Arabic engineers, founders, and curious professionals learn to *understand* AI and then *build* with it: «افهم الذكاء الاصطناعي، ثم ابنِ به.»
+
+Three product principles, all enforced server-side:
+
+1. **Honesty over theater.** Reading times are computed from real content, errors say what failed in real Arabic, the paywall never lies about what the visitor can read.
+2. **The reader is sovereign.** During free early access every published guide — including membership-tier ones — is fully readable. No dark patterns, no fake scarcity, no confirm-password, no CAPTCHA.
+3. **Machines are readers too.** Guides are served clean to humans and to AI crawlers (robots.txt policy, llms.txt/llms-full.txt, honest JSON-LD).
+
+## 2. Personas
+
+| Persona | Who | What they get |
+|---|---|---|
+| **The Curious Reader** | Arabic speaker googling «كيف أبني وكيل ذكاء اصطناعي» | Free guides, topic hubs, honest reading times, notify list |
+| **The Practitioner** | Engineer/founder implementing agents at work | Advanced guides + work files during early access (free); after billing launches: the $10/mo membership (S-01…S-08) |
+| **The Writer (Ahmed)** | Solo owner; writes in `/admin`, ships via the agent pipeline | Payload admin, agent API with secret scanning, moderation queue, comment management |
+
+## 3. MVP — shipped 2026-10-10
+
+The MVP is exactly what launched. Nothing below may regress without an explicit owner decision.
+
+### 3.1 Reading & content
+- **Guides** (`Posts`): Arabic titles/deks, Lexical bodies, categories وكلاء/نماذج/استرجاع/سلامة/أدوات/أعمال, topics (agents|models|automation|foundations), `contentType` badge (note/tutorial/case_study/comparison), `authorName` byline, «حُدّث» freshness, computed `readingMinutes` (160 wpm, written at save + backfilled honestly).
+- **Topic hubs** `/topics/{agents,models,automation,foundations}` with sitemap entries.
+- **Tables** in article bodies render as real tables (mobile-safe), not code blocks.
+- **AI/SEO surfaces**: robots.txt allows the 10 named AI crawlers; `/llms.txt` index; `/llms-full.txt` full bodies; JSON-LD Article + BreadcrumbList (+ FAQPage on /subscription, Organization on home); `isAccessibleForFree` reflects reality.
+- **Downloads**: guide attachments gated by the same access policy as their post (per-file `access`).
+
+### 3.2 Access policy (the core contract)
+- `LAUNCH_MODE` server-side policy (`web/src/lib/launch.ts`): `free_early_access` = every published post serves its full body; billing routes honestly 503 in Arabic. `paid` = membership-tier (`access: 'vip'`) posts paywall with H2-preview + fine print.
+- The *intended tier* (`access: free|vip`) is data; the *effective access* is policy. Never rewrite `access` to simulate a launch state.
+- Ghost rule: any verification must be done as a logged-out visitor reading a VIP post.
+
+### 3.3 Accounts & trust
+- Email+password signup (no confirm-password field), verification email with token, honest 429 lockout message, duplicate-email inline error, email-typo suggestion, live password hint, reassurance microcopy.
+- Verification state is written at signup (`verification_token`); verify-email flow supports changing the email.
+- Account settings + onboarding (interest/level) exist; `getViewer()` resolves the session.
+
+### 3.4 Notify list
+- `/api/notify` records every submission; sends a confirmation mail when transport is live; honest 503 «خدمة البريد غير مربوطة بعد.» when Cloudflare Email Sending is off (row still kept); duplicate emails return `alreadySubscribed: true` without re-mailing.
+
+### 3.5 Comments (decided 2026-10-11 — in MVP scope)
+- Any **logged-in** user may comment on a post — free or VIP, tier does not matter. **Anonymous visitors cannot comment** (API rejects unauthenticated; UI prompts login).
+- Moderated: comments enter a non-public status; the author identity is **forced server-side** from the session (client cannot spoof `author`), display name from `authorName` (ADR-0002).
+- Route contract: not a public CRUD API — comment creation is a server-validated route bound to the post (ADR-0001).
+- Admin moderation lives in `/admin` (status transitions: pending → published / rejected).
+
+### 3.6 Agent pipeline (authoring automation)
+- `POST/PUT /api/agent/posts` with `x-agent-key` header; strips `access`/`readingMinutes` from accepted fields; `sourceId` dedup (idempotent re-runs); secret scanning (`scanAgentPayload`) rejects AWS keys, PEM blocks, `sk-` keys, GitHub tokens, generic credentials with **422 + pattern names only**; string `content` is a 400 (Lexical JSON required); `publish: true` is explicit opt-in, PUT cannot set `status`.
+- Media/Files ingestion helpers (`agent-media.ts`, `agent-files.ts`).
+
+### 3.7 Interactions
+- One like per logged-in user per post (`PostLikes`, uniqueness enforced), public like counter; anonymous view counting on `/api/posts/[slug]/view`.
+
+### 3.8 Ops floor
+- `web/scripts/backup-db.sh` + documented restore rehearsal (VPS).
+- Feedback = `mailto:hello@anwarpy.ai` in the footer.
+- Deployment: rsync → `docker compose -f docker-compose.vps.yml up -d --build` on the VPS; migrations apply on boot.
+
+## 4. Roadmap (committed, phased)
+
+### Phase 2 — Trust & legal
+- **L-03 /terms + /privacy**: real content from owner facts recorded in `docs/launch/owner-inputs-terms-privacy.md`; effective date; §9 items 1–7. Acceptance: pages live, linked in footer, listed in sitemap.
+- **Comments shipping polish**: notification to writer on new pending comment; abuse valve (delete + block author) in admin.
+
+### Phase 3 — Money & measurement (gate: S-01…S-08 checklist §6)
+- **Stripe paid tier S-01…S-08**: checkout, webhook (`/api/stripe/webhook` exists; `stripeCustomerId` on Users), `vip-onboarding`, payment success/cancel pages; flip = `LAUNCH_MODE=paid` policy change only. Paywall CRO (H2 preview + fine print + #faq) already built.
+- **L-11 analytics**: vendor decision (owner); event list is pre-agreed in the launch checklist.
+- **L-12 editorial distribution**: owner-driven announcement; no agent-posted content.
+
+### Phase 4 — Product growth (owner-added 2026-10-11)
+- **Mailing list v2**: move from notify rows to a real newsletter (send digests of new guides; unsubscribe honoring; Cloudflare Email transport).
+- **Direct messaging with the writer**: logged-in members can message Ahmed from within the site; inbox in `/admin`; rate-limited; no exposure of his personal email.
+- **In-post tool-finder chatbot**: assistant that reads the site's own posts (llms-full corpus) and points the reader to the right guide/tool inside anwarpy.ai; Arabic-first; cites posts; never invents tools. Must reuse the same access policy (never leak VIP bodies to unauthenticated users through the bot).
+
+## 5. Strictly out of scope
+
+Do not build, do not scaffold, do not "prepare" these:
+
+- OAuth / Passkeys / SMS or WhatsApp login in the MVP — **anticipated evolution** (owner, 2026-10-11): Google auth or Clerk may be added later for easy integration; keep `viewer.ts` as the single session seam so providers can swap behind it.
+- Native mobile apps.
+- Multi-tenant or white-label anything; a second site on the same deploy.
+- Public third-party REST API beyond what exists (agent API is for the owner's pipeline only).
+- User-generated uploads of arbitrary files; media uploads stay author/admin-only.
+- CAPTCHA, aggressive rate limiting beyond the existing login lockout (owner decision, recorded).
+- Real-time anything (WebSockets/presence) until Phase 4 messaging is designed.
+- Any rewrite of `access` fields to simulate launch states.
+
+## 6. Success metrics
+
+Available now (no vendor dependency): notify signups, verified-account ratio, likes per post, views per post, comment quality (published/rejected ratio). Post-L-11: activation (first guide read), return rate, member conversion once billing is live.
+
+## 7. Acceptance culture
+
+A checkbox without evidence is not verification. Every claim in the launch doc has a command + observed output. This PRD inherits that rule: features in §3 are verified by the §11 evidence; new features get the same treatment (ghost-read checks, honest-error checks, row-count checks).