Comparison

A · CLAUDE.md · photoprism/photoprism B · Copilot instructions · photoprism/photoprism

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	14	5	0%
Commands	3	37	3	7%
Section tags	4	7	0	36%

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
+ Frontend Instructions (Vue 3)
+ Style
+ State & Data
+ Tests
+ Translations

Commands

3 shared · 37 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-short
− 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-swag
− make swag
− make lint-go
+ make lint-js
+ npx vitest run
+ make gettext-extract
make test-js
make vitest-watch
make fmt-js

Section tags

4 shared · 7 only in A · 0 only in B

− build
− architecture
− types
− git-pr
− database
− api
− do-not
test
lint-format
code-style
agent-behaviour

Line diff

+23 added−145 removed12 unchanged7.6% identical

photoprism/photoprism · .claude/CLAUDE.md

@@ −1 @@

1# CLAUDE.md

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.

5## Build Commands

7Run `make help` for an overview of the most common targets, and `make list` to list all of them. Key commands:

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**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)

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.

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

27## Testing

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)

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```

42**Run targeted JS tests:**

43- `make vitest-watch` — Vitest in watch mode

44- `make vitest-coverage` — Vitest with coverage report

46**Reset test databases before running Go tests:**

47- `make reset-testdb` — clears SQLite test DBs and MariaDB testdb

49**Subset targets:** `make test-pkg`, `make test-api`, `make test-entity`, `make test-commands`, `make test-photoprism`, `make test-ai`

51## Formatting & Linting

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`.

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>`.

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.

59## Continuous Integration

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/`.

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.

65## Schema Migrations

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```

75Migration files live in `internal/entity/migrate/`.

77## Architecture Overview

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).

81### Backend (`internal/`, `pkg/`, `cmd/`)

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/frontend.instructions.md

@@ +1 @@

1---

2applyTo: "frontend/**"

3---

5# Frontend Instructions (Vue 3)

7**Last Updated:** July 28, 2026

9Detailed rules live in `frontend/AGENTS.md`; dependency pins and the override layer are documented in `frontend/README.md`.

11## Style

13- Options API only. Do not introduce TypeScript (no `.ts` files, no `<script lang="ts">`), the Composition API, or `<script setup>`.

14- Keep the SFC block order `<template>` → `<script>` → `<style>`, and prefer existing components and Vuetify defaults over new ones.

15- Every method, computed property, and watcher that is not a trivial getter needs a compact doc comment.

16- Run `make fmt-js` and `make lint-js`. ESLint owns JS and Vue, Prettier owns CSS/SCSS/SASS only, and ESLint no longer invokes Prettier — do not reflow JS to satisfy Prettier.

18## State & Data

20- Shared state lives in reactive singleton modules under `src/common/` and `src/app/`, for example `common/config.js` and `app/session.js`. Extend an existing singleton or add a new one alongside its peers; do not propose Vuex or Pinia.

21- Route entity mutations through the model methods in `src/model/` instead of calling `$api` directly from components.

22- Avoid unnecessary reactivity and re-renders. Version pins without a caret in `frontend/package.json` are intentional — check `frontend/README.md` before changing one, and justify any new dependency.

24## Tests

26- New functions, including helpers, and new components need Vitest coverage; update the existing tests when behavior changes.

27- Run the tests with `make test-js` (watch mode: `make vitest-watch`). Do not suggest a bare `npx vitest run`: the npm script sets `TZ`, `BUILD_ENV`, `NODE_ENV`, and `BABEL_ENV`, and dozens of component and date tests fail spuriously without them.

29## Translations

31- Every user-visible string goes through `$gettext`; never hardcode a locale string. Standardized technical identifiers such as `Client ID`, `OIDC`, and `UUID` stay literal.

32- Tooltips, labels, buttons, and short imperative phrases use Title Case; running prose, full sentences, and notifications use sentence case.

33- A native void element (`<img>`, `<br>`, `<input>`) silently drops every following bare `{{ $gettext(...) }}` from the catalog — wrap the interpolation in an element such as `<span>`. `make lint-js` flags this pattern.

34- New strings only reach the translators once `make gettext-extract` has run. Land the regenerated catalogs as a separate commit rather than inside a feature commit.

@@ −1 +1 @@

1−# CLAUDE.md

1+---

2+applyTo: "frontend/**"

3+---

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+# Frontend Instructions (Vue 3)

5−## Build Commands

7+**Last Updated:** July 28, 2026

7−Run `make help` for an overview of the most common targets, and `make list` to list all of them. Key commands:

9+Detailed rules live in `frontend/AGENTS.md`; dependency pins and the override layer are documented in `frontend/README.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+- Options API only. Do not introduce TypeScript (no `.ts` files, no `<script lang="ts">`), the Composition API, or `<script setup>`.

14+- Keep the SFC block order `<template>` → `<script>` → `<style>`, and prefer existing components and Vuetify defaults over new ones.

15+- Every method, computed property, and watcher that is not a trivial getter needs a compact doc comment.

16+- Run `make fmt-js` and `make lint-js`. ESLint owns JS and Vue, Prettier owns CSS/SCSS/SASS only, and ESLint no longer invokes Prettier — do not reflow JS to satisfy Prettier.

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+## State & Data

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+- Shared state lives in reactive singleton modules under `src/common/` and `src/app/`, for example `common/config.js` and `app/session.js`. Extend an existing singleton or add a new one alongside its peers; do not propose Vuex or Pinia.

21+- Route entity mutations through the model methods in `src/model/` instead of calling `$api` directly from components.

22+- Avoid unnecessary reactivity and re-renders. Version pins without a caret in `frontend/package.json` are intentional — check `frontend/README.md` before changing one, and justify any new dependency.

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+- New functions, including helpers, and new components need Vitest coverage; update the existing tests when behavior changes.

27+- Run the tests with `make test-js` (watch mode: `make vitest-watch`). Do not suggest a bare `npx vitest run`: the npm script sets `TZ`, `BUILD_ENV`, `NODE_ENV`, and `BABEL_ENV`, and dozens of component and date tests fail spuriously without them.

3428

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−```

29+## Translations

4130

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.

31+- Every user-visible string goes through `$gettext`; never hardcode a locale string. Standardized technical identifiers such as `Client ID`, `OIDC`, and `UUID` stay literal.

32+- Tooltips, labels, buttons, and short imperative phrases use Title Case; running prose, full sentences, and notifications use sentence case.

33+- A native void element (`<img>`, `<br>`, `<input>`) silently drops every following bare `{{ $gettext(...) }}` from the catalog — wrap the interpolation in an element such as `<span>`. `make lint-js` flags this pattern.

34+- New strings only reach the translators once `make gettext-extract` has run. Land the regenerated catalogs as a separate commit rather than inside a feature commit.

15735