AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to AI Agents when working with code in this repository.
4 
5## Taskfile (Recommended)
6 
7This project uses [Task](https://taskfile.dev/) as a unified command runner. All build, dev, test, lint, and docker commands can be run from the repo root via `task <command>`. Run `task --list` to see all available commands.
8 
9Task `desc:` fields should describe **what** the task does, not **how** it does it. Keep them generic and stable: don't reference implementation details like aliases, internal helpers, mode flags, or which other task delegates to which. The description is for users picking a command from `task --list`, not a changelog of refactors.
10 
11### Quick Reference
12- `task install` — install all dependencies
13- `task dev` — start backend + frontend concurrently
14- `task dev:all` — start backend + frontend + engine concurrently
15- `task build` — build all components
16- `task test` — run all tests (backend + frontend + engine)
17- `task lint` — run all linters
18- `task format` — auto-fix formatting across all components
19- `task check` — full quality gate (lint + typecheck + test)
20- `task clean` — clean all build artifacts
21- `task docker:build` — build standard Docker image
22- `task docker:up` — start Docker compose stack
23 
24## Common Development Commands
25 
26### Build and Test
27- **Build project**: `task build`
28- **Run backend locally**: `task backend:dev`
29- **Run all tests**: `task test` (or individually: `task backend:test`, `task frontend:test`, `task engine:test`)
30- **Docker integration tests**: `./test.sh` (builds all Docker variants and runs comprehensive tests)
31- **Code formatting**: `task format` (or `task backend:format` for Java only)
32- **Full quality gate**: `task check` (runs lint + typecheck + test across all components)
33 
34After modifying any files in the project, you must run the relevant `task check` command that covers that area of the code. For example, when editing frontend files run `task frontend:check`; for Python engine files run `task engine:check`; for Java backend files run `task backend:check`.
35 
36### Docker Development
37- **Build standard**: `task docker:build` (or `docker build -t stirling-pdf -f docker/embedded/Dockerfile .`)
38- **Build fat version**: `task docker:build:fat`
39- **Build ultra-lite**: `task docker:build:ultra-lite`
40- **Start compose stack**: `task docker:up` (or `task docker:up:fat`, `task docker:up:ultra-lite`)
41- **Stop compose stack**: `task docker:down`
42- **View logs**: `task docker:logs`
43- **Example compose files**: Located in `exampleYmlFiles/` directory
44 
45### Security Mode Development
46Set `DOCKER_ENABLE_SECURITY=true` environment variable to enable security features during development. This is required for testing the full version locally.
47 
48### Python Development (AI Engine)
49 
50The engine is a Python reasoning service for Stirling: it plans and interprets work, but it does not own durable state, and it does not execute Stirling PDF operations directly. Keep the service narrow: typed contracts in, typed contracts out, with AI only where it adds reasoning value. The frontend calls the Python engine via Java as a proxy.
51 
52#### Python Commands
53All engine commands run from the repo root using Task:
54- `task engine:check` — run all checks (typecheck + lint + format-check + test)
55- `task engine:fix` — auto-fix lint + formatting
56- `task engine:install` — install Python dependencies via uv
57- `task engine:dev` — start FastAPI with hot reload (localhost:5001)
58- `task engine:test` — run pytest
59- `task engine:lint` — run ruff linting
60- `task engine:typecheck` — run pyright
61- `task engine:format` — format code with ruff
62- `task engine:tool-models` — generate `tool_models.py` from the Java OpenAPI spec
63 
64The project structure is defined in `engine/pyproject.toml`. Any new dependencies should be listed there, followed by running `task engine:install`.
65 
66#### Python Code Style
67- Keep `task engine:check` passing.
68- Use modern Python when it improves clarity.
69- Prefer explicit names to cleverness.
70- Avoid nested functions and nested classes unless the language construct requires them.
71- Prefer composition to inheritance when combining concepts.
72- Avoid speculative abstractions. Add a layer only when it removes real duplication or clarifies lifecycle.
73- Add comments sparingly and only when they explain non-obvious intent.
74 
75#### Python Typing and Models
76- Deserialize into Pydantic models as early as possible.
77- Serialize from Pydantic models as late as possible.
78- Do not pass raw `dict[str, Any]` or `dict[str, object]` across important boundaries when a typed model can exist instead.
79- Avoid `Any` wherever possible.
80- Avoid `cast()` wherever possible (reconsider the structure first).
81- All shared models should subclass `stirling.models.ApiModel` so the service behaves consistently.
82- Do not use string literals for any type annotations, including `cast()`.
83 
84#### Python Configuration
85- Keep application-owned configuration in `stirling.config`.
86- Only add `STIRLING_*` environment variables that the engine itself truly owns.
87- Do not mirror third-party provider environment variables unless the engine is actually interpreting them.
88- Let `pydantic-ai` own provider authentication configuration when possible.
89 
90#### Python Architecture
91 
92**Package roles:**
93- `stirling.contracts`: request/response models and shared typed workflow contracts. If a shape crosses a module or service boundary, it probably belongs here.
94- `stirling.models`: shared model primitives and generated tool models.
95- `stirling.agents`: reasoning modules for individual capabilities.
96- `stirling.api`: HTTP layer, dependency access, and app startup wiring.
97- `stirling.services`: shared runtime and non-AI infrastructure.
98- `stirling.config`: application-owned settings.
99 
100**Source of truth:**
101- `stirling.models.tool_models` is the source of truth for operation IDs and parameter models.
102- Do not duplicate operation lists if they can be derived from `tool_models.OPERATIONS`.
103- Do not hand-maintain parallel parameter schemas when the generated tool models already define them.
104- If a tool ID must match a parameter model, validate that relationship explicitly in code.
105 
106**Boundaries:**
107- Keep the API layer thin. Route modules should bind requests, resolve dependencies, and call agents or services. They should not contain business logic.
108- Keep agents focused on one reasoning domain. They should not own FastAPI routing, persistence, or execution of Stirling operations.
109- Build long-lived runtime objects centrally at startup when possible rather than reconstructing heavy AI objects per request.
110- If an agent delegates to another agent, the delegated agent should remain the source of truth for its own domain output.
111 
112#### Python AI Usage
113- The system must work with any AI, including self-hosted models. We require that the models support structured outputs, but should minimise model-specific code beyond that.
114- Use AI for reasoning-heavy outputs, not deterministic glue.
115- Do not ask the model to invent data that Python can derive safely.
116- Do not fabricate fallback user-facing copy in code to hide incomplete model output.
117- AI output schemas should be impossible to instantiate incorrectly.
118  - Do not require the model to keep separate structures in sync. For example, instead of generating two lists which must be the same length, generate one list of a model containing the same data.
119  - Prefer Python to derive deterministic follow-up structure from a valid AI result.
120- Use `NativeOutput(...)` for structured model outputs.
121- Use `ToolOutput(...)` when the model should select and call delegate functions.
122 
123#### Python Testing
124- Test contracts directly.
125- Test agents directly where behaviour matters.
126- Test API routes as thin integration points.
127- Prefer dependency overrides or startup-state seams to monkeypatching random globals.
128 
129### Frontend Development
130- **Frontend dev server**: `task frontend:dev` — requires backend on localhost:8080
131- **Tech Stack**: Vite + React + TypeScript + Mantine UI + TailwindCSS
132- **Proxy Configuration**: Vite proxies `/api/*` calls to backend (localhost:8080)
133- **Build Process**: DO NOT run build scripts manually - builds are handled by CI/CD pipelines
134- **Package Installation**: `task frontend:install`
135- **Deployment Options**:
136  - **Desktop App**: `task desktop:build`
137  - **Web Server**: `task frontend:build` then serve dist/ folder
138  - **Development**: `task desktop:dev` for desktop dev mode
139 
140#### Environment Variables
141- All `VITE_*` variables must be declared in the appropriate committed env file:
142  - `frontend/editor/.env` — core and shared vars (base, loaded in every mode)
143  - `frontend/editor/.env.proprietary` — proprietary-only vars, e.g. the admin portal's SaaS/account-link keys (layered on top of `.env` in proprietary mode)
144  - `frontend/editor/.env.saas` — SaaS-only vars (layered on top of `.env` in SaaS mode)
145  - `frontend/editor/.env.desktop` — desktop (Tauri)-only vars (layered on top of `.env` in desktop mode)
146- These files are committed to Git and must not contain private keys
147- Local overrides (API keys, machine-specific settings) go in uncommitted sibling `.env.local` / `.env.saas.local` / `.env.desktop.local` files — Vite automatically layers them on top
148- Never use `|| 'hardcoded-fallback'` inline — put defaults in the committed env files
149- `task frontend:prepare` creates empty `.local` override files on first run; pass `MODE=saas` or `MODE=desktop` to also create the mode-specific `.local` file
150- Prepare runs automatically as a dependency of all `dev*`, `build*`, and `desktop*` tasks
151- See `frontend/README.md#environment-variables` for full documentation
152 
153#### Import Paths - CRITICAL
154**ALWAYS use `@app/*` for imports.** Do not use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer implementation.
155 
156For a broader explanation of the frontend layering and override architecture, read @frontend/editor/DeveloperGuide.md
157 
158Before touching colours or theming (tokens, dark mode, accent colours), read @frontend/editor/src/core/theme/README.md — it explains the palette/`--c-*` token system and the rule that literal colours live only in `primitives.css`.
159 
160```typescript
161// ✅ CORRECT - Use @app/* for all imports
162import { AppLayout } from "@app/components/AppLayout";
163import { useFileContext } from "@app/contexts/FileContext";
164import { FileContext } from "@app/contexts/FileContext";
165 
166// ❌ WRONG - Do not use @core/* or @proprietary/* in normal code
167import { AppLayout } from "@core/components/AppLayout";
168import { useFileContext } from "@proprietary/contexts/FileContext";
169```
170 
171**Only use explicit aliases when:**
172- Building layer-specific override that wraps a lower layer's component
173- Example: `import { AppProviders as CoreAppProviders } from "@core/components/AppProviders"` when creating proprietary/AppProviders.tsx that extends the core version
174 
175The `@app/*` alias automatically resolves to the correct layer based on build target (core/proprietary/saas/desktop/cloud) and handles the fallback cascade — see "Frontend `cloud/` Layer" below for the full per-flavor order.
176 
177#### Frontend `cloud/` Layer
178 
179`@app/*` resolves through a per-flavor cascade — first existing file wins (shadow/override):
180 
181- **core** → core
182- **proprietary** → proprietary → core
183- **saas** → saas → cloud → proprietary → core
184- **desktop** → desktop → cloud → proprietary → core
185- **cloud** → cloud → proprietary → core
186 
187What goes where:
188 
189- **core** — OSS base.
190- **proprietary** — licensed / offline features.
191- **cloud** — the SHARED hosted/SaaS experience used by BOTH saas + desktop: PAYG, wallet, plan, billing, usage meters, cloud config/team/onboarding.
192- **saas** — web-only: Supabase web auth, AuthCallback, avatar canvas, `window.location`.
193- **desktop** — Tauri-only: keyring authService, tauriHttpClient, native files/windows, backend routing.
194 
195`cloud/` MUST NOT import `@supabase/*`, `@tauri-apps/*`, raw `fetch`, `window.location`, `localStorage`, `sessionStorage`, or `import.meta.env.VITE_*` (enforced by ESLint). It reaches platform-specific things only via `@app/*` seams: `services/apiClient`, `auth/session.getAccessToken`, `auth/supabase`, `platform/openExternal`, `services/billing`, `hooks/useSaaSMode` — each provided per-platform in `saas/` and `desktop/`.
196 
197Rule of thumb — **move, don't copy**: share via `cloud/`, override by shadowing the same `@app/*` path in a leaf (`saas/` or `desktop/`).
198 
199**Cloud feature flags on desktop.** The local `AppConfigContext` reads `/api/v1/config/app-config` from the LOCAL bundled backend, so cloud-only flags (`aiEngineEnabled`, `premiumEnabled`, …) are never seen on desktop. To read the cloud's view, use `useSaasAppConfig()` (`desktop/hooks/useSaasAppConfig.ts`, backed by the general `saasAppConfigService` — SaaS-mode-only, public endpoint, native HTTP, 5-min cache). It returns `null` outside SaaS mode, so cloud features stay off in local/self-hosted and the server keeps the on/off switch (no desktop release needed to flip a flag). Gate a feature behind a per-platform seam — e.g. `useAiEngineEnabled()` (core reads `useAppConfig()`, desktop reads `useSaasAppConfig()`) — rather than hardcoding the flag on.
200 
201#### Component Override Pattern (Stub/Shadow)
202Use this pattern for desktop-specific or proprietary-specific features WITHOUT runtime checks or conditionals.
203 
204**How it works:**
2051. Core defines stub component (returns null or no-op)
2062. Desktop/proprietary overrides with same path/name
2073. Core imports via `@app/*` - higher layer "shadows" core in those builds
2084. No `@ts-ignore`, no `isTauri()` checks, no runtime conditionals!
209 
210**Example - Desktop-specific footer:**
211 
212```typescript
213// core/components/workbenchBar/WorkbenchBarFooterExtensions.tsx (stub)
214interface WorkbenchBarFooterExtensionsProps {
215  className?: string;
216}
217 
218export function WorkbenchBarFooterExtensions(_props: WorkbenchBarFooterExtensionsProps) {
219  return null; // Stub - does nothing in web builds
220}
221```
222 
223```tsx
224// desktop/components/workbenchBar/WorkbenchBarFooterExtensions.tsx (real implementation)
225import { Box } from '@mantine/core';
226import { BackendHealthIndicator } from '@app/components/BackendHealthIndicator';
227 
228interface WorkbenchBarFooterExtensionsProps {
229  className?: string;
230}
231 
232export function WorkbenchBarFooterExtensions({ className }: WorkbenchBarFooterExtensionsProps) {
233  return (
234    <Box className={className}>
235      <BackendHealthIndicator />
236    </Box>
237  );
238}
239```
240 
241```tsx
242// core/components/shared/WorkbenchBar.tsx (usage - works in ALL builds)
243import { WorkbenchBarFooterExtensions } from '@app/components/workbenchBar/WorkbenchBarFooterExtensions';
244 
245export function WorkbenchBar() {
246  return (
247    <div>
248      {/* In web builds: renders nothing (stub returns null) */}
249      {/* In desktop builds: renders BackendHealthIndicator */}
250      <WorkbenchBarFooterExtensions className="workbench-bar-footer" />
251    </div>
252  );
253}
254```
255 
256**Build resolution:**
257- **Core build**: `@app/*` → `core/*` → Gets stub (returns null)
258- **Desktop build**: `@app/*` → `desktop/*` → Gets real implementation (shadows core)
259 
260**Benefits:**
261- No runtime checks or feature flags
262- Type-safe across all builds
263- Clean, readable code
264- Build-time optimization (dead code elimination)
265 
266#### Multi-Tool Workflow Architecture
267Frontend designed for **stateful document processing**:
268- Users upload PDFs once, then chain tools (split → merge → compress → view)
269- File state and processing results persist across tool switches
270- No file reloading between tools - performance critical for large PDFs (up to 100GB+)
271 
272#### FileContext - Central State Management
273**Location**: `frontend/editor/src/core/contexts/FileContext.tsx`
274- **Active files**: Currently loaded PDFs and their variants
275- **Tool navigation**: Current mode (viewer/pageEditor/fileEditor/toolName)
276- **Memory management**: PDF document cleanup, blob URL lifecycle, Web Worker management
277- **IndexedDB persistence**: File storage with thumbnail caching
278- **Preview system**: Tools can preview results (e.g., Split → Viewer → back to Split) without context pollution
279 
280**Critical**: All file operations go through FileContext. Don't bypass with direct file handling.
281 
282#### Processing Services
283- **enhancedPDFProcessingService**: Background PDF parsing and manipulation
284- **thumbnailGenerationService**: Web Worker-based with main-thread fallback
285- **fileStorage**: IndexedDB with LRU cache management
286 
287#### Memory Management Strategy
288**Why manual cleanup exists**: Large PDFs (up to 100GB+) through multiple tools accumulate:
289- PDF.js documents that need explicit .destroy() calls
290- Blob URLs from tool outputs that need revocation
291- Web Workers that need termination
292Without cleanup: browser crashes with memory leaks.
293 
294#### Tool Development
295 
296**Architecture**: Modular hook-based system with clear separation of concerns:
297 
298- **useToolOperation** (`frontend/editor/src/core/hooks/tools/shared/useToolOperation.ts`): Main orchestrator hook
299  - Coordinates all tool operations with consistent interface
300  - Integrates with FileContext for operation tracking
301  - Handles validation, error handling, and UI state management
302 
303- **Supporting Hooks**:
304  - **useToolState**: UI state management (loading, progress, error, files)
305  - **useToolApiCalls**: HTTP requests and file processing
306  - **useToolResources**: Blob URLs, thumbnails, ZIP downloads
307 
308- **Utilities**:
309  - **toolErrorHandler**: Standardized error extraction and i18n support
310  - **toolResponseProcessor**: API response handling (single/zip/custom)
311  - **toolOperationTracker**: FileContext integration utilities
312 
313**Three Tool Patterns**:
314 
315**Pattern 1: Single-File Tools** (Individual processing)
316- Backend processes one file per API call
317- Set `multiFileEndpoint: false`
318- Examples: Compress, Rotate
319```typescript
320return useToolOperation({
321  operationType: 'compress',
322  endpoint: '/api/v1/misc/compress-pdf',
323  buildFormData: (params, file: File) => { /* single file */ },
324  multiFileEndpoint: false,
325});
326```
327 
328**Pattern 2: Multi-File Tools** (Batch processing)
329- Backend accepts `MultipartFile[]` arrays in single API call
330- Set `multiFileEndpoint: true`
331- Examples: Split, Merge, Overlay
332```typescript
333return useToolOperation({
334  operationType: 'split',
335  endpoint: '/api/v1/general/split-pages',
336  buildFormData: (params, files: File[]) => { /* all files */ },
337  multiFileEndpoint: true,
338  filePrefix: 'split_',
339});
340```
341 
342**Pattern 3: Complex Tools** (Custom processing)
343- Tools with complex routing logic or non-standard processing
344- Provide `customProcessor` for full control
345- Examples: Convert, OCR
346```typescript
347return useToolOperation({
348  operationType: 'convert',
349  customProcessor: async (params, files) => { /* custom logic */ },
350});
351```
352 
353**Benefits**:
354- **No Timeouts**: Operations run until completion (supports 100GB+ files)
355- **Consistent**: All tools follow same pattern and interface
356- **Maintainable**: Single responsibility hooks, easy to test and modify
357- **i18n Ready**: Built-in internationalization support
358- **Type Safe**: Full TypeScript support with generic interfaces
359- **Memory Safe**: Automatic resource cleanup and blob URL management
360 
361## Architecture Overview
362 
363### Project Structure
364- **Backend**: Spring Boot application
365- **Frontend**: React-based SPA in `/frontend` directory
366  - **File Storage**: IndexedDB for client-side file persistence and thumbnails
367  - **Internationalization**: JSON-based translations (converted from backend .properties)
368- **PDF Processing**: PDFBox for core PDF operations, LibreOffice for conversions, PDF.js for client-side rendering
369- **Security**: Spring Security with optional authentication (controlled by `DOCKER_ENABLE_SECURITY`)
370- **Configuration**: YAML-based configuration with environment variable overrides
371 
372### Controller Architecture
373- **API Controllers** (`src/main/java/.../controller/api/`): REST endpoints for PDF operations
374  - Organized by function: converters, security, misc, pipeline
375  - Follow pattern: `@RestController` + `@RequestMapping("/api/v1/...")`
376 
377### Key Components
378- **SPDFApplication.java**: Main application class with desktop UI and browser launching logic
379- **ConfigInitializer**: Handles runtime configuration and settings files
380- **Pipeline System**: Automated PDF processing workflows via `PipelineController`
381- **Security Layer**: Authentication, authorization, and user management (when enabled)
382 
383### Frontend Directory Structure
384The frontend is organized with a clear separation of concerns:
385 
386- **`frontend/editor/src/core/`**: Main application code (shared, production-ready components)
387  - **`core/components/`**: React components organized by feature
388    - `core/components/tools/`: Individual PDF tool implementations
389    - `core/components/viewer/`: PDF viewer components
390    - `core/components/pageEditor/`: Page manipulation UI
391    - `core/components/tooltips/`: Help tooltips for tools
392    - `core/components/shared/`: Reusable UI components
393  - **`core/contexts/`**: React Context providers
394    - `FileContext.tsx`: Central file state management
395    - `file/`: File reducer and selectors
396    - `toolWorkflow/`: Tool workflow state
397  - **`core/hooks/`**: Custom React hooks
398    - `hooks/tools/`: Tool-specific operation hooks (one directory per tool)
399    - `hooks/tools/shared/`: Shared hook utilities (useToolOperation, etc.)
400  - **`core/constants/`**: Application constants and configuration
401  - **`core/data/`**: Static data (tool taxonomy, etc.)
402  - **`core/services/`**: Business logic services (PDF processing, storage, etc.)
403 
404- **`frontend/editor/src/desktop/`**: Desktop-specific (Tauri) code
405- **`frontend/editor/src/proprietary/`**: Proprietary/licensed features
406- **`frontend/editor/src-tauri/`**: Tauri (Rust) native desktop application code
407- **`frontend/editor/public/`**: Static assets served directly
408  - `public/locales/`: Translation JSON files
409 
410### Component Architecture
411- **Static Assets**: CSS, JS, and resources in `src/main/resources/static/` (legacy) + `frontend/editor/public/` (modern)
412- **Internationalization**:
413  - Backend: `messages_*.properties` files
414  - Frontend: JSON files in `frontend/editor/public/locales/` (converted from .properties)
415  - Conversion Script: `scripts/convert_properties_to_json.py`
416 
417### Configuration Modes
418- **Ultra-lite**: Basic PDF operations only
419- **Standard**: Full feature set
420- **Fat**: Pre-downloaded dependencies for air-gapped environments
421- **Security Mode**: Adds authentication, user management, and enterprise features
422 
423### Testing Strategy
424- **Integration Tests**: Cucumber tests in `testing/cucumber/`
425- **Docker Testing**: `test.sh` validates all Docker variants
426- **Manual Testing**: No unit tests currently - relies on UI and API testing
427 
428## Development Workflow
429 
4301. **Local Development** (using Taskfile):
431   - Backend + frontend: `task dev`
432   - All services (including AI engine): `task dev:all`
433   - Or individually: `task backend:dev` (localhost:8080), `task frontend:dev` (localhost:5173), `task engine:dev` (localhost:5001)
4342. **Quality Gate**: Run `task check` before submitting PRs
4353. **Docker Testing**: Use `./test.sh` for full Docker integration tests
4364. **Code Style**: Spotless enforces Google Java Format automatically (`task backend:format`)
4375. **Translations**:
438   - Backend: Use helper scripts in `/scripts` for multi-language updates
439   - Frontend: Update JSON files in `frontend/editor/public/locales/` or use conversion script
4406. **Documentation**: API docs auto-generated and available at `/swagger-ui/index.html`
441 
442## Frontend Architecture Status
443 
444- **Core Status**: React SPA architecture complete with multi-tool workflow support
445- **State Management**: FileContext handles all file operations and tool navigation
446- **File Processing**: Production-ready with memory management for large PDF workflows (up to 100GB+)
447- **Tool Integration**: Modular hook architecture with `useToolOperation` orchestrator
448  - Individual hooks: `useToolState`, `useToolApiCalls`, `useToolResources`
449  - Utilities: `toolErrorHandler`, `toolResponseProcessor`, `toolOperationTracker`
450  - Pattern: Each tool creates focused operation hook, UI consumes state/actions
451- **Preview System**: Tool results can be previewed without polluting file context (Split tool example)
452- **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing
453 
454## Translation Rules
455 
456- **CRITICAL**: Always update translations in `en-US` only - all other languages (including `en-GB`) are handled separately
457- Translation files are located in `frontend/editor/public/locales/`
458- After changing any translation file, run `task pre-commit:fix`
459 
460## Important Notes
461 
462- **Java Version**: Requires JDK 25.
463- **Lombok**: Used extensively - ensure IDE plugin is installed
464- **File Persistence**:
465  - **Backend**: Designed to be stateless - files are processed in memory/temp locations only
466  - **Frontend**: Uses IndexedDB for client-side file storage and caching (with thumbnails)
467- **Security**: When `DOCKER_ENABLE_SECURITY=false`, security-related classes are excluded from compilation
468- **Import Paths**: ALWAYS use `@app/*` for imports - never use `@core/*` or `@proprietary/*` unless explicitly wrapping/extending a lower layer
469- **FileContext**: All file operations MUST go through FileContext - never bypass with direct File handling
470- **Memory Management**: Manual cleanup required for PDF.js documents and blob URLs - don't remove cleanup code
471- **Tool Development**: New tools should follow `useToolOperation` hook pattern (see `useCompressOperation.ts`)
472- **Performance Target**: Must handle PDFs up to 100GB+ without browser crashes
473- **Preview System**: Tools can preview results without polluting main file context (see Split tool implementation)
474- **Adding Tools**: See `ADDING_TOOLS.md` for complete guide to creating new PDF tools
475 
476## Communication Style
477- Be direct and to the point
478- No apologies or conversational filler
479- Answer questions directly without preamble
480- Explain reasoning concisely when asked
481- Avoid unnecessary elaboration
482 
483## Decision Making
484- Ask clarifying questions before making assumptions
485- Stop and ask when uncertain about project-specific details
486- Confirm approach before making structural changes
487- Request guidance on preferences (cross-platform vs specific tools, etc.)
488- Verify understanding of requirements before proceeding
489 
490 
491## Stack reality check (don't trust LLM training data) <!-- bleeding-edge-stack-note -->
492 
493This codebase is on bleeding-edge versions of its core JVM stack: **Spring Boot 4.0.6**,
494**Jackson 3 (`tools.jackson`)**, **JDK 21/25 source/target with JDK 25 toolchain**.
495All three are *post*-2024 releases and your training corpus is overwhelmingly Spring Boot 2/3 and
496Jackson 2 patterns — those patterns will compile, run differently, or hallucinate APIs that no
497longer exist.
498 
499Before writing or editing Spring / Jackson / JDK code:
500 
5011. Open an existing module in `app/core/` or `app/common/` and grep for the actual imports being
502   used — `import tools.jackson...` not `import com.fasterxml.jackson...`, and the new
503   `org.springframework.boot` 4.x package layout.
5042. If you're not sure whether an API exists in this stack version, **check the source on disk
505   first** (the dependency JARs are downloaded under `~/.gradle/caches/modules-2/`).
5063. Do not silently downgrade a Spring Boot 4 pattern to a Spring Boot 3 equivalent. If something
507   doesn't work, surface it to the human — don't guess.
508 
509Same goes for Jackson 3's API surface (renamed `ObjectMapper` builder methods, new
510`tools.jackson.databind` namespace) and JDK 25 preview features. Ground your code in this repo's
511actual imports, not what worked three years ago.
512