### Frontend setup and dev server

Source: https://github.com/xiao-villamor/printstash/wiki/Development

Installs frontend dependencies and starts the development server.

```bash
cd frontend
pnpm install
pnpm dev
```

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

### Backend setup and run

Source: https://github.com/xiao-villamor/printstash/wiki/Development

Sets up the backend development environment and starts the FastAPI server with hot reload.

```bash
cd backend
uv sync --extra dev
uv run uvicorn app.main:app --reload
```

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

### Setup Backend Development Environment

Source: https://github.com/xiao-villamor/printstash/blob/main/CONTRIBUTING.md

Commands to synchronize dependencies and start the backend development server with a local data root.

```bash
cd backend
uv sync --extra dev

VAULT_DATA_ROOT=./_data uv run uvicorn app.main:app --reload
```

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

### Start the manual-test stack with docker compose

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/manual-testing.md

Copies the example environment file and starts the manual-testing stack with the identity and emulators profiles. Requires the copied env file to be present and the identity profile to be selected for OIDC to be enabled.

```bash
cp deploy/manual-testing/.env.example deploy/manual-testing/.env
docker compose \
  --env-file deploy/manual-testing/.env \
  -f deploy/manual-testing/compose.yml \
  --profile identity --profile emulators \
  up -d --build --wait
```

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

### Quick start: install dependencies and run uvicorn

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Sets up the development environment and starts the FastAPI server with hot reload. The VAULT_DATA_ROOT environment variable controls where app data, including SQLite, is stored.

```bash
cd backend

# First time — create venv and install deps
uv sync --extra dev

# Run the server; every app path, SQLite included, lives under ./_data
VAULT_DATA_ROOT=./_data uv run uvicorn app.main:app --reload
```

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

### Download and start PrintStash with Docker Compose

Source: https://github.com/xiao-villamor/printstash/blob/main/README.md

Use this command sequence to create a directory, download the docker-compose.yml file, and start the PrintStash container. Run it in a terminal with Docker and the Compose plugin installed.

```bash
mkdir -p printstash && cd printstash
curl -fsSL https://raw.githubusercontent.com/xiao-villamor/PrintStash/main/docker-compose.yml -o docker-compose.yml
docker compose up -d
```

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

### Retrieve setup token from API logs

Source: https://github.com/xiao-villamor/printstash/wiki/Installation

Fetches the one-process setup token from the API container logs. Use this token in the setup wizard on first launch. There is no default username or password.

```bash
docker compose logs api | grep 'setup token'
```

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

### Clean Install Commands

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/release-validation.md

Run these commands to validate a clean install. Copies the environment template, starts the stack in detached mode, and verifies the health endpoint. Expected results include the setup page at /setup and the health API returning the current app version.

```bash
cp .env.example .env
docker compose up -d --build
curl -fsS http://localhost:8000/api/v1/health
```

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

### Start advanced deployment with docker compose

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/deployment.md

Starts the advanced reference deployment. The first command runs the core stack; the second adds optional PostgreSQL and SeaweedFS (S3) services via profiles. Include -f docker-compose.advanced.yml in every later Compose command, or save it as docker-compose.yml in its own install directory. To build from a checkout, uncomment the two build: blocks and add --build.

```bash
docker compose -f docker-compose.advanced.yml up -d
# Optional services, internal-only:
docker compose -f docker-compose.advanced.yml --profile postgres --profile s3 up -d
```

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

### Perform initial S3-backed admin setup

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

This script configures the storage backend, performs the initial admin setup, and saves an admin bearer token. It requires the environment variables defined in deploy/manual-testing/.env.

```sh
requested_storage_backend="${VAULT_STORAGE_BACKEND-}"
set -a; . deploy/manual-testing/.env; set +a
if test -n "$requested_storage_backend"; then VAULT_STORAGE_BACKEND="$requested_storage_backend"; fi
API=http://localhost:${PRINTSTASH_API_PORT:-8100}
SETUP_JSON="$(jq -n \
  --arg s3 "$VAULT_S3_BUCKET" \
  --arg endpoint "$VAULT_S3_ENDPOINT_URL" \
  --arg region "$VAULT_S3_REGION" \
  --arg access "$SEAWEEDFS_ACCESS_KEY" \
  --arg secret "$SEAWEEDFS_SECRET_KEY" \
  --arg backend "${VAULT_STORAGE_BACKEND:-s3}" \
  '{username:"manual-admin",password:"manual-admin-password",email:"manual-admin@example.test",storage_backend:$backend,s3_bucket:$s3,s3_endpoint_url:$endpoint,s3_region:$region,s3_access_key:$access,s3_secret_key:$secret}')"
setup_cookie_file="$(mktemp)"
setup_csrf="$(curl -fsS -X POST "$API/api/v1/setup/session" -H "Origin: $API" -c "$setup_cookie_file" | jq -r .csrf)"
ADMIN_TOKEN="$(curl -fsS -X POST "$API/api/v1/setup" \
  -H "Origin: $API" -H "X-PrintStash-Setup-CSRF: $setup_csrf" -b "$setup_cookie_file" \
  -H 'Content-Type: application/json' --data "$SETUP_JSON" | jq -r .access_token)"
rm -f "$setup_cookie_file"
test -n "$ADMIN_TOKEN" && test "$ADMIN_TOKEN" != null
curl -fsS "$API/api/v1/health" | jq
```

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

