102 lines
8.7 KiB
Markdown
102 lines
8.7 KiB
Markdown
# 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).
|