anwar-pi-website/PRD.md

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).