Roadmap: paid AI tutor, credits, admin, and analytics

[pirajoke]

Outcome

Evolve MY DICTIONARY into a safe public Telegram language-learning product with deterministic vocabulary practice, optional metered AI/voice, Telegram Stars billing, privacy-safe analytics, protected operations, and recoverable production data.

Product principles

• Dictionary, cards, quizzes, written practice, pronunciation, and spaced repetition remain usable independently of AI.
• AI and voice stay grounded in the learner active pack and deterministic progress; usage, credits, budgets, and costs are enforced server-side.
• Analytics and operating receipts remain aggregate or metadata-only and never store learner prompts, answers, messages, credentials, charge identifiers, or contact details.
• A production Stars canary is operational evidence only; dedicated Telegram test-environment coverage remains a separate launch gate.

Delivered and verified

• PostgreSQL storage through migration 0022_custom_vocab_translation with verified backup and restore tooling.
• Eight starter languages, 100-word packs, language-pair onboarding, topics, cards, review, written/four-choice practice, readable transcription guidance, audio, XP, streaks, and localized learning flows.
• Learners can change the active study language from /lang and from Mini App settings without losing saved progress.
• Learning-first Telegram quick actions prioritize Continue, due Review, Practice mode, explicit word/topic choice, and language switching; legacy delivered keyboards remain compatible.
• Protected admin console, privacy-safe product funnel, notification outbox, audit history, and public D1/D7 cohort metrics.
• D1/D7 eligibility now excludes incomplete observation windows: D1 requires 48 hours and D7 requires 192 hours from first onboarding.
• Metered AI tutor, durable credits, bounded companion memory, per-user/project budgets, breaker, and current-runtime provider cost settlement.
• Voice tutor and translation with consented, bounded transcript handling.
• Telegram Stars order/payment/subscription/refund/reconciliation code, reviewed catalog, launch gates, operator tooling, and a completed/refunded owner-only 10 XTR production canary.
• Public Cloudflare route restored and health/login verified.
• Daily local PostgreSQL backups plus one immutable age-encrypted off-site object and checksum.
• One isolated recovery-host restore drill completed against the off-site object; temporary database removed and receipt stored privately mode 0600.
• Documentation/license gate merged; stale draft PR Document product operating model and readiness audit #37 closed.
• Autodeploy intentionally remains absent during the pilot; releases stay reviewed and operator-controlled.

Current verified state — 2026-09-14

• GitHub main and OVH bot/admin run d8d98a41b22f5fe236cd57991c5794fb28607c40 from PR Measure Telegram quick-action usage #140. Database revision remains 0022_custom_vocab_translation.
• Bot heartbeat is ready; bot/admin restart counts are zero; exactly one bot process is running; PostgreSQL, the backup monitor, three consecutive loopback probes, public health, public admin login, and Mini App are healthy.
• AI Tutor, Voice Tutor, Voice Translation, bounded Mirror memory, Mini App, and Telegram Stars runtime are enabled. Mirror voice output, production Stars canary, and autodeploy are disabled. PR Measure Telegram quick-action usage #140 changed none of these flags. The protected Stars economics review date is synchronized to the canonical 2026-08-28 snapshot; price and limits are unchanged.
• Current 30-day public onboarding cohort: 21. In the post-quick-actions window since 2026-09-10, 3 learners started lessons and 1 completed a lesson.
• Corrected retention: D1 is 2 retained / 20 eligible / 10.0%; D7 is 1 retained / 4 eligible / 25.0%. D7 remains directional because eligible N is below 10.
• Durable words remain 0; no learner has yet reached correct_count >= 3 and interval >= 7.
• At the current onboarding timestamps, 11 learners are expected to become D7-eligible by 2026-09-17. Do not run a product decision review earlier than that date.
• Aggregate 30-day commercial evidence: 5 orders, 1 payment, 1 payer, 10 XTR gross, 10 XTR refunded, 0 XTR net; AI provider cost 26,948 micro-USD.
• The pre-deploy custom-format backup mydictionary-20260914T071748.725463Z-f0fe7386190d.dump is checksum-verified at revision 0022; the timer is active and its latest service result is successful.
• Current logs have zero traceback, polling-conflict, and token-pattern matches. Unauthenticated Mini App bootstrap and privacy actions both fail closed with HTTP 401.

Operating focus

