docs: add CLAUDE.md project conventions

Author: fmaass

CLAUDE.md

@@ -0,0 +1,181 @@
+# Teedy — Conventions for Claude Code
+
+Maintained fork of sismics/docs (Teedy). Document management system with OCR, tagging, workflows, and REST API. Java 21 backend, Vue 3 frontend, PostgreSQL storage.
+
+## Tech Stack
+
+- **Backend:** Java 21, Maven 3.9.9, Jakarta EE 10, Jetty 12, Jersey 3.1, Hibernate 6.6, Lucene 10
+- **Frontend:** Vue 3 (Composition API), TypeScript, Vite, PrimeVue 4 (Lara preset), Pinia, TanStack Vue Query, vue-i18n
+- **Database:** PostgreSQL 17 (production), H2 embedded (dev/test)
+- **Docker:** Ubuntu 24.04, OpenJDK 21, Jetty 12, Tesseract OCR, ffmpeg, mediainfo
+- **CI:** GitHub Actions → GHCR multi-arch images (amd64 + arm64)
+
+## Project Structure
+
+    pom.xml                          # Maven parent (docs-parent)
+    docs-core/                       # Domain, persistence, services, Lucene, DB migrations
+    docs-web-common/                 # Shared web/security (JWT, API key filters)
+    docs-web/                        # JAX-RS REST API + Vue SPA
+      src/main/java/.../resource/    # REST endpoints (@Path)
+      src/main/webapp/               # Vue 3 SPA (Vite project)
+        src/views/                   # Page components
+        src/components/              # Reusable components
+        src/stores/                  # Pinia stores
+        src/api/                     # API client modules
+        src/assets/                  # CSS tokens + theme
+        src/theme/                   # PrimeVue preset (primary palette)
+        src/locale/                  # i18n JSON files
+      src/test/java/                 # REST integration tests (JUnit 5)
+    docs-importer/                   # Separate Node.js bulk importer (optional)
+    Dockerfile                       # Production image
+    docker-compose.yml               # Example stack (app + Postgres)
+
+## Build & Run
+
+Backend (from repo root):
+
+    ./mvnw clean -DskipTests install              # Dev build
+    ./mvnw -Pprod -DskipTests clean install        # Production WAR (includes Vite build)
+
+Frontend dev server (from docs-web/src/main/webapp/):
+
+    npm install
+    npm run dev                                    # Vite dev server with API proxy to :8080
+
+Backend dev server (from docs-web/):
+
+    ../mvnw jetty:run                              # Jetty on :8080, context /docs-web
+
+Docker:
+
+    docker compose up -d                           # App + Postgres on :8080
+
+## Tests
+
+    ./mvnw test                                    # All tests (JUnit 5, ~24 REST integration tests)
+    ./mvnw test -pl docs-web                       # Web module tests only
+    ./mvnw test -pl docs-core                      # Core module tests only
+
+Tests use embedded H2 and Jersey Test Framework. CI also requires ffmpeg, mediainfo, tesseract-ocr on the host.
+
+## Database Migrations
+
+Custom incremental SQL, not Flyway/Liquibase:
+
+    docs-core/src/main/resources/db/update/dbupdate-NNN-M.sql
+
+Current version: `db.version=36` in `config.properties`. `DbOpenHelper` reads `DB_VERSION` from `T_CONFIG` and runs upgrade scripts in order. When adding a migration, increment the version in `config.properties` and create the corresponding SQL file.
+
+## REST API
+
+All endpoints under `/api/*`. Auth via session cookie or `Authorization: Bearer tdapi_<hex>` (API keys).
+
+Key resources: `/document`, `/tag`, `/file`, `/user`, `/apikey`, `/webhook`, `/app`, `/acl`, `/group`, `/comment`, `/metadata`, `/auditlog`, `/theme`, `/route`, `/routemodel`, `/tagmatchrule`, `/oidc`.
+
+Content-Type for mutations: `application/x-www-form-urlencoded` (form params). File upload: `multipart/form-data` on `PUT /api/file`.
+
+## Frontend Conventions
+
+- PrimeVue components everywhere — no raw HTML form elements in new code
+- Colors via `--p-*` (PrimeVue semantic tokens) or `--teedy-*` aliases in `teedy-tokens.css`
+- Brand primary: `#2aabd2` defined in `src/theme/primary.ts`
+- Dark mode: `.dark-mode` class on `documentElement`, PrimeVue handles palette
+- Stores: Pinia (`auth.ts`, `tagFilter.ts`)
+- Data fetching: TanStack Vue Query for cacheable reads, direct Axios for mutations
+- i18n: `vue-i18n` with lazy-loaded locales, English bundled
+
+## Deployment (Saturn)
+
+Production runs on Saturn (Synology NAS). The production stack lives in the portainer-stacks repo, not here.
+
+    # Push code
+    git push
+
+    # Pull on Saturn and rebuild
+    ssh saturn.local "cd /volume1/docker-compose && /usr/local/bin/git pull"
+    ssh saturn.local "cd /volume1/docker-compose/stacks/teedy && sudo /usr/local/bin/docker-compose up -d --build"
+
+    # Verify
+    ssh saturn.local "sudo /usr/local/bin/docker ps --filter name=teedy"
+    ssh saturn.local "sudo /usr/local/bin/docker logs teedy --tail 20"
+
+CI publishes images to `ghcr.io/fmaass/teedy-docs` with tags: `v*` for releases, `latest` on main, `release-<branch>-rc-<sha>` for release branches.
+
+## Homelab Context
+
+- **Saturn** — Main Docker host (Synology NAS), 192.168.1.50, `ssh saturn.local`
+- **Merkur** — This machine (Mac), 192.168.1.51 — **NEVER SSH to it, run commands directly**
+- Domain: `*.discomarder.live` (Cloudflare DNS → Saturn:443 via Traefik)
+- Teedy URL: `https://teedy.discomarder.live` (behind Authelia + OIDC)
+- Database: shared `postgres17` container on Saturn
+
+Saturn requires full paths and sudo:
+
+    ssh saturn.local "sudo /usr/local/bin/docker ps"
+    ssh saturn.local "sudo /usr/local/bin/docker logs <container>"
+
+## Git Workflow
+
+- NEVER commit directly to `main`. Create `feature/<name>` or `fix/<name>` branch first.
+- Integration branch: `release/2.6` (current). Feature branches off release branch.
+- Squash merge to release branch when feature is done.
+- When release is complete: merge release branch to `main`, tag `vX.Y.Z`.
+- Delete branches after merge.
+- NEVER add `Co-authored-by` trailers or use `--trailer` flags. Subject + body only.
+- Global hook at `~/.config/git/hooks/commit-msg` strips trailers as safety net.
+
+## Environment Variables
+
+Key app config (set via Docker env or JVM system properties):
+
+    DOCS_BASE_URL               # Public URL (e.g. https://teedy.discomarder.live)
+    DOCS_DEFAULT_LANGUAGE        # OCR language (e.g. deu)
+    DOCS_ADMIN_PASSWORD_INIT     # Bcrypt hash for initial admin password
+    DOCS_TRASH_RETENTION_DAYS    # Auto-purge trashed docs (default 30)
+    DOCS_MAX_UPLOAD_SIZE         # Max file upload in bytes (default 500MB)
+    DATABASE_URL                 # JDBC URL
+    DATABASE_USER / DATABASE_PASSWORD
+    DOCS_SMTP_*                  # Email config
+
+## Working Style
+
+- Never suggest stopping, pausing, or deferring work. Just do it.
+- **Boy Scout Rule**: when touching files, clean up adjacent files in the same directory — stale references, dead docs, inconsistencies. Stay proportional, don't over-fix.
+
+## Session Review
+
+After completing an implementation session (all tasks done, committed, deployed/verified), automatically produce a **Session Review** before ending. Also produce one when prompted with "session review".
+
+Use this exact format:
+
+    # Session Review — YYYY-MM-DD
+
+    ## Delivered
+    - **Branch**: `feature/xxx` → merged to `release/2.6` / still open
+    - Feature/fix A: one-line description
+    - Feature/fix B: one-line description
+    - **Duration**: ~Xh (wall clock estimate)
+
+    ## Issues
+
+    ### 1. Short title
+    - **Symptom**: What was observed (1-2 sentences)
+    - **Root cause**: Why (1 sentence)
+    - **Fix**: What was done (1 sentence)
+    - **Rule**: Prevention rule for future sessions
+    - **Repeat?**: No / Yes — see Session YYYY-MM-DD #N
+
+    ## Observations
+    - Non-urgent patterns, things that worked well, things to watch
+
+    ## Action Items
+    | # | Action | Priority | Effort | From |
+    |---|--------|----------|--------|------|
+    | 1 | Description | High/Med/Low | Small/Med/Large | #N |
+
+Rules for writing the review:
+- **Delivered first.** Always record what shipped, not just what broke.
+- **No debugging narrative.** Each issue gets the 5-field structure above.
+- **Flag repeats.** If an issue matches a previous session's lesson, mark it.
+- **Action items link back** to the issue number via the `From` column.
+- **Keep it tight.** Each issue 5-8 lines max. Whole review fits on one screen.