### Start Development Environment with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Starts the backend and frontend development servers concurrently.

```bash
task dev
```

--------------------------------

### Run Application with Update for Manual Testing

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/scripts/dev-update-test/README.md

In a second terminal, run this command to start the application (e.g., at v0.0.1) which will then check for and potentially install the update served in the other terminal.

```bash
npm run tauri:dev-with-update
```

--------------------------------

### Install Dependencies with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Installs all project dependencies using the Taskfile.

```bash
task install
```

--------------------------------

### Start Full Development Environment with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Starts the backend, frontend, and engine development servers concurrently.

```bash
task dev:all
```

--------------------------------

### Install Stylelint and Plugin

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/devGuide/STYLELINT.md

Installs Stylelint and the stylistic/stylelint-plugin for CSS linting. Ensure you are in the 'devTools/' directory.

```bash
npm install --save-dev stylelint stylelint-config-standard
npm install --save-dev @stylistic/stylelint-plugin
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/README.md

Run these commands from the repository root using Task to manage frontend development tasks like starting the dev server, building, testing, linting, and installing dependencies.

```bash
task frontend:dev
```

```bash
task frontend:build
```

```bash
task frontend:test
```

```bash
task frontend:test:watch
```

```bash
task frontend:lint
```

```bash
task frontend:typecheck
```

```bash
task frontend:check
```

```bash
task frontend:install
```

--------------------------------

### Start Docker Compose Stack with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Starts the Docker Compose stack for development.

```bash
task docker:up
```

--------------------------------

### Start Ultra-Lite Docker Compose Stack with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Starts the Docker Compose stack with the 'ultra-lite' image.

```bash
task docker:up:ultra-lite
```

--------------------------------

### Run Backend Development Server

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/CLAUDE.md

Starts the backend development server locally.

```bash
task backend:dev
```

--------------------------------

### Install Dependencies and Playwright

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/tests/convert/README.md

Run these commands once to install project dependencies and Playwright browsers needed for E2E tests. Ensure you are in the 'frontend/' directory.

```bash
npm install
```

```bash
npx playwright install
```

--------------------------------

### Install Recommended VSCode Extensions

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/DeveloperGuide.md

Open the command palette in VSCode and run this command to install the recommended extensions for Stirling-PDF development.

```bash
Extensions: Show Recommended Extensions
```

--------------------------------

### Automated Full Install Test

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/scripts/dev-update-test/README.md

This command specifically tests the full installation of a downloaded update, simulating a user downloading and installing the update.

```bash
npm run tauri:test-update-e2e:install
```

--------------------------------

### EML File Header Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/tests/test-fixtures/README.md

Manual creation of an EML file with proper headers for testing.

```email
From: test@example.com
To: recipient@example.com
Subject: Test Email
Date: Mon, 1 Jan 2024 12:00:00 +0000

This is a test email for conversion testing.
```

--------------------------------

### Show and Update Toast Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/components/toast/Toast.README.md

Demonstrates how to initially display a toast with a progress bar and then update its progress. This is useful for showing ongoing processes.

```tsx
const toastId = alert({ title: 'Processing...', progressBarPercentage: 0 });
updateToast(toastId, { progressBarPercentage: 75 });
```

--------------------------------

### Start Frontend Development Service

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/DeveloperGuide.md

Starts the Vite development server for the frontend, serving the UI on localhost:5173. It automatically proxies API calls to the backend.

```bash
task frontend:dev
```

--------------------------------

### Start Python Engine with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Starts the FastAPI Python engine with hot-reloading enabled on localhost:5001.

```bash
task engine:dev
```

--------------------------------

### Start Fat Docker Compose Stack with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Starts the Docker Compose stack with the 'fat' image.

```bash
task docker:up:fat
```

--------------------------------

### Install Python Engine Dependencies with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Installs Python dependencies for the engine using uv.

```bash
task engine:install
```

--------------------------------

### Install Tesseract OCR Languages on Fedora

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/HowToUseOCR.md

Install Tesseract language packs on Fedora systems. Use 'dnf search' to discover available packs and 'rpm -qa' to list installed packages.

```bash
# All languages
# sudo dnf install -y tesseract-langpack-*

