# TELEGRAM_WALKTHROUGH — Oshun Telegram Mini App

A checklist-driven inventory of every view and interaction in the Oshun
**Telegram Mini App** — the Telegram WebApp served from
`apps/oshun/telegram-miniapp`. Parallel to
[`../WALKTHROUGH/`](../WALKTHROUGH/README.md); same per-view file format,
different app.

## What this is (and is not)

- **Is**: A per-view checklist for the mini app's two routes plus the
  cross-cutting findings about its Telegram-WebApp integration state.
- **Is not**: A duplicate of `WALKTHROUGH/`. This is a separate Next.js app
  exposing **customer + curated-creator surfaces only** — operator and AAA-tier
  workflows deliberately stay in Oshun web.

## Surface map

2 routes, single Next.js app at `apps/oshun/telegram-miniapp`.

| Route        | File         | What it is                                                     |
| ------------ | ------------ | -------------------------------------------------------------- |
| `/`          | `home.md`    | Surface-list landing — links into the seven curated surfaces   |
| `/[surface]` | `surface.md` | Dynamic per-surface detail (7 static slugs; unknown → `today`) |

The seven surface slugs are `today`, `sophia`, `veritas`, `nyx`, `arete`,
`nisaba`, `illustration` (statically generated via `generateStaticParams`).

## Folder layout

```
TELEGRAM_WALKTHROUGH/
  README.md          # this file
  home.md            # /
  surface.md         # /[surface]
  matrix/
    routes.csv       # route,group,source,target,status,notes
```

## Per-view files

Each follows
[`../WALKTHROUGH/00-conventions.md`](../WALKTHROUGH/00-conventions.md). Both
routes are **drafted**.

## Notable finding — Telegram WebApp runtime is not yet wired (V1)

There is no `telegram-web-app.js` script in `layout.tsx`, no `window.Telegram`
access, and `src/lib/telegram-webapp.ts` (initData header, `themeParams` CSS
vars, `MainButton` / `BackButton` / `HapticFeedback`) is imported nowhere under
`src/app/` — it is only exercised by its own unit test. The app currently has no
middleware, no auth, and no BFF/`fetch` calls; all action buttons mutate local
`useState` and update a `role="status"` line. Frontmatter therefore declares
`auth: none`. Wiring the Telegram runtime (initData validation, theme params,
native buttons, haptics) is the load-bearing V1 follow-up — tracked in each
file's "Open questions / known gaps."