# Agent Instructions — Codex (Nuxt 3 + FastAPI, Greenfield, Mock-First)

This repository contains a **Nuxt 3 frontend**.
A **FastAPI** backend will be developed in parallel (may be in a separate repo/service).

You are an automated coding agent (Codex).

Your job is to make **precise, minimal, correct changes** while strictly following these rules.
Do not guess. If required information is missing, stop and ask one clear question.

This is an early-stage project. Prefer **simple, explicit patterns**.

---

## Repository Structure

- Root directory:
  - Deployment artifacts: `Dockerfile`, `deploy/docker-compose.yml`
  - Nuxt application lives in `NautilusDeskTimeFrontend/`

- `NautilusDeskTimeFrontend/app/`
  - Nuxt application source (pages, layouts, components, composables)

- `NautilusDeskTimeFrontend/server/`
  - Nuxt/Nitro server code may exist
  - Backend business logic belongs in FastAPI, not here

- `NautilusDeskTimeFrontend/public/`
  - Static assets served as-is

- Generated output (DO NOT EDIT):
  - `NautilusDeskTimeFrontend/.nuxt/`
  - `NautilusDeskTimeFrontend/.output/`

---

## Commands (Frontend)

Run all frontend commands from `NautilusDeskTimeFrontend/`.

- `npm install`
- `npm run dev` (`http://localhost:3000`)
- `npm run build`
- `npm run preview`
- `npm run generate` (if used)

Do not modify build scripts unless explicitly instructed.

---

## Tech Stack

Frontend:
- Nuxt 3
- Vue 3 (Composition API only)
- TypeScript
- Vite
- Tailwind CSS
- Plain CSS is allowed when needed

Backend (separate service):
- FastAPI
- JWT authentication

Do not introduce new dependencies unless explicitly requested.

---

## Global Coding Rules (Strict)

- Prefer clarity over abstraction
- Keep diffs small and scoped
- Do not refactor unless asked
- Do not change behavior unless asked
- Do not remove code unless instructed
- Avoid speculative features
- Do not add comments explaining obvious code

When no established pattern exists yet:
- introduce a simple, conventional pattern
- apply it consistently
- do not over-engineer

---

## Vue & Nuxt Conventions

### Components
- Use `<script setup lang="ts">`
- No Options API
- No class-based components
- Props and emits must be typed
- Avoid `any` and unsafe casts
- Components must do one job

### Pages & Routing
- Use Nuxt file-based routing
- Page files in `app/pages/` use lowercase filenames
- Use `definePageMeta` for layout, middleware, SEO
- Do not manually configure routes

### Composables
- Prefix composables with `use`
- No side effects at import time
- Return only what is required
- Keep UI concerns out of composables

---

## Backend Integration (FastAPI)

### Source of Truth
- Backend business logic will live in FastAPI
- Do not create new `/server/api/*` endpoints in Nuxt unless explicitly instructed
- Nuxt server code is infrastructure only (optional proxy/SSR helpers)

### API Contract & Mocking (IMPORTANT)
- The FastAPI API may not exist yet.
- If OpenAPI schema is not available, use **mock data** to build the frontend.

Rules for mock data:
- Mock data must be centralized in a single place (e.g. `app/mocks/`).
- Mocks should match likely real shapes (typed interfaces).
- Switching from mock to real API must be easy:
  - Use a single API layer (e.g. `app/composables/useApi.ts` or `app/services/api/`).
  - Pages/components must not directly embed mock fixtures.
- Prefer feature flags via runtime config (e.g. `useMockApi`) only if needed.
- Do not invent endpoints; if endpoints are unknown, create placeholders and document assumptions in code only when necessary.

### API Access
- Use `$fetch` for HTTP calls from composables/stores.
- Use `useFetch` / `useAsyncData` in pages/components when SSR-friendly loading is needed.
- Do not hardcode hostnames/ports.

### Configuration
- FastAPI base URL must come from runtime config or environment variables.
- If config keys do not exist yet, create them in `nuxt.config` using conventional names:
  - `runtimeConfig.public.apiBaseUrl`
- Keep client-only values in `runtimeConfig.public`.

---

## Authentication (JWT)

JWT will be used for authentication.

Rules:
- Do not assume token storage strategy unless specified.
- Default strategy (if not otherwise specified):
  - Store JWT in memory (Pinia) and optionally persist using existing project preference when defined.
- Do not implement auth flows that require backend behavior not defined yet.
- If backend endpoints for auth are unknown, build UI using mock auth responses and typed models.

When adding auth:
- Centralize token attach logic in the API layer (single place).
- Do not sprinkle Authorization header logic across components.
- Use `Authorization: Bearer <token>` when making authenticated requests.

If any auth detail is unclear (login endpoint, refresh tokens, expiry behavior):
- Stop and ask one question.

---

## State Management

- Use Pinia only if needed and keep it minimal
- One store per domain
- Setup-style stores only
- Handle async errors explicitly
- Stores must not manipulate the DOM

---

## Styling

- Use Tailwind by default
- Plain CSS is allowed when needed
- Avoid inline styles unless unavoidable
- Keep `.vue` indentation at **4 spaces**

---

## TypeScript Rules

- Be explicit with types
- Prefer narrowing over casting
- Avoid `any`
- Avoid `as unknown as`

---

## Testing & Validation

- No test framework is configured yet
- Validate changes by running `npm run dev`
- Manually exercise affected routes/features
- If tests are added, document how to run them

---

## Git Rules (MANDATORY)

For every logical change:
1. Make the change
2. `git status` must be clean after commit
3. Commit with a concise imperative message
4. Push the commit

Rules:
- One logical change per commit
- Do not mix unrelated changes
- Do not leave uncommitted changes

If commit or push cannot be completed:
- Stop
- Explain why
- Ask one concise question

---

## Output Requirements

When responding with code changes:
- Modify only relevant files
- Do not include unchanged files
- Do not include explanations unless explicitly requested
- Do not include emojis or conversational text
- Prefer minimal diffs

---

## Failure Handling

If a task cannot be completed safely:
- Stop
- State what is missing
- Ask one clear question

---

You are a deterministic Nuxt 3 frontend coding agent.
Build against mock data when the API is not available.
Integrate with FastAPI via runtime-configured base URLs.
Use JWT auth via Bearer tokens when endpoints are defined.
Maintain clean git history with commit+push for each change.