• NSM: durable words (correct_count >= 3 and interval >= 7).
• OMTM through 2026-10-03: public D7 retained / eligible / rate.
• Do not make a product decision from a retention percentage with fewer than 10 D7-eligible learners.
• The immediate product bottleneck is not first-use activation (82.4%) but the path from activation to completed repetition and the first durable word (currently 0).
• PR Measure Telegram quick-action usage #140 now records privacy-safe quick_action_selected events and reply_keyboard lesson attribution; compare action selection, lesson start, completion, and first durable-word movement at the 2026-09-17 checkpoint.

Remaining gates

• Observe the current public cohort through 2026-09-17, then record D1/D7 with at least 10 D7-eligible learners and review the activation-to-durable-word drop-off.
• Provision dedicated Telegram test-server bot/user credentials and isolated database/data directory; complete purchase, duplicate delivery, restart recovery, reconciliation, refund, and subscription-cancel scenarios; create and review the private telegram_test receipt. The production 10 XTR canary does not satisfy this gate.
• Rotate the historically exposed Telegram production token through BotFather, verify the replacement heartbeat, and preserve the sanitized evidence copy.
• Archive or remove the original historical source log when that source becomes available.

Release posture

• No open delivery PR remains; production is on PR Measure Telegram quick-action usage #140 with quick-action attribution active.
• Telegram Stars runtime is enabled and unchanged by the retention release; the dedicated test-environment receipt remains required before billing is treated as fully launch-ready.
• Autodeploy stays disabled for the pilot; deploys follow the reviewed OVH release runbook with backup, exact SHA, restart, schema, heartbeat, health, and rollback acceptance.
• The next decision-grade product checkpoint is 2026-09-17. Until then, avoid reacting to the D7 percentage at eligible N=1 and concentrate on instrumentation and the activation-to-durable-word path.

[pirajoke]

Stages 0-1 are implemented in draft PR #7.\n\nDelivered:\n- architecture, ADR, AI evaluation gate, and billing assumptions\n- Alembic-managed PostgreSQL schema for users, profiles, and per-word progress\n- per-Telegram-user runtime isolation and fail-closed access control\n- idempotent migration from the legacy JSON state\n- PostgreSQL CI integration\n\nValidation: 34/34 tests pass in GitHub Actions with PostgreSQL.\n\nNo merge or production deployment has been performed. Stage 2 (provider-neutral AI gateway and usage metering) remains the next implementation boundary after review.

[pirajoke]

Stage 2 implementation is available as stacked draft PR #8: #8

Implemented scope:

• feature-flagged AI tutor grounded in the current active block
• Russian-first output with canonical target writing, Latin transcription, Russian meaning, and examples
• transactional pilot credit reservation, settlement, automatic in-process refunds, and observable recovery failures
• privacy-minimized request/token/cost/latency metering with no prompt or answer storage
• migration 0002_ai_tutor_usage and deterministic EN/VI/JA evaluations

Local verification: 51/51 tests passed on PostgreSQL 16; compile, dependency, and diff checks passed. The feature remains off with zero credits by default. No provider call, payment, real charge, merge, or production deployment was performed.

[pirajoke]

Product Foundation implementation started on agent/product-foundation from main 5db01c3. Scope: private/public vocabulary catalogs, administrator personal-pack isolation, guided onboarding, analytics events, migration, and deterministic tests. Excludes merge, production deployment, live AI calls, and payments.

[pirajoke]

Product Foundation implementation is ready for review in draft PR #10.

Included: versioned pack catalog, admin-only personal English pack with legacy progress preservation, persisted onboarding and enrollments, server-side pack authorization, privacy-minimized product events, and a learner-only admin funnel.

Validation: 82 passed, 2 skipped (TEST_POSTGRES_URL not configured), 1291 subtests; SQLite migration upgrade/downgrade/upgrade round-trip passed. Commit: 92f3409.

No merge, production deploy, AI calls, or payments were performed.

[pirajoke]

Ops hardening is implemented in draft PR #14 from the approved base bf67fba.

Delivered scope: versioned deploy/admin wrappers, credential-minimized candidate validation, exact Telegram heartbeat and HTTP readiness, protected content/schema gates, validated private PostgreSQL backups, migration-aware fail-closed recovery, failed-SHA quarantine, ADR, runbook, and focused tests.

Local validation: 126 tests passed with 2 PostgreSQL-only tests skipped locally; GitHub CI runs those against PostgreSQL. PR #14 remains draft. No merge or production change was performed, and autodeploy, AI, payments, access mode, and token state are unchanged.

[pirajoke]

Ops hardening draft PR #14 now also includes a standalone recurring PostgreSQL backup wrapper.

