From 3012786d82e63d26f3134e0411fe27d4e2217b79 Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Tue, 5 May 2026 09:40:18 +0000 Subject: [PATCH] Docs: Drop private subrepo references from public files Sweeps top-level CODEMAP/GLOSSARY, package READMEs under internal/, and a handful of source-comment references that linked to the private specs/ subrepo. AGENTS.md hints stay (agent-instruction document) and the agent-skill linking targets in Makefile are guarded with directory checks. --- CODEMAP.md | 2 -- GLOSSARY.md | 2 +- frontend/src/model/model-cache.js | 5 ++--- frontend/src/model/photo.js | 8 +++----- internal/api/README.md | 1 - internal/config/test.go | 2 +- internal/mcp/README.md | 6 ++---- internal/server/README.md | 2 +- 8 files changed, 10 insertions(+), 18 deletions(-) diff --git a/CODEMAP.md b/CODEMAP.md index 69e64142d..8fb9c49f9 100644 --- a/CODEMAP.md +++ b/CODEMAP.md @@ -136,7 +136,6 @@ Cluster / Portal - Registry/provisioner: `internal/service/cluster/registry/*`, `internal/service/cluster/provisioner/*`. - Theme endpoint (server): GET `/api/v1/cluster/theme`; client/CLI installs theme only if missing or no `app.js`. - Portal-only extensions: `portal/internal/portal` (Portal defaults, flags, provisioning options, `/i/*` proxy router). -- See specs cheat sheet: `specs/portal/README.md`. Logging & Events - Logger and event hub: `internal/event/*`; `event.Log` is the shared logger. @@ -289,7 +288,6 @@ Useful Make Targets (selection) See Also - AGENTS.md (repository rules and tips for agents) - Developer Guide (Setup/Tests/API) — links in AGENTS.md → Sources of Truth -- Specs: `specs/dev/backend-testing.md`, `specs/dev/api-docs-swagger.md`, `specs/portal/README.md` Go Internal Import Rule - Keep temporary Go helpers inside `internal/...`; the Go toolchain blocks importing `internal/` packages from directories such as `/tmp`, so use a disposable path like `internal/tmp/` when you need scratch space. diff --git a/GLOSSARY.md b/GLOSSARY.md index 088cc8965..451c8ed98 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -4,7 +4,7 @@ ### Purpose & Scope -- This is the single source of truth for terminology used across `specs/` and related docs. +- This is the single source of truth for terminology used across PhotoPrism documentation. - Define terms once here and reference this file instead of redefining the same terms in multiple documents. - Keep technical/API contract names unchanged where required, even when user-facing wording differs. diff --git a/frontend/src/model/model-cache.js b/frontend/src/model/model-cache.js index c7789d8d4..5f07a24b0 100644 --- a/frontend/src/model/model-cache.js +++ b/frontend/src/model/model-cache.js @@ -25,8 +25,7 @@ Additional information can be found in our Developer Guide: // Deep-clones a plain object via JSON. Used at both ends of the cache // lifecycle (set + hydrate) so callers can never share refs with cached -// values — see "isolation contract" in -// specs/frontend/model-lru-cache.md. +// values (cache isolation contract). function deepClone(value) { if (value === null || typeof value !== "object") { return value; @@ -52,7 +51,7 @@ export class ModelCacheStaleFetchError extends Error { // is model-layer infrastructure: a subclass (e.g. Photo) supplies snapshot // and hydrate hooks so the cache can stay neutral about model shape. // -// Contract (see specs/frontend/model-lru-cache.md): +// Contract: // - Stores plain value snapshots, never live model instances. // - Returns a fresh hydrated instance for every cache hit so callers // can mutate freely without aliasing the cached source of truth. diff --git a/frontend/src/model/photo.js b/frontend/src/model/photo.js index a7cf80ccd..aa87110fe 100644 --- a/frontend/src/model/photo.js +++ b/frontend/src/model/photo.js @@ -1286,9 +1286,8 @@ export class Photo extends RestModel { // Module-level Photo cache. Per-subclass scoping (rather than a shared // static on Rest) keeps Photo's size budget and invalidation surface - // independent from other model caches — see - // specs/frontend/model-lru-cache.md. Snapshot via getValues so - // type coercion through getDefaults() is applied; hydrate by constructing + // independent from other model caches. Snapshot via getValues so type + // coercion through getDefaults() is applied; hydrate by constructing // a fresh Photo from the cached values. static _cache = new ModelCache({ max: 50, @@ -1323,8 +1322,7 @@ export class Photo extends RestModel { // in-flight fetch whose epoch no longer matches REJECTS with // ModelCacheStaleFetchError instead of resolving — so neither the // cache nor a .then-chained UI assignment can leak role-A data into - // role B during the post-logout unmount window. See - // specs/frontend/model-lru-cache.md Decisions §5 for the design. + // role B during the post-logout unmount window. static clearCache() { Photo._cache.clear(); } diff --git a/internal/api/README.md b/internal/api/README.md index 7a4cc5cdf..564fd9a17 100644 --- a/internal/api/README.md +++ b/internal/api/README.md @@ -56,7 +56,6 @@ The API package exposes PhotoPrism’s HTTP endpoints via Gin handlers. Each fil status.Error(err), }, refID) ``` -- See `specs/common/audit-logs.md` for the full conventions and additional examples that agents should follow. ### Swagger Documentation diff --git a/internal/config/test.go b/internal/config/test.go index dd8d864f3..ff8292f12 100644 --- a/internal/config/test.go +++ b/internal/config/test.go @@ -312,7 +312,7 @@ func NewIsolatedTestConfig(dbName, dataPath string, createDirs bool) *Config { } // NewTestConfig initializes test data so required directories exist before tests run. -// See AGENTS.md (Test Data & Fixtures) and specs/dev/backend-testing.md for guidance. +// See AGENTS.md (Test Data & Fixtures) for guidance. func NewTestConfig(dbName string) *Config { defer log.Debug(capture.Time(time.Now(), "config: new test config created")) diff --git a/internal/mcp/README.md b/internal/mcp/README.md index fa94864a8..2b01312c3 100644 --- a/internal/mcp/README.md +++ b/internal/mcp/README.md @@ -1,8 +1,6 @@ ## PhotoPrism MCP Server -**Last Updated:** April 20, 2026 - -> See `specs/platform/mcp.md` for the canonical specification, including the rationale for the user-access policy and the role/grant matrix per edition. +**Last Updated:** May 5, 2026 ### Current Capabilities @@ -242,6 +240,6 @@ To revoke access without disabling the user account, the administrator runs: ./photoprism clients remove ``` -> **Heads up:** `photoprism auth add --scope mcp ` creates an *app password* tied to a user account, but it currently does **not** grant MCP access — `RoleUser` is not in the `ResourceMCP` ACL. Use `photoprism clients add` for MCP integrations until that policy changes. The reasoning is documented in `specs/platform/mcp.md` under *User Access Model* (deliberate hold, not an oversight). +> **Heads up:** `photoprism auth add --scope mcp ` creates an *app password* tied to a user account, but it currently does **not** grant MCP access — `RoleUser` is not in the `ResourceMCP` ACL. Use `photoprism clients add` for MCP integrations until that policy changes. This is a deliberate hold, not an oversight. When MCP eventually grows tools that need user-scoped data (e.g. "list my albums"), the team will revisit the policy and likely add `RoleUser → GrantSearchAll` so the app-password path lights up. Until then, every MCP integration is an admin-provisioned client token tied to a named application. diff --git a/internal/server/README.md b/internal/server/README.md index 2bd52ddd0..7f7acf3f0 100644 --- a/internal/server/README.md +++ b/internal/server/README.md @@ -45,7 +45,7 @@ ### Configuration & Safety Notes -- Compression: configured via `PHOTOPRISM_HTTP_COMPRESSION` / `--http-compression` as a comma-separated preference list. Supported tokens are `zstd`, `gzip`, and `none` (empty value also disables compression). The default ships as `zstd,gzip` so capable clients receive zstd while everyone else falls back to gzip; unknown tokens are ignored with a startup warning. See [`specs/platform/http-compression.md`](../../specs/platform/http-compression.md) for the negotiation rules and exclusion list. +- Compression: configured via `PHOTOPRISM_HTTP_COMPRESSION` / `--http-compression` as a comma-separated preference list. Supported tokens are `zstd`, `gzip`, and `none` (empty value also disables compression). The default ships as `zstd,gzip` so capable clients receive zstd while everyone else falls back to gzip; unknown tokens are ignored with a startup warning. - Bundled frontend assets under `/static/*` are served with precompressed `.zst` / `.gz` siblings produced at build time by `frontend/scripts/precompress.js` (the npm `postbuild` hook for `make build-js`), selected via `PrecompressedStatic` in `static_precompressed.go`. Custom static assets under `/c/static/*` go through the same handler so extensions and operators *may* ship precompressed siblings alongside their files; without siblings the route serves identity. The runtime middleware bypasses both routes so it never re-encodes an already-encoded body and so `PHOTOPRISM_HTTP_COMPRESSION=none` consistently disables every encoded code path on these routes. - Trusted proxies/platform headers are read from config; keep the list tight. - If no trusted proxy ranges are configured (or the configured ranges are invalid), proxy trust is disabled and client IP resolution falls back to the TCP peer address.