### Start stack with printer emulators profile

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Adds the emulators profile to the default PostgreSQL+S3+Authentik mode. The emulators are built from the checked-in core testkit, so no package installation occurs at container startup. For SQLite/no-identity mode, omit --profile identity and add only --profile emulators.

```sh
docker compose -p printstash-manual -f deploy/manual-testing/compose.yml \
  --env-file deploy/manual-testing/.env --profile identity --profile emulators \
  up --wait --build
```

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

### Start API with Postgres override

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Starts the API with the PostgreSQL URL in an override. The image entrypoint normalizes the URL for Psycopg 3 and runs migrations before serving.

```bash
docker compose up -d --wait api
```

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

### Local development setup commands

Source: https://github.com/xiao-villamor/printstash/blob/main/UPGRADE.md

Commands to set up the backend for local development. Use '--extra async-db' only when exercising SQLite through create_async_engine.

```bash
cd backend
uv sync --extra dev --extra full
uv run alembic upgrade head
```

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

### Start SeaweedFS with Docker Compose

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Starts the SeaweedFS service using the 's3' profile. Requires Docker Compose and the bundled SeaweedFS image pinned to version 4.41.

```bash
docker compose --profile s3 up -d seaweedfs
```

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

### Example environment variables for storage configuration

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0003-storage-capability-tiers.md

Shows the naming convention for environment variables used to configure storage providers.

```text
VAULT_STORAGE_PROVIDER=nextcloud
VAULT_NEXTCLOUD_URL=https://cloud.example.com
VAULT_NEXTCLOUD_USERNAME=printstash
VAULT_NEXTCLOUD_APP_PASSWORD=…
VAULT_NEXTCLOUD_FOLDER=/PrintStash
```

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

### Start PostgreSQL+S3+Authentik stack with identity profile

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Starts the default PostgreSQL+S3+Authentik stack with the identity profile and waits for the application and OIDC provider to be ready. Compose health alone does not prove blueprint reconciliation, so the wait-ready script is required.

```sh
docker compose -p printstash-manual -f deploy/manual-testing/compose.yml \
  --env-file deploy/manual-testing/.env --profile identity \
  up --wait --build
./deploy/manual-testing/bin/wait-ready.sh deploy/manual-testing/.env
```

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

### Upgrade flow (local dev): sync, migrate, run

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Local development upgrade flow: sync dependencies, run migrations, and start the server with reload.

```bash
cd backend
uv sync --extra dev
uv run python -m app.db.migrate
uv run uvicorn app.main:app --reload
```

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

### Start Postgres with Docker Compose profile

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Starts the Postgres service using the built-in `postgres` profile. Use this when you need higher write concurrency, larger datasets, or operational tooling beyond a single SQLite file.

```bash
docker compose --profile postgres up -d postgres
```

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

### Full stack Docker Compose

Source: https://github.com/xiao-villamor/printstash/wiki/Development

Starts the full-stack environment using Docker Compose.

```bash
docker compose -f docker-compose.light.yml up
```

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

### POST /api/v1/provider-connections/myminifactory/authorize

Source: https://github.com/xiao-villamor/printstash/wiki/API

Start per-user OAuth.

```APIDOC
## POST /api/v1/provider-connections/myminifactory/authorize

### Description
Start per-user OAuth.

### Method
POST

### Endpoint
/api/v1/provider-connections/myminifactory/authorize

### Response
#### Success Response (200)
- Start per-user OAuth.

```

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

### Upgrade flow (Docker): pull and start

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Docker upgrade flow: pulls or rebuilds the image and starts the container, letting the entrypoint run migrations before serving.

```bash
# Pull or rebuild, then let the image entrypoint migrate before serving.
docker compose pull
docker compose up -d --wait
```

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

### Build and run from checkout

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/deployment.md

Builds the unified image from a checkout using Docker Buildx and then starts the stack with the locally built image. The API and frontend both come from the checkout; no published base image is required.

```bash
docker buildx bake -f docker-bake.hcl unified --load
PRINTSTASH_IMAGE=printstash PRINTSTASH_VERSION=local docker compose up -d
```

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

### Unraid bind mount mapping for library enrollment

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/0.13.0-release-guide.md

Example mapping for an Unraid user share into the API container for initial enrollment. The API image starts with the 10001:10001 identity unless PUID and PGID are set; set both to the positive numeric owner. After the source root is verified, the mount may be changed to Read-only unless write-back is required.

```text
Host path:      /mnt/user/3d-library
Container path: /mnt/library
Access:         Read/Write for enrollment

```

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

### Stop, update, and troubleshoot with docker compose

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/deployment.md

Run these commands in the install directory to check status and logs, stop the service while preserving data, and update to the selected image tag. Read UPGRADE.md and make a backup before updating.

```bash
# Status and logs
docker compose ps
docker compose logs --tail=100 printstash

# Stop while preserving data
docker compose down

# Update to the selected image tag (latest unless pinned)
docker compose pull && docker compose up -d
```

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

### Clone and start PrintStash with Docker Compose

Source: https://github.com/xiao-villamor/printstash/wiki/Installation

Clones the PrintStash repository and starts the default Compose stack. The web UI is available at http://localhost:3000 and the health endpoint at http://localhost:3000/api/v1/health. No .env file is required for first launch.

```bash
git clone https://github.com/xiao-villamor/PrintStash.git
cd PrintStash
docker compose up -d
```

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

### Start API with Docker Compose (advanced)

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Starts the API using the advanced compose file. Uncomment the two `build:` blocks in docker-compose.advanced.yml first. Named volumes under `/data/` persist files and DB across rebuilds. The image runs as unprivileged `10001:10001`; set `PUID`/`PGID` in `.env` for bind-mounted data directories.