Backup guarantees: private custom-format dumps, Alembic revision + SHA-256 manifests, freshness check, 30-day/7-copy default floors, explicit validated prune, bounded command timeouts, and symlink-safe locking. Host-local backup does not cover host loss; encrypted off-host replication remains an open Stage 5 item.

Local validation now covers 138 tests (2 PostgreSQL integration tests skipped locally) and 39 ops-focused tests. GitHub CI runs the PostgreSQL cases. PR #14 remains draft; production and autodeploy are unchanged.

[pirajoke]

Project update: Latest GitHub and local UX state verified

Status: verified_with_divergence

Verified that GitHub main advanced to commit 6415555 at 2026-08-06 01:02 JST with the merged stages 4-7 release (billing, safety/privacy, voice tutor, launch readiness). The local codex/telegram-ux-p0 branch remains based on b8c0940 and has uncommitted daily-lesson UX changes last modified at 2026-08-05 15:20:47 JST.

Evidence

• GitHub latest commit verified through connected GitHub app
• Local branch, working tree, diff summary, and file modification times inspected

Next

• Integrate current GitHub main before publishing local P0 UX changes

• Resolve likely overlap in bot.py and rerun the full test suite

• Source repository: pirajoke/mydictionary

• Branch: codex/telegram-ux-p0

• Source commit: b8c0940bf68d0d2d9f272d232e107d14512cd18a

• Obsidian log: 90-Operations/project-update-webhook/logs/2026-08-05 -- my-dictionary -- latest-github-and-local-ux-state-verified -- 64b2a02d5c74.md

• Vault commit: e371a20b

[pirajoke]

Learning UX and Pilot Operations update — 2026-08-06

• Draft PR Improve block learning UX and translation variants #25: compact Telegram command menu (6 commands with AI off, 7 with AI on), curated Russian answer variants for bonjour, and two block-scoped modes: four-option test and written answer. Quiz distractors come only from the original active block.
• Draft PR Add pilot operations dashboard and notification outbox #26: dedicated pilot dashboard, cohort funnel, D1/D7 retention, stage filters, transactional access events, and a leased/retryable Telegram approval-notification outbox. PR Add pilot operations dashboard and notification outbox #26 is stacked on Improve block learning UX and translation variants #25.
• Review fixes prevent historical learning sessions from inflating pilot activation and align onboarding copy with the two visible block modes.
• Verification: full local suite passed with 248 tests; 2 PostgreSQL-only tests skipped because no integration URL was configured. Focused post-rebase suite passed 54 tests with the same 2 skips.
• No merge or production deploy was performed. Production access mode was not changed. No real notification, AI call, payment, or charge was executed.

[pirajoke]

Production release — 2026-08-06

Merged and deployed:

• PR Improve block learning UX and translation variants #25 (Learning UX) squash-merged.
• PR Add pilot operations dashboard and notification outbox #26 (Pilot Operations) rebased onto main, CI passed, squash-merged.
• Production runs main SHA 71fdc373e93120673916fd371d399814e396fd1c.
• PostgreSQL migration advanced to 0011_pilot_operations.
• Pre-deploy backup was created and validated; post-deploy restore-list validation passed.
• Bot, admin, local health and public health checks passed.
• Access remains pilot; AI tutor, voice tutor, Telegram Stars and autodeploy remain disabled.
• No real AI calls, payments or Telegram notification deliveries were performed.

Delivered product scope:

• Eight public starter packs with 100 words each, Russian meanings, Latin transcription and TTS metadata.
• Topic/block learning, written testing, four-choice block testing and accepted translation variants.
• Telegram command menu reduced to seven primary commands.
• Pilot funnel dashboard, allowlist controls and approval-notification outbox.

Remaining before broad commercial launch:

1. Add PostgreSQL-backed CI integration and migration round-trip tests.
2. Run a monitored pilot cohort and validate D1/D7 funnel, retention and notification delivery.
3. Configure encrypted off-host backups and complete a restore drill.
4. Rotate the Telegram bot token and sanitize historical logs (previously deferred).
5. Complete AI unit economics, budget limits and a separately approved real-call evaluation before enabling AI.
6. Complete Stars pricing, terms/support and a separately approved low-value payment/refund/reconciliation test before enabling payments.
7. Review/rebase or close stale documentation PR docs: add repository README and MIT license #12.

Issue stays open until pilot and commercial enablement are complete.

[pirajoke]

Project update: Telegram UX-P0 rebased and verified

Status: verified