# Find languages:
dnf search -C tesseract-langpack-

# View installed languages:
rpm -qa | grep tesseract-langpack | sed 's/tesseract-langpack-//g'
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/DeveloperGuide.md

Commands to start the backend and frontend development servers for React frontend development. The Vite dev server automatically proxies API calls to the backend.

```bash
task backend:dev
```

```bash
task frontend:dev
```

--------------------------------

### Automated End-to-End Update Test Setup

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/scripts/dev-update-test/README.md

Run this command once to set up the development environment for auto-update testing, including generating signing keys and configuration overrides.

```bash
npm run tauri:setup-dev-update
```

--------------------------------

### Start Tauri Dev Server

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/README.md

Starts the Tauri development server. This command ensures the JLink runtime and backend JAR are available before launching Tauri in dev mode.

```bash
task desktop:dev
```

--------------------------------

### Install Tooltip Component

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/components/shared/tooltip/Tooltip.README.md

Import the Tooltip component from its path. Ensure the path is correct for your project structure.

```tsx
import { Tooltip } from '@/components/shared';
```

--------------------------------

### Start Docker Compose Stacks Manually

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/docker/README.md

Manually start Stirling-PDF Docker Compose stacks using specific compose files. Ensure you are in the project root directory. The `--build` flag is used to build images before starting containers.

```bash
# Standard version
docker-compose -f docker/compose/docker-compose.yml up --build

# Ultra-lite version
docker-compose -f docker/compose/docker-compose.ultra-lite.yml up --build

# Fat version
docker-compose -f docker/compose/docker-compose.fat.yml up --build
```

--------------------------------

### TOML Pluralization Example (Simple)

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/scripts/translations/README.md

Shows how to define plural forms for a key using _one, _other, and _zero suffixes. Always provide _other as a fallback.

```toml
[common]
fileCount_one = "{{count}} file"
fileCount_other = "{{count}} files"
fileCount_zero = "No files"
```

--------------------------------

### Markdown Test File Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/tests/test-fixtures/README.md

Example of a Markdown file with various formatting elements used for testing.

```markdown
# Test Document

This is a **test** markdown file.

## Features

- Lists
- **Bold text**
- *Italic text*
- [Links](https://example.com)

### Code Block

```javascript
console.log('Hello, world!');
```

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |
```

--------------------------------

### Verify Tesseract Language Installation

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/HowToUseOCR.md

Command to list the languages currently recognized by Tesseract OCR. This is useful for verifying installation on Windows.

```bash
tesseract --list-langs
```

--------------------------------

### Start Stirling PDF Remote UNO Stack

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/docker/embedded/compose/README-remote-uno.md

Use this command to bring up all services defined in the compose file in detached mode.

```bash
docker compose -f docker-compose-latest-security-remote-uno.yml up -d
```

--------------------------------

### Compact JSON Output Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/scripts/translations/README.md

Example of the compact JSON output format used in the compact translation workflow.

```json
{"key1":"English text","key2":"Another text","key3":"More text"}
```

--------------------------------

### TOML Translation File Structure Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/scripts/translations/README.md

Illustrates the basic TOML structure for translation keys, including nested keys and string values.

```toml
[addPageNumbers]
title = "Add Page Numbers"

[addPageNumbers.selectText]
"1" = "Select PDF file:"
"2" = "Margin Size"
```

--------------------------------

### Integrate New Tool with API

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/DeveloperGuide.md

Example of how to make a POST request to a new API endpoint for processing files with a new tool.

```typescript
const response = await fetch('/api/v1/new-tool', {
  method: 'POST',
  body: formData
});
```

--------------------------------

### Add a Third UNO Server Service Definition

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/docker/embedded/compose/README-remote-uno.md

Example of how to define an additional UNO server service in the Docker Compose file.

```yaml
  unoserver3:
    container_name: UNO-Server-3
    image: ghcr.io/stirling-tools/stirling-unoserver:latest
    # ... same config as unoserver1/2
```

--------------------------------

