| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 14 | 4 | 0% |
| Commands | 1 | 39 | 3 | 2% |
| Section tags | 3 | 8 | 1 | 25% |
What each file covers
Sections
0 shared · 14 only in A · 4 only in B- − CLAUDE.md
- − Build Commands
- − Testing
- − Formatting & Linting
- − Continuous Integration
- − Schema Migrations
- − or via Makefile:
- − Architecture Overview
- − Backend (`internal/`, `pkg/`, `cmd/`)
- − Frontend (`frontend/`)
- − API Conventions
- − Config & Flags
- − Verify Before Propagating
- − Detailed Rules
- + API Guidelines
- + Handler Conventions
- + Roles, Scopes & Sessions
- + Swagger & API Tests
Commands
1 shared · 39 only in A · 3 only in B- − go test ./internal/api -run 'TestFunctionName' -count=1
- − go test ./internal/photoprism -run 'TestMediaFile_' -count=1
- − go test ./internal/entity/... -count=1 -tags="slow,develop"
- − go run cmd/photoprism/photoprism.go migrations ls
- − go run cmd/photoprism/photoprism.go migrations run
- − make migrate
- − make help
- − make list
- − make build-go
- − make build-all
- − go build ./...
- − make build-js
- − make watch-js
- − make dep
- − make dep-js
- − npm ci
- − npm rebuild --ignore-scripts=false <pkg>
- − npm rebuild
- − make docker-build
- − docker compose up
- − make terminal
- − make test
- − make test-go
- − make test-js
- − make test-short
- − make vitest-watch
- − make vitest-coverage
- − make reset-testdb
- − make test-pkg
- − make test-api
- − make test-entity
- − make test-commands
- − make test-photoprism
- − make test-ai
- − make fmt
- − make fmt-go
- − make fmt-js
- − make fmt-swag
- − make lint-go
- + make fmt-go swag-fmt swag
- + make swag-json
- + go test ./internal/api -run Cluster -count=1
- make swag
Section tags
3 shared · 8 only in A · 1 only in B- − build
- − lint-format
- − architecture
- − types
- − git-pr
- − database
- − do-not
- − agent-behaviour
- + testing-strategy
- test
- code-style
- api
Line diff
photoprism/photoprism · .claude/CLAUDE.md
@@ −1 @@
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Detailed rules are in `.claude/rules/*.md` files organized by topic.
4
5## Build Commands
6
7Run `make help` for an overview of the most common targets, and `make list` to list all of them. Key commands:
8
9**Backend (Go):**
10- `make build-go` — build the `photoprism` binary (develop mode)
11- `make build-all` — build backend + frontend
12- `go build ./...` — compile all Go packages
13
14**Frontend (Vue 3):**
15- `make build-js` — production build of the frontend
16- `make watch-js` — watch mode for frontend development (Ctrl+C to stop)
17
18**Dependencies:**
19- `make dep` — install all dependencies (TensorFlow models, ONNX models, JS packages)
20- `make dep-js` — install JS dependencies only (`npm ci`). The `photoprism/develop` image and the repo `Makefile` both set `NPM_CONFIG_IGNORE_SCRIPTS=true`, so install scripts are skipped automatically; when running npm directly in an env without that default, pass `--ignore-scripts`. Rebuild native addons with `npm rebuild --ignore-scripts=false <pkg>` — a bare `npm rebuild` no-ops wherever the env default is active.
21
22**Docker dev environment:**
23- `make docker-build` — build local Docker image
24- `docker compose up` — start dev environment (app at http://localhost:2342/)
25- `make terminal` — open shell in dev container
26
27## Testing
28
29**Run all tests:**
30- `make test` — runs both JS and Go tests
31- `make test-go` — all Go tests (slow, ~20 min)
32- `make test-js` — frontend unit tests (Vitest)
33- `make test-short` — short Go tests in parallel (~5 min)
34
35**Run targeted Go tests:**
36```bash
37go test ./internal/api -run 'TestFunctionName' -count=1
38go test ./internal/photoprism -run 'TestMediaFile_' -count=1
39go test ./internal/entity/... -count=1 -tags="slow,develop"
40```
41
42**Run targeted JS tests:**
43- `make vitest-watch` — Vitest in watch mode
44- `make vitest-coverage` — Vitest with coverage report
45
46**Reset test databases before running Go tests:**
47- `make reset-testdb` — clears SQLite test DBs and MariaDB testdb
48
49**Subset targets:** `make test-pkg`, `make test-api`, `make test-entity`, `make test-commands`, `make test-photoprism`, `make test-ai`
50
51## Formatting & Linting
52
53Available targets: `make fmt` (everything), `make fmt-go`, `make fmt-js`, `make fmt-swag` / `make swag` (Swagger), `make lint-go`, `make lint-js`. Detailed conventions live in `.claude/rules/go-code-style.md` and `.claude/rules/frontend-rules.md`.
54
55When creating or editing shell scripts, run `shellcheck <file>` and resolve warnings. When editing Markdown files that contain tables, format them with `npx --yes markdown-table-formatter <filename>`.
56
57The curated `make help` overviews are maintained by hand in a `HELP_TEXT` block per Makefile. After renaming or removing a target, run `make check-make-help` (also part of `make lint`) to confirm that no overview still advertises it.
58
59## Continuous Integration
60
61**GitHub Actions is not enabled for this repository.** The workflow files under `.github/workflows/` do not execute, so pushes and pull requests produce no check runs. Treat them as dormant configuration: do not diagnose the absence of runs as a broken workflow, do not propose enabling Actions, and do not add workflows or bot configuration that assumes they will run. Ask a maintainer before changing anything under `.github/workflows/`.
62
63The `make` targets above are the authoritative build, format, and test gate — run them locally and report the output rather than relying on a hosted runner.
64
65## Schema Migrations
66
67If a change touches database schema, check migrations:
68```bash
69go run cmd/photoprism/photoprism.go migrations ls
70go run cmd/photoprism/photoprism.go migrations run
71# or via Makefile:
72make migrate
73```
74
75Migration files live in `internal/entity/migrate/`.
76
77## Architecture Overview
78
79PhotoPrism is a self-hosted photo management app. The backend is Go, the frontend is Vue 3 + Vuetify 3, and the database is MariaDB or SQLite (via GORM).
80
81### Backend (`internal/`, `pkg/`, `cmd/`)
82
83| Package | Purpose |
84|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
85| `internal/photoprism` | **Core application logic**: indexing originals, metadata extraction, thumbnail generation, import/stacking, converter orchestration (FFmpeg/ImageMagick/ExifTool). Entry point for workers and CLI. |
86| `internal/entity` | **Database models** (GORM): Photo, File, Album, Label, Face, User, Session, etc. Contains fixtures for tests and migration helpers. |
87| `internal/entity/query` | Database query helpers used by the API and core packages. |
88| `internal/api` | **REST API handlers** (Gin): thin handlers that validate input, enforce ACL/auth, delegate to services. Annotated with Swagger comments. |
89| `internal/server` | HTTP server setup, routing (Gin engine), WebDAV, static assets, middleware wiring. Routes are registered in `routes.go`. |
90| `internal/config` | Application configuration: CLI flags, env vars, client config sent to the frontend. |
91| `internal/workers` | Background workers: indexing scheduler, metadata sync, sharing, backup, vision jobs. |
92| `internal/commands` | CLI command implementations (`github.com/urfave/cli/v2`). |
93| `internal/auth` | Authentication: ACL (`auth/acl`), JWT (`auth/jwt`), OIDC (`auth/oidc`), session management. |
94| `internal/form` | Request form/binding structs for the API layer. |
95| `internal/meta` | Metadata extraction from EXIF, XMP, JSON sidecars. |
96| `internal/ffmpeg` | FFmpeg/transcoding helpers. |
97| `internal/thumb` | Thumbnail generation helpers. |
98| `internal/ai` | AI/vision model integration (TensorFlow, ONNX). |
99| `internal/service` | Services: maps geocoding, hub (membership), cluster, WebDAV client, CIDR helpers. |
100| `internal/event` | Event bus for structured logging and audit events. |
101| `pkg/` | Standalone, reusable packages: `fs`, `geo`, `media`, `txt`, `clean`, `rnd`, `i18n`, `http`, `time`, etc. No dependency on `internal/`. |
102
103**Request flow:** HTTP request → Gin middleware (auth, rate limiting) → `internal/api` handler → `internal/photoprism` or `internal/entity` → response.
104
105**Audit logging convention** (`event.AuditInfo/Warn/Err`): slices must follow the pattern **Who → What → Outcome**:
106- Who: `ClientIP(c)` + actor context (`"session %s"`, `"user %s"`)
107- What: resource constant + action segments
108- Outcome: single token like `status.Succeeded`, `status.Failed`, `status.Denied`, `status.Error(err)`
109
110### Frontend (`frontend/`)
111
112Vue 3 app using the Options API and Vuetify 3.
113
114| Directory | Purpose |
115|---------------------------|-------------------------------------------------------------------------------------------------|
116| `frontend/src/model/` | Client-side models mirroring API responses (Photo, Album, File, User, etc.) |
117| `frontend/src/app/` | App bootstrap, routing (`routes.js`), and the `$session` reactive singleton |
118| `frontend/src/page/` | Page-level components |
119| `frontend/src/component/` | Reusable UI components |
120| `frontend/src/common/` | Shared utilities, the API client (`$api`), and reactive singletons (`$config`, `$view`, `$log`) |
121| `frontend/src/locales/` | i18n translation files |
122| `frontend/tests/` | Vitest unit tests + TestCafe acceptance tests |
123
124State management uses reactive singleton modules in `src/common/` and `src/app/`, not Vuex or Pinia. Frontend code-style, formatting, testing, translation, and Playwright rules live in `.claude/rules/frontend-rules.md`.
125
126### API Conventions
127
128- REST API v1 base path: `/api/v1/` (configured via `conf.BaseUri()`)
129- Authentication: Bearer token (`Authorization` header) or `X-Auth-Token` header
130- Pagination: `count`, `offset`, `limit` parameters (default 100, max 1000)
131- After adding/changing API handlers, regenerate Swagger docs: `make fmt-go swag-fmt swag`
132- New routes must be registered in `internal/server/routes.go`
133
134### Config & Flags
135
136Verify config option names before using them:
137```bash
138./photoprism --help
139./photoprism show config-options
140./photoprism show config-yaml
141```
142
143### Verify Before Propagating
144
145Before promoting a claim from `CLAUDE.md`, `AGENTS.md`, a memory entry, or another spec into a new rule, spec, code comment, or commit message, verify it against the current code (grep imports, list directories, read the cited file). Stale documentation silently turns into stale rules and stale specs that future sessions will trust. When the claim names a package, function, file, or framework, the cost of one grep is much smaller than the cost of repeating an error across multiple files.
146
147### Detailed Rules
148
149Topic-specific conventions live under `.claude/rules/` and are loaded alongside this file:
150
151- `code-comments.md` — shared JS/Go doc comment rules (length cap, what to omit); referenced by both style files.
152- `go-code-style.md`, `go-testing.md` — Go style, package boundaries, test patterns, fixtures.
153- `frontend-rules.md` — JS/Vue code style, formatting, dependencies, tests, Playwright, translations.
154- `commit-and-docs-style.md` — commit-message format, GitHub issue templates, spec heading style.
155- `safety-and-security.md` — Git/data safety, destructive commands, file I/O and archive-extraction policies, HTTP download helpers.
156- `api-and-config.md`, `cluster-operations.md`, `import-index-download.md`, `build-and-runtime.md`, `sources-of-truth.md` — domain-specific guidance.
157
photoprism/photoprism · internal/api/AGENTS.md
@@ +1 @@
1# API Guidelines
2
3**Last Updated:** April 9, 2026
4
5## Handler Conventions
6
7- Reuse limiter stacks such as `limiter.Auth` and `limiter.Login`, and use `limiter.AbortJSON` for `429` responses.
8- Lean on `api.ClientIP`, `header.BearerToken`, and the shared `Abort*` helpers instead of duplicating request parsing.
9- Compare secrets in constant time and set `Cache-Control: no-store` on sensitive responses.
10- Register routes in `internal/server/routes.go`.
11- New list endpoints should default to `count=100`, cap at `1000`, require `offset >= 0`, and document their parameters explicitly.
12- When a test or fixture needs portal mode, set `PHOTOPRISM_NODE_ROLE=portal` together with `PHOTOPRISM_JOIN_TOKEN`.
13
14## Roles, Scopes & Sessions
15
16- Map user roles through `acl.ParseRole(s)` and `acl.UserRoles[...]`; map client roles through `acl.ClientRoles[...]`.
17- Treat `RoleAliasNone` (`none`) and the empty string as `RoleNone`; default unknown client roles to `RoleClient`.
18- When checking JWT or client scopes, use `acl.ScopePermits` and `acl.ScopeAttrPermits` instead of handwritten parsing.
19- Use `AuthenticateAdmin`, `AuthenticateUser`, or `OAuthToken` helpers in tests rather than building auth flows manually.
20- Build client-session requests with `entity.AddClientSession(..., authn.GrantClientCredentials, nil)` and `AuthenticatedRequest(...)`.
21- Admin sessions may see `AdvertiseUrl` and `Database`; client and user sessions must not. `SiteUrl` and the client `storageNamespace` derived from it are safe to expose.
22
23## Swagger & API Tests
24
25- Annotate only routed handlers in `internal/api/*.go`; use full `/api/v1/...` paths and skip helper functions.
26- Regenerate API docs with `make fmt-go swag-fmt swag` or `make swag-json`; `make swag` may fetch modules, so confirm network access first.
27- While iterating, prefer focused runs such as `go test ./internal/api -run Cluster -count=1`.
28- Isolate config paths with `t.TempDir()` and reuse `NewConfig`, `CliTestContext`, and `NewApiTest()` helpers.
29- For negative permission checks, prefer OAuth client tokens over non-admin user fixtures.
30- Register `CreateSession(router)` only once per test router; a second registration panics on duplicate routes.
31
32
@@ −1 +1 @@
1−# CLAUDE.md
1+# API Guidelines
22
3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Detailed rules are in `.claude/rules/*.md` files organized by topic.
3+**Last Updated:** April 9, 2026
44
5−## Build Commands
5+## Handler Conventions
66
7−Run `make help` for an overview of the most common targets, and `make list` to list all of them. Key commands:
7+- Reuse limiter stacks such as `limiter.Auth` and `limiter.Login`, and use `limiter.AbortJSON` for `429` responses.
8+- Lean on `api.ClientIP`, `header.BearerToken`, and the shared `Abort*` helpers instead of duplicating request parsing.
9+- Compare secrets in constant time and set `Cache-Control: no-store` on sensitive responses.
10+- Register routes in `internal/server/routes.go`.
11+- New list endpoints should default to `count=100`, cap at `1000`, require `offset >= 0`, and document their parameters explicitly.
12+- When a test or fixture needs portal mode, set `PHOTOPRISM_NODE_ROLE=portal` together with `PHOTOPRISM_JOIN_TOKEN`.
813
9−**Backend (Go):**
10−- `make build-go` — build the `photoprism` binary (develop mode)
11−- `make build-all` — build backend + frontend
12−- `go build ./...` — compile all Go packages
14+## Roles, Scopes & Sessions
1315
14−**Frontend (Vue 3):**
15−- `make build-js` — production build of the frontend
16−- `make watch-js` — watch mode for frontend development (Ctrl+C to stop)
16+- Map user roles through `acl.ParseRole(s)` and `acl.UserRoles[...]`; map client roles through `acl.ClientRoles[...]`.
17+- Treat `RoleAliasNone` (`none`) and the empty string as `RoleNone`; default unknown client roles to `RoleClient`.
18+- When checking JWT or client scopes, use `acl.ScopePermits` and `acl.ScopeAttrPermits` instead of handwritten parsing.
19+- Use `AuthenticateAdmin`, `AuthenticateUser`, or `OAuthToken` helpers in tests rather than building auth flows manually.
20+- Build client-session requests with `entity.AddClientSession(..., authn.GrantClientCredentials, nil)` and `AuthenticatedRequest(...)`.
21+- Admin sessions may see `AdvertiseUrl` and `Database`; client and user sessions must not. `SiteUrl` and the client `storageNamespace` derived from it are safe to expose.
1722
18−**Dependencies:**
19−- `make dep` — install all dependencies (TensorFlow models, ONNX models, JS packages)
20−- `make dep-js` — install JS dependencies only (`npm ci`). The `photoprism/develop` image and the repo `Makefile` both set `NPM_CONFIG_IGNORE_SCRIPTS=true`, so install scripts are skipped automatically; when running npm directly in an env without that default, pass `--ignore-scripts`. Rebuild native addons with `npm rebuild --ignore-scripts=false <pkg>` — a bare `npm rebuild` no-ops wherever the env default is active.
23+## Swagger & API Tests
2124
22−**Docker dev environment:**
23−- `make docker-build` — build local Docker image
24−- `docker compose up` — start dev environment (app at http://localhost:2342/)
25−- `make terminal` — open shell in dev container
25+- Annotate only routed handlers in `internal/api/*.go`; use full `/api/v1/...` paths and skip helper functions.
26+- Regenerate API docs with `make fmt-go swag-fmt swag` or `make swag-json`; `make swag` may fetch modules, so confirm network access first.
27+- While iterating, prefer focused runs such as `go test ./internal/api -run Cluster -count=1`.
28+- Isolate config paths with `t.TempDir()` and reuse `NewConfig`, `CliTestContext`, and `NewApiTest()` helpers.
29+- For negative permission checks, prefer OAuth client tokens over non-admin user fixtures.
30+- Register `CreateSession(router)` only once per test router; a second registration panics on duplicate routes.
2631
27−## Testing
28−
29−**Run all tests:**
30−- `make test` — runs both JS and Go tests
31−- `make test-go` — all Go tests (slow, ~20 min)
32−- `make test-js` — frontend unit tests (Vitest)
33−- `make test-short` — short Go tests in parallel (~5 min)
34−
35−**Run targeted Go tests:**
36−```bash
37−go test ./internal/api -run 'TestFunctionName' -count=1
38−go test ./internal/photoprism -run 'TestMediaFile_' -count=1
39−go test ./internal/entity/... -count=1 -tags="slow,develop"
40−```
41−
42−**Run targeted JS tests:**
43−- `make vitest-watch` — Vitest in watch mode
44−- `make vitest-coverage` — Vitest with coverage report
45−
46−**Reset test databases before running Go tests:**
47−- `make reset-testdb` — clears SQLite test DBs and MariaDB testdb
48−
49−**Subset targets:** `make test-pkg`, `make test-api`, `make test-entity`, `make test-commands`, `make test-photoprism`, `make test-ai`
50−
51−## Formatting & Linting
52−
53−Available targets: `make fmt` (everything), `make fmt-go`, `make fmt-js`, `make fmt-swag` / `make swag` (Swagger), `make lint-go`, `make lint-js`. Detailed conventions live in `.claude/rules/go-code-style.md` and `.claude/rules/frontend-rules.md`.
54−
55−When creating or editing shell scripts, run `shellcheck <file>` and resolve warnings. When editing Markdown files that contain tables, format them with `npx --yes markdown-table-formatter <filename>`.
56−
57−The curated `make help` overviews are maintained by hand in a `HELP_TEXT` block per Makefile. After renaming or removing a target, run `make check-make-help` (also part of `make lint`) to confirm that no overview still advertises it.
58−
59−## Continuous Integration
60−
61−**GitHub Actions is not enabled for this repository.** The workflow files under `.github/workflows/` do not execute, so pushes and pull requests produce no check runs. Treat them as dormant configuration: do not diagnose the absence of runs as a broken workflow, do not propose enabling Actions, and do not add workflows or bot configuration that assumes they will run. Ask a maintainer before changing anything under `.github/workflows/`.
62−
63−The `make` targets above are the authoritative build, format, and test gate — run them locally and report the output rather than relying on a hosted runner.
64−
65−## Schema Migrations
66−
67−If a change touches database schema, check migrations:
68−```bash
69−go run cmd/photoprism/photoprism.go migrations ls
70−go run cmd/photoprism/photoprism.go migrations run
71−# or via Makefile:
72−make migrate
73−```
74−
75−Migration files live in `internal/entity/migrate/`.
76−
77−## Architecture Overview
78−
79−PhotoPrism is a self-hosted photo management app. The backend is Go, the frontend is Vue 3 + Vuetify 3, and the database is MariaDB or SQLite (via GORM).
80−
81−### Backend (`internal/`, `pkg/`, `cmd/`)
82−
83−| Package | Purpose |
84−|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
85−| `internal/photoprism` | **Core application logic**: indexing originals, metadata extraction, thumbnail generation, import/stacking, converter orchestration (FFmpeg/ImageMagick/ExifTool). Entry point for workers and CLI. |
86−| `internal/entity` | **Database models** (GORM): Photo, File, Album, Label, Face, User, Session, etc. Contains fixtures for tests and migration helpers. |
87−| `internal/entity/query` | Database query helpers used by the API and core packages. |
88−| `internal/api` | **REST API handlers** (Gin): thin handlers that validate input, enforce ACL/auth, delegate to services. Annotated with Swagger comments. |
89−| `internal/server` | HTTP server setup, routing (Gin engine), WebDAV, static assets, middleware wiring. Routes are registered in `routes.go`. |
90−| `internal/config` | Application configuration: CLI flags, env vars, client config sent to the frontend. |
91−| `internal/workers` | Background workers: indexing scheduler, metadata sync, sharing, backup, vision jobs. |
92−| `internal/commands` | CLI command implementations (`github.com/urfave/cli/v2`). |
93−| `internal/auth` | Authentication: ACL (`auth/acl`), JWT (`auth/jwt`), OIDC (`auth/oidc`), session management. |
94−| `internal/form` | Request form/binding structs for the API layer. |
95−| `internal/meta` | Metadata extraction from EXIF, XMP, JSON sidecars. |
96−| `internal/ffmpeg` | FFmpeg/transcoding helpers. |
97−| `internal/thumb` | Thumbnail generation helpers. |
98−| `internal/ai` | AI/vision model integration (TensorFlow, ONNX). |
99−| `internal/service` | Services: maps geocoding, hub (membership), cluster, WebDAV client, CIDR helpers. |
100−| `internal/event` | Event bus for structured logging and audit events. |
101−| `pkg/` | Standalone, reusable packages: `fs`, `geo`, `media`, `txt`, `clean`, `rnd`, `i18n`, `http`, `time`, etc. No dependency on `internal/`. |
102−
103−**Request flow:** HTTP request → Gin middleware (auth, rate limiting) → `internal/api` handler → `internal/photoprism` or `internal/entity` → response.
104−
105−**Audit logging convention** (`event.AuditInfo/Warn/Err`): slices must follow the pattern **Who → What → Outcome**:
106−- Who: `ClientIP(c)` + actor context (`"session %s"`, `"user %s"`)
107−- What: resource constant + action segments
108−- Outcome: single token like `status.Succeeded`, `status.Failed`, `status.Denied`, `status.Error(err)`
109−
110−### Frontend (`frontend/`)
111−
112−Vue 3 app using the Options API and Vuetify 3.
113−
114−| Directory | Purpose |
115−|---------------------------|-------------------------------------------------------------------------------------------------|
116−| `frontend/src/model/` | Client-side models mirroring API responses (Photo, Album, File, User, etc.) |
117−| `frontend/src/app/` | App bootstrap, routing (`routes.js`), and the `$session` reactive singleton |
118−| `frontend/src/page/` | Page-level components |
119−| `frontend/src/component/` | Reusable UI components |
120−| `frontend/src/common/` | Shared utilities, the API client (`$api`), and reactive singletons (`$config`, `$view`, `$log`) |
121−| `frontend/src/locales/` | i18n translation files |
122−| `frontend/tests/` | Vitest unit tests + TestCafe acceptance tests |
123−
124−State management uses reactive singleton modules in `src/common/` and `src/app/`, not Vuex or Pinia. Frontend code-style, formatting, testing, translation, and Playwright rules live in `.claude/rules/frontend-rules.md`.
125−
126−### API Conventions
127−
128−- REST API v1 base path: `/api/v1/` (configured via `conf.BaseUri()`)
129−- Authentication: Bearer token (`Authorization` header) or `X-Auth-Token` header
130−- Pagination: `count`, `offset`, `limit` parameters (default 100, max 1000)
131−- After adding/changing API handlers, regenerate Swagger docs: `make fmt-go swag-fmt swag`
132−- New routes must be registered in `internal/server/routes.go`
133−
134−### Config & Flags
135−
136−Verify config option names before using them:
137−```bash
138−./photoprism --help
139−./photoprism show config-options
140−./photoprism show config-yaml
141−```
142−
143−### Verify Before Propagating
144−
145−Before promoting a claim from `CLAUDE.md`, `AGENTS.md`, a memory entry, or another spec into a new rule, spec, code comment, or commit message, verify it against the current code (grep imports, list directories, read the cited file). Stale documentation silently turns into stale rules and stale specs that future sessions will trust. When the claim names a package, function, file, or framework, the cost of one grep is much smaller than the cost of repeating an error across multiple files.
146−
147−### Detailed Rules
148−
149−Topic-specific conventions live under `.claude/rules/` and are loaded alongside this file:
150−
151−- `code-comments.md` — shared JS/Go doc comment rules (length cap, what to omit); referenced by both style files.
152−- `go-code-style.md`, `go-testing.md` — Go style, package boundaries, test patterns, fixtures.
153−- `frontend-rules.md` — JS/Vue code style, formatting, dependencies, tests, Playwright, translations.
154−- `commit-and-docs-style.md` — commit-message format, GitHub issue templates, spec heading style.
155−- `safety-and-security.md` — Git/data safety, destructive commands, file I/O and archive-extraction policies, HTTP download helpers.
156−- `api-and-config.md`, `cluster-operations.md`, `import-index-download.md`, `build-and-runtime.md`, `sources-of-truth.md` — domain-specific guidance.
15732
