| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 14 | 5 | 0% |
| Commands | 5 | 35 | 2 | 12% |
| Section tags | 8 | 3 | 0 | 73% |
What each file covers
Sections
0 shared · 14 only in A · 5 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
- + Backend Instructions (Go)
- + Style
- + Package Boundaries & Filesystem
- + Tests
- + API, Config & Schema
Commands
5 shared · 35 only in A · 2 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-js
- − make vitest-watch
- − make vitest-coverage
- − make test-pkg
- − make test-api
- − make test-entity
- − make test-commands
- − make test-photoprism
- − make test-ai
- − make fmt
- − make fmt-js
- − make fmt-swag
- − make swag
- + go test ./internal/<pkg> -run '<TestName>' -count=1
- + make fmt-go swag-fmt swag
- make test-go
- make test-short
- make reset-testdb
- make fmt-go
- make lint-go
Section tags
8 shared · 3 only in A · 0 only in B- − build
- − architecture
- − git-pr
- test
- lint-format
- code-style
- types
- database
- api
- do-not
- agent-behaviour
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 · .github/instructions/backend.instructions.md
@@ +1 @@
1---
2applyTo: "internal/**,pkg/**,cmd/**"
3---
4
5# Backend Instructions (Go)
6
7**Last Updated:** July 28, 2026
8
9Package-level rules live in the nearest `AGENTS.md`, for example `internal/AGENTS.md`, `internal/api/AGENTS.md`, `internal/config/AGENTS.md`, `internal/commands/AGENTS.md`, and `pkg/AGENTS.md`.
10
11## Style
12
13- Keep functions small and focused, wrap errors with context, and keep the exported surface minimal.
14- Doc comments begin with the name of the identifier and stay compact: one line for the "what", plus a line or two only when the "why" cannot be inferred from the code. No issue numbers, no change history.
15- Every package contains a `<package>.go` file with the license header and a short package comment.
16- Run `make fmt-go` (gofmt + goimports) and `make lint-go` after edits; never hand-format indentation.
17
18## Package Boundaries & Filesystem
19
20- `pkg/*` must not import from `internal/*`. Code that needs config, entity, or database access belongs under `internal/`.
21- Use the permission constants from `pkg/fs` (`fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`) instead of literal file modes, and alias the standard library as `iofs "io/fs"` where both are needed.
22- Use `filepath.Join` for filesystem paths and reserve `path.Join` for URL paths.
23
24## Tests
25
26- Every added function, including unexported helpers and helpers extracted by a refactor, needs a matching `Test<Name>` in a sibling `*_test.go`, with at least a success and a failure case.
27- Group cases with `t.Run(...)` and PascalCase names such as `Success` or `InvalidRequest`.
28- Prefer focused runs — `go test ./internal/<pkg> -run '<TestName>' -count=1` — over `make test-go`, which takes about 20 minutes. `make test-short` is the fast full pass, and `make reset-testdb` resets the test databases.
29
30## API, Config & Schema
31
32- Keep handlers thin, register new routes in `internal/server/routes.go`, and regenerate the documentation with `make fmt-go swag-fmt swag`. Never edit `internal/api/swagger.json` by hand.
33- Declare new config options in `internal/config/options.go`, register them in `internal/config/flags.go`, and expose a getter. Confirm names with `photoprism --help`, `photoprism show config-options`, or `photoprism show config-yaml` before suggesting them.
34- Schema changes need a migration in `internal/entity/migrate/`; verify with `photoprism migrations ls` and `photoprism migrations run`.
35
@@ −1 +1 @@
1−# CLAUDE.md
1+---
2+applyTo: "internal/**,pkg/**,cmd/**"
3+---
24
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.
5+# Backend Instructions (Go)
46
5−## Build Commands
7+**Last Updated:** July 28, 2026
68
7−Run `make help` for an overview of the most common targets, and `make list` to list all of them. Key commands:
9+Package-level rules live in the nearest `AGENTS.md`, for example `internal/AGENTS.md`, `internal/api/AGENTS.md`, `internal/config/AGENTS.md`, `internal/commands/AGENTS.md`, and `pkg/AGENTS.md`.
810
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
11+## Style
1312
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)
13+- Keep functions small and focused, wrap errors with context, and keep the exported surface minimal.
14+- Doc comments begin with the name of the identifier and stay compact: one line for the "what", plus a line or two only when the "why" cannot be inferred from the code. No issue numbers, no change history.
15+- Every package contains a `<package>.go` file with the license header and a short package comment.
16+- Run `make fmt-go` (gofmt + goimports) and `make lint-go` after edits; never hand-format indentation.
1717
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.
18+## Package Boundaries & Filesystem
2119
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
20+- `pkg/*` must not import from `internal/*`. Code that needs config, entity, or database access belongs under `internal/`.
21+- Use the permission constants from `pkg/fs` (`fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`) instead of literal file modes, and alias the standard library as `iofs "io/fs"` where both are needed.
22+- Use `filepath.Join` for filesystem paths and reserve `path.Join` for URL paths.
2623
27−## Testing
24+## Tests
2825
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)
26+- Every added function, including unexported helpers and helpers extracted by a refactor, needs a matching `Test<Name>` in a sibling `*_test.go`, with at least a success and a failure case.
27+- Group cases with `t.Run(...)` and PascalCase names such as `Success` or `InvalidRequest`.
28+- Prefer focused runs — `go test ./internal/<pkg> -run '<TestName>' -count=1` — over `make test-go`, which takes about 20 minutes. `make test-short` is the fast full pass, and `make reset-testdb` resets the test databases.
3429
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−```
30+## API, Config & Schema
4131
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.
32+- Keep handlers thin, register new routes in `internal/server/routes.go`, and regenerate the documentation with `make fmt-go swag-fmt swag`. Never edit `internal/api/swagger.json` by hand.
33+- Declare new config options in `internal/config/options.go`, register them in `internal/config/flags.go`, and expose a getter. Confirm names with `photoprism --help`, `photoprism show config-options`, or `photoprism show config-yaml` before suggesting them.
34+- Schema changes need a migration in `internal/entity/migrate/`; verify with `photoprism migrations ls` and `photoprism migrations run`.
15735