### Import Stirling-PDF Public GPG Key

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/docs/security/VERIFYING_RELEASES.md

Import the Stirling-PDF public GPG key into your local keyring. This is a one-time setup required for signature verification. You can import it from the repository over HTTPS or from a keyserver.

```bash
# Option 1 — from the repo over HTTPS
curl -fsSL https://raw.githubusercontent.com/Stirling-Tools/Stirling-PDF/main/docs/security/signing-key.pub \
  | gpg --import
```

```bash
# Option 2 — from a keyserver
gpg --keyserver hkps://keys.openpgp.org \
    --recv-keys EBB9258BFEA47D92342F00DFB8C096A59BEF2A8B
```

--------------------------------

### Example Docker Compose for Security

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/DeveloperGuide.md

This configuration enables login and security features for the Stirling PDF Docker container. Ensure volumes are correctly mapped for persistent data.

```yaml
services:
  stirling-pdf:
    container_name: Stirling-PDF-Security
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    deploy:
      resources:
        limits:
          memory: 4G
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080$${SYSTEM_ROOTURIPATH:-''}/api/v1/info/status | grep -q 'UP' && curl -fL http://localhost:8080/ | grep -q 'Please sign in'"]
      interval: 5s
      timeout: 10s
      retries: 16
    ports:
      - "8080:8080"
    volumes:
      - ./stirling/latest/data:/usr/share/tessdata:rw
      - ./stirling/latest/config:/configs:rw
      - ./stirling/latest/logs:/logs:rw
    environment:
      DISABLE_ADDITIONAL_FEATURES: "false"
      SECURITY_ENABLELOGIN: "true"
      PUID: 1002
      PGID: 1002
      UMASK: "022"
      SYSTEM_DEFAULTLOCALE: en-US
      UI_APPNAME: Stirling-PDF
      UI_HOMEDESCRIPTION: Demo site for Stirling-PDF Latest with Security
      UI_APPNAMENAVBAR: Stirling-PDF Latest
      SYSTEM_MAXFILESIZE: "100"
      METRICS_ENABLED: "true"
      SYSTEM_GOOGLEVISIBILITY: "true"
      SHOW_SURVEY: "true"
    restart: on-failure:5
```

--------------------------------

### Run Full Automated End-to-End Update Tests

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/scripts/dev-update-test/README.md

Execute this command to perform a complete automated test of the update process. This includes building the JRE and JAR, signing the bundle, starting the server and application, and running checks.

```bash
npm run tauri:test-update-e2e
```

--------------------------------

### Automatic Auditing for Controller Methods

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/main/resources/templates/AUDIT_USAGE.md

Controller methods with web mapping annotations are automatically audited at the STANDARD level. This example shows a GET request.

```java
@GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable String id) {
        // Method implementation
        return ResponseEntity.ok(user);
    }
```

--------------------------------

### Build Project with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Builds all components of the project.

```bash
task build
```

--------------------------------

### Boot JAR and Configure Datasource

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/app/proprietary/src/test/resources/db-migration-fixtures/README.md

Boots the downloaded JAR in a temporary directory with specific H2 database configurations. `DB_CLOSE_ON_EXIT=TRUE` ensures the H2 file flushes on JVM exit.

```bash
# 2. Boot the JAR in a clean working directory. DB_CLOSE_ON_EXIT=TRUE is
#    the only override that matters - it makes the H2 file flush on JVM exit
#    even if you Ctrl-C instead of going through a graceful shutdown.
workdir=$(mktemp -d)
mkdir -p "$workdir/configs"
cd "$workdir"
java -jar /tmp/stirling-v2.10.0.jar \
  --server.port=8089 \
  --spring.datasource.url='jdbc:h2:file:./configs/stirling-pdf-DB-2.3.232;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=TRUE;MODE=PostgreSQL'
  &
```

--------------------------------

### Install Tesseract OCR Languages on Debian

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/HowToUseOCR.md

Update package lists and install Tesseract OCR language packs on Debian-based systems. Use 'apt search' to find available languages and 'dpkg-query' to list installed ones.