```bash
# Uncomment the two `build:` blocks in docker-compose.advanced.yml first.
docker compose -f docker-compose.advanced.yml up --build
```

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

### Start advanced stack with workers

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/deployment.md

Starts the advanced stack with PostgreSQL and worker containers. Workers run the API image with VAULT_PROCESS_ROLE=worker and the command /app/.venv/bin/python -m app.worker; they serve no HTTP, never migrate, and stop cleanly on SIGTERM. A worker refuses to start on SQLite or without VAULT_SHARED_STORAGE=true.

```bash
docker compose -f docker-compose.advanced.yml --profile postgres --profile workers up -d
```

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

### ProviderConfig base class and NextcloudConfig example

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0003-storage-capability-tiers.md

Defines the abstract ProviderConfig base with ClassVar metadata and an abstract transport method, followed by a concrete NextcloudConfig subclass. The union type AnyProviderConfig and TypeAdapter are also shown. This enables concrete type parsing, exhaustiveness checking, and prevents metadata drift.

```python
class ProviderConfig(BaseModel, ABC):
    """One provider's typed, user-facing settings."""

    provider: ClassVar[StorageProvider]
    label: ClassVar[str]
    blurb: ClassVar[str]
    category: ClassVar[ProviderCategory]
    expected_tier: ClassVar[StorageTier]
    docs_anchor: ClassVar[str]

    @abstractmethod
    def transport(self) -> TransportSpec: ...


class NextcloudConfig(ProviderConfig):
    provider = StorageProvider.NEXTCLOUD
    label = "Nextcloud"
    category = ProviderCategory.WEBDAV
    expected_tier = StorageTier.UNGUARDED
    ...

    kind: Literal[StorageProvider.NEXTCLOUD] = StorageProvider.NEXTCLOUD
    server_url: HttpUrl
    app_password: SecretStr
    ...


AnyProviderConfig = Annotated[
    LocalConfig | S3Config | R2Config | NextcloudConfig | WebdavConfig | SftpConfig
    | AzureBlobConfig | GcsConfig,
    Field(discriminator="kind"),
]
PROVIDER_CONFIG = TypeAdapter(AnyProviderConfig)
```

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

### Start SQLite+local storage mode for write-back

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Starts a separate disposable SQLite+local-storage mode for testing external-library write-back. This mode is required because PrintStash's write-back guard requires the vault storage backend to be local; it is not the PostgreSQL+S3 or SQLite+S3 backup mode.

```sh
VAULT_DB_URL=sqlite:////data/db/printstash.sqlite \
VAULT_STORAGE_BACKEND=local \
VAULT_OIDC_ENABLED=false \
docker compose -p printstash-manual -f deploy/manual-testing/compose.yml \
  --env-file deploy/manual-testing/.env \
  up --wait --build
VAULT_OIDC_ENABLED=false ./deploy/manual-testing/bin/wait-ready.sh \
  deploy/manual-testing/.env
```

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

### Upgrade API with Docker Compose

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Pulls the latest images and recreates services. The entrypoint runs migrations before the API starts. Do not override the entrypoint with a manual Alembic command.

```bash
docker compose pull
docker compose up -d --wait
```

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

### GET /api/v1/files/{id}/download

Source: https://github.com/xiao-villamor/printstash/wiki/API

Download an Artifact.

```APIDOC
## GET /api/v1/files/{id}/download

### Description
Download an Artifact.

### Method
GET

### Endpoint
/api/v1/files/{id}/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the file to download.

### Response
#### Success Response (200)
- Download an Artifact.

```

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

### List Compose volumes and Docker volumes

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/0.13.0-release-guide.md

Check the effective volume names before starting the new image. Use the same Compose project name so Docker resolves existing volumes; do not create replacement volumes with similar names.

```bash
docker compose config --volumes
docker volume ls

```

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

### Advanced deployment build command

Source: https://github.com/xiao-villamor/printstash/blob/main/UPGRADE.md

Command to build and start the advanced deployment with Docker Compose. Uncomment the 'build:' blocks in docker-compose.advanced.yml before running.

```bash
docker compose -f docker-compose.advanced.yml up -d --build --wait
```

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

### GET /api/v1/models

Source: https://github.com/xiao-villamor/printstash/wiki/API

Browse accessible Models.

```APIDOC
## GET /api/v1/models

### Description
Browse accessible Models.

### Method
GET

### Endpoint
/api/v1/models

### Response
#### Success Response (200)
- Browse accessible Models.

```

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

### GET /api/v1/config

Source: https://github.com/xiao-villamor/printstash/wiki/API

Superuser configuration with secrets masked and measured storage tier/capabilities.

```APIDOC
## GET /api/v1/config

### Description
Superuser configuration with secrets masked and measured storage tier/capabilities.

### Method
GET

### Endpoint
/api/v1/config

### Response
#### Success Response (200)
- Superuser configuration with secrets masked and measured storage tier/capabilities.

```

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

### GET /api/v1/health

Source: https://github.com/xiao-villamor/printstash/wiki/API

Minimal liveness response.

```APIDOC
## GET /api/v1/health

### Description
Minimal liveness response.

### Method
GET

### Endpoint
/api/v1/health

### Response
#### Success Response (200)
- Minimal liveness response.

```

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

### Copy env file and render Compose config

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Run from the repository root. Requires Docker Compose v2, curl, jq, and a POSIX shell. Copies the test-only env file and renders the Compose YAML without pulling or starting images. The env filename is deploy/manual-testing/.env.

