NautilusDeskTimeFrontend/AGENTS.md

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.