# Kenly — Product Vision & Surfaces > Companion to [`spec.md`](https://docs.getkenly.com/spec). The spec defines the **engine** — the resumable, approval-gated, > page-by-page translation pipeline (Milestones M1–M4). This document defines the **product**: the > surfaces real users (and their AI agents) touch, and how Kenly becomes a business. Brand: see > [`brand/name-kenly.md`](https://docs.getkenly.com/brand/name-kenly) and [`brand/brand-guide.md`](https://docs.getkenly.com/brand/brand-guide). > > **Status:** vision / scoping. Nothing here is built yet except the core engine. Each surface below > maps to a Feature on the ADO board (Aeonic-Tech → Manuscript Translator). --- ## 1. Where this is going Today Kenly is a .NET engine with a Minimal API and fake/real adapters, driven locally. The vision is a **multi-surface product**: a hosted web app, a public API, an MCP server for AI agents, a metered token economy, and eventually native desktop apps — all sitting on top of the same state-machine engine. ``` ┌──────────────────────────────┐ │ Kenly engine (spec.md) │ │ state machine · pipeline · │ │ OCR/lang/translate adapters │ └──────────────┬───────────────┘ │ (one core, many surfaces) ┌───────────────┬────────────────────┼───────────────────┬──────────────────┐ ▼ ▼ ▼ ▼ ▼ Web app Public API MCP server Token billing Desktop apps getkenly.com (keys, docs, (users' own AI (buy credits, (Win/Mac/Linux, upload→approve rate limits) agents drive it) metered/page) right-click → ken) → download ``` **Design tenet (inherited from the engine):** every surface is a thin client over the *same* explicit, resumable, approval-gated state machine. No surface gets to bypass the human-approval gate or cascade operations — the API, the MCP tools, the web UI, and the desktop apps all speak the same guarded transitions (spec §3). --- ## 2. Surfaces ### 2.1 Web frontend — `getkenly.com` *(Feature: Web app)* The flagship surface. A signed-in user can: - Create a project and **upload** a PDF / scanned pages / screenshots (with progress). - Watch the **approval-gated pipeline** run (1 → 5 → 25 → 100 → rest), reviewing each batch and **approving/rejecting** before escalation — the gate is the product's signature UX. - See **cost estimates** before committing (the engine already meters ~$0.001/page; project whole-book cost up front). - **Download** results (Markdown today; DOCX/EPUB/PDF as they land) with original scan beside the English translation. - Manage account, billing, and token balance. - **Branding requirement:** the Kenly logo appears as the **favicon in the browser tab** on every page (see brand guide §3). ### 2.2 Public API (GA) *(Feature: Public API)* Promote the internal Minimal API to a **documented, authenticated, public** API: - API keys / OAuth, per-tenant isolation, rate limits, quotas tied to token balance. - One endpoint per state-machine transition (already the design — spec §7); 409 on guard violations. - Versioning, OpenAPI spec, and published docs. - Webhooks for async events (batch ready for review, project complete, export ready). - This API is the substrate the web app, MCP server, and desktop apps all consume. ### 2.3 MCP server — agent access *(Feature: MCP server)* Let users' **own AI agents** drive Kenly via the Model Context Protocol, so the agent can manage the whole job for them instead of the human clicking through it: - MCP tools mirroring the public API: `create_project`, `upload_pages`, `get_cost_estimate`, `process_next_batch`, `get_review_package`, `approve_batch` / `reject_batch`, `export`, `download_result`, `get_token_balance`, `purchase_tokens` (or surface a checkout link). - Authenticated per user (scoped key / OAuth), drawing on the same token balance and quotas. - Honors the **approval gate**: an agent can be granted auto-approve scopes explicitly, but the default is the human stays in the loop — the MCP layer must not silently bypass review. - Ships as a deployable server + a `npx`-style local connector; listed for Claude/other MCP clients. ### 2.4 Token economy & billing *(Feature: Billing & tokens)* Monetization via **prepaid tokens/credits**, a natural fit since the engine already meters GPU cost per page: - Users **purchase tokens** (Stripe or similar); balance is consumed per page/per model-operation. - Transparent metering: the existing cost estimator (`cost/samples.jsonl`, `GET …/cost` + `/estimate`) becomes the user-facing "this book will cost ~N tokens" quote before they commit. - Plans/packs, low-balance alerts, receipts/invoices, usage history. - Quotas + spend caps enforced at the API layer so web, MCP, and desktop all share one balance. - Free tier / trial credits for onboarding. ### 2.5 Native desktop apps *(Feature: Desktop apps)* Eventually, native apps for **Windows, macOS, and Linux** with deep OS integration: - **Right-click a file → "Ken this" (translate to English)** from the OS file manager (shell extension / Finder Quick Action / Linux file-manager action). The killer convenience feature. - Thin client over the public API: uploads the file, runs the approval-gated job (with a local review UI), downloads the result back next to the original. - Sign in with the same account/token balance; offline queueing where sensible. - Likely .NET-based (MAUI / Avalonia) to share the existing C# core, or a Tauri-style shell — to be decided in the Feature's spike. --- ## 3. Cross-cutting work the surfaces require These are prerequisites that span multiple surfaces (each likely its own PBI under the relevant Feature): - **Accounts & auth** — identity, sessions, API keys, OAuth, per-tenant data isolation (multi-tenancy). - **Cloud storage** — move project state off the local filesystem (`FileSystemProjectStore`) to durable cloud storage / DB while preserving the resumable-JSON design (spec §6). - **Hosting & scale** — deploy the API + workers (RunPod for models, spec §8 M4), autoscaling, observability. **Plan + cost estimate:** [`deployment.md`](https://docs.getkenly.com/deployment). - **Security & privacy** — users upload copyrighted/private manuscripts; encryption at rest/in transit, data-retention policy, deletion. - **Branding rollout** — rename `ManuscriptTranslator` → Kenly across surfaces; apply the brand guide (logo, favicon, colors, type). See `brand/brand-guide.md`. --- ## 4. Rough sequencing (not committed dates) 1. **Brand & identity** (name ✅ / domain ✅ → logo, colors, brand guide, apply) — in flight now. 2. **Accounts + cloud storage + Public API GA** — the foundation every other surface needs. 3. **Web frontend** on `getkenly.com` — the flagship, drives first real users. 4. **Token economy & billing** — turn it into a business. 5. **MCP server** — unlock agent-driven usage. 6. **Native desktop apps** — the right-click-to-translate convenience layer. > This ordering is a default, not a contract — billing and the web app overlap heavily, and the MCP > server can come earlier if agent-driven demand leads.