```sh
cp deploy/manual-testing/.env.example deploy/manual-testing/.env
docker compose -p printstash-manual -f deploy/manual-testing/compose.yml \
  --env-file deploy/manual-testing/.env config
```

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

### GET /api/v1/storage/providers

Source: https://github.com/xiao-villamor/printstash/wiki/API

Public provider catalogue without credentials.

```APIDOC
## GET /api/v1/storage/providers

### Description
Public provider catalogue without credentials.

### Method
GET

### Endpoint
/api/v1/storage/providers

### Response
#### Success Response (200)
- Public provider catalogue without credentials.

```

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

### GET /api/v1/provider-connections

Source: https://github.com/xiao-villamor/printstash/wiki/API

List the current user's capture-provider connections.

```APIDOC
## GET /api/v1/provider-connections

### Description
List the current user's capture-provider connections.

### Method
GET

### Endpoint
/api/v1/provider-connections

### Response
#### Success Response (200)
- List the current user's capture-provider connections.

```

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

### Obtain admin token via local login

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Use this command in a new shell session to retrieve the admin bearer token using the credentials established during the initial setup.

```sh
ADMIN_TOKEN="$(curl -fsS -X POST "$API/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  --data '{"username":"manual-admin","password":"manual-admin-password"}' \
  | jq -r .access_token)"
```

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

### GET /api/v1/health/details

Source: https://github.com/xiao-villamor/printstash/wiki/API

Authenticated database, storage, backup, job, and provider diagnostics.

```APIDOC
## GET /api/v1/health/details

### Description
Authenticated database, storage, backup, job, and provider diagnostics.

### Method
GET

### Endpoint
/api/v1/health/details

### Response
#### Success Response (200)
- Authenticated database, storage, backup, job, and provider diagnostics.

```

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

### Server-Described Provider API Response

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0003-storage-capability-tiers.md

Example JSON structure returned by the API to dynamically generate provider configuration forms.

```json
GET /api/v1/storage/providers
[
  { "id": "nextcloud", "label": "Nextcloud", "category": "webdav",
    "blurb": "Store the library in a Nextcloud folder.",
    "expected_tier": "unguarded",
    "consequences": ["Two simultaneous uploads of the same revision …"],
    "docs_url": "…/storage-providers.md#nextcloud",
    "fields": [
      { "name": "server_url", "label": "Nextcloud URL", "type": "url",
        "help": "e.g. https://cloud.example.com", "secret": false,
        "required": true },
      { "name": "app_password", "label": "App password", "type": "string",
        "help": "Settings → Security → Create new app password.",
        "secret": true, "required": true }
    ] }
]
```

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

### Docker Compose upgrade commands

Source: https://github.com/xiao-villamor/printstash/blob/main/UPGRADE.md

Commands to pull, start, and verify the PrintStash services. The API image runs migrations automatically; do not add manual Alembic commands. For advanced deployments, add '-f docker-compose.advanced.yml' to each command.

```bash
docker compose pull
docker compose up -d --wait
docker compose ps
curl -fsS http://localhost:3000/api/v1/health
```

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

### NextcloudConfig provider implementation

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0003-storage-capability-tiers.md

Full example of a provider that encapsulates Nextcloud's WebDAV endpoint layout. It uses OpenDAL transport with scheme 'webdav', sets the root to the configured folder, and builds the endpoint from the server URL and username. The app password is stored as a SecretStr and retrieved via get_secret_value().

```python
class NextcloudConfig(ProviderConfig):
    server_url: HttpUrl = Field(title="Nextcloud URL",
                                description="e.g. https://cloud.example.com")
    username: str = Field(title="Username")
    app_password: SecretStr = Field(
        title="App password",
        description="Settings → Security → Create new app password.")
    folder: str = Field(default="/PrintStash", title="Folder")

    def transport(self) -> TransportSpec:
        # Nextcloud's WebDAV endpoint layout is our problem, not the user's.
        return TransportSpec(
            kind=TransportKind.OPENDAL,
            scheme="webdav",
            root=self.folder,
            options={"endpoint":
                     f"{self.server_url}/remote.php/dav/files/{self.username}"},
            secret_options={"username": self.username,
                            "password": self.app_password.get_secret_value()},
        )
```

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

### Start SQLite+S3 mode without identity

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Switches to SQLite+S3 mode without identity using shell overrides that take precedence over .env values. Do not include --profile identity in this mode; the PostgreSQL container may remain present but the API does not connect to it.

```sh
VAULT_DB_URL=sqlite:////data/db/printstash.sqlite \
VAULT_OIDC_ENABLED=false \
docker compose -p printstash-manual -f deploy/manual-testing/compose.yml \
  --env-file deploy/manual-testing/.env \
  up --wait --build
VAULT_OIDC_ENABLED=false ./deploy/manual-testing/bin/wait-ready.sh \
  deploy/manual-testing/.env
```

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

### Run ingestion under backfill load test

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/ai-search-performance.md

Command to run the ingestion load test with specified parameters. The test measures p95 upload-to-completion latency, requiring at most 25% additional latency and no failed ingests. It uses a fresh installation and ordered G-code corpus, with a 900-second startup allowance for backfill reconciliation.

```sh
uv run python -m tests.fakes.search_ingest_load \
  --directory /tmp/ai-search-ingest-load \
  --model-directory /absolute/path/to/bge-export \
  --count 10000 --uploads 20
```

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

