summercms/.planning/research/SUMMARY.md

# Project Research Summary

**Project:** SummerCMS (Go) — v1 = Płytarium (fonoteka) headless backend port
**Domain:** Go 1.27 WinterCMS/Laravel-shaped CMF, compiled-plugin model, porting a live PHP headless API to Go with byte-level response parity for an unchanged Nuxt 4 app and MCP/OAuth client
**Researched:** 2026-09-16
**Confidence:** HIGH on stack versions, plugin-architecture mechanics, and PHP-source-grounded pitfalls; MEDIUM on architectural judgment calls (migration tool, OpenAPI approach, config format) and on features/patterns inferred from ecosystem comparison rather than direct source reading

## Executive Summary

SummerCMS v1 is not a from-scratch CMS design problem — it is a constrained port of a fully-specified, already-running PHP application (Płytarium/fonoteka: 25 models, 154 routes, 27 migrations, 3 jobs, 3 console commands) onto a compiled-plugin Go framework whose shape (Caddy/xcaddy-style build-time registration) is already decided and well-precedented. All four research passes converge on the same operating principle: **the PHP source is the spec, and the parity harness is the compiler.** Every stack pick, feature, architectural pattern, and pitfall in this research is grounded in reading the actual `fonoteka` PHP source (models, controllers, routes.php, serializer traits) rather than a generic "how do headless CMSes work" survey — this is the single most load-bearing fact for how the roadmap should be sequenced.

The recommended approach: stand up a minimal kernel (config, plugin registry, event bus, container) only far enough to support one real vertical slice — `GET /_fonoteka/api/v1/genres` through every layer (config → DB → plugin registry → routing → JWT auth → GORM → JSON response), diffed byte-for-byte against a recorded PHP fixture — before any further kernel abstraction work. This directly avoids the one documented failure mode this project has already suffered once: the Scala predecessor stalled building "Illuminate-shaped infrastructure bottom-up with no real app pulling requirements" (`why-go-not-scala.md`). In parallel, an API-parity fixture-recording harness can start at t=0 with zero Go code, since it only needs a running PHP backend to record against — this should be treated as an independent workstream, not a phase gated behind framework progress.

The key risks are not "will Go's ecosystem support this" (STACK.md and go-ecosystem.md answer that affirmatively for every named concern, OAuth2/OIDC included) but **silent parity drift**: Go's idioms actively fight several PHP behaviors this app depends on byte-for-byte — nil slices marshal to `null` where PHP guarantees `[]`, `time.Time` renders `Z` where Carbon renders `+00:00`, a plain `bool` cannot express PHP's tri-state `null`/`true`/`false` fields, GORM's default many-to-many silently drops the `sort_order` pivot column driving album-artist display order, and a "clean" unified response-envelope or error-middleware instinct will break the RFC 8414/6749 OAuth endpoints the MCP server and ChatGPT connector depend on. None of these fail loudly; all are exactly the class of bug a parity harness diffing full response bodies (not just status codes) is built to catch. The roadmap should treat the parity harness as a first-class deliverable from phase 1, not a late QA pass.

## Key Findings

### Recommended Stack

The stack is almost entirely already-decided (per PROJECT.md); this research pass confirmed versions and resolved five open integration questions. All core picks (Go 1.27, GORM v1.31.2 + `gorm.io/driver/postgres` v1.6.3, River v0.47.0, zitadel/oidc v3.51.0, golang-jwt/jwt v5.3.1, go-playground/validator v10.30.4, cobra v1.10.2, gocloud.dev v0.46.0, koanf/v2, go-i18n/v2) are current and actively maintained as of 2026-09-16 (verified via pkg.go.dev, GitHub, and official docs directly, not secondhand).

