harb/landing/AGENTS.md

<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
# Landing Interface - Agent Guide

Vue 3 + Vite application that delivers the public marketing site and forthcoming staking UI.

## Technology Snapshot
- Vue 3 (Composition API) with TypeScript and Vite toolchain
- Vue Router for multi-view navigation
- Sass-based design system with custom typography
- `@wagmi/vue` for wallet connection (injected, WalletConnect, Coinbase Wallet)
- `@tanstack/vue-query` — required peer dependency of `@wagmi/vue`; must be registered via `VueQueryPlugin` in `main.ts`
- `@harb/web3` shared composables for wagmi config and wallet hooks
- `@harb/analytics` — self-hosted Umami wrapper; call `initAnalytics(url, id)` in `main.ts`, use `trackCtaClick(label)` via the `navigateCta` helper in views

## Key Views & Components
- `HomeView.vue` - Launch countdown, feature overview, and staking CTA
- `DocsView.vue` - Documentation portal with responsive navigation and generated table of contents
- `SecurityInfo.vue` - Displays unaudited badge (planned Q3 2026), KRAIKEN Token and Stake contract addresses with copy-to-clipboard, BaseScan and source links (#147)
- `landing/public/pitch-deck.html` — self-contained, print-optimized pitch deck for influencer outreach; accessible at `/pitch-deck.html`; footer link added in `KFooter.vue`
- Layout components (`KNavbar.vue`, `KFooter.vue`, `LeftRightComponent.vue`) manage shared chrome
- UI components (`KButton.vue`, `Countdown.vue`, `SocialButton.vue`, icon set) supply reusable primitives

## Design Notes
- Dark theme palette: primary `#07111B`, accent `#9667BE`
- Mobile-first breakpoints at 768px drive layout shifts and slide-out navigation
- Motion relies on CSS transitions to keep runtime costs low

## Development Workflow
- Boot the full stack with `nohup ./scripts/dev.sh start &`; the script handles landing dev server wiring.
- Use local package scripts for targeted tasks:
  - `npm install`
  - `npm run build`
  - `npm run preview`
  - `npm run type-check`
- Deployments assume hash-based routing and the Vite `base` setting configured for static hosting.

## Analytics

The landing page uses `@harb/analytics` (a self-hosted Umami wrapper) for conversion funnel tracking.

- `initAnalytics(VITE_UMAMI_URL, VITE_UMAMI_WEBSITE_ID)` is called in `main.ts` — the Umami `<script>` tag is injected dynamically so ad-blocker state is handled gracefully.
- CTA buttons use `navigateCta(path, label)` in `HomeView.vue` instead of `router.push()` directly — this fires `trackCtaClick(label)` before navigating. Tracked labels: `hero_get_krk`, `how_it_works_get_krk`, `getting_started_get_krk`, `view_protocol`, `how_it_works_docs`.
- **Cross-app routing**: paths starting with `/app` use `window.location.href` instead of `router.push()` — the webapp is a separate Vue app served by Caddy, so client-side router pushes would be caught by the catch-all and redirect back to `/`.
- All tracking calls are safe no-ops if Umami is unavailable (ad-blocked, env vars unset, dev mode without Umami running).
- Env vars required: `VITE_UMAMI_URL` (script URL), `VITE_UMAMI_WEBSITE_ID` (UUID). See `docs/ENVIRONMENT.md`.

## Upcoming Integrations
- Wallet connection with Base network switching
- Staking dashboard that reuses shared helpers from `kraiken-lib`
- Data visualisations sourced from the Ponder GraphQL API

## Quality Guidelines
- Favour Composition API and strongly typed props/emit definitions
- Keep components focused; push shared logic into composables when possible
- Use Sass variables and mixins from the design system for consistent styling

## Performance Tips
- Lazy load route components
- Optimise imagery (WebP) and leverage Vite asset handling
- Prefer CSS animations to JavaScript when animating UI elements