### Run Frontend Performance Experiments

Source: https://github.com/xiao-villamor/printstash/blob/main/CONTRIBUTING.md

Commands for running experimental build and test lanes in the frontend.

```bash
cd frontend
pnpm dev:bundle                 # Vite's experimental bundled development server
pnpm build:react-compiler       # native Oxc React Compiler production build
pnpm test:fast                  # audited pure tests: threads + shared module graph
pnpm test:changed               # root tests related to the current Git diff
pnpm test:happy-dom             # compatibility/timing trial; jsdom stays authoritative
pnpm test:jsdom                 # explicit authoritative root-suite comparison
pnpm test:e2e:bundle            # full mock-API E2E against bundled development
pnpm test:perf                  # 3 baseline production-build browser samples
pnpm test:perf:react-compiler   # same browser samples with native React Compiler
```

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

### Configure first administrator via environment variables

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/first-run.md

Set VAULT_SETUP_MODE to 'environment' and provide the administrator credentials to create the first administrator at startup without browser registration. The password must be at least 8 characters, and the email is optional. These variables are consumed once and do not change existing accounts.

```yaml
environment:
  VAULT_SETUP_MODE: environment
  VAULT_SETUP_ADMIN_USERNAME: admin
  VAULT_SETUP_ADMIN_PASSWORD: <at least 8 characters>
  VAULT_SETUP_ADMIN_EMAIL: admin@example.net # optional
```

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

### Reproduce native experiment from backend/

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/mesh-processing-performance.md

Run these commands from the backend/ directory to reproduce the native Rust prototype experiment. The first command compiles the Rust source with optimization level 3, and the second runs the Python module with the --native flag pointing to the compiled binary.

```sh
rustc --edition=2021 -C opt-level=3 tests/fakes/proximity_probe.rs -o /tmp/proximity-probe
uv run python -m tests.fakes.proximity_probe --native /tmp/proximity-probe --verify
```

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

### Run extension tests and builds

Source: https://github.com/xiao-villamor/printstash/blob/main/browser-extension/README.md

Run the WXT/Vitest adapter, storage, messaging, and popup fixtures. This command builds clean Chrome, Firefox, and Edge MV3 targets before running the manifest and behavior fixtures.

```bash
cd browser-extension && pnpm test && pnpm build && pnpm build:firefox
```

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

### Run Frontend Checks

Source: https://github.com/xiao-villamor/printstash/blob/main/CONTRIBUTING.md

Commands to execute linting, formatting, and type checking for the frontend.

```bash
cd frontend
pnpm lint          # oxlint
pnpm format:check  # oxfmt
pnpm typecheck     # TypeScript 7 native compiler
```

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

### Browser extension checks and build

Source: https://github.com/xiao-villamor/printstash/wiki/Development

Runs browser extension checks and builds the extension.

```bash
cd browser-extension
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

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

### Configure source and target credentials for migration

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/minio-migration.md

Set environment variables for MinIO source and SeaweedFS target credentials and bucket names. Defaults match the previously bundled services; use existing deployment credentials if they differ.

```bash
export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=minioadmin
export MINIO_MIGRATION_SOURCE_BUCKET=printstash-vault
export SEAWEEDFS_ACCESS_KEY=printstash
export SEAWEEDFS_SECRET_KEY=printstash-secret
export SEAWEEDFS_MIGRATION_TARGET_BUCKET=printstash-vault
```

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

### GET /api/v1/printers/{id}/diagnostics

Source: https://github.com/xiao-villamor/printstash/wiki/API

Inspect provider capabilities and connectivity.

```APIDOC
## GET /api/v1/printers/{id}/diagnostics

### Description
Inspect provider capabilities and connectivity.

### Method
GET

### Endpoint
/api/v1/printers/{id}/diagnostics

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the printer.

### Response
#### Success Response (200)
- Inspect provider capabilities and connectivity.

```

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

### Run visual benchmark and quality test commands

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/ai-search-visual-study.md

Run the explicit local-only measurement tools from `backend/` with preplaced, verified model assets. Neither command downloads weights or sends library data.

```shell
uv run python -m tests.fakes.visual_candidate_benchmark --help
uv run python -m tests.fakes.visual_existing_benchmark /path/to/clip-b32 /tmp/existing.json
uv run pytest -n 0 tests/integration/modules/search/retrieval/test_visual_quality.py
```

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

### Upgrade from previous release to candidate

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Tests a version upgrade by pulling a previous release, seeding data, capturing a PostgreSQL and S3 checkpoint, and then deploying the current candidate build while retaining volumes.

```sh
PREVIOUS_VERSION=0.12.2
docker pull ghcr.io/xiao-villamor/printstash-api:$PREVIOUS_VERSION
docker pull ghcr.io/xiao-villamor/printstash-frontend:$PREVIOUS_VERSION
docker tag ghcr.io/xiao-villamor/printstash-api:$PREVIOUS_VERSION printstash-manual-api:previous
docker tag ghcr.io/xiao-villamor/printstash-frontend:$PREVIOUS_VERSION printstash-manual-frontend:previous
PRINTSTASH_IMAGE_TAG=previous docker compose -p printstash-manual \
  -f deploy/manual-testing/compose.yml --env-file deploy/manual-testing/.env \
  --profile identity up --wait --no-build
