bea-edit/agents.md

# Project Agent Guide

## Project overview

This repository contains **juri-merger**, a German-language SvelteKit application whose current UI is branded as **beA-Edit**. The main route lets users select or drag ZIP files in the browser. It currently displays the selected filenames; no server-side upload or archive-processing flow is present in this version.

The application also contains German legal pages for the imprint and privacy policy.

## Technology stack

- SvelteKit 2
- Svelte 5 with runes mode forced for project source files
- TypeScript with strict mode
- Vite 8
- Tailwind CSS 4 through `@tailwindcss/vite`
- Skeleton 4 with a custom `nominandum` theme
- pnpm and `pnpm-lock.yaml`
- `@sveltejs/adapter-auto`
- Prettier with the Svelte and Tailwind plugins

Use **pnpm**, not npm or yarn, when installing packages or running project scripts.

## Commands

```sh
pnpm install             # Install dependencies
pnpm dev                 # Start the development server
pnpm build               # Create a production build
pnpm preview             # Preview the production build
pnpm check               # Run Svelte and TypeScript diagnostics
pnpm check:watch         # Run diagnostics in watch mode
pnpm lint                # Check formatting with Prettier
pnpm format              # Format the repository with Prettier
```

There is currently no automated unit or end-to-end test suite. For code changes, run at least:

```sh
pnpm check
pnpm lint
pnpm build
```

If pre-existing warnings remain outside the files being changed, report them rather than making unrelated edits.

## Repository structure

```text
src/
├── app.html                         # German document shell and Skeleton theme selection
├── app.d.ts                         # SvelteKit application type declarations
├── lib/
│   ├── assets/                      # Bundled favicon and Nunito font files
│   ├── components/                  # Reusable Svelte components
│   │   ├── Button.svelte
│   │   ├── Card.svelte
│   │   └── ZipDropzone.svelte
│   ├── index.ts                     # Public `$lib` exports
│   └── nom-theme.css                # Custom Skeleton theme tokens
└── routes/
    ├── +layout.svelte               # Shared logo header and branded footer
    ├── +page.svelte                 # Main ZIP-selection page
    ├── layout.css                   # Tailwind/Skeleton imports and global font setup
    ├── datenschutz/+page.svelte     # Privacy policy
    └── impressum/+page.svelte       # Imprint
static/                              # Files served unchanged from the site root
```

Generated directories such as `.svelte-kit/`, `build/`, and `node_modules/` must not be edited or committed.

## Svelte conventions

- Use Svelte 5 runes and current event syntax. Prefer `$props()`, `$state`, `$derived`, snippets, `{@render ...}`, and handlers such as `onclick` over legacy APIs.
- Keep component scripts typed with `<script lang="ts">`.
- Define a local `Props` type for non-trivial component props.
- Use callback props for child-to-parent communication, as `ZipDropzone.svelte` does with `onFilesSelected`.
- Use `$lib/...` for imports from `src/lib` rather than long relative paths.
- Name reusable component files in PascalCase and route files according to SvelteKit conventions.
- Keep browser-only APIs such as `File`, `FileList`, and drag-and-drop handling in components that execute in the browser. Do not introduce server-side upload behavior unless requested.
- Preserve semantic HTML. Interactive drop zones must remain keyboard-operable buttons with an accessible name.

The Vite configuration forces runes mode for application files, so do not add legacy Svelte component patterns.

## Styling conventions

Use **Tailwind utility classes in Svelte markup** for component and route styling. Orient new work around the existing classes in `+layout.svelte`, `+page.svelte`, `Card.svelte`, and `ZipDropzone.svelte`.

- Prefer existing theme utilities such as `bg-primary-50`, `text-primary-900`, `border-primary-500`, and `rounded-container`.
- Use the custom `primary`, `secondary`, `tertiary`, and `surface` scales defined in `src/lib/nom-theme.css` instead of adding arbitrary brand colors.
- Keep the established visual language: cool blue-gray page background, white cards, dark blue headings, subtle shadows, rounded containers, and the Nunito typeface.
- Use responsive Tailwind variants and ensure layouts work on narrow screens.
- Prefer utilities over new component-level `<style>` blocks or inline styles. Add global CSS only when defining shared theme primitives, imports, font faces, or behavior that cannot reasonably be expressed with utilities.
- Tailwind 4 is configured through Vite and `src/routes/layout.css`; there is no `tailwind.config` file.
- Keep complete utility class names visible to Tailwind. For variants, map each state to complete class strings rather than constructing fragments such as `text-${color}`.
- Preserve clear focus states, adequate contrast, and visible drag-and-drop feedback.

`src/app.html` applies `data-theme="nominandum"`. Theme-level changes belong in `src/lib/nom-theme.css`; global Tailwind and Skeleton imports belong in `src/routes/layout.css`.

## Formatting

Follow the checked-in Prettier configuration:

- Tabs for indentation
- Single quotes in scripts and styles where supported
- No trailing commas
- 100-character print width
- Svelte-aware and Tailwind-aware formatting

Use `pnpm exec prettier --write <changed-files>` for targeted formatting. Avoid formatting unrelated files solely to clean up existing differences.

## Product and content constraints

- User-facing copy is German unless a task explicitly requests another language.
- Preserve legal text in `datenschutz/+page.svelte` and `impressum/+page.svelte` unless the request explicitly asks for content changes.
- Keep the shared Nominandum logo, footer artwork, and theme consistent across routes.
- ZIP selection is client-side and accepts `.zip`, `application/zip`, and `application/x-zip-compressed` files.
- Resetting the file input after selection is intentional so the same archive can be selected twice.
- Do not add network requests, file uploads, analytics, or persistence without an explicit requirement.

## Change discipline

- Keep changes scoped to the request and preserve unrelated work, including untracked files.
- Inspect existing components and theme tokens before introducing new abstractions.
- Do not hand-edit generated output or lockfile contents. Update the lockfile only through pnpm when dependency changes are required.
- Avoid adding dependencies when the task can be completed with Svelte, browser APIs, Tailwind, or existing Skeleton packages.
- After implementation, review the changed files, run the relevant checks, and mention any remaining warnings or limitations.