```bash
sudo apt update &&\
# All languages
# sudo apt install -y 'tesseract-ocr-*'

# Find languages:
apt search tesseract-ocr-

# View installed languages:
dpkg-query -W tesseract-ocr- | sed 's/tesseract-ocr-//g'
```

--------------------------------

### Run Local Development Server

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Use Taskfile for local development. Run `task dev` for backend and frontend, `task dev:all` for all services including the AI engine, or individual services like `task backend:dev`.

```bash
task dev
task dev:all
task backend:dev
task frontend:dev
task engine:dev
```

--------------------------------

### Configuration Settings

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/FILE_SHARING.md

Details on how to configure storage and sharing settings via the `settings.yml` file.

```APIDOC
## Storage Configuration

All storage-related settings are managed under the `storage:` key in `settings.yml`.

```yaml
storage:
  enabled: true                  # Requires security.enableLogin = true
  provider: local                # 'local' or 'database'
  local:
    basePath: './storage'        # Filesystem base directory (local provider only)
  quotas:
    maxStorageMbPerUser: -1      # Per-user storage cap in MB; -1 = unlimited
    maxStorageMbTotal: -1        # Total storage cap in MB; -1 = unlimited
    maxFileMb: -1                # Max size per upload (main + history + audit) in MB; -1 = unlimited
  sharing:
    enabled: false               # Master switch for all sharing (opt-in)
    linkEnabled: false           # Enable token-based share links (requires system.frontendUrl)
    emailEnabled: false          # Enable email notifications (requires mail.enabled)
    linkExpirationDays: 3        # Days until share links expire
```

### Prerequisites

- `storage.enabled` requires `security.enableLogin = true`.
- `sharing.linkEnabled` requires `system.frontendUrl` to be set.
- `sharing.emailEnabled` requires `mail.enabled = true`.
```

--------------------------------

### Build Ultra-Lite Docker Image with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Builds the 'ultra-lite' version of the Docker image.

```bash
task docker:build:ultra-lite
```

--------------------------------

### Serve Signed Update for Manual Testing

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/scripts/dev-update-test/README.md

In one terminal, run this command to serve the signed update package (e.g., v99.0.0) for manual testing.

```bash
npm run tauri:serve-dev-update
```

--------------------------------

### Run Full Quality Gate with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Performs a full quality check including linting, type checking, and testing.

```bash
task check
```

--------------------------------

### GET /api/v1/security/cert-sign/sign-requests - Participant Access

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/SHARED_SIGNING.md

Retrieves sign requests for authenticated participants. This endpoint can be used to get a list of all sign requests or a specific one by sessionId.

```APIDOC
## GET /api/v1/security/cert-sign/sign-requests

### Description
Retrieves sign requests for authenticated participants. This endpoint can be used to get a list of all sign requests or a specific one by sessionId.

### Method
GET

### Endpoint
/api/v1/security/cert-sign/sign-requests

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sessionId** (string) - Optional - The ID of the session to retrieve.

### Response
#### Success Response (200)
- Returns a list of sign requests or details for a specific session.

#### Response Example
(Response structure will vary based on whether a sessionId is provided)
```json
[
  {
    "sessionId": "uuid",
    "documentName": "contract.pdf",
    "status": "VIEWED"
  }
]
```
```

```APIDOC
## GET /api/v1/security/cert-sign/sign-requests/{sessionId}/document

### Description
Retrieves the document associated with a specific session ID for authenticated participants.

### Method
GET

### Endpoint
/api/v1/security/cert-sign/sessions/{sessionId}/document

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session whose document is to be retrieved.

### Response
#### Success Response (200)
- Returns the PDF document content.

#### Response Example
(Returns binary PDF content)
```

--------------------------------

### Run Task Command

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Execute any available Task command from the repository root. Use `task --list` to see all commands.

```bash
task <command>
```

--------------------------------

### Create AI Translation Template (Quick Workflow)

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/scripts/translations/README.md

Creates a template JSON file for AI translation in the legacy quick workflow.

```bash
python scripts/translations/translation_merger.py fr-FR create-template --output fr_template.json
```

--------------------------------