./deploy/manual-testing/bin/wait-ready.sh deploy/manual-testing/.env
# Seed a marker and exercise the old release. Capture this exact paired
# PostgreSQL+S3 checkpoint before switching image tags.
mkdir -p deploy/manual-testing/evidence/pre-upgrade
set -a; . deploy/manual-testing/.env; set +a
docker compose -p printstash-manual -f deploy/manual-testing/compose.yml \
  --env-file deploy/manual-testing/.env exec -T printstash-db \
  pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom \
  > deploy/manual-testing/evidence/pre-upgrade/printstash.dump
docker run --rm -v printstash-manual_printstash_manual_seaweedfs:/from:ro \
  -v "$PWD/deploy/manual-testing/evidence/pre-upgrade:/to" alpine:3.20 \
  sh -c 'tar czf /to/seaweedfs.tgz -C /from .'
PRINTSTASH_IMAGE_TAG=candidate docker compose -p printstash-manual \
  -f deploy/manual-testing/compose.yml --env-file deploy/manual-testing/.env \
  --profile identity up --wait --build
./deploy/manual-testing/bin/wait-ready.sh deploy/manual-testing/.env
```

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

### Run preplaced CLIP integration test

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/tests/fixtures/embeddings/README.md

Run the preplaced CLIP integration test from the backend/ directory. Set SIMILARITY_CLIP_ASSETS to the absolute path of the directory containing the ONNX and tokenizer files, and copy the fixture as manifest.json there.

```bash
SIMILARITY_CLIP_ASSETS=/absolute/path/to/assets uv run pytest \
  tests/integration/modules/inference/preplaced_clip.py -q
```

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

### POST /api/v1/backups

Source: https://github.com/xiao-villamor/printstash/wiki/API

Create a full backup.

```APIDOC
## POST /api/v1/backups

### Description
Create a full backup.

### Method
POST

### Endpoint
/api/v1/backups

### Response
#### Success Response (200)
- Create a full backup.

```

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

### Run native-vector feasibility test

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/ai-search-performance.md

Executes the native-vector feasibility harness from the backend directory. Requires a new destination directory and measures sqlite-vec exact KNN with 500,000 vectors, recording recall@10, latency percentiles, build time, database size, and resource use. A fresh SQLite connection verifies the snapshot without loading the vector extension.

```sh
uv run python -m tests.fakes.vector_scale \
  --directory /tmp/ai-vector-scale-500k \
  --count 500000 --dimension 384 --queries 32
```

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

### Run Backend Checks

Source: https://github.com/xiao-villamor/printstash/blob/main/CONTRIBUTING.md

Commands to execute tests, linting, formatting, and type checking for the backend.

```bash
cd backend
uv run pytest tests -v
uv run ruff check app/ tests/
uv run ruff format app/ tests/
uv run pyright
uv run ty check app/  # advisory while ty is pre-1.0
```

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

### Run similarity resource probe under 1 GiB memory limit

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0005-similar-models-benchmark.md

Runs the similarity resource probe under a 1 GiB memory limit using systemd-run. The probe resolves the Spatula 3MF into a temporary STL, verifies 5,000 points, and concurrently renders a thumbnail. The command fails when acceptance assertions fail.

```sh
systemd-run --user --scope -p MemoryMax=1G -p MemorySwapMax=0 --quiet \
  uv run --directory backend python -m tests.fakes.similarity_resource_probe \
  --output /tmp/printstash-similarity-resource.json
```

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

### Frontend Development Commands

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/release-validation.md

Run these commands from the `frontend` directory to lint, format-check, type-check, test, build, and run end-to-end tests.

```bash
cd frontend
pnpm lint
pnpm format:check
pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e
pnpm test:e2e:real
```

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

### Run printed photo benchmark with multiview_mean profile

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/ai-search-visual-study.md

Runs the printed photo benchmark using the specified CLIP model directory and outputs results to a JSON file. The profile must be explicitly provided; the command preserves all profile results and fails if the selected profile misses the fixed top-10 target. Selecting 'thumbnail' retains the measured failure.

```sh
uv run python -m tests.fakes.printed_photo_benchmark \
  --model-directory /path/to/clip-b32 \
  --output /tmp/printed-photo.json --profile multiview_mean
```

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

### Run text candidate benchmark with uv

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/ai-search-model-study.md

Run the text candidate benchmark from the backend/ directory. The command never downloads models, checks assets and canaries through the production provider, and keeps query inputs in memory. Repeat --model-dir to compare candidates. An output marked runtime_rejected is a failed admission, not a zero-quality measurement.

```sh
uv run python -m tests.fakes.text_candidate_benchmark \
  --model-dir /absolute/path/to/preplaced/model \
  --output /tmp/text-candidate-measurements.json
```

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

### Backend Development Commands

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/release-validation.md

Run these commands from the `backend` directory to sync dependencies, format, lint, type-check, test, and audit the codebase. The test command enforces 95% coverage.

```bash
cd backend
uv sync --extra dev --extra full --frozen
uv run ruff format --check app/ tests/
uv run ruff check app/ tests/
uv run pyright
uv run deptry app
uv run pytest tests --cov=app --cov-report=term-missing --cov-fail-under=95
uv run bandit -r app -q
uv run pip-audit
```

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

### Run cold benchmark for mesh fingerprint preparation

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/mesh-processing-performance.md

Command to run the standalone cold benchmark that builds a new library from byte-distinct exports, seeds no fingerprints, and verifies cached response behavior. Run from the backend/ directory. The completed run used 1,001 artifacts, 256 verification samples, and reported cold fingerprint preparation time of 1,095.45 seconds.

```sh
uv run python -m tests.fakes.similarity_cold_benchmark \
  --root /tmp/new-mesh-library --count 1001 --batch 250