Daily lesson, two-step onboarding, single-card learning flow, pace settings and privacy-safe card analytics were rebased onto current main while preserving billing, privacy and voice flows.

Evidence

• git diff --check
• python compileall
• 255 unit tests passed; 2 PostgreSQL tests skipped because TEST_POSTGRES_URL is not set

Next

• Push codex/telegram-ux-p0 as a draft PR and add a PostgreSQL service test job to GitHub Actions.

• Source commit: b8a985d

• Obsidian log: 90-Operations/project-update-webhook/logs/2026-08-06 -- mydictionary -- telegram-ux-p0-rebased-and-verified -- fa3966baf75b.md

• Vault commit: cec989ef

[pirajoke]

Encrypted backup restore progress — 2026-08-06

Draft PR #28 adds the missing recovery-host restore drill: exact immutable object selection, encrypted checksum validation, age decryption, custom-archive validation, a real restore into a generated disposable PostgreSQL database, exact Alembic revision verification, guaranteed database cleanup, and a private JSON receipt.

Validation: 254 tests passed in GitHub Actions with PostgreSQL 16. Both PostgreSQL integration tests executed through PostgresqlImpl; no tests were skipped. PR #28 is mergeable and remains draft.

Production audit found that the previous verified local dump contained pre-migration revision 0010_launch_readiness. A new private local dump was therefore created at 2026-08-06 06:13:09 UTC and independently rechecked: revision 0011_pilot_operations, size 77,473 bytes, backup check exit 0. Public health remained HTTP 200.

The roadmap backup item remains open until an actual remote is configured, this current-revision dump is encrypted and uploaded, and a separate approved recovery host produces and reviews a real receipt. The production host currently has PostgreSQL 16 tools but does not have age or rclone. No external upload, decryption, restore, deployment, or feature activation was performed.

[pirajoke]

Pilot baseline — 2026-08-06

Privacy-safe production aggregate (no learner identifiers): cohort 1; access active 1; onboarding completed 1; block started 1; block completed 1; approval notifications 0. Language: French; acquisition: direct.

D1 and D7 are not yet measurable because the cohort has 0 eligible learners. The first learner joined at 2026-08-06 06:12:56 CEST. Eligibility begins at:

• D1: 2026-08-07 13:12:56 JST
• D7: 2026-08-13 13:12:56 JST

A daily read-only thread heartbeat is scheduled for 13:20 JST. It will query only aggregate pilot_overview(days=30), public health, and notification counts; it is explicitly prohibited from reading identities, approving users, sending messages, enabling features, merging, or deploying. The pilot item remains open until eligible D1/D7 results and real notification delivery are verified.

[pirajoke]

Acceptance gates update — 2026-08-06 15:39 JST

Docs/license — PR #12

• FACT: merged as b541777; CI passed. README now documents fail-closed allowlist setup, marks render.yaml unsupported, and separates source-code MIT licensing from vocabulary-content provenance.
• DONE: documentation/license gate is closed.
• WAITING ON MARK: none for the merge; it completed before the manager scope clarification.
• BLOCKER: none.
• NEXT: provenance notes for legacy datasets remain a non-blocking documentation follow-up.

Telegram UX — PR #27

• FACT: merged as fbda64e; CI passed after updating onto current main. Adds focused daily/review entry, two-step onboarding, card-style learning with emoji/progress/audio controls, pace settings, and privacy-safe lesson analytics.
• DONE: code acceptance and merge are complete.
• WAITING ON MARK: explicit production deployment decision.
• BLOCKER: none in code; production intentionally remains on 71fdc37.
• NEXT: deploy only as a separately approved observed release; do not enable autodeploy.

Encrypted restore tooling — PR #28

• FACT: draft, CLEAN, mergeable at f4c2ed6; CI passed 261/261, including both PostgreSQL tests through PostgresqlImpl.
• DONE: isolated restore-drill tooling and automated acceptance coverage are ready.
• WAITING ON MARK: explicit approval to merge PR Add isolated encrypted-backup restore drill #28 and a selected off-site storage/key arrangement.
• BLOCKER: production has no configured off-site backend, age, or rclone; no real encrypted off-site upload/decrypt/restore has occurred.
• NEXT: choose the private off-site backend and recovery-host key custody, then perform and receipt one real isolated restore drill.

Pilot measurement