### FitText with Explicit Starting Font Size

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/components/shared/fitText/FitText.README.md

Sets an explicit starting font size of 1.2rem for the FitText component. The font size will scale down only if the text exceeds the container width at this initial size.

```tsx
<FitText text="Starts at 1.2rem, scales down if needed" fontSize={1.2} />
```

--------------------------------

### Run All Tests with Taskfile

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/DeveloperGuide.md

Use the Taskfile to execute all backend and frontend unit/integration tests. The `test` command runs all tests, while `check` performs a full quality gate including linting and type checking.

```bash
task test    # run all tests (backend + frontend + engine)
```

```bash
task check   # full quality gate: lint + typecheck + test
```

--------------------------------

### Toast Initialization

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/components/toast/Toast.README.md

Import and use the `alert` function to display different types of toast notifications.

```APIDOC
## Toast Initialization

### Description
Import the `alert` function from the toast component to display notifications. You can specify the `alertType`, `title`, and `body` for each notification.

### Functions
- `alert(options)`: Displays a toast notification.

### Parameters for `alert`
- `options` (object) - Configuration for the toast notification:
  - `alertType` (string) - Type of alert: 'success', 'error', 'warning', 'neutral'.
  - `title` (string) - The main heading of the toast notification.
  - `body` (string | ReactNode) - The content of the toast notification. Can be plain text or rich JSX.

### Usage Examples
```javascript
import { alert } from '@/components/toast';

// Success notification
alert({
  alertType: 'success',
  title: 'File processed successfully',
  body: 'Your document has been converted to PDF.'
});

// Error notification
alert({
  alertType: 'error',
  title: 'Processing failed',
  body: 'Unable to process the selected files.'
});
```
```

--------------------------------

### Contextual Translation Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/scripts/translations/README.md

This JSON snippet demonstrates how context information is provided for translation keys to aid accuracy.

```json
{
  "addPageNumbers.title": {
    "original": "Add Page Numbers",
    "context": "Feature for adding page numbers to PDFs"
  }
}
```

--------------------------------

### Convert Certificate and Private Key to PFX

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/WINDOWS_SIGNING.md

Use this command if you have separate certificate (.cer) and private key (.key) files and need to combine them into a .pfx file for Windows code signing.

```bash
openssl pkcs12 -export -out certificate.pfx -inkey private-key.key -in certificate.cer
```

--------------------------------

### Preserve Placeholders in Translations

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/scripts/translations/README.md

This example shows how translation keys preserve placeholders like {n}, {total}, and {filename}.

```json
"customNumberDesc": "Defaults to {n}, also accepts 'Page {n} of {total}'"
```

--------------------------------

### JavaScript Code Block Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/tests/test-fixtures/README.md

A simple JavaScript code block embedded within a Markdown file for testing.

```javascript
console.log('Hello, world!');
```

--------------------------------

### Run Frontend Quality Gate with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Performs a quality check on frontend files, including lint, typecheck, and test.

```bash
task frontend:check
```

--------------------------------

### JavaScript Usage of Pluralized Translation

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/scripts/translations/README.md

Example of how to call a pluralized translation key in JavaScript using the t function with a count parameter.

```javascript
t("common.uploadCount", { count: files.length });
```

--------------------------------

### Update Service Dependencies for New UNO Server

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/docker/embedded/compose/README-remote-uno.md

Ensure the stirling-pdf service waits for the new UNO server to be healthy before starting.

```yaml
    depends_on:
      unoserver1:
        condition: service_healthy
      unoserver2:
        condition: service_healthy
      unoserver3:
        condition: service_healthy
```

--------------------------------

### Build Standard Docker Image with Task

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Builds the standard Docker image for the project.

```bash
task docker:build
```

--------------------------------

### List Available Task Commands

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

View all commands supported by the Taskfile.

```bash
task --list
```

--------------------------------

### Integrate RAG Capability into an Agent

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/engine/src/stirling/documents/README.md

This snippet shows how to initialize an `Agent` with the RAG capability provided by `AppRuntime`. The agent will gain a `search_knowledge` tool.