```

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

### Migrate MinIO to SeaweedFS

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/README.md

Runs the migration helper script to copy and verify MinIO volumes for SeaweedFS. The helper never deletes source objects or the source volume.

```bash
./scripts/migrate_minio_to_seaweedfs.sh
```

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

### Run real E2E suites (pnpm test:e2e:real, test-critical.sh, storage)

Source: https://github.com/xiao-villamor/printstash/blob/main/frontend/tests/e2e-real/README.md

Commands for the real end-to-end test suites: pnpm test:e2e:real runs all real-backend specs, ./scripts/test-critical.sh runs the release-blocking subset (backup recovery, ingestion, organisation, trash, scans, remote storage), pnpm test:e2e:storage runs the storage-provider suite, and PLAYWRIGHT_STORAGE_NEXTCLOUD_URL=http://127.0.0.1:8780 pnpm test:e2e:storage enables the additional real-Nextcloud contract when the URL is reachable.

```bash
pnpm test:e2e:real
```

```bash
./scripts/test-critical.sh
```

```bash
pnpm test:e2e:storage
```

```bash
PLAYWRIGHT_STORAGE_NEXTCLOUD_URL=http://127.0.0.1:8780 pnpm test:e2e:storage
```

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

### ensure_setup() refuses Unguarded backend unless VAULT_STORAGE_ALLOW_UNVERIFIED=true

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0003-storage-capability-tiers.md

Raises RuntimeError when the backend tier is UNGUARDED and the environment variable is not set. The flag is environment-only, not runtime-config, to avoid circularity, limit blast radius, and require deliberate action.

```python
def ensure_setup(self) -> None:
    caps = self.capabilities()
    if caps.tier is StorageTier.UNGUARDED and not settings.storage_allow_unverified:
        raise RuntimeError(
            f"storage backend {self.backend_name!r} cannot create objects without "
            "replacement. Set VAULT_STORAGE_ALLOW_UNVERIFIED=true to accept the "
            "consequences listed at <docs link>."
        )