**Core technologies and resolved questions:**
- **GORM + River share one `*sql.DB`** (via `pgx/v5/stdlib`), not two independent pools — River's own docs (`riverqueue.com/docs/gorm`) document this pattern directly; a small separate `pgxpool.Pool` is used only for River's LISTEN/NOTIFY wake-ups.
- **Migrations: gormigrate, not goose.** This is a load-bearing correction to earlier documents (ARCHITECTURE.md and PITFALLS.md both still reference goose per the older `go-ecosystem.md` pick). STACK.md's deeper dive concludes gormigrate's plain `[]*gormigrate.Migration` structs (with first-class `RollbackLast()`/`RollbackTo()`) compose more naturally with per-plugin migration sets aggregated at boot than goose's filesystem-and-provider model, and matches the "drop the last migration and fix it" workflow PROJECT.md names verbatim. **This is a genuine open decision to close before the data-layer phase — see Gaps below.**
- **Config: koanf + plain YAML, not literal HOCON.** No maintained Go HOCON parser exists at this project's dependency-quality bar. PROJECT.md's "HOCON-style layered config" should be read as a layering *design* (base + env overlay + per-plugin namespace), which koanf achieves natively with YAML — not a mandate for HOCON syntax.
- **YAML parsing: goccy/go-yaml, not `gopkg.in/yaml.v3`.** `gopkg.in/yaml.v3`'s upstream was archived by its maintainer April 2025 and is explicitly marked unmaintained (confirmed by reading the repo directly) — this changes a style preference into a must, for both `fields.yaml`/`columns.yaml` parsing and (transitively, via koanf) config.
- **OpenAPI: swaggo/swag (comment-driven, code-first), not Huma.** Huma's typed-handler convention would restructure all 154 ported routes right when byte-compatible parity with an existing contract is the entire point; swag annotates ordinary `net/http` handlers with no signature changes.
- **GORM plain structs, not gorm gen/go-gorm/cli codegen**, for v1 — matches the explicit "simplest line-by-line Eloquent-to-GORM port" design goal.

### Expected Features

Płytarium's actual source (not a generic CMS feature list) defines table stakes. FEATURES.md read `Plugin.php`, `routes.php` (569 lines / ~160 routes), all 5 admin controllers' YAML configs, all 25 models, 3 jobs, and 3 console commands directly.

