| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 16 | 8 | 0% |
| Commands | 2 | 28 | 16 | 4% |
| Section tags | 4 | 8 | 1 | 31% |
What each file covers
Sections
0 shared · 16 only in A · 8 only in B- − PhotoPrism Repository Guidelines
- − Purpose
- − Sources of Truth
- − Subtree Guides
- − Local Agent Progress
- − Style Notes
- − Commit Messages
- − GitHub Issues
- − Specifications & Documentation
- − Safety & Data
- − Project Layout & Shared Rules
- − JS/Go Code Comments
- − Agent Runtime
- − Build, Format & Test
- − Continuous Integration
- − Container Image Builds
- + Frontend Guidelines
- + Dependencies & Pins
- + Frontend Linting & Test Entry Points
- + Templates, Session Bootstrap & Browser Baseline
- + Translations
- + Focus Management
- + Playwright MCP Usage
- + Frontend Test Gotchas
Commands
2 shared · 28 only in A · 16 only in B- − git status
- − git config
- − make fmt-go
- − npm exec --yes <agent> -- --help
- − npx <agent> ...
- − npm ci
- − npm install
- − make
- − npm rebuild --ignore-scripts=false <pkg>
- − npm rebuild
- − make help
- − make list
- − make docker-build
- − docker compose up
- − docker compose up -d
- − docker compose logs -f --tail=100 photoprism
- − docker compose exec photoprism ./photoprism help
- − docker compose exec -u "$(id -u):$(id -g)" photoprism <command>
- − make terminal
- − docker compose --profile=all down --remove-orphans
- − make down
- − make dep
- − make build-go
- − make watch-js
- − make test
- − make lint
- − make check-make-help
- − go test ./path/to/pkg -run Name -count=1
- + git log -p -S "<pkg>" -- frontend/package.json
- + npm install --ignore-scripts --no-audit --no-fund --no-update-notifier
- + make audit
- + make test-js
- + npm ls <pkg> --all
- + make -C frontend help
- + make -C frontend list
- + make vitest-watch
- + make vitest-coverage
- + make storage/acceptance
- + make acceptance-sqlite-restart
- + make wait-2
- + make acceptance-sqlite-stop
- + make gettext-extract
- + make -C plus gettext-extract
- + npx
- make notice
- make build-js
Section tags
4 shared · 8 only in A · 1 only in B- − build
- − lint-format
- − architecture
- − git-pr
- − security
- − do-not
- − agent-behaviour
- − docs
- + dependencies
- setup
- test
- code-style
- testing-strategy
Line diff
photoprism/photoprism · AGENTS.md
@@ −1 @@
1# PhotoPrism Repository Guidelines
2
3**Last Updated:** July 28, 2026
4
5## Purpose
6
7Entry point for agents and humans.
8
9## Sources of Truth
10
11- Makefile: https://github.com/photoprism/photoprism/blob/develop/Makefile
12- Setup guide: https://docs.photoprism.app/developer-guide/setup/
13- Test guide: https://docs.photoprism.app/developer-guide/tests/
14- Contributing: https://github.com/photoprism/photoprism/blob/develop/CONTRIBUTING.md
15- Security: https://github.com/photoprism/photoprism/blob/develop/SECURITY.md
16- REST API: https://docs.photoprism.dev/ and https://docs.photoprism.app/developer-guide/api/
17- Code maps: [`CODEMAP.md`](CODEMAP.md), [`frontend/CODEMAP.md`](frontend/CODEMAP.md)
18- Package docs: `README.md` files under `internal/`, `pkg/`, `frontend/`, and `frontend/src/`
19- Frontend dependency pins, override layer, and orphan-audit pattern: [`frontend/README.md`](frontend/README.md) (read before bumping any non-caret pin or adding/removing a top-level dep)
20- AI/Vision docs: [`internal/ai/face/README.md`](internal/ai/face/README.md), [`internal/ai/vision/README.md`](internal/ai/vision/README.md), [`internal/ai/vision/openai/README.md`](internal/ai/vision/openai/README.md), [`internal/ai/vision/ollama/README.md`](internal/ai/vision/ollama/README.md)
21- Glossary: [`GLOSSARY.md`](GLOSSARY.md)
22- When dependencies change, regenerate `NOTICE` files with `make notice`; do not edit `NOTICE` or `frontend/NOTICE` manually.
23
24## Subtree Guides
25
26- [`internal/AGENTS.md`](internal/AGENTS.md): internal Go rules.
27- [`internal/api/AGENTS.md`](internal/api/AGENTS.md): API rules.
28- [`internal/config/AGENTS.md`](internal/config/AGENTS.md): config rules.
29- [`internal/commands/AGENTS.md`](internal/commands/AGENTS.md): CLI rules.
30- [`internal/photoprism/AGENTS.md`](internal/photoprism/AGENTS.md): import and index rules.
31- [`internal/service/cluster/AGENTS.md`](internal/service/cluster/AGENTS.md): cluster rules.
32- [`frontend/AGENTS.md`](frontend/AGENTS.md): frontend rules.
33- [`pkg/AGENTS.md`](pkg/AGENTS.md): `pkg/*` security and test rules.
34
35Optional nested repositories such as `plus/`, `pro/`, `portal/`, and `specs/` may contain their own `AGENTS.md` files. When present, treat those files as additional directory-local guidance.
36
37## Local Agent Progress
38
39- Use `.agents/TODO.md` for actionable tasks and `.agents/DONE.md` for completed work.
40- These files are local workflow aids and may not exist in every workspace.
41
42## Style Notes
43
44### Commit Messages
45
46- Use concise imperative subjects with a one-word prefix, for example `Config: Add tests for "darktable-cli" path detection`.
47- Append issue or PR IDs when relevant.
48- Commit messages must not exceed 80 characters.
49
50### GitHub Issues
51
52- Titles MUST be concise, imperative, and start with one capitalized prefix plus `: `, for example `Search: Add filter for RAW image formats`.
53- Descriptions MUST begin with a one-sentence bold user story: `**As a <role>, I want <goal>, so that <outcome>.**`
54- Use level-3 Markdown headings for sections within issue descriptions, for example `### Acceptance Criteria`.
55- Follow with behavior, rationale, technical considerations, and constraints.
56- End with `- [ ]` checklist items for the acceptance criteria, each using `MUST`, `SHOULD`, or `MAY`.
57 - Keep the checklist current: once the work for a criterion is implemented **and verified**, mark it done (`- [x]`).
58 - Leave items that are unverified, not yet implemented, or skipped optional (`MAY`) enhancements unchecked.
59 - An issue is complete only when every `MUST` is checked; never tick a box on the strength of a plan alone or an unrun test.
60 - When referencing an issue from a commit that fulfills some of its criteria, update the matching boxes first.
61- Agents MUST create, edit, close, reopen, relabel, or otherwise modify GitHub issues only when explicitly requested by the user.
62
63### Specifications & Documentation
64
65- Markdown headings use a Chicago-style title case, with additional code- and path-aware normalization rules (see *Title Case rules* below). Always spell the product name as `PhotoPrism`.
66- Put option flags before positional arguments unless the command requires another order.
67- Use RFC 3339 UTC timestamps and valid ID, UID, and UUID examples in docs and tests.
68- The nested `specs/` repository may be absent. Do not add main-repo `Makefile` targets that depend on it; when present, you may run its tools manually.
69- Testing guides live at `specs/dev/backend-testing.md` and `specs/dev/frontend-testing.md`.
70- Do not read, analyze, or modify `specs/generated/`; refer humans to `specs/generated/README.md` when regeneration is needed.
71- Refresh `**Last Updated:**` when you change document contents, but leave it unchanged for whitespace-only or formatting-only edits.
72- Nested Git repositories may appear ignored; change into them before staging or committing updates.
73
74Title Case rules (Chicago-style, with code- and path-aware normalization):
75- Capitalize the first word, the first word after a colon, dash, or end punctuation, and all major words, including the second part of a hyphenated major word.
76- Lowercase only articles, short conjunctions, and short prepositions of three letters or fewer when they are not in one of those positions.
77- Preserve known acronyms (for example, API, CLI, HTTP, JSON) and slash-separated acronym groups (for example, CSV/TSV) as uppercase.
78- Preserve RFC 2119 / RFC 8174 normative keywords (MUST, SHOULD, MAY, SHALL, REQUIRED, RECOMMENDED, OPTIONAL) as uppercase when used in their normative sense.
79- Preserve inline code spans (`` `foo` ``), file paths (e.g. `docs/foo-bar.md`), and slash commands (e.g. `/grill-me`) verbatim; do not recase their contents.
80- Use `&` instead of `And`/`Or` in headings.
81
82## Safety & Data
83
84- If `git status` shows unexpected changes, assume a human may be editing; ask before using reset-style commands.
85- Do not run `git config` at either the global or repository level.
86- Do not run destructive commands against production data; prefer ephemeral volumes and test fixtures for acceptance tests.
87- Never commit secrets, local configurations, or cache files; use environment variables or a local `.env`.
88- Ensure `.env`, `.config`, `.local`, `.codex`, and `.gocache` are ignored in `.gitignore` and `.dockerignore`.
89- Prefer existing caches, workers, and batching strategies already referenced by the code and `Makefile`.
90- Consider CPU and memory impact; only suggest profiling or benchmarks when justified.
91- If anything here conflicts with the `Makefile` or the sources of truth, ask for clarification before proceeding.
92
93## Project Layout & Shared Rules
94
95- Backend: Go in `internal/`, `pkg/`, and `cmd/`, backed by MariaDB or SQLite.
96- Frontend: Vue 3 plus Vuetify 3 under `frontend/`.
97- Local dev and CI use Docker Compose; Traefik provides local TLS via `*.localssl.dev`.
98- Code in `pkg/*` must not import from `internal/*`. If you need config, entity, or DB access, add code under `internal/`.
99- Shared Go rules:
100 - After Go edits, run `make fmt-go` and keep `gofmt` tab indentation.
101 - Every added/modified Go function, including unexported helpers, must have focused test coverage in the corresponding `*_test.go` files; update existing tests or add new ones as needed.
102 - Every Go package must contain a root `<package>.go` file with the standard license header and a short package description comment.
103 - Use `pkg/fs` permission constants: `fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`, and `fs.ModeBackupFile`.
104 - When importing the stdlib `io/fs`, alias it to avoid collisions, for example `iofs "io/fs"` or `gofs "io/fs"`.
105 - Do not pass stdlib `io/fs` mode flags where permission bits are expected.
106 - Prefer `filepath.Join` for filesystem paths and `path.Join` only for URL paths.
107 - Normalize slash-based logical paths stored in DB, config, or API payloads with `clean.SlashPath(...)`.
108- Shared JS/Vue rules:
109 - Added/modified JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
110 - Added/modified Vue components should have component-test coverage, and existing component tests should be updated as needed when behavior changes.
111- When adding a metadata source such as `SrcOllama` or `SrcOpenAI`, update both `internal/entity/src.go` and `frontend/src/common/util.js` so backend and UI stay aligned.
112
113### JS/Go Code Comments
114
115A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher:
116- Keep comments **compact** and default to one line for "what" in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
117- Add 1-2 follow-up lines (`// …`) **only** if the "why" is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code. If readers can infer the "why" from the function body or a nearby line, then omit it.
118- Multi-paragraph explanations belong in `specs/`, package `README.md` files, or GitHub issues — never in the source itself.
119
120Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period. For short examples in comments, indent code instead of using backticks.
121
122Use US English spelling in all code comments (`parameterized`, `behavior`, `color`, `serialize`, `normalize`, `optimize`, …) — not the British `-ised`/`-our`/`-re` variants.
123
124> **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.
125
126## Agent Runtime
127
128- Detect container mode by checking for `/.dockerenv`.
129- If the repo path is `/go/src/github.com/photoprism/photoprism` and `/.dockerenv` is absent, treat the environment as host mode with a bind mount and prefer host-side Docker commands.
130- Bash check: `[ -f "/.dockerenv" ] && echo container || echo host`
131- Node.js check: `require("fs").existsSync("/.dockerenv")`
132- Inside the container, prefer `npm exec --yes <agent> -- --help` or `npx <agent> ...`; if a global npm install is unavoidable, install it only inside the container.
133- The `photoprism/develop` base image and the repo `Makefile` both set `NPM_CONFIG_IGNORE_SCRIPTS=true`, so `npm ci`/`npm install` via `make` targets skip install scripts out of the box. When running npm directly in an environment that does not set or inherit that default, pass `--ignore-scripts` explicitly to mitigate supply-chain attacks. Rebuild native addons with `npm rebuild --ignore-scripts=false <pkg>` — a bare `npm rebuild` is a silent no-op wherever the env default is active.
134- On the host, use the vendor-recommended install method and run from the repository root so agent discovery sees this file.
135
136## Build, Format & Test
137
138- Run `make help` for an overview of the most common targets, and `make list` to see all of them.
139- Host mode:
140 - `make docker-build`
141 - `docker compose up` or `docker compose up -d`
142 - `docker compose logs -f --tail=100 photoprism`
143 - `docker compose exec photoprism ./photoprism help`
144 - `docker compose exec -u "$(id -u):$(id -g)" photoprism <command>` to avoid root-owned files
145 - `make terminal`
146 - `docker compose --profile=all down --remove-orphans` or `make down`
147- Container mode:
148 - `make dep`
149 - `make build-js` and `make build-go`
150 - `make watch-js` or `cd frontend && npm run watch`
151 - `./photoprism start`
152 - Local URLs: `http://localhost:2342/` and, with Traefik, `https://app.localssl.dev/`
153 - Local compose defaults to `admin` / `photoprism`; inspect `compose.yaml` if they differ.
154 - Do not use the Docker CLI inside the container; manage Compose from the host instead.
155- The public CLI name is always `photoprism`; development-only side-by-side binaries may use edition-specific names.
156- Our command examples assume a Linux or Unix shell on 64-bit AMD64 or ARM64; see the Developer Guide FAQ for Windows-specific notes.
157
158Formatting and test entry points:
159- Full suite: `make test`, `make lint`
160- After renaming or removing a Makefile target, run `make check-make-help` (also included in `make lint`) so that no `make help` overview keeps advertising it.
161- Go-specific lint, format, and package-test rules live in [`internal/AGENTS.md`](internal/AGENTS.md).
162- Frontend lint, Vitest, acceptance, and Playwright rules live in [`frontend/AGENTS.md`](frontend/AGENTS.md).
163- Go tests live next to their sources; use PascalCase `t.Run(...)` names for related subtests. Keep consecutive subtests inside the same `Test*` function back-to-back without blank lines so the cases read as a compact table; reserve blank lines for separating distinct setup blocks.
164- Do not run multiple test commands in parallel; suites share fixtures, assets, and database state.
165- Prefer focused test runs such as `go test ./path/to/pkg -run Name -count=1` while iterating.
166- Use `mariadb -D photoprism` inside the dev shell when you need to inspect MariaDB state directly.
167- Run `shellcheck <file>` on edited shell scripts, or use the corresponding `make` target.
168
169### Continuous Integration
170
171- **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/`.
172- 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.
173
174### Container Image Builds
175
176- **Never mix Debian and Ubuntu `apt` repositories in the same image:**
177 - Don't add a Debian source to an Ubuntu base (or vice versa) to install a single missing package — the transitive deps drift, apt's solver pulls newer libraries from the foreign distro, and other build steps in the same `RUN` (e.g. `install-libheif.sh` running `apt-get install libavcodec-dev`) silently link against the wrong soname.
178 - Symptoms surface much later as `dlopen: libfoo.so.N: cannot open shared object file` at image runtime, with the binary referencing a soname that exists only in the foreign distro.
179 - If a package isn't available in the host distro's repos, prefer (a) a same-distro PPA / backports source, (b) a vendor-supplied .deb (e.g. Google Chrome from `dl.google.com`), or (c) a from-source build pinned to a known version.
180
photoprism/photoprism · frontend/AGENTS.md
@@ +1 @@
1# Frontend Guidelines
2
3**Last Updated:** July 28, 2026
4
5## Dependencies & Pins
6
7- [`frontend/README.md`](README.md) is the canonical doc for dependency pin rationale, the `overrides` layer, ESM-only upgrade blockers, and the orphan-audit pattern.
8- **Pins are intentional.** When a version has no caret (e.g., `"axios": "1.17.0"`, `"vuetify": "3.12.2"`), check `frontend/README.md` and `git log -p -S "<pkg>" -- frontend/package.json` for the reason before changing it.
9- npm is a workspace; run `npm install --ignore-scripts --no-audit --no-fund --no-update-notifier` from the **repo root** (not `frontend/`) so the root `package-lock.json` updates.
10- After dep changes run `make audit`, `make build-js`, `make test-js`, and `make notice`.
11- Before adding a new dep — and especially before declaring an existing one "unused" — verify with `rg -nF "<pkg>" frontend …` plus `npm ls <pkg> --all` that no consumer or peer-dep needs it.
12
13## Frontend Linting & Test Entry Points
14
15- Run `make -C frontend help` for an overview of the most common frontend targets, and `make -C frontend list` to see all of them.
16- Use the lint and format scripts declared in `frontend/package.json`; all added JS, Vue, and frontend tests must follow those standards.
17- Frontend unit tests use Vitest. Common entry points are `make test-js`, `make vitest-watch`, and `make vitest-coverage`.
18- New JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
19- New Vue components should have component-test coverage, and existing component tests should be updated as needed when component behavior changes.
20- Acceptance tests use the `acceptance-*` targets in the root `Makefile`.
21- For one-off TestCafe checks, keep startup and cleanup in the repository root: `make storage/acceptance`, `make acceptance-sqlite-restart`, `make wait-2`, then `(cd frontend && npm run testcafe -- "chrome --headless=new --use-gl=angle --use-angle=swiftshader --disable-features=LocalNetworkAccessChecks" --config-file ./testcaferc.json --test-meta mode=public,type=short,testID=components-001 "tests/acceptance")`, then `make acceptance-sqlite-stop`.
22- If a command temporarily changes into `frontend/`, return to the repository root before running `make acceptance-sqlite-stop`.
23
24## Templates, Session Bootstrap & Browser Baseline
25
26- HTML entry points live under `assets/templates/`; the key files are `index.gohtml`, `app.gohtml`, `app.js.gohtml`, and `splash.gohtml`.
27- Browser checks live in `assets/static/js/browser-check.js` and must load before the main bundle from `app.js.gohtml`. Do not add `defer` or `async` unless you restore guarded loading.
28- OIDC completion is bridged through `assets/templates/auth.gohtml` and must stay aligned with `frontend/src/common/session.js`, `frontend/src/common/storage.js`, and `frontend/src/page/auth/login.vue`. Preserve the `session` storage preference across the callback so `sessionStorage` logins survive redirect.
29- When touching frontend session bootstrap, verify that `frontend/src/common/session.js` resolves `storageNamespace` from the real client config shape (`window.__CONFIG__` or `config.values`), not only from simplified mocks. Include a focused test that would fail if restore fell back to `pp:root:`.
30- The loader partial is reused in `pro/assets/templates/index.gohtml`, `plus/assets/templates/index.gohtml`, and `portal/assets/templates/index.gohtml`; whenever you change `app.js.gohtml` or bundle loading, verify those files still include the shared partial.
31- Splash styles live in `frontend/src/css/splash.css`; add new splash elements there so public and private editions stay aligned.
32- Browser baseline: the `browserslist` query in `frontend/package.json` is authoritative — `.babelrc` sets no explicit `targets`, so `@babel/preset-env` compiles to that set. Resolve it with `(cd frontend && npx browserslist)` rather than quoting fixed versions, which go stale as caniuse data updates. Update the message in `assets/templates/app.js.gohtml` and matching CSS if the support matrix changes.
33
34## Translations
35
36- Translation extraction source of truth is the root `make gettext-extract`, which runs `scripts/gettext-extract.sh` across `frontend/src` and any available `plus`, `pro`, or `portal` overlays.
37- Compatibility targets such as `make -C plus gettext-extract` delegate to the root target.
38- Avoid punctuation-only gettext keys such as `$gettext("—")`; they create noisy entries in `frontend/src/locales/translations.pot`.
39- Case conventions: tooltips, labels, buttons, placeholders, and short imperative phrases use **Title Case** (`Zoom In`, `Toggle Thumbnails`, `Add to Album`); running prose, full sentences, and notifications use **sentence case** (`Failed to save changes`). Lowercase only articles, short conjunctions, and ≤3-letter prepositions when not first. The forced-as-is Vuetify 3 UI messages in `frontend/src/locales.js` are adopted verbatim — exempt, and not a casing reference to copy. Full rules: `specs/frontend/translations.md` §"Case Conventions".
40
41## Focus Management
42
43- Dialogs must follow the shared focus pattern documented in `frontend/src/common/README.md`.
44- Always expose `ref="dialog"` on `<v-dialog>` overlays, call `$view.enter` and `$view.leave` in `@after-enter` and `@after-leave`, and avoid positive `tabindex` values.
45- Persistent dialogs must handle Escape via `@keydown.esc.exact` so Vuetify's rejection animation is suppressed; keep other shortcuts on `@keyup` so inner inputs can cancel them first.
46- Global shortcuts flow through `onShortCut(ev)` in `common/view.js`; it forwards only Escape and `ctrl` or `meta` combinations.
47- When a dialog opens nested menus such as combobox suggestion lists, verify they still cooperate with the global trap.
48
49## Playwright MCP Usage
50
51- Default endpoint is `http://localhost:2342/`; default login routes are `/library/login` for CE, Plus, and Pro, and `/portal/login` for Portal.
52- Use the local compose admin credentials; if login fails, inspect the active compose environment.
53- Desktop sessions default to `1280x900`; mobile sessions should use the mobile Playwright server with `375x667`.
54- Close the browser tab after scripted interactions.
55- Prefer waits over sleeps, click only visible and enabled elements, and use role, label, or text selectors instead of brittle XPath selectors.
56- Keep screenshots small and reproducible: prefer JPEG, visible viewport, deterministic `.local/screenshots/<case>/<step>__<viewport>.jpg` names, and no large inline screenshots.
57- If `npx` fetches an MCP server at runtime, add `--yes` or preinstall it to avoid prompts.
58
59## Frontend Test Gotchas
60
61- Hidden-route UI checks under `/library/hidden` or `/portal/hidden` require both `files.file_error` and `photos.photo_quality = -1`; `file_error` alone will not surface the row.
62
@@ −1 +1 @@
1−# PhotoPrism Repository Guidelines
1+# Frontend Guidelines
22
33 **Last Updated:** July 28, 2026
44
5−## Purpose
5+## Dependencies & Pins
66
7−Entry point for agents and humans.
7+- [`frontend/README.md`](README.md) is the canonical doc for dependency pin rationale, the `overrides` layer, ESM-only upgrade blockers, and the orphan-audit pattern.
8+- **Pins are intentional.** When a version has no caret (e.g., `"axios": "1.17.0"`, `"vuetify": "3.12.2"`), check `frontend/README.md` and `git log -p -S "<pkg>" -- frontend/package.json` for the reason before changing it.
9+- npm is a workspace; run `npm install --ignore-scripts --no-audit --no-fund --no-update-notifier` from the **repo root** (not `frontend/`) so the root `package-lock.json` updates.
10+- After dep changes run `make audit`, `make build-js`, `make test-js`, and `make notice`.
11+- Before adding a new dep — and especially before declaring an existing one "unused" — verify with `rg -nF "<pkg>" frontend …` plus `npm ls <pkg> --all` that no consumer or peer-dep needs it.
812
9−## Sources of Truth
13+## Frontend Linting & Test Entry Points
1014
11−- Makefile: https://github.com/photoprism/photoprism/blob/develop/Makefile
12−- Setup guide: https://docs.photoprism.app/developer-guide/setup/
13−- Test guide: https://docs.photoprism.app/developer-guide/tests/
14−- Contributing: https://github.com/photoprism/photoprism/blob/develop/CONTRIBUTING.md
15−- Security: https://github.com/photoprism/photoprism/blob/develop/SECURITY.md
16−- REST API: https://docs.photoprism.dev/ and https://docs.photoprism.app/developer-guide/api/
17−- Code maps: [`CODEMAP.md`](CODEMAP.md), [`frontend/CODEMAP.md`](frontend/CODEMAP.md)
18−- Package docs: `README.md` files under `internal/`, `pkg/`, `frontend/`, and `frontend/src/`
19−- Frontend dependency pins, override layer, and orphan-audit pattern: [`frontend/README.md`](frontend/README.md) (read before bumping any non-caret pin or adding/removing a top-level dep)
20−- AI/Vision docs: [`internal/ai/face/README.md`](internal/ai/face/README.md), [`internal/ai/vision/README.md`](internal/ai/vision/README.md), [`internal/ai/vision/openai/README.md`](internal/ai/vision/openai/README.md), [`internal/ai/vision/ollama/README.md`](internal/ai/vision/ollama/README.md)
21−- Glossary: [`GLOSSARY.md`](GLOSSARY.md)
22−- When dependencies change, regenerate `NOTICE` files with `make notice`; do not edit `NOTICE` or `frontend/NOTICE` manually.
15+- Run `make -C frontend help` for an overview of the most common frontend targets, and `make -C frontend list` to see all of them.
16+- Use the lint and format scripts declared in `frontend/package.json`; all added JS, Vue, and frontend tests must follow those standards.
17+- Frontend unit tests use Vitest. Common entry points are `make test-js`, `make vitest-watch`, and `make vitest-coverage`.
18+- New JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
19+- New Vue components should have component-test coverage, and existing component tests should be updated as needed when component behavior changes.
20+- Acceptance tests use the `acceptance-*` targets in the root `Makefile`.
21+- For one-off TestCafe checks, keep startup and cleanup in the repository root: `make storage/acceptance`, `make acceptance-sqlite-restart`, `make wait-2`, then `(cd frontend && npm run testcafe -- "chrome --headless=new --use-gl=angle --use-angle=swiftshader --disable-features=LocalNetworkAccessChecks" --config-file ./testcaferc.json --test-meta mode=public,type=short,testID=components-001 "tests/acceptance")`, then `make acceptance-sqlite-stop`.
22+- If a command temporarily changes into `frontend/`, return to the repository root before running `make acceptance-sqlite-stop`.
2323
24−## Subtree Guides
24+## Templates, Session Bootstrap & Browser Baseline
2525
26−- [`internal/AGENTS.md`](internal/AGENTS.md): internal Go rules.
27−- [`internal/api/AGENTS.md`](internal/api/AGENTS.md): API rules.
28−- [`internal/config/AGENTS.md`](internal/config/AGENTS.md): config rules.
29−- [`internal/commands/AGENTS.md`](internal/commands/AGENTS.md): CLI rules.
30−- [`internal/photoprism/AGENTS.md`](internal/photoprism/AGENTS.md): import and index rules.
31−- [`internal/service/cluster/AGENTS.md`](internal/service/cluster/AGENTS.md): cluster rules.
32−- [`frontend/AGENTS.md`](frontend/AGENTS.md): frontend rules.
33−- [`pkg/AGENTS.md`](pkg/AGENTS.md): `pkg/*` security and test rules.
26+- HTML entry points live under `assets/templates/`; the key files are `index.gohtml`, `app.gohtml`, `app.js.gohtml`, and `splash.gohtml`.
27+- Browser checks live in `assets/static/js/browser-check.js` and must load before the main bundle from `app.js.gohtml`. Do not add `defer` or `async` unless you restore guarded loading.
28+- OIDC completion is bridged through `assets/templates/auth.gohtml` and must stay aligned with `frontend/src/common/session.js`, `frontend/src/common/storage.js`, and `frontend/src/page/auth/login.vue`. Preserve the `session` storage preference across the callback so `sessionStorage` logins survive redirect.
29+- When touching frontend session bootstrap, verify that `frontend/src/common/session.js` resolves `storageNamespace` from the real client config shape (`window.__CONFIG__` or `config.values`), not only from simplified mocks. Include a focused test that would fail if restore fell back to `pp:root:`.
30+- The loader partial is reused in `pro/assets/templates/index.gohtml`, `plus/assets/templates/index.gohtml`, and `portal/assets/templates/index.gohtml`; whenever you change `app.js.gohtml` or bundle loading, verify those files still include the shared partial.
31+- Splash styles live in `frontend/src/css/splash.css`; add new splash elements there so public and private editions stay aligned.
32+- Browser baseline: the `browserslist` query in `frontend/package.json` is authoritative — `.babelrc` sets no explicit `targets`, so `@babel/preset-env` compiles to that set. Resolve it with `(cd frontend && npx browserslist)` rather than quoting fixed versions, which go stale as caniuse data updates. Update the message in `assets/templates/app.js.gohtml` and matching CSS if the support matrix changes.
3433
35−Optional nested repositories such as `plus/`, `pro/`, `portal/`, and `specs/` may contain their own `AGENTS.md` files. When present, treat those files as additional directory-local guidance.
34+## Translations
3635
37−## Local Agent Progress
36+- Translation extraction source of truth is the root `make gettext-extract`, which runs `scripts/gettext-extract.sh` across `frontend/src` and any available `plus`, `pro`, or `portal` overlays.
37+- Compatibility targets such as `make -C plus gettext-extract` delegate to the root target.
38+- Avoid punctuation-only gettext keys such as `$gettext("—")`; they create noisy entries in `frontend/src/locales/translations.pot`.
39+- Case conventions: tooltips, labels, buttons, placeholders, and short imperative phrases use **Title Case** (`Zoom In`, `Toggle Thumbnails`, `Add to Album`); running prose, full sentences, and notifications use **sentence case** (`Failed to save changes`). Lowercase only articles, short conjunctions, and ≤3-letter prepositions when not first. The forced-as-is Vuetify 3 UI messages in `frontend/src/locales.js` are adopted verbatim — exempt, and not a casing reference to copy. Full rules: `specs/frontend/translations.md` §"Case Conventions".
3840
39−- Use `.agents/TODO.md` for actionable tasks and `.agents/DONE.md` for completed work.
40−- These files are local workflow aids and may not exist in every workspace.
41+## Focus Management
4142
42−## Style Notes
43+- Dialogs must follow the shared focus pattern documented in `frontend/src/common/README.md`.
44+- Always expose `ref="dialog"` on `<v-dialog>` overlays, call `$view.enter` and `$view.leave` in `@after-enter` and `@after-leave`, and avoid positive `tabindex` values.
45+- Persistent dialogs must handle Escape via `@keydown.esc.exact` so Vuetify's rejection animation is suppressed; keep other shortcuts on `@keyup` so inner inputs can cancel them first.
46+- Global shortcuts flow through `onShortCut(ev)` in `common/view.js`; it forwards only Escape and `ctrl` or `meta` combinations.
47+- When a dialog opens nested menus such as combobox suggestion lists, verify they still cooperate with the global trap.
4348
44−### Commit Messages
49+## Playwright MCP Usage
4550
46−- Use concise imperative subjects with a one-word prefix, for example `Config: Add tests for "darktable-cli" path detection`.
47−- Append issue or PR IDs when relevant.
48−- Commit messages must not exceed 80 characters.
51+- Default endpoint is `http://localhost:2342/`; default login routes are `/library/login` for CE, Plus, and Pro, and `/portal/login` for Portal.
52+- Use the local compose admin credentials; if login fails, inspect the active compose environment.
53+- Desktop sessions default to `1280x900`; mobile sessions should use the mobile Playwright server with `375x667`.
54+- Close the browser tab after scripted interactions.
55+- Prefer waits over sleeps, click only visible and enabled elements, and use role, label, or text selectors instead of brittle XPath selectors.
56+- Keep screenshots small and reproducible: prefer JPEG, visible viewport, deterministic `.local/screenshots/<case>/<step>__<viewport>.jpg` names, and no large inline screenshots.
57+- If `npx` fetches an MCP server at runtime, add `--yes` or preinstall it to avoid prompts.
4958
50−### GitHub Issues
59+## Frontend Test Gotchas
5160
52−- Titles MUST be concise, imperative, and start with one capitalized prefix plus `: `, for example `Search: Add filter for RAW image formats`.
53−- Descriptions MUST begin with a one-sentence bold user story: `**As a <role>, I want <goal>, so that <outcome>.**`
54−- Use level-3 Markdown headings for sections within issue descriptions, for example `### Acceptance Criteria`.
55−- Follow with behavior, rationale, technical considerations, and constraints.
56−- End with `- [ ]` checklist items for the acceptance criteria, each using `MUST`, `SHOULD`, or `MAY`.
57− - Keep the checklist current: once the work for a criterion is implemented **and verified**, mark it done (`- [x]`).
58− - Leave items that are unverified, not yet implemented, or skipped optional (`MAY`) enhancements unchecked.
59− - An issue is complete only when every `MUST` is checked; never tick a box on the strength of a plan alone or an unrun test.
60− - When referencing an issue from a commit that fulfills some of its criteria, update the matching boxes first.
61−- Agents MUST create, edit, close, reopen, relabel, or otherwise modify GitHub issues only when explicitly requested by the user.
62−
63−### Specifications & Documentation
64−
65−- Markdown headings use a Chicago-style title case, with additional code- and path-aware normalization rules (see *Title Case rules* below). Always spell the product name as `PhotoPrism`.
66−- Put option flags before positional arguments unless the command requires another order.
67−- Use RFC 3339 UTC timestamps and valid ID, UID, and UUID examples in docs and tests.
68−- The nested `specs/` repository may be absent. Do not add main-repo `Makefile` targets that depend on it; when present, you may run its tools manually.
69−- Testing guides live at `specs/dev/backend-testing.md` and `specs/dev/frontend-testing.md`.
70−- Do not read, analyze, or modify `specs/generated/`; refer humans to `specs/generated/README.md` when regeneration is needed.
71−- Refresh `**Last Updated:**` when you change document contents, but leave it unchanged for whitespace-only or formatting-only edits.
72−- Nested Git repositories may appear ignored; change into them before staging or committing updates.
73−
74−Title Case rules (Chicago-style, with code- and path-aware normalization):
75−- Capitalize the first word, the first word after a colon, dash, or end punctuation, and all major words, including the second part of a hyphenated major word.
76−- Lowercase only articles, short conjunctions, and short prepositions of three letters or fewer when they are not in one of those positions.
77−- Preserve known acronyms (for example, API, CLI, HTTP, JSON) and slash-separated acronym groups (for example, CSV/TSV) as uppercase.
78−- Preserve RFC 2119 / RFC 8174 normative keywords (MUST, SHOULD, MAY, SHALL, REQUIRED, RECOMMENDED, OPTIONAL) as uppercase when used in their normative sense.
79−- Preserve inline code spans (`` `foo` ``), file paths (e.g. `docs/foo-bar.md`), and slash commands (e.g. `/grill-me`) verbatim; do not recase their contents.
80−- Use `&` instead of `And`/`Or` in headings.
81−
82−## Safety & Data
83−
84−- If `git status` shows unexpected changes, assume a human may be editing; ask before using reset-style commands.
85−- Do not run `git config` at either the global or repository level.
86−- Do not run destructive commands against production data; prefer ephemeral volumes and test fixtures for acceptance tests.
87−- Never commit secrets, local configurations, or cache files; use environment variables or a local `.env`.
88−- Ensure `.env`, `.config`, `.local`, `.codex`, and `.gocache` are ignored in `.gitignore` and `.dockerignore`.
89−- Prefer existing caches, workers, and batching strategies already referenced by the code and `Makefile`.
90−- Consider CPU and memory impact; only suggest profiling or benchmarks when justified.
91−- If anything here conflicts with the `Makefile` or the sources of truth, ask for clarification before proceeding.
92−
93−## Project Layout & Shared Rules
94−
95−- Backend: Go in `internal/`, `pkg/`, and `cmd/`, backed by MariaDB or SQLite.
96−- Frontend: Vue 3 plus Vuetify 3 under `frontend/`.
97−- Local dev and CI use Docker Compose; Traefik provides local TLS via `*.localssl.dev`.
98−- Code in `pkg/*` must not import from `internal/*`. If you need config, entity, or DB access, add code under `internal/`.
99−- Shared Go rules:
100− - After Go edits, run `make fmt-go` and keep `gofmt` tab indentation.
101− - Every added/modified Go function, including unexported helpers, must have focused test coverage in the corresponding `*_test.go` files; update existing tests or add new ones as needed.
102− - Every Go package must contain a root `<package>.go` file with the standard license header and a short package description comment.
103− - Use `pkg/fs` permission constants: `fs.ModeDir`, `fs.ModeFile`, `fs.ModeConfigFile`, `fs.ModeSecretFile`, and `fs.ModeBackupFile`.
104− - When importing the stdlib `io/fs`, alias it to avoid collisions, for example `iofs "io/fs"` or `gofs "io/fs"`.
105− - Do not pass stdlib `io/fs` mode flags where permission bits are expected.
106− - Prefer `filepath.Join` for filesystem paths and `path.Join` only for URL paths.
107− - Normalize slash-based logical paths stored in DB, config, or API payloads with `clean.SlashPath(...)`.
108−- Shared JS/Vue rules:
109− - Added/modified JavaScript functions, including helpers, should be tested whenever practical; update existing tests or add new ones as needed.
110− - Added/modified Vue components should have component-test coverage, and existing component tests should be updated as needed when behavior changes.
111−- When adding a metadata source such as `SrcOllama` or `SrcOpenAI`, update both `internal/entity/src.go` and `frontend/src/common/util.js` so backend and UI stay aligned.
112−
113−### JS/Go Code Comments
114−
115−A doc comment is **required** for every function (including unexported helpers), as well as for every non-trivial Vue `methods:` / `computed:` / watcher:
116−- Keep comments **compact** and default to one line for "what" in the format `// Name does X.`. Skip trivial getters (`isOpen: () => this.open`).
117−- Add 1-2 follow-up lines (`// …`) **only** if the "why" is non-obvious: a hidden invariant, a workaround that would otherwise be undone by a future cleanup, a contract a reader can't infer from the code. If readers can infer the "why" from the function body or a nearby line, then omit it.
118−- Multi-paragraph explanations belong in `specs/`, package `README.md` files, or GitHub issues — never in the source itself.
119−
120−Doc comments for packages and exported identifiers must be complete sentences that begin with the name of the thing being described and end with a period. For short examples in comments, indent code instead of using backticks.
121−
122−Use US English spelling in all code comments (`parameterized`, `behavior`, `color`, `serialize`, `normalize`, `optimize`, …) — not the British `-ised`/`-our`/`-re` variants.
123−
124−> **Don't include in code comments:** Issue / PR numbers, "previously…" history, alternatives considered, what the function used to do, references to old commits, names of subsequent reviewers, or any narrative that names the change rather than the steady-state behavior. That context belongs in commit messages, specs, or handover notes.
125−
126−## Agent Runtime
127−
128−- Detect container mode by checking for `/.dockerenv`.
129−- If the repo path is `/go/src/github.com/photoprism/photoprism` and `/.dockerenv` is absent, treat the environment as host mode with a bind mount and prefer host-side Docker commands.
130−- Bash check: `[ -f "/.dockerenv" ] && echo container || echo host`
131−- Node.js check: `require("fs").existsSync("/.dockerenv")`
132−- Inside the container, prefer `npm exec --yes <agent> -- --help` or `npx <agent> ...`; if a global npm install is unavoidable, install it only inside the container.
133−- The `photoprism/develop` base image and the repo `Makefile` both set `NPM_CONFIG_IGNORE_SCRIPTS=true`, so `npm ci`/`npm install` via `make` targets skip install scripts out of the box. When running npm directly in an environment that does not set or inherit that default, pass `--ignore-scripts` explicitly to mitigate supply-chain attacks. Rebuild native addons with `npm rebuild --ignore-scripts=false <pkg>` — a bare `npm rebuild` is a silent no-op wherever the env default is active.
134−- On the host, use the vendor-recommended install method and run from the repository root so agent discovery sees this file.
135−
136−## Build, Format & Test
137−
138−- Run `make help` for an overview of the most common targets, and `make list` to see all of them.
139−- Host mode:
140− - `make docker-build`
141− - `docker compose up` or `docker compose up -d`
142− - `docker compose logs -f --tail=100 photoprism`
143− - `docker compose exec photoprism ./photoprism help`
144− - `docker compose exec -u "$(id -u):$(id -g)" photoprism <command>` to avoid root-owned files
145− - `make terminal`
146− - `docker compose --profile=all down --remove-orphans` or `make down`
147−- Container mode:
148− - `make dep`
149− - `make build-js` and `make build-go`
150− - `make watch-js` or `cd frontend && npm run watch`
151− - `./photoprism start`
152− - Local URLs: `http://localhost:2342/` and, with Traefik, `https://app.localssl.dev/`
153− - Local compose defaults to `admin` / `photoprism`; inspect `compose.yaml` if they differ.
154− - Do not use the Docker CLI inside the container; manage Compose from the host instead.
155−- The public CLI name is always `photoprism`; development-only side-by-side binaries may use edition-specific names.
156−- Our command examples assume a Linux or Unix shell on 64-bit AMD64 or ARM64; see the Developer Guide FAQ for Windows-specific notes.
157−
158−Formatting and test entry points:
159−- Full suite: `make test`, `make lint`
160−- After renaming or removing a Makefile target, run `make check-make-help` (also included in `make lint`) so that no `make help` overview keeps advertising it.
161−- Go-specific lint, format, and package-test rules live in [`internal/AGENTS.md`](internal/AGENTS.md).
162−- Frontend lint, Vitest, acceptance, and Playwright rules live in [`frontend/AGENTS.md`](frontend/AGENTS.md).
163−- Go tests live next to their sources; use PascalCase `t.Run(...)` names for related subtests. Keep consecutive subtests inside the same `Test*` function back-to-back without blank lines so the cases read as a compact table; reserve blank lines for separating distinct setup blocks.
164−- Do not run multiple test commands in parallel; suites share fixtures, assets, and database state.
165−- Prefer focused test runs such as `go test ./path/to/pkg -run Name -count=1` while iterating.
166−- Use `mariadb -D photoprism` inside the dev shell when you need to inspect MariaDB state directly.
167−- Run `shellcheck <file>` on edited shell scripts, or use the corresponding `make` target.
168−
169−### Continuous Integration
170−
171−- **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/`.
172−- 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.
173−
174−### Container Image Builds
175−
176−- **Never mix Debian and Ubuntu `apt` repositories in the same image:**
177− - Don't add a Debian source to an Ubuntu base (or vice versa) to install a single missing package — the transitive deps drift, apt's solver pulls newer libraries from the foreign distro, and other build steps in the same `RUN` (e.g. `install-libheif.sh` running `apt-get install libavcodec-dev`) silently link against the wrong soname.
178− - Symptoms surface much later as `dlopen: libfoo.so.N: cannot open shared object file` at image runtime, with the binary referencing a soname that exists only in the foreign distro.
179− - If a package isn't available in the host distro's repos, prefer (a) a same-distro PPA / backports source, (b) a vendor-supplied .deb (e.g. Google Chrome from `dl.google.com`), or (c) a from-source build pinned to a known version.
61+- Hidden-route UI checks under `/library/hidden` or `/portal/hidden` require both `files.file_error` and `photos.photo_quality = -1`; `file_error` alone will not surface the row.
18062