```python
from pydantic_ai import Agent

from stirling.services import AppRuntime

class MyAgent:
    def __init__(self, runtime: AppRuntime) -> None:
        rag = runtime.rag_capability
        self.agent = Agent(
            model=runtime.smart_model,
            system_prompt="Your prompt here...",
            instructions=rag.instructions,
            toolsets=[rag.toolset],
        )
```

--------------------------------

### Run Stirling PDF with Docker

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/README.md

This command starts Stirling PDF using Docker. Access the application via http://localhost:8080 after running.

```bash
docker run -p 8080:8080 docker.stirlingpdf.com/stirlingtools/stirling-pdf
```

--------------------------------

### Build Standard Docker Image with Docker CLI

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/AGENTS.md

Builds the standard Docker image using the Docker CLI.

```bash
docker build -t stirling-pdf -f docker/embedded/Dockerfile .
```

--------------------------------

### JavaScript Code Block Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/tests/test-fixtures/sample.htm

A sample JavaScript function embedded within the HTML document. This snippet demonstrates how code blocks are rendered.

```javascript
function testFunction() {
    console.log("This is a test function");
    return "Hello from HTML to PDF conversion";
}
```

--------------------------------

### Single-line FitText Example

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/components/shared/fitText/FitText.README.md

Renders a long single-line title that will automatically shrink its font size to fit within its container. This is the default behavior.

```tsx
<FitText text="Very long single-line title that should shrink" />
```

--------------------------------

### Get Share Link Metadata API

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/FILE_SHARING.md

Retrieves metadata for a given share link token, including file details and access permissions.

```APIDOC
## GET /api/v1/storage/share-links/{token}/metadata

### Description
Retrieves metadata for a given share link token, including file details and access permissions.

### Method
GET

### Endpoint
/api/v1/storage/share-links/{token}/metadata

### Parameters
#### Path Parameters
- **token** (string) - Required - The share link token.
```

--------------------------------

### Get Share Link Metadata

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/FILE_SHARING.md

Retrieves metadata for a given share link token, including file details, access role, and timestamps.

```bash
GET /api/v1/storage/share-links/{token}/metadata
```

--------------------------------

### Initialize Mobile Upload UI and Logic

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/app/core/src/main/resources/static/mobile-upload.html

Sets up event listeners for file inputs, buttons, and handles the display of selected files and upload progress. It configures API endpoints and session handling.