**Must have (table stakes, all P1):**
- Plugin descriptor with register/boot lifecycle, dependency declaration, and cross-plugin extension via events (not inheritance) — the core mechanism plugins use to extend each other (`getApiArray` payload extension, model-created notification listeners, auth guard registration)
- Full GORM relation/cast/hook fidelity: pivot models with business columns (not bare pivot arrays), polymorphic file attachments, `$jsonable`/`$fillable`/`$hidden`/`encrypted`-cast discipline, cascading soft-delete inside transactions, custom attribute casts (e.g. money as fixed-decimal string)
- **Three parallel, mutually-exclusive auth groups sharing controllers**: JWT (SPA), personal scoped token (`inv.scope:read|write|ai`, used by MCP), and public/onboarding — the single hardest routing requirement, since the same controller must serve different route subsets per group, plus 7+ named per-bucket rate limiters
- OAuth2.1 authorization server (auth code + PKCE, refresh tokens, RFC 7591 DCR, RFC 8414 discovery) for MCP/ChatGPT — already the named zitadel/oidc pick
- `fields.yaml`/`columns.yaml` → JSON schema pipeline including a **relation-manager schema type** (link/unlink UI for a belongsToMany with pivot) — used once in Płytarium (Collections' editors tab) but structurally necessary
- River-backed jobs with a debounce/coalescing pattern (wishlist digest) and a self-redispatching rate-limit-aware pattern (Discogs match job) — not just "a queue exists"
- Centrifugo publisher + pluggable per-channel-namespace authorizer registry (kept as existing infra, only publisher/token-issuing ported)
- Typesense sync that is tenant-scoped and always treated as a pre-filter re-gated in SQL, never a source of truth
- Multi-step, resumable, queued CSV import pipeline (not a single upload action)
- 3-tier BYOK-or-org-or-site-admin credential resolver pattern (used identically for Discogs and AI credentials)

**Should have / differentiators (not v1 blockers):** compile-time plugin registration removing WinterCMS's `class_exists`/`elevated` boot-order fragility; a single typed "fire and collect vs. fire and forget" event bus generalizing two hand-rolled PHP patterns into one kernel primitive; generalizing the 3-tier credential resolver into one reusable piece instead of two copies; a first-class relation-manager schema type replacing the `partial` field-type escape hatch.

**Explicitly deferred (confirmed unused by Płytarium, do not build for v1):** server-rendered theme engine, backend AJAX/partial-refresh framework, `Sluggable`/`Sortable`/`NestedTree`/`Revisionable` model behaviors (none used anywhere in the plugin — slugs are hand-rolled in lifecycle hooks), MySQL support, payments/chat/forum/video, policy-based row/field-level admin permissions (Płytarium's admin RBAC is coarse role gates only).

### Architecture Approach

Two-repo split: `summercms.go` (framework core, one Go module: `pact`, `towel`, `compass`, `festival`, `backpack`, `party`, `bonfire`, `surf`, `lagoon`, `bouncer`, `lifeguard`, `cooler`, `conga`, `postcard`, `sandcastle`, `phrasebook`, `sunset`) and `fonoteka.go` (the application, a `go.work` workspace of per-plugin Go modules requiring the framework). The framework has zero knowledge of Płytarium; plugins import the framework, never the reverse. Stack plugins (user, translate, websockets) live inside the app repo's workspace for v1 and are only extracted to their own repos when a second app needs them.

**Major components:**
1. **`party` (plugin registry)** — Caddy/xcaddy-style: each plugin self-registers via `init()`, `summer build` regenerates a blank-import list; one required `Plugin` interface (`ID/Requires/Register/Boot`) plus small optional capability interfaces (`HasModels`, `HasRoutes`, `HasJobs`, etc.) replace WinterCMS's optional-override inheritance.
2. **Three concrete plugin-extends-plugin mechanisms**, not one generic hook system: (a) typed "filter" events on `festival` for response/serialization extension, (b) GORM's own callback registry (`db.Callback()`) for model lifecycle extension, (c) migration + companion embedding struct for schema extension (one plugin adding columns to another's table). Conflating these into one abstraction is explicitly called out as the wrong move.
3. **`lagoon` (GORM/Postgres) + `conga` (River)** sharing one `*sql.DB`, with a separate pgx listener pool for LISTEN/NOTIFY — the concrete first-party-documented integration pattern from STACK.md.
4. **`surf` (routing)** implementing the three-auth-group/per-bucket-rate-limit requirement as first-class routing structure, with OAuth/RFC routes in a structurally separate group carrying no shared envelope/error middleware.
5. **First vertical slice**: `GET /_fonoteka/api/v1/genres` end-to-end (config → container → migration → plugin registry → JWT-guarded route → GORM → JSON diffed against a PHP fixture) is identified as the one phase that cannot be skipped or parallelized — every other phase's pattern is a repetition of this slice's pieces.
6. Suggested build order is a 9-layer DAG (pact/towel → compass/phrasebook/bonfire → festival → backpack → party → lagoon/surf → bouncer → [vertical-slice checkpoint] → lifeguard/cooler/conga/postcard/sandcastle → admin schema + parity harness + bulk model/route porting, parallelizable → sunset last, thin).

### Critical Pitfalls

Fifteen critical pitfalls were identified, each cited to specific PHP source lines. The five most consequential for roadmap sequencing:

1. **Bottom-up kernel over-building (recurrence risk)** — this project already failed once this way in Scala. Avoid by interleaving kernel work with the first real vertical slice; never let plugin descriptor/event-bus/config shape get a "finished" design pass before a real model/route exists end to end.
2. **Package-level global state instead of `context.Context`** for per-request org/tenant/collection resolution — PHP-FPM's process-per-request model silently protected against this; Go's shared-process concurrency does not. Must be settled as a convention before any plugin consumes it.
3. **Reusing GORM model structs as JSON request-binding structs** — loses the `$fillable`/`$guarded` mass-assignment boundary that is a named security invariant in the PHP source (e.g., `market_price_source`, `public_token` deliberately excluded). Requires per-endpoint DTOs from the first ported model onward, not retrofitted later.
4. **A "clean" generic response envelope or blanket error/auth middleware** — the PHP house style deliberately has at least three incompatible envelope families (house REST with no `links` key, Laravel-shaped validation-error maps, and unenveloped RFC 8414/6749 OAuth responses with specific cache headers). A single `APIResponse[T]` generic wrapper is flagged explicitly as a smell to catch in phase planning, not a shortcut to allow.
5. **Type-level parity gaps that don't fail loudly**: nil slice → `null` vs PHP's guaranteed `[]`; `time.Time` → `Z` vs Carbon's `+00:00`; plain `bool` unable to express tri-state null/true/false; `float64` reintroducing float-precision bugs PHP deliberately avoided for money fields via a custom cast. All of these require the parity harness to diff full response bodies field-by-field, not just check status codes or rough shape.

## Implications for Roadmap

### Phase 1: Kernel foundation + first vertical slice (interleaved, not sequential)
**Rationale:** Directly avoids Pitfall 1 (the documented Scala failure mode). The kernel must be built exactly as far as the first vertical slice needs it, no further, before any additional kernel design work.
**Delivers:** `compass` (config), `backpack` (container), `festival` (event bus), `party` (plugin registry + `summer build`), `bonfire` (CLI skeleton) — each only fleshed out to the point `GET /_fonoteka/api/v1/genres` requires. Also establishes the `context.Context`-based org/tenant-resolution convention (Pitfall 2) before any plugin uses it.
**Addresses:** Kernel/plugins table-stakes features (plugin descriptor, dependency declaration, event bus, console command registration).
**Avoids:** Pitfall 1 (bottom-up over-build), Pitfall 2 (global state vs. context).

### Phase 2: First vertical slice checkpoint — one real endpoint end to end
**Rationale:** ARCHITECTURE.md identifies this as the one phase that cannot be skipped or parallelized: every later phase depends on all its pieces (config, container, migration, plugin registry, routing, JWT auth, GORM, JSON response) existing together.
**Delivers:** `Genre` (or `Style`) model + migration (via gormigrate — see Gaps), one JWT-guarded route through `surf`, a working `party` plugin registration, and the first parity-harness fixture (recorded from the live PHP backend, diffed byte-for-byte).
**Uses:** GORM + gormigrate, `golang-jwt/jwt`, stdlib `ServeMux`.
**Implements:** The full request-flow pattern in ARCHITECTURE.md that every subsequent route repeats.

### Phase 3: API parity harness (parallel workstream, starts at t=0)
**Rationale:** Near-zero dependency on framework internals — it only needs a running PHP backend to record fixtures against. All four research passes agree this should not be gated behind kernel/framework progress.
**Delivers:** Fixture-recording tooling against the live PHP backend, an `httptest.Server`-based replay-and-diff harness with a normalizer for non-deterministic fields, and — critically — assertions covering the specific parity classes named in Pitfalls 4/6/7/8 (nil-vs-empty-array, date format/null-vs-omitted, tri-state bool, envelope/conditional-key shape), not just status-code/rough-shape checks.
**Avoids:** Pitfalls 4, 5, 6, 7, 8 (all of which "look done but aren't" without a byte-level diff).

### Phase 4: Data layer — full model/relation/cast fidelity
**Rationale:** Every endpoint touches this; the security-load-bearing `$fillable`/`$hidden`/encrypted-cast discipline and the DTO-vs-model convention (Pitfall 3) must be established here, not retrofitted after models exist.
**Delivers:** Per-plugin gormigrate migration sets (one per PHP migration, up/down tested), all 25 models with correct relation types (dedicated pivot models with business columns, not bare arrays — Pitfall 12), polymorphic file attachments, soft-delete + partial unique index audits (Pitfall 11), money-as-fixed-decimal-string and other custom casts (Pitfall 5).
**Addresses:** Data/models table-stakes row in FEATURES.md in full.
**Avoids:** Pitfalls 3, 5, 11, 12, 13 (GORM AutoMigrate misuse).

### Phase 5: HTTP/auth — three-group routing, rate limiting, personal tokens
**Rationale:** The entire 154-route API surface sits behind this; retrofitting the routing structure after routes exist is called out explicitly as expensive.
**Delivers:** JWT + personal-scoped-token (`inv.scope`) + public/onboarding route groups sharing controllers, named per-bucket rate limiters ported 1:1 (not redesigned), the must-change-password gate with its one deliberate exception route, and — critically — a structural exemption of any future OAuth/RFC route group from generic envelope/error middleware, decided now rather than after 26 models' worth of routes exist.
**Uses:** `surf`, `bouncer`, `cooler` (rate-limit buckets).
**Avoids:** Pitfall 9 (blanket middleware corrupting OAuth), "rate-limit bucket parity" moderate pitfall.

### Phase 6: OAuth2.1 server (zitadel/oidc)
**Rationale:** Depends on the routing/middleware abstraction from Phase 5 existing first (same "not-the-SPA's-JWT" pattern), but is a distinct credential type (`OAuthClient`/`OAuthAuthCode`/`OAuthRefreshToken` vs. `ApiToken`) — build the shared abstraction once, then implement both guards against it.
**Delivers:** `AuthStorage`/`OPStorage` interface implementations mapped onto the existing OAuth models, RFC 8414/7591 endpoints, and exact `WWW-Authenticate`/Protected-Resource-Metadata header contract (Pitfall 10) verified against the actual `fonoteka-mcp` client, not just unit tests.
**Avoids:** Pitfalls 9, 10; the "trusting zitadel/oidc defaults without diffing" technical-debt pattern.
**Research flag:** needs verification of whether `ClientCredentialsStorage`/`TokenExchangeStorage` are actually needed (check `wavepath.org/plugins/golem15/oauthserver` before assuming not).

### Phase 7: Admin schema pipeline (fields.yaml/columns.yaml → JSON) + minimal Vue 3 SPA
**Rationale:** Requires the data-layer serialization boundary (Phase 4) to already exist; cannot be phased independently of it per FEATURES.md's dependency notes.
**Delivers:** Form/list/relation-manager JSON schema for the 5 admin controllers, OpenAPI generation via swaggo/swag, generated TS types, and a decision on the `partial` field-type escape hatch (likely: replace with the relation-manager schema directly, per the Collections' editors-tab case).
**Research flag:** relation-manager schema design and the `partial`-type replacement are the least-precedented parts of this research pass (used once in the PHP source) — worth a `--research-phase` pass.

### Phase 8: Background jobs, realtime, search, integrations
**Rationale:** Depends on Phase 4 (models/events) and benefits from Phase 1's event bus; independently parallelizable across CSV import, Discogs/AI clients, Centrifugo, and Typesense once the data layer is stable.
**Delivers:** River with the correct dual-driver split (`riverdatabasesql` for transactional enqueue, `riverpgxv5` for LISTEN/NOTIFY work processing — Pitfall 14), the CSV import multi-step pipeline, wishlist digest debounce, Centrifugo suppress-then-emit-once broadcast pattern, Typesense sync with the SQL re-gate (never trusting search results as pre-authorized — Pitfall 15), Discogs/AI clients with the 3-tier BYOK credential resolver.
**Avoids:** Pitfalls 14, 15, and the moderate "Centrifugo broadcast-suppression" and "rate-limit bucket parity" pitfalls.

### Phase 9: Bulk remaining route/model port + full parity cutover
**Rationale:** By this point the pattern is proven and repeatable; this phase is mostly volume, parallelizable across plugins/models gated only by FK order (the same DAG the 27 PHP migrations already encode).
**Delivers:** All remaining routes/models, full parity-harness green against all 154 routes, `vue-fonoteka-app` and `fonoteka-mcp` running unchanged against the Go backend — the literal definition of done in PROJECT.md.

### Phase Ordering Rationale

- Kernel and first-slice phases are interleaved specifically to prevent the Scala-era failure mode from recurring — this is the single strongest signal across all four research documents.
- The parity harness is pulled out as an explicit parallel-from-t=0 workstream because three of the four research documents independently flag it as near-zero-dependency and because its assertions are the actual mechanism that catches most of the "critical pitfalls" — sequencing it late would defeat its purpose.
- Data layer precedes HTTP/auth precedes OAuth because each has a documented one-way dependency (auth needs models to authenticate against; OAuth reuses the auth-group routing pattern) — reversing this order was explicitly flagged as more expensive to retrofit.
- Admin schema pipeline is placed after data layer specifically because FEATURES.md's dependency notes say these "cannot be phased independently" without under-building the `$fillable`/`$hidden` security contract.
- Background/integrations is placed late because it is the most parallelizable-once-unblocked phase and has the fewest cross-dependencies on routing/OAuth decisions.

### Research Flags

Needs deeper research during planning:
- **OAuth2.1 phase** — `zitadel/oidc` storage-interface implementation against the real PHP OAuth models, and the exact `ClientCredentialsStorage`/`TokenExchangeStorage` scope question (check `wavepath.org/plugins/golem15/oauthserver` first).
- **Admin schema pipeline phase** — the relation-manager schema type and the `partial` field-type replacement are the least-precedented design surface in this research (one real usage in the PHP source, no direct library equivalent).
- **Background/jobs phase** — River's dual-driver (`riverdatabasesql` vs `riverpgxv5`) split is documented but not yet implemented in this codebase; verify the transactional-enqueue-plus-LISTEN/NOTIFY pattern against a real test before trusting the docs-only description.

Phases with standard, well-documented patterns (safe to skip `--research-phase`):
- **Kernel/plugin-registry phase** — Caddy/xcaddy's compiled-plugin model is directly precedented and already verified against real xcaddy-generated code.
- **Data layer phase** — GORM patterns (relations, casts, callbacks) are well-documented; the risk here is PHP-source-fidelity auditing (a planning/testing discipline), not unknown Go patterns.

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | HIGH | Versions and maintenance status verified directly via pkg.go.dev/GitHub/official docs this session; MEDIUM on judgment calls (migration tool, OpenAPI approach, config format) but those calls are well-reasoned and explicit about trade-offs |
| Features | HIGH for table stakes (grounded in direct reading of the full `fonoteka` PHP source — Plugin.php, routes.php, all models/controllers/YAML configs); MEDIUM for differentiators and anti-features (informed by ecosystem comparison, not exhaustively re-audited) |
| Architecture | HIGH for plugin-registration mechanics (verified against real Caddy/xcaddy docs) and request-lifecycle mapping (grounded in the real `Plugin.php`/`routes.php`); MEDIUM for the cross-plugin schema-extension pattern and the two-repo split (design recommendation, not yet validated by an actual build) |
| Pitfalls | HIGH for anything cited to actual PHP source (routes.php, controllers/api/*.php, models/Album.php, SerializesFonoteka.php, fonoteka-mcp/src/http.ts) or official GORM/River docs; MEDIUM for Go-ecosystem-general claims and the "Laravel-shaped framework in Go" class of pitfall |

**Overall confidence:** HIGH — this research is unusually well-grounded because three of the four passes read the actual target PHP application's source directly rather than reasoning from a generic domain description.

### Gaps to Address

- **gormigrate vs. goose is not yet settled across documents.** STACK.md's deep-dive recommends gormigrate (better fit for per-plugin migration composition and the "drop the last migration and fix it" workflow); ARCHITECTURE.md and PITFALLS.md still reference goose per the earlier `go-ecosystem.md` pick and have not been updated. **Resolve this explicitly before the data-layer phase** — do not let two documents silently disagree into implementation. STACK.md's reasoning is more recent and more specific to this project's shape; the roadmap should default to gormigrate unless a phase decision overrides it.
- **PROJECT.md's field-type list needs correction.** PROJECT.md's Active requirements list `number`, `fileupload`, `repeater`, `datepicker` as WinterCMS field types Płytarium uses; FEATURES.md's direct read of all 5 controllers' `fields.yaml` files found the actual set is `text`, `textarea`, `checkbox`, `switch`, `dropdown` (model-method-fed), `relation`, and `partial` (an escape hatch, not a clean schema type) — no `number`/`fileupload`/`repeater`/`datepicker` anywhere in the plugin. Update PROJECT.md's requirement line to match, and treat `partial` as the one field type needing a bespoke design decision (see Phase 7's research flag).
- **PROJECT.md's "HOCON-style layered config" wording should be clarified as a design, not a syntax mandate** — no viable Go HOCON parser exists; koanf + YAML achieves the same layering semantics. Worth a one-line PROJECT.md update so a future reader doesn't chase a literal HOCON parser.
- **No Sluggable/Sortable/NestedTree/Revisionable behaviors are used anywhere in Płytarium** — confirmed by direct source read. These should not appear as implicit v1 scope anywhere; PROJECT.md does not currently list them, but flag this explicitly so no phase accidentally builds a packaged Sluggable behavior when the PHP source only ever hand-rolls slugs in lifecycle hooks.
- **`gopkg.in/yaml.v3` is unmaintained (archived April 2025)** — any lingering assumption (in code, docs, or a future dependency choice) that yaml.v3 is the default YAML library should be corrected to `goccy/go-yaml` before it's load-bearing anywhere.
- **typesense-go (v3.2.0, Mar 2025) and centrifugal/gocent/v3's exact latest tag** are both flagged MEDIUM confidence in STACK.md due to research-session gaps since their last verified release — re-check both at the implementation time of the search/realtime phase rather than trusting the pinned versions blindly.
- **zitadel/oidc's `ClientCredentialsStorage`/`TokenExchangeStorage` necessity** is an open question STACK.md itself flags — resolve by reading `wavepath.org/plugins/golem15/oauthserver` before the OAuth phase's interface-implementation work begins.

## Sources

### Primary (HIGH confidence)
- `/media/nvme/dev/golem15/fonoteka/plugins/golem15/fonoteka/` — Plugin.php, routes.php (569 lines/~160 routes), all 5 admin controllers + config_form/config_list/config_relation.yaml, all 25 models, 3 jobs, 3 console commands, config/fonoteka.php (read directly for FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
- `/media/nvme/dev/golem15/fonoteka/plugins/golem15/fonoteka/traits/SerializesFonoteka.php`, `controllers/api/AlbumApiController.php`, `controllers/api/OAuthTokenController.php`, `controllers/api/OAuthMetadataController.php`, `models/Album.php` — serialization/envelope/security contract detail (PITFALLS.md)
- `/media/nvme/dev/golem15/fonoteka/fonoteka-mcp/src/http.ts`, `vue-fonoteka-app/app/composables/useCentrifugo.ts` — client-side contract confirmation
- pkg.go.dev version pages, GitHub repos/releases for every core and supporting library (GORM, River, zitadel/oidc, golang-jwt, goccy/go-yaml, gormigrate, swaggo/swag, etc.) — fetched/read directly 2026-09-16
- `riverqueue.com/docs/gorm` — official River+GORM pool-sharing integration guide
- Caddy/xcaddy official docs and generated `main.go` mechanics; PocketBase hook-system/schema-driven-admin docs
- This repo's `.planning/PROJECT.md`, `.planning/notes/why-go-not-scala.md`, `.planning/research/go-ecosystem.md`, `CLAUDE.md`

### Secondary (MEDIUM confidence)
- `/media/nvme/dev/golem15/fonoteka/plugins/golem15/user/`, `plugins/golem15/websockets/` — skimmed, not fully read
- WebSearch: Directus/Strapi/PocketBase/Goravel 2026 comparisons (cross-checked against training knowledge, MEDIUM confidence)
- koanf's YAML parser migrating to goccy/go-yaml — WebSearch-sourced, corroborated by two independent results and go-i18n's own release notes

### Tertiary (LOW confidence, needs validation)
- Exact latest tags for typesense-go and centrifugal/gocent/v3 (both flagged as needing a fresh check at implementation time)
- otter-vs-ristretto cache performance claim carried from go-ecosystem.md (maintainer benchmarks, not independently verified)

---
*Research completed: 2026-09-16*
*Ready for roadmap: yes*