• FACT: aggregate cohort=1, active=1, onboarding completed=1, block started=1, block completed=1; D1/D7 eligible=0. First D1 window opens 2026-08-07 13:12 JST, D7 2026-08-13 13:12 JST.
• DONE: daily read-only aggregate monitor remains scheduled for 13:20 JST.
• WAITING ON MARK: no action required before the D1 window; more real users are still needed for meaningful retention.
• BLOCKER: retention cannot be claimed before eligibility/observation.
• NEXT: record D1 and D7 after their windows without identifiers or outreach.

Telegram token/log security

• FACT: private bot.log is mode 0600 and contains 6,380 historical Telegram API URL occurrences from 2026-08-03 07:22 to 2026-08-04 00:57 server time. The latest 64 KiB contains zero; HTTPX INFO logging is suppressed. Admin and autodeploy logs contain zero occurrences.
• DONE: new leakage is stopped and the historical exposure is quantified without exposing the token.
• WAITING ON MARK: separate approval for token rotation and destructive historical-log cleanup.
• BLOCKER: the old token must be treated as historically exposed until rotated.
• NEXT: rotate first, verify polling with the replacement, then securely redact/archive historical logs.

No deploy, Telegram message, AI/Voice/Stars activation, payment, secret display, token rotation, or log deletion was performed.

[pirajoke]

AI/Stars economics readiness — 2026-08-06 16:21 JST

Draft PR #29 (fffea3c) is open, CLEAN, mergeable, and green 266/266 in GitHub Actions with PostgreSQL 16.

FACT

• The reviewed OpenAI Standard prices for gpt-5.6-luna are versioned in a dated snapshot: $0.20 input, $0.02 cached input, $0.25 cache writes, and $1.20 output per 1M tokens.
• Telegram's current $0.013/Star reward reference is not treated as guaranteed net income. Package formulas use a conservative $0.010/Star assumption; the runtime hard cap falls to $0.0085 when private-chat topics are enabled because Telegram currently applies a 15% fee.
• Draft limits are 5 attempts/user/rolling 24h, $0.005 max measured cost/request, 12,000 provider-input characters, and 1,000 output tokens.

DONE

• AI activation now requires a current pricing-review date and positive cost limits.
• Failed provider attempts count toward the daily limit; a completed cost outlier opens a circuit breaker for later tutor requests.
• Stars activation requires a current economics-review date, explicit approval of the exact terms, monitored support configuration, and a conservative net value.
• Three formula-checked packages and Russian terms exist only as draft hypotheses.
• ops/mydictionary_economics.py validates formulas/sources/terms and renders only non-secret values with AI, Stars, and terms approval explicitly false.
• Admin diagnostics expose review freshness, limits, terms approval, and private-chat topic-fee state.

WAITING ON MARK

• Review the draft prices and Russian terms in PR Add fail-closed AI and Stars economics #29.
• Separately authorize one bounded real AI call after a provider key/budget is configured.
• Separately authorize a Telegram test-environment payment/refund/subscription-cancel run.
• Merge remains a separate explicit decision.

BLOCKER

No measured real AI cost, approved final legal/privacy terms, monitored production support contact, or test payment evidence exists yet. Therefore AI and Stars remain intentionally disabled and no product is active.

NEXT

After review, run exactly one real AI call, replace package cost hypotheses with measured usage, then run the separate Telegram test-payment gate. Do not deploy or enable paid access as part of PR #29.

[pirajoke]

Project update: Draft AI and Stars economics readiness PR is green

Status: waiting_on_mark

Draft PR #29 adds dated fail-closed AI/Stars economics, a conservative 10000 microUSD/XTR net assumption, rolling AI limits, cost circuit breaker, explicit terms approval, formula-checked draft products, draft Russian terms, admin diagnostics, and a non-secret disabled environment renderer. AI, Voice, and Stars remain off; no live API call or payment occurred.

Evidence

• local unittest 266 passed, 2 PostgreSQL-only skipped
• GitHub Actions 266/266 with PostgreSQL 16
• economics verifier OK
• compileall OK
• secret-pattern scan clean

Next

• Mark reviews draft prices and terms in PR Add fail-closed AI and Stars economics #29

• separate approval for one real AI call

• separate approval for Telegram test payment/refund/subscription cancellation

• no merge or deploy without explicit decision

• Source repository: pirajoke/mydictionary

• Source commit: fffea3c26b078132e1797bda21ffd59f714e46ef

• Obsidian log: 90-Operations/project-update-webhook/logs/2026-08-06 -- mydictionary -- draft-ai-and-stars-economics-readiness-pr-is-green -- 2e446243add5.md

• Vault commit: 77fc1516