```

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

### AWS-style S3 bucket CORS rule for native_parts upload

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/artifact-uploads.md

JSON array of CORS rules for an S3 bucket to permit direct browser uploads (native_parts) to PrintStash. Must list every exact browser origin; do not use '*' for authenticated deployments. The example sets AllowedOrigins to https://printstash.example.com, AllowedMethods to PUT, allows content-type and x-amz-checksum-sha256 headers, and exposes ETag and x-amz-checksum-sha256. ExposeHeaders are required for the browser to read checksum/ETag receipts.

```json
[
  {
    "AllowedOrigins": ["https://printstash.example.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["content-type", "x-amz-checksum-sha256"],
    "ExposeHeaders": ["ETag", "x-amz-checksum-sha256"],
    "MaxAgeSeconds": 300
  }
]
```

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

### Run similarity benchmark for 10,000 artifacts

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0005-similar-models-benchmark.md

Runs the similarity benchmark to prepare an index of 10,000 artifacts with 32 geometry variants. The command fails when acceptance assertions fail. The fixture is a prepared index with one uncached artifact in the requested Model scope, not a cold backfill.

```sh
uv run --directory backend python -m tests.fakes.similarity_benchmark \
  --root /tmp/printstash-similarity-benchmark --count 10000 --designs 32
```

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

### PostgreSQL and SeaweedFS snapshot

Source: https://github.com/xiao-villamor/printstash/blob/main/deploy/manual-testing/README.md

Export the database and SeaweedFS volume to the evidence directory before performing upgrades or resets.

```sh
set -a; . deploy/manual-testing/.env; set +a
mkdir -p deploy/manual-testing/evidence/pre-upgrade
docker volume inspect printstash-manual_printstash_manual_seaweedfs
docker compose -p printstash-manual -f deploy/manual-testing/compose.yml \
  --env-file deploy/manual-testing/.env exec -T printstash-db \
  pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom \
  > deploy/manual-testing/evidence/pre-upgrade/printstash.dump
docker run --rm \
  -v printstash-manual_printstash_manual_seaweedfs:/from:ro \
  -v "$PWD/deploy/manual-testing/evidence/pre-upgrade:/to" alpine:3.20 \
  sh -c 'tar czf /to/seaweedfs.tgz -C /from .'
sha256sum deploy/manual-testing/evidence/pre-upgrade/printstash.dump \
  deploy/manual-testing/evidence/pre-upgrade/seaweedfs.tgz
```

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

### Run test suite with ./scripts/test.sh

Source: https://github.com/xiao-villamor/printstash/blob/main/backend/tests/README.md

Commands to run the test suite. `full` requires Docker and fails without it; `fast` needs nothing. Use `affected` to run only tests for changed files, and `serial` to disable xdist for debugging ordering issues.

```bash
./scripts/test.sh            # fast: unit + integration, parallel
./scripts/test.sh contract   # contract lane
./scripts/test.sh e2e        # e2e lane
./scripts/test.sh full       # everything
./scripts/test.sh affected   # only what your working tree touches
./scripts/test.sh serial     # no xdist, for debugging an ordering problem
./scripts/test.sh --help
```

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

### Reviewer instructions for PrintStash extension

Source: https://github.com/xiao-villamor/printstash/blob/main/browser-extension/CHROME-WEB-STORE.md

Text block with step-by-step instructions for the Chrome Web Store reviewer. It covers setting up a local PrintStash server, pairing the browser, sending a model to Pending Imports, and reviewing the captured item. It also notes that provider challenges are not bypassed and a manual-file fallback exists.

```text
This extension requires a self-hosted PrintStash server. It does not require an
account with the extension publisher. Installation instructions for the server
are available in the linked PrintStash repository README.

1. Start PrintStash locally and complete its initial account setup.
2. In PrintStash Settings → Imports, create a browser pairing code.
3. Open the extension, enter the local server URL and code, and click Pair browser.
4. Open a supported model page, reopen the extension, and select Send to Pending
   Imports. For MakerWorld, sign in on the source site first. Select files when
   prompted and keep the popup open until the transfer completes.
5. Open Pending Imports in PrintStash and review the captured item before import.
6. The Help & privacy link works without a server or a source-site account.

Provider challenges or sign-in restrictions are not bypassed. A manual-file
fallback is available where the provider cannot complete automatic capture.
```

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

### Repository layout (text)

Source: https://github.com/xiao-villamor/printstash/wiki/Architecture

Directory tree showing the backend structure with app subdirectories (api/v1, core, db, services, schemas), packages/printstash-core, frontend, browser-extension, and docs.

```text
backend/
  app/
    api/v1/       routers
    core/         configuration, auth, HTTP, logging
    db/           models, migrations, scopes, sessions
    services/     domain workflows and provider composition
    schemas/      public request/response contracts
  packages/
    printstash-core/  reusable archive, G-code, mesh, import, and network logic
frontend/
  src/            application UI
  packages/       shared frontend domain and UI packages
browser-extension/
docs/
```

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

### Bind storage configuration with generics

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/adr/0003-storage-capability-tiers.md

Use generics to ensure that a storage backend is correctly paired with its corresponding provider configuration.

```python
C = TypeVar("C", bound=ProviderConfig)

def bind(config: C, backend: StorageBackend) -> BoundStorage[C]: ...
```

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

### Frontend checks and tests

Source: https://github.com/xiao-villamor/printstash/wiki/Development

Runs frontend formatting, linting, type checking, and unit tests.

```bash
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
```

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

### Export OpenShape point cloud model

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/ai-search-point-study.md

Run from backend/ with a Python environment containing torch==2.14.0+cpu, onnx==1.22.0, onnxruntime==1.30.0, dgl==1.1.3, torch-redstone==0.0.6, einops, NumPy, and pydantic==2.12.5. The destination must be new; the tool verifies checkpoint SHA, support revision, paired Space, original-vs-split output, operator domains, and ONNX canary before writing the manifest. It uses torch.load(weights_only=True) and performs no download.

```sh
PYTHONPATH=.:packages/printstash-core/src python scripts/export_openshape.py \
  --checkpoint /path/to/pointbert-b32.pt \
  --support /path/to/openshape-demo-support \
  --paired /path/to/verified-clip-b32 \
  --output /path/to/new-point-export
```

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

### Backend tests and linting

Source: https://github.com/xiao-villamor/printstash/wiki/Development

Runs the backend test suites and static checks.

```bash
cd backend
./scripts/test.sh fast -q
./scripts/test.sh full -q
uv run ruff check app/ tests/
uv run pyright
```

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

### Run WebDAV cleanup contract tests

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/webdav-cleanup-evidence.md

Run the WebDAV cleanup contract suite from the backend directory with Docker available. The command uses the full test script with zero workers and quiet output, targeting the specific cleanup test file.

```sh
./scripts/test.sh full -n 0 -q tests/contract/modules/storage/storage_opendal/test_webdav_cleanup.py
```

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

### Architecture diagram (text)

Source: https://github.com/xiao-villamor/printstash/wiki/Architecture

ASCII diagram showing the flow from browser UI/extension/scripts/OrcaSlicer through FastAPI API to domain/services and provider adapters, then to storage (SQLite/local files default, Postgres/remote optional).

```text
Browser UI / extension / scripts / OrcaSlicer
                    |
                    v
              FastAPI API
                    |
        +-----------+------------+
        |                        |
 domain/services          provider adapters
        |                printers / capture / storage
        |                        |
        +-----------+------------+
                    |
       SQLite + local files (default)
       Postgres + remote storage (optional)
```

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

### Verify library mount inside container

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/0.13.0-release-guide.md

Verify the host mount from inside the container before enrolling an existing mounted library source. Enroll only when the expected files are visible; a missing or wrong mount must not be accepted as the old source.

```bash
docker compose exec api sh -c 'test -r /mnt/library && find /mnt/library -maxdepth 1 -type f | head'

```

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

### Run remote discovery contract tests

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/remote-discovery-benchmarks.md

Run the remote discovery contract suite from the backend/ directory. The suite asserts exact key coverage, pages of at most 1,000 entries, and less than 64 MiB of peak RSS growth. It also exercises stalled S3, WebDAV, and SFTP requests under short scan deadlines.

```sh
./scripts/test.sh contract -q tests/contract/modules/sources/test_remote_discovery.py --junitxml=/tmp/discovery.xml
```

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

### Unraid container volume mapping for library source

Source: https://github.com/xiao-villamor/printstash/blob/main/docs/library-sources.md

Maps the Unraid user share /mnt/user/3d-library to /mnt/library with read/write access for enrollment. After the root is verified, it may be changed to read-only unless write-back is required. User shares are FUSE-backed, so rely on scheduled scans and the runtime-probed storage tier.

```text
Host path:      /mnt/user/3d-library
Container path: /mnt/library
Access:         Read/Write for enrollment
```