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

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

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.
 

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
+// values (cache isolation contract).
-// specs/frontend/model-lru-cache.md.
 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.

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
+  // independent from other model caches. Snapshot via getValues so type
-  // specs/frontend/model-lru-cache.md. Snapshot via getValues so
+  // coercion through getDefaults() is applied; hydrate by constructing
-  // 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
+  // role B during the post-logout unmount window.
-  // specs/frontend/model-lru-cache.md Decisions §5 for the design.
   static clearCache() {
     Photo._cache.clear();
   }

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
 

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

internal/mcp/README.md

@@ -1,8 +1,6 @@
 ## PhotoPrism MCP Server
 
-**Last Updated:** April 20, 2026
+**Last Updated:** May 5, 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.
 
 ### Current Capabilities
 
@@ -242,6 +240,6 @@ To revoke access without disabling the user account, the administrator runs:
 ./photoprism clients remove <client-id>
 ```
 
-> **Heads up:** `photoprism auth add --scope mcp <username>` 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 <username>` 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.

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.