```javascript
(function () { "use strict"; var API_BASE = new URL(".", window.location.href).href; var params = new URLSearchParams(window.location.search); var sessionId = (params.get("session") || "").trim(); var SESSION_RE = /^A-Za-z0-9-]{8,128}$/; var els = { status: document.getElementById("status"), statusText: document.getElementById("statusText"), cameraBtn: document.getElementById("cameraBtn"), fileBtn: document.getElementById("fileBtn"), cameraInput: document.getElementById("cameraInput"), fileInput: document.getElementById("fileInput"), fileList: document.getElementById("fileList"), uploadBtn: document.getElementById("uploadBtn"), progressWrap: document.getElementById("progressWrap"), progressBar: document.getElementById("progressBar"), hint: document.getElementById("hint"), uploader: document.getElementById("uploader"), successCard: document.getElementById("successCard"), successText: document.getElementById("successText") }; var selected = []; var sessionReady = false; function setStatus(text, kind) { els.statusText.textContent = text; els.status.className = "status" + (kind ? " " + kind : ""); } function enableInputs(on) { sessionReady = on; els.cameraBtn.disabled = !on; els.fileBtn.disabled = !on; refreshUploadBtn(); } function refreshUploadBtn() { els.uploadBtn.disabled = !sessionReady || selected.length === 0; els.uploadBtn.textContent = selected.length > 0 ? "Upload " + selected.length + " file" + (selected.length > 1 ? "s" : "") : "Upload"; } function formatSize(bytes) { if (bytes < 1024) return bytes + " B"; if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(0) + " KB"; return (bytes / (1024 * 1024)).toFixed(1) + " MB"; } var FILE_ICON = '<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6Zm0 2 4 4h-4V4Z"/></svg>'; function renderFiles() { els.fileList.innerHTML = ""; selected.forEach(function (file, idx) { var row = document.createElement("div"); row.className = "file"; var thumb = document.createElement("div"); thumb.className = "thumb"; if (file.type && file.type.indexOf("image/") === 0) { var img = document.createElement("img"); img.style.width = "100%"; img.style.height = "100%"; img.style.objectFit = "cover"; img.alt = ""; img.src = URL.createObjectURL(file); img.onload = function () { URL.revokeObjectURL(img.src); }; thumb.appendChild(img); } else { thumb.innerHTML = FILE_ICON; } var meta = document.createElement("div"); meta.className = "meta"; var name = document.createElement("div"); name.className = "name"; name.textContent = file.name || "image.jpg"; var size = document.createElement("div"); size.className = "size"; size.textContent = formatSize(file.size); meta.appendChild(name); meta.appendChild(size); var remove = document.createElement("button"); remove.className = "remove"; remove.type = "button"; remove.setAttribute("aria-label", "Remove"); remove.innerHTML = "&times;"; remove.onclick = function () { selected.splice(idx, 1); renderFiles(); refreshUploadBtn(); }; row.appendChild(thumb); row.appendChild(meta); row.appendChild(remove); els.fileList.appendChild(row); }); } function addFiles(fileList) { for (var i = 0; i < fileList.length; i++) { selected.push(fileList[i]); } renderFiles(); refreshUploadBtn(); } els.cameraBtn.onclick = function () { els.cameraInput.click(); }; els.fileBtn.onclick = function () { els.fileInput.click(); }; els.cameraInput.onchange = function (e) { addFiles(e.target.files); e.target.value = ""; }; els.fileInput.onchange = function (e) { addFiles(e.target.files); e.target.value = ""; }; els.uploadBtn.onclick = function () { if (!sessionReady || selected.length === 0) return; upload(); }; function upload() { var form = new FormData(); selected.forEach(function (file) { form.append("files", file, file.name); }); var xhr = new XMLHttpRequest(); xhr.open("POST", API_BASE + "api/v1/mobile-scanner/upload/" + encodeURIComponent(sessionId)); els.uploadBtn.disabled = true; els.cameraBtn.disabled = true; els.fileBtn.disabled = true; els.progressWrap.classList.remove("hidden"); els.progressBar.style.width = "0%"; xhr.upload.onprogress = function (e) { if (e.lengthComputable) { els.progressBar.style.width = Math.round((e.loaded / e.total) * 100) + "% "; } }; xhr.onload = function () { els.progressWrap.classList.add("hidden"); if (xhr.status >= 200 && xhr.status < 300) { var count = selected.length; els.successText.textContent = count + " file" + (count > 1 ? "s are" : " is") + " now on your computer."; els.uploader.classList.add("hidden"); els.successCard.classList.remove("hidden"); } else { var msg = "Upload failed. Please try again."; if (xhr.status === 403) msg = "Mobile upload is not enabled on this server."; else if (xhr.status === 400) msg = "Session expired. Please refresh the page."; els.statusText.textContent = msg; els.status.className = "status error"; } }; xhr.onerror = function () { els.progressWrap.classList.add("hidden"); els.statusText.textContent = "Upload failed. Please try again."; els.status.className = "status error"; }; }; })();
```

--------------------------------

### Build Ultra-Lite Stirling PDF Docker Image

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/DeveloperGuide.md

Command to build the Stirling PDF ultra-lite Docker image. This version is optimized for basic PDF operations.

```bash
docker build --no-cache --pull --build-arg VERSION_TAG=alpha -t stirlingtools/stirling-pdf:latest-ultra-lite -f ./Dockerfile.ultra-lite .
```

--------------------------------

### Import Toast Functions

Source: https://github.com/stirling-tools/stirling-pdf/blob/main/frontend/editor/src/core/components/toast/Toast.README.md

Import the necessary functions for using the toast system. No additional setup is required as it's integrated at the app root.

```tsx
import { alert, updateToast, dismissToast } from '@/components/toast';
```