Plyrum Documentation Map

Last reviewed: 2026-05-13.

This directory is the product documentation source of truth. It separates what is already implemented from what is still required before a paid production launch.

Reviewed Code Areas

• Web app routes: web/app/**/page.tsx
• Web API routes: web/app/api/**/route.ts
• Billing and pricing: web/lib/billing.ts, web/lib/pricing.ts, web/lib/fx.ts, web/lib/billing-cache.ts
• Dashboard data: web/lib/dashboard-data.ts
• Model catalog and routing: web/lib/provider-catalog.ts, web/lib/scoring.ts, web/lib/moa.ts
• Prisma schema: web/prisma/schema.prisma
• Local and CI gates: Makefile, scripts/smoke.sh, .github/workflows/*
• CLI and engine docs context: README.md, docs/architecture.md, docs/cost-arbitrage.md

Documentation Set

Document	Purpose	Status
docs/product-site.md	Website pages, user flows, dashboard behavior, launch gaps	Added
docs/billing-and-payments.md	Current billing implementation, missing real payments, recommended payment methods, ledger design	Added
docs/api-and-operations.md	API reference, env vars, smoke gates, local/prod runbook	Added
docs/architecture.md	Existing architecture summary	Existing
docs/cost-arbitrage.md	Existing MoA/direct cost evidence	Existing
docs/product-gap-audit.md	Current implemented/partial/missing map against goal.md and donor scans	Added
docs/F5_DONE.md	Existing v0.1/v0.2 readiness checklist	Existing

Current Product Status

Area	Status	Notes
Marketing site	Partial	/ exists and shows model catalog. The public docs page is still a placeholder.
Auth	Implemented	Register/login/refresh with JWT and DB refresh-token rotation. Dev superaccount exists for local use.
Dashboard	Implemented MVP	Dashboard, model settings, reliability, doctor, usage, transcripts, MoA, audit pages exist.
CLI	Implemented MVP	Auth, TUI, model selection, run, usage, audit, doctor, permissions, workflow, memory/persona commands.
Model orchestration	Implemented	Scoring, compliance filters, reliability, MoA, Self-MoA, route explanations, progress events.
Usage accounting	Implemented	UsageEvent rows are persisted with canonical usage and micro-RUB cost.
Wallet balance display	Partial	CreditWallet exists and /api/balance reads spendable balance as total minus reserved. Dev superaccount shows unlimited balance.
Wallet usage debit	Implemented/partial	Completed positive-cost usage creates idempotent WalletLedgerEntry(type=usage_debit) rows and updates wallet balance transactionally. Hard preflight rejection and balance hold/reservation exist behind PLYRUM_BILLING_ENFORCE_BALANCE=1; real top-up is still missing.
Real top-up/payment provider	Partial/contract-only	/billing/topup is now a sandbox-oriented checkout form with payment history and return-state display. Payment, PaymentWebhookEvent, FiscalReceipt, and Invoice DB tables exist. Mock checkout/history/webhook APIs exist, sandbox succeeded webhooks can idempotently credit wallet, admin-only sandbox refunds can idempotently debit wallet, YooKassa hosted checkout/webhook code can credit wallet after provider re-fetch verification, admin YooKassa refunds call provider /v3/refunds before local ledger debit, accepted top-ups/refunds create pending FiscalReceipt rows, and YooKassa checkout requires explicit terms acceptance. Checkout links to /legal/offer, /legal/privacy, /legal/refund, and /legal/tariffs. Paid launch is still blocked by YooKassa sandbox browser E2E, external fiscal/refund receipt submission, final legal review/entity details, production payment methods and provider-specific reconciliation/runbook.
Browser E2E	Partial	Playwright config and route tests exist. Payment browser E2E cannot fully exist until top-up UI and real checkout/webhook exist.
Production legal docs	Partial/draft	Customer-facing draft pages exist at /legal/offer, /legal/privacy, /legal/refund, and /legal/tariffs, and checkout links to them. They still need legal review, seller details, fiscal receipt policy and final public contacts before real payments.

Documentation Required Before Paid Launch

User-facing:

• Product overview: what Plyrum does, which tasks it is good for, and where it should not be trusted blindly.
• CLI guide: install, login, run, TUI controls, commands, sandbox permissions, file-write behavior, audit and memory controls.
• Web dashboard guide: account, model settings, doctor, reliability, usage, transcripts, why/explanations, audit.
• Model policy: supported providers, model IDs, routing modes, compliance filters, data residency, privacy tiers.
• Pricing and tariffs: how token usage becomes RUB cost, what is included, how prepaid balance works, minimum top-up, refunds, taxes.
• Payment instructions: cards/MIR, SBP, SberPay/T-Pay where supported, business invoice flow.
• Terms of service / public offer.
• Privacy policy, including 152-FZ personal data handling.
• Refund policy.
• Data retention and deletion policy.
• Security page: secret handling, provider-key storage, audit log, sandbox limitations, incident contact.

Internal/operator:

• Production runbook: deploy, migrate, rollback, backup, smoke, restore.
• Billing ledger runbook: top-up, debit, refund, adjustment, reconciliation.
• Payment-provider integration notes: checkout, webhook verification, idempotency, fiscal receipts, sandbox/live modes.
• Incident response: provider outage, double-charge, webhook replay, data leak, model producing unsafe output.
• Compliance matrix: who can enable providers/models, org policy inheritance, no-PII mode, residency enforcement.
• Release checklist: tests, smoke, trust guard, secret scan, browser E2E, live payment sandbox proof.

Next Documentation Work

1. Turn /docs in the web app from a placeholder into a real product docs landing page that links to public docs.
2. Add an OpenAPI spec once the payment endpoints are implemented.
3. Add screenshots/GIFs for CLI TUI and dashboard flows.
4. Add a customer-facing pricing page after the tariff and payment-provider decisions are locked.
5. Add a legal-review pass for offer/privacy/refund texts before accepting real money.