---
name: tuturuuu-satellite-app-ux
description: "Implement Tuturuuu satellite app shells, app-session auth, and workspace navigation."
---

# Tuturuuu Satellite App UX

## Core Workflow

Use this skill for standalone app surfaces under `apps/*` that behave like
satellite apps rather than sections inside `apps/web`.

For shell or auth changes, trace the target app's relevant `proxy.ts`, providers,
workspace layout, navigation, or app-session routes. A local UI change does not
require a full shell audit.

## App Shell Checklist

- Use `@tuturuuu/satellite` providers, i18n helpers, constants, and app-session
  helpers where the app already follows that pattern.
- Keep auth target names consistent across proxy, verify-token, refresh, logout,
  and server session reads.
- Preserve workspace route shapes and locale handling. New dashboard routes need
  navigation aliases, icons, permissions or access gates, and empty states.
- Build the actual app workspace as the first screen. Avoid marketing-style
  landing pages for operational apps.
- Prefer a focused app shell with clear primary navigation, search/filter tools,
  and compact repeated actions over a generic dashboard card wall.
- Add strings to the owning app's English and Vietnamese bundles. If shared UI
  strings are added, update every app bundle that ships that shared surface.

## Data And Mutation Rules

- Use TanStack Query for client fetching/mutation.
- Put shared app API clients behind `packages/internal-api/src/*` when code is
  reused outside one route.
- Do not add raw client-side app API fetches.
- Keep protected data reads and writes behind server-owned APIs. Do not expose
  privileged Supabase access to satellite clients.

## Cross-App Parity

For Calendar or Finance, assume the standalone app and the `apps/web`
counterpart move together unless the user explicitly scopes an exception.

For other satellite apps, inspect whether a shared package or `apps/web`
counterpart already owns the behavior before duplicating logic in the app.

## Verification

Run focused tests for the target app first, then required repo checks:

```bash
bun i18n:add --app chat --key common.save --value en="Save" --value vi="Lưu"
bun type-check:chat
bun i18n:sort
bun i18n:check
```

Use `bun i18n:add` for satellite translation key add/remove/replace work when
possible; use `--entries` or `--entries-file` for bulk updates so every detected
locale file is updated and sorted together. Reserve manual message JSON edits
for broad prose rewrites or value-only updates. Finish with `bun check` for
TypeScript, JavaScript, messages, or repo config changes unless an unrelated
pre-existing blocker prevents it. Finite builds needed to validate the authorized change may run. Start long-lived
servers only when requested or needed for explicitly requested runtime verification.