Kenly Developers

Kenly — Product Vision & Surfaces ​

Companion to spec.md. 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 and brand/brand-guide.md.

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