quickstart

Quickstart Defaults

The quickstart package (module github.com/goliatone/go-admin/quickstart) bundles opt-in defaults for go-admin so hosts can get a working admin with minimal wiring while keeping override hooks.

Bootstrap helpers

Each helper is optional and composable.

Temporary bootstrap passwords

For first-instance provisioning, keep orchestration in go-users and enforcement in go-auth:

1. Generate a one-time password and hash it with auth.HashPassword.
2. Execute service.Commands().UserBootstrapPassword with the target user, hash, actor, and optional TTL. The default TTL is 24 hours.
3. Wire login with auth.NewUserProvider(repoManager.Users()) or an equivalent provider that reads go-auth user metadata.
4. Add auth.TemporaryPasswordClaimsDecorator() to the authenticator when the UI needs a compact password_change_required session/JWT hint.
5. Add TemporaryPasswordGateForAdmin or TemporaryPasswordGate after auth middleware so temporary sessions can only reach password-change/reset routes.
6. When the user sets a permanent password, run the normal UserPasswordReset/confirm path; temporary-password metadata is cleared when the repository supports it, and the reset token is claimed/finalized through the password-reset lifecycle repository so concurrent confirms cannot double-apply the password.

The metadata contract is migration-free: password_temporary, password_change_required, password_temporary_issued_at, and password_temporary_expires_at. Expired temporary passwords are rejected by local go-auth password verification.

The admin temporary password guide covers the full provisioning, auth wiring, password-change gate, and recovery flow.

Deployment identity

Set admin.Config.Deployment before calling quickstart.NewAdmin. Quickstart keeps the identity resolved by that Admin when it builds the Fiber developer error handler, so the error page and debug surfaces report the same process:

cfg := quickstart.NewAdminConfig("/admin", "Orders", "en")
cfg.Deployment = admin.DeploymentIdentityConfig{
    AppID:       "orders-admin",
    AppName:     "Orders Admin",
    Environment: "development",
    Persona: admin.DeploymentPersonaConfig{
        Enabled: true,
    },
}

adm, _, err := quickstart.NewAdmin(cfg, quickstart.AdapterHooks{})

The optional persona identifies the artifact; InstanceName and InstanceID still identify the answering process. Its seed precedence is typed seed, APP_DEPLOYMENT_SEED, then the full resolved commit. A missing stable seed omits the persona.

For deployed artifacts, inject APP_COMMIT_SHA, APP_VERSION, APP_BUILD_TIME, and APP_GIT_REF; use APP_INSTANCE_NAME and APP_INSTANCE_ID for orchestrator-owned runtime identity. Local processes get a generated readable name and UUID when those values are absent. See docs/GUIDE_DEBUG_MODULE.md for precedence, validation, and environment-color configuration, and docs/GUIDE_DEVELOPMENT.md for linker, GitHub Actions, and container examples.

Host lifecycle and readiness

Admin initialization registers admin routes; the host owns process startup, listener binding, readiness, and shutdown. Reuse the core module's github.com/goliatone/go-admin/pkg/go-lifecycle runner for phased startup and supervised workers. These helpers are opt-in:

• RegisterLifecycleReadinessRoute(r, routePath, provider) mounts a readiness handler and returns the resolved path; the default is /readyz.
• LifecycleReadinessHandler(provider) returns 503 until the provider's snapshot is ready, then 200. It does not infer readiness from an open socket.
• LifecycleStatusPayload(snapshot) projects serving/ready flags and task state.
• LifecycleDoctorCheck(provider) creates the quickstart.lifecycle diagnostic check; register it with the host's doctor configuration.

Register the readiness route while the backing router is collecting:

// runner is a *lifecycle.Runner, created from the host's lifecycle registry.
readyPath, err := quickstart.RegisterLifecycleReadinessRoute(
    host.InternalOps(), "", runner,
)
if err != nil {
    return err
}
_ = readyPath

Run pre-bind tasks before initializing/serving the backing router; after the listener accepts requests, explicitly mark serving and run post-bind/ready work. Consume background failures and finish lifecycle shutdown before closing shared resources. See the host lifecycle guide and runnable starter for ownership details.

Storage-backed uploads

• NewStorageBundle(ctx context.Context, cfg StorageBundleConfig) (*StorageBundle, error) - Inputs: shared go-uploader provider config, optional validator/logger/startup validation toggle. Outputs: configured storage provider plus uploader manager for host apps.

• StorageBundleConfig reuses go-uploader provider config so host apps can select fs, s3, or multi without embedding backend-specific construction logic into app modules.

• NewAdminConfig(basePath, title, defaultLocale string, opts ...AdminConfigOption) admin.Config - Inputs: base path/title/locale plus option setters. Outputs: admin.Config with quickstart defaults and overrides applied.

• DefaultMinimalFeatures() map[string]bool - Outputs: minimal Stage 1 feature set (dashboard + cms) intended for WithFeatureSet(...) or custom feature-gate construction.

• WithDebugConfig(cfg admin.DebugConfig) AdminConfigOption - Inputs: debug config; outputs: option that applies debug config (used to derive debug gate defaults).

• WithDebugOptions(opt DebugOption) AdminConfigOption - Inputs: explicit debug option overrides; outputs: option that applies targeted debug fields.

• WithErrorConfig(cfg admin.ErrorConfig) AdminConfigOption - Inputs: error config; outputs: option that applies error presentation defaults.

• WithErrorOptions(opt ErrorOption) AdminConfigOption - Inputs: explicit error option overrides; outputs: option that applies targeted error fields.

• WithTheme(name, variant string) AdminConfigOption - Inputs: default admin selector values; outputs: option that sets the configured theme and named variant.

• WithThemeTokens(tokens map[string]string) AdminConfigOption - Inputs: portable/package semantic or compatible legacy tokens; outputs: option that merges config tokens and final token overrides.

• WithThemeAssetURLs(assets map[string]string) AdminConfigOption - Inputs: resolved asset URLs/paths keyed by theme asset name; outputs: option that overlays final admin theme assets such as logo, icon, and favicon.

• WithLoginLogoPlacement(placement admin.LoginLogoPlacement) AdminConfigOption - Inputs: outside-card or inside-card; outputs: normalized login identity-mark placement while preserving theme asset selection.

• WithThemeAssetPrefix(prefix string) AdminConfigOption - Inputs: final config-level asset prefix; outputs: option applied after provider selection.

• WithRoutingConfig(cfg routing.Config) AdminConfigOption - Inputs: routing roots/module mount overrides; outputs: option that applies explicit routing policy overrides during quickstart config assembly.

• WithScopeConfig(scope ScopeConfig) AdminConfigOption - Inputs: scope config; outputs: option that applies single/multi-tenant defaults.

• WithScopeMode(mode ScopeMode) AdminConfigOption - Inputs: scope mode (single or multi); outputs: option that sets the mode.

• WithDefaultScope(tenantID, orgID string) AdminConfigOption - Inputs: default tenant/org IDs; outputs: option that sets defaults for single-tenant mode.

• NewAdmin(cfg admin.Config, hooks AdapterHooks, opts ...AdminOption) (*admin.Admin, AdapterResult, error) - Inputs: config, adapter hooks, optional context/dependencies. Outputs: admin instance, adapter result summary, error.

• WithAdapterFlags(flags AdapterFlags) AdminOption - Inputs: adapter flags; outputs: option that applies explicit adapter toggles.

• WithFeatureDefaults(defaults map[string]bool) AdminOption - Inputs: feature override map; outputs: compatibility option that merges overrides into DefaultAdminFeatures().

• WithFeatureOverrides(defaults map[string]bool) AdminOption - Inputs: feature override map; outputs: explicit merge-style option for quickstart feature defaults.

• WithFeatureSet(defaults map[string]bool) AdminOption - Inputs: full feature default map; outputs: option that replaces DefaultAdminFeatures() as the base set used by NewAdmin.

• WithMinimalFeatures() AdminOption - Outputs: option that replaces the default quickstart feature set with DefaultMinimalFeatures().

• WithStartupPolicy(policy StartupPolicy) AdminOption - Inputs: startup policy (enforce or warn); outputs: option controlling module startup validation handling.

• WithCommandExecutionPolicy(policy admin.CommandExecutionPolicy) AdminOption - Inputs: command execution policy (global default + per-command overrides); outputs: option that injects command routing policy into bootstrap.

• WithCommandQueueRouting(cfg CommandQueueRoutingConfig) AdminOption - Inputs: queue routing config (enabled, enqueuer, optional command registry + dedupe store); outputs: option that attaches the queued dispatcher executor.

• WithRPCTransport(cfg RPCTransportConfig) AdminOption - Inputs: RPC transport config (enabled, optional invoke_path, require_auth, explicit allow_unauthenticated opt-out, discovery_enabled, optional command rules/policy hook); outputs: option that mounts Fiber RPC invoke routes and wires admin RPC command policy defaults.

• TranslationExchangeCommandIDs() []string - Outputs: canonical translation-exchange command ids for policy configuration.

• TranslationQueueCommandIDs() []string - Outputs: canonical translation-queue command ids for policy configuration.

• WithTranslationProfile(profile TranslationProfile) AdminOption - Inputs: profile (none, core, core+exchange, core+queue, full); outputs: option that applies productized translation defaults.

• WithTranslationProductConfig(cfg TranslationProductConfig) AdminOption - Inputs: product config (SchemaVersion, Profile, optional module overrides); outputs: option that resolves effective translation module wiring with deterministic precedence.

• TranslationCapabilities(adm *admin.Admin) map[string]any - Inputs: admin instance; outputs: resolved translation capability metadata (profile, schema_version, module enablement, feature flags, routes, resolver keys, panels, warnings).

• WithTranslationPolicyConfig(cfg TranslationPolicyConfig) AdminOption - Inputs: workflow transition requirements by policy entity/content type; outputs: option that wires the default translation policy and reports missing suitable checker services.

• WithTranslationPolicyServices(services TranslationPolicyServices) AdminOption - Inputs: page/content services implementing CheckTranslations; outputs: explicit checker overrides for hosts whose CMS container is not discoverable.

• ValidateTranslationPolicyCoverage(cfg TranslationPolicyConfig, contentTypes []string) (TranslationPolicyValidationResult, error) - Inputs: policy config plus content types included in family readiness; outputs: validation warnings/error for missing policy coverage.

• WithTranslationExchangeConfig(cfg TranslationExchangeConfig) AdminOption - Inputs: exchange config (disabled by default); outputs: option that enables exchange feature + command wiring when configured.

• WithTranslationQueueConfig(cfg TranslationQueueConfig) AdminOption - Inputs: queue config (disabled by default); outputs: option that enables queue feature + panel/command wiring when configured.

• EnablePreferences() AdminOption - Inputs: none; outputs: option to enable FeaturePreferences.

• EnableFeature(feature admin.FeatureKey) AdminOption - Inputs: feature key; outputs: option to enable a single feature gate key.

• RegisterTranslationExchangeWiring(adm *admin.Admin, cfg TranslationExchangeConfig) error - Inputs: admin + exchange config; outputs: error (registers exchange commands and optional permission entries).

• RegisterTranslationQueueWiring(adm *admin.Admin, cfg TranslationQueueConfig, policyCfg TranslationPolicyConfig, hasPolicyCfg bool) error - Inputs: admin + queue config + policy context; outputs: error (registers queue panel, tabs, commands, and optional permission entries).

• WithGoUsersPreferencesRepository(repo types.PreferenceRepository) AdminOption - Inputs: go-users preferences repo; outputs: option that wires a PreferencesStore via the adapter when one is not already set.

• WithGoUsersPreferencesRepositoryFactory(factory func() (types.PreferenceRepository, error)) AdminOption - Inputs: repo builder; outputs: option to lazily construct a preferences repo (used when dependencies do not already supply a PreferencesStore).

• WithGoUsersUserManagement(cfg GoUsersUserManagementConfig) AdminOption - Inputs: go-users auth/inventory/role repositories (plus optional profile repo and scope resolver); outputs: option that wires user/role/profile dependencies.

• RegisterUserRoleBulkRoutes(r admin.AdminRouter, cfg admin.Config, adm *admin.Admin) error - Inputs: admin router, config, and admin instance; outputs: error. This is an explicit migration bridge for deprecated static role routes; new hosts should use panel bulk actions.

• NewUsersModule(opts ...admin.UserManagementModuleOption) *admin.UserManagementModule - Inputs: user module options; outputs: configured built-in users module.

• NewExportBundle(opts ...ExportBundleOption) *ExportBundle - Inputs: go-export options (store/guard/actor/base path overrides). Outputs: runner/service plus go-admin registry/registrar/metadata adapters.

• PreferencesPermissions() []PermissionDefinition - Outputs: default preferences permission definitions.

• RegisterPreferencesPermissions(register PermissionRegisterFunc) error - Inputs: register func; outputs: error (registers default preferences permissions).

• TranslationExchangePermissions() []PermissionDefinition - Outputs: default translation exchange permission definitions.

• RegisterTranslationExchangePermissions(register PermissionRegisterFunc) error - Inputs: register func; outputs: error (registers translation exchange permissions).

• TranslationQueuePermissions() []PermissionDefinition - Outputs: default translation queue permission definitions.

• RegisterTranslationQueuePermissions(register PermissionRegisterFunc) error - Inputs: register func; outputs: error (registers translation queue permissions).

• NewPreferencesModule(cfg admin.Config, menuParent string, opts ...PreferencesModuleOption) admin.Module - Inputs: admin config, optional menu parent, preferences module options. Outputs: configured Preferences module.

• WithPreferencesSchemaPath(path string) PreferencesModuleOption - Inputs: schema path (file or directory); outputs: option that overrides the Preferences form schema.

• WithPreferencesJSONEditorStrict(strict bool) PreferencesModuleOption - Inputs: strict toggle; outputs: option that enforces client-side JSON validation for raw_ui.

• NewFiberErrorHandler(adm *admin.Admin, cfg admin.Config, isDev bool, opts ...FiberErrorHandlerOption) fiber.ErrorHandler - Inputs: admin, config, dev flag + options. Outputs: Fiber error handler.

• WithFiberErrorMappers(mappers ...goerrors.ErrorMapper) FiberErrorHandlerOption - Inputs: extra mappers; outputs: error handler option (appended to defaults).

• NewViewEngine(baseFS fs.FS, opts ...ViewEngineOption) (fiber.Views, error) - Inputs: base FS and view options. Outputs: Fiber views engine and error.

• RenderTemplateView(c router.Context, template string, viewCtx router.ViewContext) error - Inputs: active router context, template name, and view context. Outputs: rendered response or error after propagating request CSRF helpers and normalizing whole-number JSON values.

• WithViewAdmin(adm *admin.Admin) ViewEngineOption - Inputs: Admin instance; outputs: binds Admin's structural-partial lookup to the exact normalized first-wins view stack during NewViewEngine construction.

• DefaultTemplateFuncs(opts ...TemplateFuncOption) map[string]any - Outputs: default template helpers (JSON, dict, singularize/pluralize, adminURL, widget titles, etc.).

• MergeTemplateFuncs(overrides map[string]any, opts ...TemplateFuncOption) map[string]any - Inputs: overrides + optional template options. Outputs: merged map for WithViewTemplateFuncs.

• WithTemplateURLResolver(urls urlkit.Resolver) TemplateFuncOption - Inputs: URLKit resolver; outputs: option that configures adminURL to resolve via URLKit.

• WithViewURLResolver(urls urlkit.Resolver) ViewEngineOption - Inputs: URLKit resolver; outputs: option that configures adminURL to resolve via URLKit.

• WithThemeContext(ctx router.ViewContext, adm *admin.Admin, req router.Context) router.ViewContext - Inputs: view context, admin, request. Outputs: context enriched with theme tokens/selection, the serialized lowercase admin_partials template map, bounded structural diagnostics, and query/header theme preview overrides.

• admin.EnrichLayoutViewContextWithChrome(adm *admin.Admin, req router.Context, ctx router.ViewContext, chrome admin.AdminPageChrome) router.ViewContext - Inputs: Admin, request, base view context, and typed page presentation. Outputs: a cloned context where non-zero typed title/pretitle/subtitle/breadcrumb/navigation/body values win over legacy keys before request-scoped shell enrichment; trusted action markup remains template-owned.

• WithNav(ctx router.ViewContext, adm *admin.Admin, cfg admin.Config, active string, reqCtx context.Context) router.ViewContext - Inputs: base view context + admin/config/request state. Outputs: context enriched with feature flags (activity_enabled, activity_feature_enabled, translation_capabilities, body_classes), session user payload, nav items, theme payload, and path helpers.

• WithNavPlacements(ctx router.ViewContext, adm *admin.Admin, cfg admin.Config, placements PlacementConfig, placement MenuPlacementKey, active string, reqCtx context.Context) router.ViewContext - Inputs: same as WithNav, plus placement mapping. Outputs: placement-aware nav context for non-sidebar menus while preserving the same feature/session/theme enrichment.

• ResolveDashboardArea(placements PlacementConfig, placement placement.DashboardPlacementKey, fallback string) string - Inputs: placement config, shared dashboard placement key, fallback area code. Outputs: resolved dashboard area code for quickstart-owned widget wiring.

• BuildPanelExportConfig(cfg admin.Config, opts PanelViewCapabilityOptions) map[string]any - Inputs: admin config and panel capability options. Outputs: normalized export_config payload (endpoint, definition, optional validated variant); explicit capabilities fail closed when export is false or no resolved export is supplied.

• BuildPanelDataGridConfig(opts PanelDataGridConfigOptions) map[string]any - Inputs: datagrid options. Outputs: normalized datagrid_config payload (table_id, api_endpoint, action_base, optional capabilities, optional preferences_endpoint, column_storage_key, optional translation/grouped-mode keys, state_store, and url_state).

• BuildPanelViewCapabilities(cfg admin.Config, opts PanelViewCapabilityOptions) router.ViewContext - Inputs: admin config and panel capability options. Outputs: template capability context including list_capabilities, capability-gated export_config, and datagrid_config. Omit Capabilities only for legacy caller behavior; quickstart-owned panel lists pass an explicit normalized projection.

• PathViewContext(cfg admin.Config, pathCfg PathViewContextConfig) router.ViewContext - Inputs: config + path resolver hints. Outputs: normalized base_path, api_base_path, asset_base_path, preferences_api_path.

• WithPathViewContext(ctx router.ViewContext, cfg admin.Config, pathCfg PathViewContextConfig) router.ViewContext - Inputs: existing context + path resolver hints. Outputs: merged context with canonical path keys.

• WithThemeSelector(selector theme.ThemeSelector, manifest *theme.Manifest) AdminOption - Inputs: admin go-theme selector + manifest; outputs: option that wires admin theme selection + manifest into NewAdmin (including Preferences variant options).

• NewFiberServer(viewEngine fiber.Views, cfg admin.Config, adm *admin.Admin, isDev bool, opts ...FiberServerOption) (router.Server[*fiber.App], router.Router[*fiber.App]) - Inputs: views, config, admin, dev flag, server options. Outputs: go-router server adapter and router.

• NewThemeSelector(name, variant string, tokenOverrides map[string]string, opts ...ThemeOption) (theme.Selector, *theme.Manifest, error) - Inputs: theme name/variant, token overrides, theme options. Outputs: selector, manifest, error.

• WithThemeRegistry(registry theme.Registry) ThemeOption - Inputs: reusable theme registry; outputs: selector option that reuses or registers against it.

• WithThemeManifest(manifest *theme.Manifest) ThemeOption - Inputs: complete manifest; outputs: selector option that replaces the generated compatibility manifest.

• WithThemeAssets(prefix string, files map[string]string) ThemeOption - Inputs: manifest-relative asset files and optional prefix; outputs: selector option that fills missing manifest asset metadata.

• WithThemeVariants(variants map[string]theme.Variant) ThemeOption - Inputs: named variant definitions; outputs: selector option that fills missing manifest variants.

• NewStaticAssets(r router.Router[T], cfg admin.Config, assetsFS fs.FS, opts ...StaticAssetsOption) - Inputs: router, config, host assets FS, asset options. Outputs: none (registers static routes).

• ResolveDashboardShellAssetsPrefix(cfg admin.Config, opts ...StaticAssetsOption) string - Inputs: admin config and the same static asset options passed to NewStaticAssets. Outputs: resolved go-dashboard shell asset prefix for content-builder UI route registration.

• WithContentTypeBuilderUIStaticAssetOptions(cfg admin.Config, opts ...StaticAssetsOption) ContentTypeBuilderUIOption - Inputs: admin config and the same static asset options passed to NewStaticAssets. Outputs: content-builder UI option that keeps rendered shell asset URLs aligned with the mounted shell prefix.

• ResolveDiskAssetsDir(marker string, candidates ...string) string - Inputs: marker file + candidate directories. Outputs: first matching directory.

• RegisterAdminUIRoutes(r router.Router[T], cfg admin.Config, adm *admin.Admin, auth admin.HandlerAuthenticator, opts ...UIRouteOption) error - Inputs: router/config/admin/auth wrapper + options. Outputs: error (registers dashboard + notifications UI routes, and injects feature-aware view context such as activity_enabled + body_classes).

• WithContentEntryDataGridStateStore(cfg PanelDataGridStateStoreOptions) ContentEntryUIOption - Inputs: DataGrid state-store config for content-entry list templates. Outputs: content-entry route option (default mode remains localStorage when unset).

• WithContentEntryDataGridURLState(cfg PanelDataGridURLStateOptions) ContentEntryUIOption - Inputs: URL sync limits/token config for content-entry list templates. Outputs: content-entry route option.

• WithContentEntryUpdateIntentPolicy(policy ContentEntryUpdateIntentPolicy) ContentEntryUIOption - Inputs: nested-array update-intent policy. Outputs: content-entry route option that patches configured array paths before persistence.

• Nested object-array patch/preserve behavior for CMS content-entry forms is an explicit opt-in contract, not the default. Use schema/UI schema/capability metadata or WithContentEntryUpdateIntentPolicy(...); custom renderers must submit the same row and array markers as generated go-formgen repeatable arrays.

• RegisterAuthUIRoutes(r router.Router[T], cfg admin.Config, routeAuth *auth.RouteAuthenticator, opts ...AuthUIOption) error - Inputs: router/config/go-auth route authenticator + options. Outputs: error (registers login/reset UI routes plus POST /logout; GET /logout is registered only when WithAuthUILogoutGET(true) is passed).

• RegisterRegistrationUIRoutes(r router.Router[T], cfg admin.Config, opts ...RegistrationUIOption) error - Inputs: router/config + options. Outputs: error (registers signup UI route).

• NewAuthUIBrowserProtection(cfg admin.Config, opts ...AuthUIBrowserProtectionOption) (*AuthUIBrowserProtection, error) - Inputs: admin config plus optional stable key, cookie, trusted secure-request resolver, and origin policy. Outputs: a reusable browser-bound CSRF contract for Auth UI pages and onboarding mutations.

• AuthUIViewContext(cfg admin.Config, state AuthUIState, paths AuthUIPaths) router.ViewContext - Inputs: config/state/paths; outputs: view context with auth flags + paths (base_path, api_base_path, asset_base_path, preferences_api_path).

• Browser/admin routes rendered through quickstart now carry CSRF helpers automatically. Generated forms should include the hidden _token field, and same-origin JavaScript writes should send X-CSRF-Token from meta[name="csrf-token"].

• For cookie-backed browser pages, prefer the package-managed browser protection path instead of a custom CSRF wrapper so origin checks, CSRF header emission, and session-key resolution stay aligned with go-auth.

• Login, registration, and password-reset forms use a browser-bound pre-auth cookie plus stateless CSRF signatures and same-origin checks. Create one AuthUIBrowserProtection and pass it through WithAuthUIBrowserProtection, WithRegistrationUIBrowserProtection, and WithOnboardingBrowserProtection so every page/mutation pair shares the same key and cookie contract.

• Multi-instance deployments must use a shared cfg.PreviewSecret or WithAuthUIBrowserProtectionSecureKey(...). Use WithAuthUIBrowserProtectionSecureRequestResolver(...) when TLS terminates at a trusted proxy so the pre-auth cookie is marked Secure.

• On trusted HTTPS requests, the default cookie uses the __Host- prefix, Path=/, no Domain, HttpOnly, and SameSite=Lax; plain HTTP keeps a development-compatible host-only name.

• When an authenticated admin shell renders logout, use a POST form with the page's ambient csrf_field, and pass WithAuthUILogoutAuthenticator(authn) or WithAuthUILogoutMiddleware(mw) so /logout validates with the same browser auth/CSRF contract that produced the token. Login and password reset remain on the standalone Auth UI CSRF path.

• WithAuthUILogoutGET(true) remains an opt-in compatibility route. If a logout authenticator or middleware is configured, the GET route is wrapped by the same middleware; new shells should keep POST logout canonical. Without that option, GET /admin/logout is a route miss.

• WithProtectedAppAuth(routeAuth *auth.RouteAuthenticator, cfg auth.Config, opts ...admin.GoAuthAuthenticatorOption) *admin.GoAuthAuthenticator - Inputs: shared go-auth route authenticator plus canonical admin config with protected-app roots. Outputs: a protected-app browser/API authenticator that reuses the same actor/session and CSRF model as admin routes.

• AttachDebugMiddleware(r router.Router[T], cfg admin.Config, adm *admin.Admin) - Inputs: router/config/admin; outputs: none (registers debug request capture middleware).

• AttachDebugLogHandler(cfg admin.Config, adm *admin.Admin) - Inputs: config/admin; outputs: none (wires slog debug handler).

• ConfigureExportRenderers(bundle *ExportBundle, templatesFS fs.FS, opts ...ExportTemplateOption) error - Inputs: export bundle + templates FS + options. Outputs: error (registers template/PDF renderers).

• NewModuleRegistrar(adm *admin.Admin, cfg admin.Config, modules []admin.Module, isDev bool, opts ...ModuleRegistrarOption) error - Inputs: admin, config, module list, dev flag, options. Outputs: error.

• WithModuleFeatureGates(gates gate.FeatureGate) ModuleRegistrarOption - Inputs: feature gate; outputs: option to filter modules/menu items.

• WithModuleFeatureDisabledHandler(handler func(feature, moduleID string) error) ModuleRegistrarOption - Inputs: handler; outputs: option for disabled modules.

• WithTranslationCapabilityMenuMode(mode TranslationCapabilityMenuMode) ModuleRegistrarOption - Inputs: translation menu seeding mode (tools default, none opt-out); outputs: option controlling whether translation dashboard/queue/exchange links are added to server-seeded navigation.

• BuildMenuSeedPlan(opts MenuSeedPlanOptions) (MenuSeedPlan, error) - Inputs: menu code/locale, module contributors, optional parent replacement, module/target parent overrides, base item transforms, module item transforms, and extra base items. Outputs: deterministic expected generated menu rows used by quickstart seeding and reconciliation.

• WithMenuSeedPlanOptions(mutator func(*MenuSeedPlanOptions)) ModuleRegistrarOption - Inputs: mutator for the expected menu seed plan. Outputs: option for advanced host layout control before generated rows are reconciled.

• WithMenuSeedParents(parents ...admin.MenuItem) ModuleRegistrarOption - Inputs: host-defined parent/group rows. Outputs: option that replaces default quickstart parent groups for the primary menu while retaining module and translation capability collection.

• WithMenuSeedTargetParentOverride(targetKey, parentID string) ModuleRegistrarOption - Inputs: stable menu target key and parent ID. Outputs: option that moves matching generated rows without copying quickstart seed internals.

• WithMenuSeedModuleParentOverride(moduleID, parentID string) ModuleRegistrarOption - Inputs: module ID and parent ID. Outputs: option that moves all menu rows contributed by that module under the given parent.

• WithMenuSeedBaseItemTransform(transforms ...MenuSeedBaseItemTransform) ModuleRegistrarOption - Inputs: transforms for quickstart base/capability rows such as translation dashboard, queue, assignments, and exchange links. Outputs: option for host label, target, permission, parent, or sparse sort-weight tweaks before generated rows are reconciled.

• WithMenuSeedItemTransform(transforms ...MenuSeedItemTransform) ModuleRegistrarOption - Inputs: transforms for module-contributed menu rows. Outputs: option for host label, permission, parent, or sparse sort-weight tweaks before generated rows are reconciled.

• ReconcileGeneratedNavigation(ctx context.Context, opts NavigationReconcileOptions) (NavigationReconcileReport, error) - Inputs: menu service, expected items, locale, menu code, apply/dry-run mode, raw-inventory scope, and optional destructive cleanup. Outputs: creates, updates, preserved user rows, duplicate identities, destructive candidates, stale target cleanup, route failures, capability omissions, permission-filtered rows, preserved generated fields, parent-prune diagnostics, raw-inventory availability, raw-present-but-not-rendered rows, and coordination support diagnostics.

• DefaultContentParentPermissions() []string - Outputs: canonical permission set used by the default sidebar Content parent (media, content_types, block_definitions).

• WithGoAuth(adm *admin.Admin, routeAuth *auth.RouteAuthenticator, cfg auth.Config, authz admin.GoAuthAuthorizerConfig, authCfg *admin.AuthConfig, opts ...admin.GoAuthAuthenticatorOption) (*admin.GoAuthAuthenticator, *admin.GoAuthAuthorizer) - Inputs: admin, route auth, auth config, authz config, admin auth config, options. Outputs: adapters.

• WithDefaultDashboardRenderer(adm *admin.Admin, viewEngine fiber.Views, cfg admin.Config, opts ...DashboardRendererOption) error - Inputs: admin, view engine, config, renderer options. Outputs: error.

• WithDashboardTemplatesFS(fsys fs.FS) DashboardRendererOption - Inputs: template FS; outputs: renderer option for overrides.

• WithDashboardEmbeddedTemplates(enabled bool) DashboardRendererOption - Inputs: boolean; outputs: renderer option to enable/disable embedded templates.

• NewCompositeActivitySink(primary admin.ActivitySink, hooks dashboardactivity.Hooks, cfg dashboardactivity.Config) admin.ActivitySink - Inputs: primary sink, dashboard hooks/config. Outputs: activity sink bridge.

• NewGoAuthActivitySink(sink admin.ActivitySink, opts ...GoAuthActivitySinkOption) auth.ActivitySink - Inputs: admin sink + options. Outputs: go-auth activity adapter.

• NewSharedActivitySinks(primary admin.ActivitySink, hooks dashboardactivity.Hooks, cfg dashboardactivity.Config, opts ...GoAuthActivitySinkOption) SharedActivitySinks - Inputs: primary sink + dashboard hooks/config. Outputs: shared admin/go-auth sinks.

• NewFormGenerator(openapiFS fs.FS, templatesFS fs.FS, opts ...FormGeneratorOption) (*formgenorchestrator.Orchestrator, error) - Inputs: OpenAPI FS, templates FS, optional configuration. Outputs: form generator orchestrator and error.

• WithComponentRegistry(reg *components.Registry) FormGeneratorOption - Inputs: custom registry; outputs: option that replaces default components (clean replace).

• WithComponentRegistryMergeDefaults(reg *components.Registry) FormGeneratorOption - Inputs: custom registry; outputs: option that merges into defaults, overriding matching names.

• WithVanillaOption(opt formgenvanilla.Option) FormGeneratorOption - Inputs: vanilla renderer option; outputs: option applied last so it can override templates/styles/registry.

• The form generation guide covers the end-to-end form generation pipeline, UI schema overlays, component registration, submission parsing, and nested-array update-intent contract.

• DefaultSecureLinkConfig(basePath string) SecureLinkConfig - Inputs: base path; outputs: securelink defaults.

• DefaultSecureLinkRoutes(basePath string) map[string]string - Inputs: base path; outputs: securelink routes map.

• NewSecureLinkManager(cfg SecureLinkConfig) (types.SecureLinkManager, error) - Inputs: securelink config; outputs: go-users securelink manager.

• NewNotificationsSecureLinkManager(cfg SecureLinkConfig) (links.SecureLinkManager, error) - Inputs: securelink config; outputs: go-notifications securelink manager (delegates to go-notifications/adapters/securelink.NewManager).

• ApplySecureLinkManager(cfg *userssvc.Config, manager types.SecureLinkManager, opts ...SecureLinkUsersOption) - Inputs: go-users config + manager; outputs: config mutated with securelink routes/manager.

• NewSecureLinkNotificationBuilder(manager links.SecureLinkManager, opts ...linksecure.Option) links.LinkBuilder - Inputs: notification manager + options; outputs: notification link builder.

• RegisterOnboardingRoutes(r router.Router[T], cfg admin.Config, handlers OnboardingHandlers, opts ...OnboardingRouteOption) error - Inputs: router/config/handlers; outputs: error (registers onboarding API routes; public registration and password-reset mutations require the browser-bound CSRF token/cookie/origin contract).

• RegisterUserMigrations(client *persistence.Client, opts ...UserMigrationsOption) error - Inputs: persistence client + options; outputs: error (registers go-auth/go-users/go-notifications migrations using canonical profiles + source labels).

Routing policy overrides

Quickstart exposes the admin/routing policy directly. Host roots and per-module mount overrides remain explicit, and startup logs plus doctor output now include effective roots, resolved module mounts, and conflicts.

Release policy for quickstart matches core:

• mounted modules must expose RouteContract() routing.ModuleContract
• routing validation is strict fail-fast in every environment
• public API exposure is opt-in through PublicAPIRoutes
• the supported diagnostics surfaces are adm.RoutingReport(), adm.RoutingPlanner().Manifest(), startup logs, and the quickstart.routing doctor check

The routing guide covers the published external-module contract, manifest-diff workflow, and PR review guidance.

cfg := quickstart.NewAdminConfig(
	"/admin",
	"Admin",
	"en",
	quickstart.WithRoutingConfig(routing.Config{
		Roots: routing.RootsConfig{
			AdminRoot:     "/control",
			APIRoot:       "/ops/admin/api",
			PublicAPIRoot: "/api/v2",
		},
		Modules: map[string]routing.ModuleConfig{
			"preferences": {
				Mount: routing.ModuleMountOverride{
					UIBase: "/control/workbench/preferences",
				},
			},
			"partner_tools": {
				Mount: routing.ModuleMountOverride{
					UIBase:  "/control/workbench/partner-tools",
					APIBase: "/ops/admin/api/modules/partner-tools",
				},
			},
		},
	}),
)

External-style modules keep declaring relative contracts and let the host compute absolute paths:

type PartnerToolsModule struct{}

func (*PartnerToolsModule) Manifest() admin.ModuleManifest {
	return admin.ModuleManifest{ID: "partner.tools"}
}

func (*PartnerToolsModule) RouteContract() routing.ModuleContract {
	return routing.ModuleContract{
		Slug: "partner_tools",
		UIRoutes: map[string]string{
			"partner_tools.index": "/",
		},
		APIRoutes: map[string]string{
			"partner_tools.ping": "/ping",
		},
	}
}

func (*PartnerToolsModule) Register(ctx admin.ModuleContext) error {
	ctx.Router.Get(ctx.Routing.RoutePath(routing.SurfaceUI, "partner_tools.index"), handler)
	ctx.ProtectedRouter.Get(ctx.Routing.RoutePath(routing.SurfaceAPI, "partner_tools.ping"), apiHandler)
	return nil
}

Fiber runtime route options can relax adapter behavior for path matching, but they do not disable admin/routing startup validation. Route ownership and path conflicts still fail before router mutation.

Protected app quickstart

Protected-app support extends the existing host-router surface model instead of introducing a second application container.

• Enable it explicitly with cfg.Routing.ProtectedAppEnabled = true.
• Omit roots to use the canonical defaults /app and /app/api.
• Root overrides are only active when ProtectedAppEnabled is true; stale /app values do not reserve the surface by themselves.
• Map host runtime config such as protected_app.enabled, protected_app.root, and protected_app.api_root into cfg.Routing; quickstart does not read app.json directly.
• Use host.ProtectedAppUI() and host.ProtectedAppAPI() for explicit route ownership.
• Use WithProtectedAppAuth(...) for browser/API auth semantics on /app and /app/api.
• Use quickstart/protectedapp helpers for shell registration, bundle mounting, reserved-prefix derivation, and SPA history fallback.

Example:

cfg := quickstart.NewAdminConfig("/admin", "Admin", "en")
cfg.Routing.ProtectedAppEnabled = true

host := quickstart.NewHostRouter(server.Router(), cfg)

host.ProtectedAppAPI().Get("/app/api/me", apiHandler)

appAuth := quickstart.WithProtectedAppAuth(routeAuth, authCfg)
host.ProtectedAppUI().Get("/app/settings", appAuth.WrapHandler(settingsPage))

if err := protectedapp.RegisterShell(host.ProtectedAppUI(), cfg, appAuth.WrapHandler(appShell)); err != nil {
	panic(err)
}
if err := protectedapp.MountBundle(host.Static(), cfg, "/app/assets", "./dist"); err != nil {
	panic(err)
}
if err := protectedapp.RegisterHistoryFallback(
	host.ProtectedAppUI(),
	cfg,
	appAuth.WrapHandler(appShell),
	"/app/assets",
	"/admin",
	"/api",
	"/static",
	"/.well-known",
); err != nil {
	panic(err)
}

Notes:

• Existing hosts that do not enable protected-app routing keep their current /app behavior unchanged.
• admin.WithProtectedSurfaceRoots(...) inherits canonical roots for the side you do not override, so partial overrides keep browser/API split semantics intact.
• protectedapp.RegisterHistoryFallback(...) is intended for Fiber-backed quickstart hosts. On httprouter-backed hosts, use explicit app routes instead of the SPA history-fallback helper.
• quickstart.BuildSessionUser(...) reads the authenticated actor/claims from the same protected-app request context, so app handlers can project session metadata without a second auth adapter.

Split deployment:

• The same primitives work if you split surfaces later. A public-site deployment only mounts PublicSite() plus site fallback. A protected-app deployment mounts ProtectedAppUI(), ProtectedAppAPI(), and WithProtectedAppAuth(...). An admin deployment mounts AdminUI(), AdminAPI(), and the existing admin auth wiring.
• Keep the configured roots aligned across deployments. The public site should still reserve the protected-app and admin prefixes, while the protected-app deployment should own its own /app and /app/api surfaces directly instead of reintroducing a different routing model.

Command routing

Quickstart defaults to inline command execution. To opt into queued execution, configure policy and queue wiring explicitly.

RPC transport hardening defaults

• RPC transport is opt-in (WithRPCTransport).
• When enabled, quickstart requires an authenticator by default and fails startup when RPC routes are mounted if missing.
• Unauthenticated RPC transport must be opted into explicitly with allow_unauthenticated=true.
• Discovery route mounting is disabled by default (discovery_enabled=false).
• Admin command RPC dispatch is deny-by-default until command rules are configured (command_rules / commands.rpc.commands).
• Command RPC permission checks use resource-role authorization by default. Set permission_mode=exact on the transport or individual command rules when commands require explicit grants such as operational permissions.

The RPC guide covers the full transport, command dispatch, and workflow RPC contract.

Dev inline (default)

adm, _, err := quickstart.NewAdmin(
	cfg,
	quickstart.AdapterHooks{},
	quickstart.WithCommandExecutionPolicy(admin.CommandExecutionPolicy{
		DefaultMode: command.ExecutionModeInline,
	}),
)

Dev local queue (same process API + worker)

queueRegistry := queuecommand.NewRegistry()
_ = commandregistry.AddResolver("queue", queuecommand.QueueResolver(queueRegistry))

queueStorage := queuepostgres.NewStorage(db)
queueAdapter := queuepostgres.NewAdapter(queueStorage)

adm, _, err := quickstart.NewAdmin(
	cfg,
	quickstart.AdapterHooks{},
	quickstart.WithCommandExecutionPolicy(admin.CommandExecutionPolicy{
		PerCommand: map[string]command.ExecutionMode{
			"documents.pdf.remediate": command.ExecutionModeQueued,
		},
	}),
	quickstart.WithCommandQueueRouting(quickstart.CommandQueueRoutingConfig{
		Enabled:  true,
		Enqueuer: queueAdapter,
		Registry: queueRegistry,
	}),
)
if err != nil {
	return err
}
if err := commandregistry.Start(context.Background()); err != nil {
	return err
}
worker, err := queuecommand.StartLocalWorker(context.Background(), queueAdapter, queueRegistry, queuecommand.LocalWorkerConfig{})
if err != nil {
	return err
}
defer worker.Stop(context.Background())

Prod remote worker (API process only)

queueRegistry := queuecommand.NewRegistry()
_ = commandregistry.AddResolver("queue", queuecommand.QueueResolver(queueRegistry))

queueStorage := queuepostgres.NewStorage(db)
queueAdapter := queuepostgres.NewAdapter(queueStorage)

adm, _, err := quickstart.NewAdmin(
	cfg,
	quickstart.AdapterHooks{},
	quickstart.WithCommandExecutionPolicy(admin.CommandExecutionPolicy{
		PerCommand: map[string]command.ExecutionMode{
			"documents.pdf.remediate": command.ExecutionModeQueued,
		},
	}),
	quickstart.WithCommandQueueRouting(quickstart.CommandQueueRoutingConfig{
		Enabled:  true,
		Enqueuer: queueAdapter,
		Registry: queueRegistry,
	}),
)
if err != nil {
	return err
}
if err := commandregistry.Start(context.Background()); err != nil {
	return err
}

Run workers in a separate process with the same queue adapter + command registry wiring (queuecommand.RegisterAll/StartLocalWorker).

Translation quickstart modules keep their existing async options and can now reuse command policy primitives:

• TranslationExchangeConfig.CommandExecutionMode
• TranslationQueueConfig.CommandExecutionMode

Command routing observability

When using queued routing (for example documents.pdf.remediate), quickstart emits structured dispatch logs with canonical routing fields:

• command_id
• execution_mode
• dispatch_id
• correlation_id
• accepted

Host applications should expose command and domain counters from their own observability package and keep raw secrets and idempotency material out of metric labels.

User management

Quickstart can wire go-users repositories and expose the built-in users module. The users feature flag is enabled by default in DefaultAdminFeatures(); if you disable it, the users module is skipped and user/role endpoints return FeatureDisabledError.

Use WithGoUsersUserManagement to provide the required repositories (AuthRepo, InventoryRepo, RoleRegistry) and optional ProfileRepo + ScopeResolver. This wires UserRepository, RoleRepository, and (when provided) ProfileStore. When ScopeResolver is omitted, quickstart uses ScopeBuilder(cfg) so single-tenant defaults apply to the standard go-users user, role, and profile adapters. Explicit resolvers still win.

Bulk role operations should use panel bulk routes (/panels/:panel/bulk/:action, e.g. /admin/api/panels/users/bulk/assign-role). Legacy static routes are not part of bootstrap. If a migration window still requires them, register the compatibility routes explicitly before the router seals:

if err := quickstart.RegisterUserRoleBulkRoutes(host.Admin(), cfg, adm); err != nil {
	return err
}

Quickstart Fiber defaults use prefer_static path conflict resolution, so absolute static routes (for example /users/bulk/assign-role) can coexist with wildcard siblings (for example /users/bulk/:action) deterministically. Override path conflict behavior with WithFiberAdapterConfig(...). Quickstart also defaults Fiber request-header ReadBufferSize to 16KB; override with WithFiberConfig(...) when your deployment needs a different limit.

cfg := quickstart.NewAdminConfig("/admin", "Admin", "en")

adm, _, err := quickstart.NewAdmin(
\tcfg,
\tquickstart.AdapterHooks{},
\tquickstart.WithGoUsersUserManagement(quickstart.GoUsersUserManagementConfig{
\t\tAuthRepo:      authRepo,
\t\tInventoryRepo: inventoryRepo,
\t\tRoleRegistry:  roleRegistry,
\t\tProfileRepo:   profileRepo,   // optional
\t\tScopeResolver: scopeResolver, // optional; omitted uses quickstart.ScopeBuilder(cfg)
\t}),
)
if err != nil {
\treturn err
}

_ = adm.RegisterModule(quickstart.NewUsersModule(
\tadmin.WithUserMenuParent("main"),
\tadmin.WithUserProfilesPanel(), // opt-in managed profiles panel
\tadmin.WithUserPanelTabs(admin.PanelTab{
\t\tID:     "activity",
\t\tLabel:  "Activity",
\t\tScope:  admin.PanelTabScopeDetail,
\t\tTarget: admin.PanelTabTarget{Type: "path", Path: "/admin/users/:id/activity"},
\t}),
))

The managed profiles panel and activity tab are opt-in; omit WithUserProfilesPanel or WithUserPanelTabs to keep the default users panel.

All user management URLs should resolve via URLKit (admin namespace). Defaults:

• adm.URLs().Resolve("admin.users") -> /admin/users
• adm.URLs().Resolve("admin.roles") -> /admin/roles
• Panel API collection endpoints are canonical under /admin/api/panels/<panel> (for example /admin/api/panels/users, /admin/api/panels/roles).
• Panel API detail endpoints are canonical under /admin/api/panels/<panel>/<id>.
• adm.URLs().Resolve("admin.user_profiles") -> /admin/user-profiles (when the profiles panel is enabled)

Panel entry behavior:

• Canonical panel UI routes (registered by RegisterContentEntryUIRoutes) now honor PanelBuilder.WithEntryMode(...).
• RegisterContentEntryUIRoutes must register concrete canonical routes before the generic /content/:name/* handlers. Reordering them can cause paths like /admin/content/documents/new to be captured by the generic matcher and skip the intended browser handler.
• profile defaults to admin.PanelEntryModeDetailCurrentUser, so GET /admin/profile resolves to the current user detail view instead of the profile datagrid/list.
• Successful profile create-as-update and update submissions return to the canonical route with saved=1, preserving channel and requested locale. WithContentEntryPostCreatePolicy still runs once after create and may add query state, but cannot replace the singleton destination or reserved state.
• Panels without explicit entry mode use admin.PanelEntryModeList.

To opt a panel into a different canonical entry point:

usersModule := quickstart.NewUsersModule(
	admin.WithUsersPanelConfigurer(func(builder *admin.PanelBuilder) *admin.PanelBuilder {
		if builder == nil {
			return nil
		}
		return builder.WithEntryMode(admin.PanelEntryModeDetailCurrentUser)
	}),
)
_ = usersModule

Bulk role routes are auto-registered by quickstart when users is enabled:

• adm.URLs().Resolve("admin.api.users.bulk.assign_role") -> /admin/api/users/bulk/assign-role
• adm.URLs().Resolve("admin.api.users.bulk.unassign_role") -> /admin/api/users/bulk/unassign-role

Translation exchange (opt-in)

Translation exchange is disabled by default in quickstart. Enable it explicitly with WithTranslationExchangeConfig(...).

Translation product profiles

Quickstart supports one product-level translation entry point:

quickstart.WithTranslationProductConfig(quickstart.TranslationProductConfig{
	SchemaVersion: 1, // defaults to 1
	Profile:       quickstart.TranslationProfileCore, // default for cms-enabled apps
	Exchange:      nil, // optional module override
	Queue:         nil, // optional module override
})

Supported profiles:

• none
• core
• core+exchange
• core+queue
• full

Deterministic precedence order:

1. Profile baseline (core default when cms is enabled, otherwise none).
2. Product module overrides (TranslationProductConfig.Exchange / Queue).
3. Legacy options (WithTranslationExchangeConfig, WithTranslationQueueConfig) as final compatibility overrides.

When exchange is enabled through profiles, quickstart still validates that required exchange handlers are configured. If cms is disabled, any effective profile/module enablement other than none fails startup with a typed translation product config error. Quickstart publishes resolved translation metadata to both:

• quickstart.TranslationCapabilities(adm) for backend/example wiring.
• translation_capabilities in UI route view context and quickstart.WithNav(...) context for template/frontend gating.
• Startup diagnostics log event: translation.capabilities.startup (INFO) with profile, schema_version, module enablement, feature flags, routes, panels, resolver keys, and warnings.
• Validation failures log translation.capabilities.startup (ERROR) with deterministic fields: error_code, error_message, hint, failed_checks.
• SchemaVersion=0 is treated as a supported legacy input and normalized to schema version 1 with warning translation.productization.schema.upconverted.
• Explicit translation module feature overrides in WithFeatureDefaults are honored (translations.exchange, translations.queue) before dependency validation.
• dashboard=false only suppresses dashboard exposure; it does not disable translation policy enforcement or queue/exchange wiring by itself.

Migration and compatibility contract

Product wiring and legacy manual wiring can coexist during migration.

• Conflict handling is deterministic: legacy module options are applied after profile + product module overrides.
• Mixed product+legacy usage emits warning translation.productization.legacy_override.
• Switching to product config changes runtime wiring source only and must not mutate persisted translation records, exchange artifacts, or queue assignments.
• Legacy manual wiring options remain supported for at least two minor releases after product API GA.

The CMS guide contains the detailed translation productization contract and rollout rules.

Minimal in-process wiring:

adm, _, err := quickstart.NewAdmin(
	cfg,
	quickstart.AdapterHooks{},
	quickstart.WithTranslationExchangeConfig(quickstart.TranslationExchangeConfig{
		Enabled: true,
		Store:   translationExchangeStore, // implements admin.TranslationExchangeStore
	}),
)
if err != nil {
	return err
}

Optional permission registration:

err := quickstart.RegisterTranslationExchangePermissions(func(def quickstart.PermissionDefinition) error {
	// host permission catalog integration
	return permissionRegistry.Register(def.Key, def.Description)
})

Permission ownership:

• Quickstart defines and can register translation permission keys into a host permission catalog.
• Quickstart does not create roles or assign permissions to users.
• The host application must seed/assign permissions for every role that should access exchange/queue routes.
• Exchange endpoints require:
  • admin.translations.export -> POST /admin/api/translations/exchange/export
  • admin.translations.import.view -> GET /admin/api/translations/exchange/template
  • admin.translations.import.validate -> POST /admin/api/translations/exchange/import/validate
  • admin.translations.import.apply -> POST /admin/api/translations/exchange/import/apply

Optional async apply integration for production workers:

quickstart.WithTranslationExchangeConfig(quickstart.TranslationExchangeConfig{
	Enabled: true,
	Store:   translationExchangeStore,
	AsyncApply: func(ctx context.Context, input admin.TranslationImportApplyInput) (admin.TranslationExchangeResult, error) {
		// enqueue job in external worker and return queued contract
		return admin.TranslationExchangeResult{
			Summary: admin.TranslationExchangeSummary{
				Processed: len(input.Rows),
			},
			Metadata: map[string]any{"queued": true},
		}, nil
	},
})

Exchange contract and trigger reuse

Exchange adapters should preserve one command contract across HTTP, CLI, and jobs.

HTTP routes:

• POST /admin/api/translations/exchange/export
• GET /admin/api/translations/exchange/template
• POST /admin/api/translations/exchange/import/validate
• POST /admin/api/translations/exchange/import/apply

Row linkage fields (rows[*]):

• resource
• entity_id
• family_id
• target_locale
• field_path

Safety semantics:

• Run validate before apply.
• apply never auto-publishes imported rows.
• Missing locale variants require explicit create intent (create_translation).
• source_hash mismatch is a typed row conflict unless explicitly overridden.
• Duplicate linkage rows in one payload produce deterministic row conflicts and do not write duplicate changes.

Trigger command names:

• admin.translations.exchange.import.run (typed run command)
• jobs.translations.exchange.import.run (cron/manual trigger)

Job wrapper:

• examples/web/jobs.NewTranslationImportRunJob(...) builds a cron trigger command that dispatches the same typed run message contract.

Grouped translation-family lists

Quickstart grouped translation UX expects sibling locale rows to exist as real list records.

Behavior:

• locale=en stays locale-scoped.
• locale=all requests wildcard list reads for translation-enabled panels.
• group_by=family_id groups already-expanded sibling rows into one family row with locale children.
• family_id=<id> without an explicit locale returns all siblings for that family.

This contract applies to both structured content panels and page-backed panels when their repositories/read adapters use the CMS translation-family expansion path.

Translation queue (opt-in)

Translation queue is disabled by default in quickstart. Enable it with WithTranslationQueueConfig(...).

Minimal wiring:

policyCfg := quickstart.TranslationPolicyConfig{
	Required: map[string]quickstart.TranslationPolicyEntityConfig{
		"catalog_items": {
			"publish": {Locales: []string{"en", "es"}},
		},
	},
}

adm, _, err := quickstart.NewAdmin(
	cfg,
	quickstart.AdapterHooks{},
	quickstart.WithTranslationPolicyConfig(policyCfg),
	quickstart.WithTranslationQueueConfig(quickstart.TranslationQueueConfig{
		Enabled: true,
		// Optional: provide repository/service overrides.
		// Repository: admin.NewInMemoryTranslationAssignmentRepository(),
	}),
)
if err != nil {
	return err
}

Locale alignment rule:

• If supported_locales is omitted, quickstart derives queue locales from active translation policy requirements.
• If supported_locales is explicitly set and policy locales are available, sets must match exactly or startup fails with ErrTranslationQueueConfig.

Optional permission registration:

err := quickstart.RegisterTranslationQueuePermissions(func(def quickstart.PermissionDefinition) error {
	return permissionRegistry.Register(def.Key, def.Description)
})

Queue permission map:

• admin.translations.view -> queue list/detail read access.
• admin.translations.assign -> queue create/new and assign/release actions.
• admin.translations.edit -> submit-review/update flows.
• admin.translations.approve -> approve/reject review actions.
• admin.translations.manage -> archive/manage/bulk lifecycle actions.
• admin.translations.claim -> claim open-pool assignments.

Auth note:

• Non-CRUD permissions (for example admin.translations.export and admin.translations.assign) are checked as explicit permission strings.
• After changing role permissions, reload the page so permission checks and diagnostics reflect current role assignments.

URL configuration

Quickstart defaults still mount admin under /admin and the public API under /api/v1, but the canonical URL surface now lives in cfg.URLs.

Example:

cfg := quickstart.NewAdminConfig("/admin", "Admin", "en")
cfg.URLs.Admin.BasePath = "/control"
cfg.URLs.Admin.APIPrefix = "api"
cfg.URLs.Public.APIVersion = "v2"

If you need full control, set cfg.URLs.URLKit to a custom URLKit config and use adm.URLs() for template helpers and route registration.

For panel-backed navigation targets, prefer canonical panel URL helpers instead of hardcoded paths:

• quickstart.ResolveAdminPanelURL(adm.URLs(), cfg.BasePath, "<panel>")

The helper resolves the canonical panel entry URL. When a panel opts into PanelEntryModeDetailCurrentUser, that same URL opens detail for the current authenticated user.

Scope defaults (single vs multi-tenant)

Quickstart can enforce a single-tenant default scope or require explicit tenant/org claims for multi-tenant projects.

Modes:

• single (default): injects default tenant/org IDs when claims are missing.
• multi: never injects defaults; scope must come from auth claims/metadata.

The standard WithGoUsersUserManagement path uses these rules automatically when ScopeResolver is omitted. Custom repositories, handlers, or direct go-users registry calls must use quickstart.ScopeBuilder(cfg) or an equivalent config-aware resolver themselves.

The authentication and permissions guide covers the broader role, scope, debug console, doctor, and permissions-panel workflow.

go-admin request and service paths should resolve trusted tenant/org scope through Admin.EffectiveScope(...) or Admin.EffectiveScopeFromRequest(...). These helpers preserve explicit trusted scope, apply configured defaults only in single-tenant mode, and ignore browser query tenant_id / org_id values for authenticated actor scope. Repository code should receive the resolved scope and apply explicit predicates; do not add global persistence hooks that inject scope into every query.

Defaults:

• tenant: 11111111-1111-1111-1111-111111111111
• org: 22222222-2222-2222-2222-222222222222

Explicit config:

cfg := quickstart.NewAdminConfig("/admin", "Admin", "en",
	quickstart.WithScopeConfig(quickstart.ScopeConfig{
		Mode:            quickstart.ScopeModeSingle,
		DefaultTenantID: "11111111-1111-1111-1111-111111111111",
		DefaultOrgID:    "22222222-2222-2222-2222-222222222222",
	}),
)

Quickstart registers a quickstart.scope_drift doctor check for single-tenant translation data. Hosts can wire it with:

adm, _, err := quickstart.NewAdmin(
	cfg,
	hooks,
	quickstart.WithScopeDriftInspector(quickstart.NewBunScopeDriftInspector(db)),
)

The check inspects the allowlisted translation tables content_families, locale_variants, family_blockers, and translation_assignments for blank tenant/org rows. It reports counts and default scope metadata, skips multi-tenant mode, reports unavailable/missing tables as informational findings, and never mutates data.

When the same Bun inspector is wired, quickstart also registers the explicit command quickstart.scope_drift.repair. Dispatch without apply to dry-run the allowlisted tables; dispatch with apply: true to backfill blank tenant/org values to the configured single-tenant defaults. Apply mode rejects multi-tenant configurations and never updates tables outside the allowlist.

Explicit Fiber v3 host and presentation

NewFiberV3ViewEngine, DefaultFiberV3TemplateFuncs and WithViewFiberV3TemplateFuncs use the go-router Fiber v3 contracts and are available without build tags. Existing NewViewEngine and v2 host defaults remain unchanged. NewFiberV3ErrorHandler shares the v2 HTML/API presentation policy and accepts the same FiberErrorHandlerOption values, including custom error mappers. WithDefaultFiberV3DashboardRenderer installs typed dashboard SSR on the shared v3 views while preserving an existing renderer.

views, err := quickstart.NewFiberV3ViewEngine(
    client.Templates(),
    quickstart.WithViewBasePath("/admin"),
    quickstart.WithViewFeatureGate(featureGate),
    quickstart.WithViewTranslator(translator),
    quickstart.WithViewReload(false),
)
if err != nil { return err }
// The explicit host installs the shared HTML/API error policy by default.
server, routes := quickstart.NewFiberV3Server(views, cfg, adm, isDev)
// Install the renderer before Admin initialization when the host needs dashboard SSR.
err = quickstart.WithDefaultFiberV3DashboardRenderer(adm, views, cfg)

WithFiberV3ErrorHandler and native WithFiberV3Config overrides remain authoritative. Register authentication, admin routes and assets before initialization, then start with server.Serve(address). WithFiberV3AdapterConfig forwards native ListenConfig through Serve; callers starting server.WrappedRouter() directly must supply their native listener/TLS/hook settings themselves.

Hosts own long-lived sessions. Cancel the contexts assigned to dashboard WebSocket and SSE requests, wait for their handlers/subscriptions to finish, then call server.Shutdown(ctx) with the caller's bounded context. The admin-shell shutdown coordinator drains the native server before lifecycle hooks and shared-resource release; wrap its server shutdown operation with stream cleanup. If the deadline expires, retain shared resources and retry cleanup after remaining requests finish. Native server shutdown alone does not establish WebSocket cleanup.

The maintained TestFiberCandidateHostIntegration, TestFiberCandidateHostLifecycle and TestFiberCandidateHostStartupFailure tests under examples/admin-shell/internal/core exercise both native hosts on real local listeners. They verify candidate package composition; publication and application adoption remain separate steps.

The same filesystem, overlay, asset, admin-lookup, translation and ordinary helper options work on both constructors. The v3 engine registers tojson locally and retains its JSON/null fallback and escaping behavior across reloads. Feature and CSRF helpers retain their names and policies through native v7 helper signatures. Request context stays in render-local helper closures rather than becoming an object exposed to templates; configured context keys, scope, cancellation and snapshots remain available to the helpers.

Synthetic route-miss diagnostics require an explicit terminal fallback. For a standalone native app, register app.Use(quickstart.NewFiberV3RouteMissHandler(cfg)) last, after all application routes and middleware (v2 uses NewFiberRouteMissHandler). With a go-router adapter, call server.Init() first so deferred routes and assets are registered, then append the native fallback. NewFiberServer and NewFiberV3Server do this automatically during initialization; configure native middleware through their options before Init, WrappedRouter or Serve.

The fallback marks only owned admin misses reached at the end of routing and retains native method-not-allowed behavior. Error presentation preserves direct and wrapped middleware errors. Without the terminal fallback, a standalone app still presents native 404s with their original diagnostics; sentinel identity and message text alone never establish a synthetic miss.

Keep WithViewTemplateFuncs(shared) for the shared/v2 map. Add WithViewFiberV3TemplateFuncs(v7Overrides) for application helpers using v7 Value or execution-context types under the same template names. Overrides do not modify the shared map or affect v2. Arbitrary v6 tags and boxed values are not translated; port their Go implementations explicitly. Additional v7 filters and tags can register on the returned router.FiberV3ViewExtensions interface.

Use the repository workspace and the published dependencies declared in go.mod. From quickstart:

go test -race . -run '^TestFiberPresentation|^TestFiberV3|^TestDashboard' -count=1
go run ./examples/fiber-v3-presentation -addr 127.0.0.1:3001

Open /admin for the standalone preview; ?state=empty, /admin/denied, /admin/failure, /admin/api/denied and /admin/redirect exercise presentation states. The example embeds its page overlay and stylesheet and serves packaged admin assets through NewStaticAssets. It supplies the T00 presentation ports without using the quickstart server constructor. It is a local presentation sample, not an authenticated production host or evidence of final host acceptance. Existing v2 examples are retained.

The parity tests compare the real login, users, translations, activity, feature-flags, media and dashboard templates against v2. Native HTTP checks cover HTML/API status, correlation, cookies, explicit redirects, theme/partial overlays, failed-render fallback, safe locals, CSRF helpers and concurrent request isolation. Asset tests verify matching helper output, GET/HEAD bytes, fallback precedence and missing files; the example has a real HTTP listener smoke test. Final host defaults, authenticated integration, lifecycle validation and publication remain separate.

Template functions

NewViewEngine wires DefaultTemplateFuncs() when no template functions are supplied. Prefer WithViewURLResolver(adm.URLs()) (or WithTemplateURLResolver(adm.URLs())) so adminURL resolves via URLKit; WithViewBasePath(cfg.BasePath) remains as a fallback for legacy setups. WithViewTemplateFuncs is a strict override; use MergeTemplateFuncs if you want to keep defaults and add/override a subset. The go-router Pongo2 engine treats these helpers as functions (globals), not filters, so call them like {{ singularize(resource_label|default:resource)|title }} instead of {{ resource_label|singularize }}.

adminURL is available by default. Use it for admin-relative links and admin-hosted assets such as {{ adminURL("login") }} or {{ adminURL("assets/dist/dashboard/index.js") }}. When a template intentionally supports a separate asset host or CDN, prefer asset_base_path instead of adminURL.

Template function options let you override widget title labels without touching the core map:

• WithWidgetTitleOverrides(overrides map[string]string) TemplateFuncOption - merges label overrides into defaults.
• WithWidgetTitleMap(titles map[string]string) TemplateFuncOption - replaces the default map entirely.
• WithWidgetTitleFunc(fn func(string) string) TemplateFuncOption - provides a custom resolver.
• Widget definition constants are available via constants such as admin.WidgetUserProfileOverview.
• WithTemplateBasePath(basePath string) TemplateFuncOption - sets the fallback base path used by the adminURL helper.
• WithTemplateURLResolver(urls urlkit.Resolver) TemplateFuncOption - configures the URLKit resolver used by adminURL.
• WithTemplateFeatureGate(gate fggate.FeatureGate, opts ...fgtemplates.HelperOption) TemplateFuncOption - registers feature gate template helpers (featureEnabled, featureDisabled, etc.) from go-featuregate.
• WithTemplateIconRenderer(renderFunc func(ref string, variant string) string) TemplateFuncOption - injects a custom icon renderer for renderIcon and renderIconVariant helpers; if not provided, templates use the built-in legacy icon rendering.

funcs := quickstart.MergeTemplateFuncs(
	map[string]any{
		"titleize": strings.ToUpper,
	},
	quickstart.WithTemplateURLResolver(adm.URLs()),
	quickstart.WithTemplateBasePath(cfg.BasePath),
	quickstart.WithWidgetTitleOverrides(map[string]string{
		admin.WidgetUserProfileOverview: "Profile Overview",
	}),
)

views, err := quickstart.NewViewEngine(
	os.DirFS("./web"),
	quickstart.WithViewTemplateFuncs(funcs),
)
if err != nil {
	return err
}

UI routes

Quickstart includes opt-in helpers for common UI routes (admin shell, notifications, login/logout, password reset).

if err := quickstart.RegisterAdminUIRoutes(router, cfg, adm, authn); err != nil {
	return err
}

if err := quickstart.RegisterAuthUIRoutes(
	router,
	cfg,
	routeAuth,
	quickstart.WithAuthUILogoutAuthenticator(authn),
	quickstart.WithAuthUITitles("Login", "Password Reset"),
); err != nil {
	return err
}

if err := quickstart.RegisterRegistrationUIRoutes(
	router,
	cfg,
	quickstart.WithRegistrationUITitle("Register"),
); err != nil {
	return err
}

if err := quickstart.RegisterContentEntryUIRoutes(
	router,
	cfg,
	adm,
	authn,
	quickstart.WithContentEntryDataGridStateStore(quickstart.PanelDataGridStateStoreOptions{
		Mode: "preferences", // optional; default is local storage when unset
	}),
	quickstart.WithContentEntryDataGridURLState(quickstart.PanelDataGridURLStateOptions{
		MaxURLLength:     1800,
		MaxFiltersLength: 600,
	}),
); err != nil {
	return err
}

When canonical panel UI routes are active (PanelUIRouteModeCanonical), the base panel route (/admin/<panel>) uses the panel entry mode. For example, detail_current_user renders detail for the authenticated user; default mode remains list/datagrid.

Panel list template contract

For list templates rendered from quickstart panel/content-entry routes, use datagrid_config as the canonical contract for DataGrid wiring:

• datagrid_config.table_id
• datagrid_config.api_endpoint
• datagrid_config.action_base
• datagrid_config.preferences_endpoint (optional; resolved panel preferences API path)
• datagrid_config.column_storage_key
• datagrid_config.translation_ux_enabled (optional)
• datagrid_config.enable_grouped_mode, default_view_mode, group_by_field (optional)
• datagrid_config.state_store (optional: {mode, resource, sync_debounce_ms, hydrate_timeout_ms, max_share_entries})
• datagrid_config.url_state (optional: {max_url_length, max_filters_length, enable_state_token})
• datagrid_config.export_config

State persistence behavior:

• default mode is localStorage (state_store omitted or mode=local).
• optional preferences mode (mode=preferences) hydrates/syncs user state through /api/panels/preferences, with local cache fallback.
• URL sync writes compact query state; when limits are exceeded, DataGrid can fallback to state=<token> instead of writing large query payloads.

Compatibility keys (datatable_id, list_api, action_base, export_config) are still present for legacy templates, but new/updated templates should read from datagrid_config first.

The CRUD guide covers the full CRUD/DataGrid/action wiring contract. The search guide covers admin global search, public site search, go-search adapter wiring, application-defined variants, typed evidence and named counts, validated page-size policy, bounded filter-only execution, and panel DataGrid search distinctions. Optional search policy blocks are validated by site.RegisterSiteRoutes; nil blocks preserve legacy behavior.

Password reset UI defaults to two pages:

• Request: /admin/password-reset (template password_reset)
• Confirm: /admin/password-reset/confirm (template password_reset_confirm)

Override the confirm route or template with WithAuthUIPasswordResetConfirmPath and WithAuthUIPasswordResetConfirmTemplate.

Auth UI SSO provider context

The default login template reads optional sso_providers from auth UI view context. Integrations such as go-auth/adapters/goadmin can inject it with WithAuthUIViewContextBuilder(...); go-admin does not discover providers, configure OIDC, handle callbacks, or receive secrets.

Each provider entry is a display-safe map:

• key: stable non-secret provider identifier.
• label: required user-facing provider name.
• login_url: required begin-login URL for enabled providers.
• icon_class: optional CSS/icon class metadata.
• icon_url: optional image/icon asset URL.
• disabled_reason: optional non-secret reason for unavailable providers.

Entries without a usable label are ignored. Entries with label, login_url, and no disabled_reason render as sign-in links. Entries with a disabled_reason render disabled without href. A usable login_url is a non-empty relative URL or http/https URL without control characters; blank URLs and unsafe schemes never produce active links. Missing, empty, or fully malformed provider lists omit the SSO divider and provider section.

quickstart.WithAuthUIViewContextBuilder(func(ctx router.ViewContext, c router.Context) router.ViewContext {
	ctx["sso_providers"] = []map[string]any{
		{
			"key":       "acme",
			"label":     "Acme ID",
			"login_url": "/admin/auth/sso/acme",
		},
	}
	return ctx
})

Theme assets for auth UI

Auth and registration UI routes support theme assets (logo, icon, favicon) via dedicated options. Assets are exposed in templates as theme.assets.logo, theme.assets.icon, theme.assets.favicon, etc. Relative filenames are joined with the provided prefix; already resolved absolute URLs/paths are preserved.

Reserved branding semantics:

• logo: expanded sidebar / horizontal lockup
• icon: compact sidebar mark and auth-card icon
• favicon: browser/app icon

authThemeAssets := map[string]string{
	"icon":    "icon.svg",
	"logo":    "logo.svg",
	"favicon": "favicon.svg",
}
authThemeAssetPrefix := path.Join(cfg.BasePath, "assets")

if err := quickstart.RegisterAuthUIRoutes(
	router,
	cfg,
	routeAuth,
	quickstart.WithAuthUILogoutAuthenticator(authn),
	quickstart.WithAuthUITitles("Login", "Password Reset"),
	quickstart.WithAuthUIThemeAssets(authThemeAssetPrefix, authThemeAssets),
); err != nil {
	return err
}

if err := quickstart.RegisterRegistrationUIRoutes(
	router,
	cfg,
	quickstart.WithRegistrationUITitle("Register"),
	quickstart.WithRegistrationUIThemeAssets(authThemeAssetPrefix, authThemeAssets),
); err != nil {
	return err
}

For manual route handlers, use WithAuthUIViewThemeAssets to merge theme assets into the view context:

viewCtx := router.ViewContext{
	"title":     cfg.Title,
}
viewCtx = quickstart.WithPathViewContext(viewCtx, cfg, quickstart.PathViewContextConfig{
	BasePath: cfg.BasePath,
})
viewCtx = quickstart.WithAuthUIViewThemeAssets(viewCtx, authThemeAssets, authThemeAssetPrefix)
return c.Render("register", viewCtx)

Auth templates prefer theme.assets.icon when it exists and fall back to theme.assets.logo.

For non-auth/public handlers, prefer the same path helper before rendering templates that link JS/CSS assets:

viewCtx := quickstart.WithPathViewContext(nil, cfg, quickstart.PathViewContextConfig{
	BasePath:    cfg.BasePath,
	APIBasePath: "/api/v1/public",
})

Templates use a conditional fallback pattern:

{% if theme and theme.assets and theme.assets.logo %}
<img src="{{ theme.assets.logo }}" alt="Logo" class="w-10 h-10" />
{% else %}
<!-- inline SVG fallback -->
{% endif %}

CMS workflow defaults

Quickstart wires CMS workflows through the shared go-admin workflow system. This section covers startup helpers; the workflow guide covers the full workflow/state-machine contract.

To start from defaults and override only a subset, register defaults before your overrides or opt in to default registration on a custom engine:

workflow := admin.NewFSMWorkflowEngine()
admin.RegisterDefaultCMSWorkflows(workflow)
workflow.RegisterWorkflow("content", admin.WorkflowDefinition{
    EntityType:   "content",
    InitialState: "draft",
    Transitions: []admin.WorkflowTransition{
        {Name: "submit_for_approval", From: "draft", To: "approval"},
        {Name: "publish", From: "approval", To: "published"},
    },
})

adm, _, err := quickstart.NewAdmin(
    cfg,
    hooks,
    quickstart.WithAdminDependencies(admin.Dependencies{
        Workflow: workflow,
    }),
)
if err != nil {
    return err
}
adm.WithCMSWorkflowDefaults()

Workflow capability precedence for dynamic content panels:

1. workflow_id (aliases: workflowId, workflow-id)
2. legacy workflow
3. persisted workflow runtime binding (content_type, then trait, then global)
4. no workflow

Content type capability examples:

{
  "panel_traits": ["editorial"],
  "workflow_id": "editorial.news"
}

{
  "panel_traits": ["editorial"],
  "workflow": "editorial.default"
}

Migration guidance:

1. Keep legacy workflow keys initially.
2. Add runtime bindings for shared defaults.
3. Add explicit workflow_id for content types that must override defaults.
4. Remove legacy workflow after validation.

External workflow config (YAML/JSON) can be loaded at startup:

schema_version: 1
workflows:
  editorial.default:
    initial_state: draft
    transitions:
      - name: submit_for_approval
        from: draft
        to: approval
      - name: publish
        from: approval
        to: published
  editorial.news:
    initial_state: draft
    transitions:
      - name: submit_for_approval
        from: draft
        to: approval
      - name: publish
        from: approval
        to: published
bindings:
  - scope_type: trait
    scope_ref: editorial
    workflow_id: editorial.default
    priority: 100
    status: active

adm, _, err := quickstart.NewAdmin(
    cfg,
    hooks,
    quickstart.WithWorkflowConfigFile("workflow_config.yaml"),
)

Definitions are registered into the configured workflow engine during startup. Bindings are seeded when WithWorkflowRuntime(...) is also provided.

Validation fails fast with actionable field errors for:

• unsupported schema versions
• invalid workflow definitions (missing initial_state, transition fields, duplicate transition names)
• bindings referencing unknown workflow IDs

Persisted workflow runtime can be wired for dynamic workflow and binding management:

runtime := admin.NewWorkflowRuntimeService(
    admin.NewInMemoryWorkflowDefinitionRepository(),
    admin.NewInMemoryWorkflowBindingRepository(),
)

adm, _, err := quickstart.NewAdmin(
    cfg,
    hooks,
    quickstart.WithAdminDependencies(admin.Dependencies{
        Workflow: admin.NewFSMWorkflowEngine(),
    }),
    quickstart.WithWorkflowRuntime(runtime),
)

Runtime binding resolution order is:

1. content type binding
2. trait binding
3. global binding

Capability precedence is unchanged: explicit workflow_id/workflow on the content type still wins over persisted bindings.

Workflow management API endpoints:

• GET /admin/api/workflows
• POST /admin/api/workflows
• PUT /admin/api/workflows/:id (expected_version required for updates; rollback_to_version enables rollback)
• GET /admin/api/workflows/bindings
• POST /admin/api/workflows/bindings
• PUT /admin/api/workflows/bindings/:id (expected_version required)
• DELETE /admin/api/workflows/bindings/:id

The workflow guide covers operational migration, rollback, and persistence details.

CMS demo panels default to the submit_for_approval and publish actions. Override them with:

adm.WithCMSWorkflowActions(
    admin.Action{Name: "submit_for_approval", Label: "Submit for approval"},
    admin.Action{Name: "publish", Label: "Publish"},
)

Translation policy (workflow enforcement)

Quickstart can enforce translation completeness during workflow transitions (publish/promote). Provide a TranslationPolicyConfig via WithTranslationPolicyConfig; quickstart wires the default policy when the config is present (or when deny_by_default/required are set).

Config example (YAML/JSON):

translation_policy:
  deny_by_default: false
  required_fields_strategy: "error" # error|warn|ignore
  page_entities: ["landing_pages"] # optional: additional entities that use page checker
  entity_aliases:
    article: news
  required:
    landing_pages:
      publish:
        locales: ["en", "es"]
      promote:
        environments:
          staging:
            locales: ["en"]
          prod:
            locales: ["en", "es", "fr"]
    articles:
      publish:
        locales: ["en"]
        required_fields:
          en: ["title", "path"]

Behavior notes:

• required keys map to policy entities (panel slug or content type slug). If a payload includes policy_entity/policyEntity, it overrides the entity lookup.
• pages is the go-cms Pages service policy entity and uses the page checker by default; page is the backing content type slug used when page records are bridged through generic content APIs. Other entities use the content checker unless listed in page_entities; quickstart does not use a page checker as fallback for content entities or a content checker as fallback for page entities.
• Entity lookup is singular/plural tolerant (for example item vs items) using inflection-based matching against configured required keys.
• Use entity_aliases for irregular/legacy names that need explicit mapping.
• Transition names are the workflow transition names (publish, promote, etc.).
• If an environment match is present, it overrides transition-level locales/required_fields for that transition.
• required_fields is a map of locale → required field keys. If locales is empty but required_fields is set, locales are derived from the map keys.
• required_fields_strategy controls how unknown field keys are handled during validation (error, warn, ignore).
• deny_by_default=true blocks transitions when no requirements are configured for a transition.
• Every content type included in translation family readiness needs effective publish requirements. Use ValidateTranslationPolicyCoverage when hosts know the family content types at startup; an entity key without publish locales or required fields is not enough.
• The default policy needs page/content services that implement CheckTranslations. Quickstart discovers them from go-cms wiring when possible; use WithTranslationPolicyServices when the CMS container is not discoverable or when custom entity routing needs explicit page/content services.
• Family readiness is persisted by sync. After policy, checker-service, or CMS fixture changes, rerun family sync so content_families, locale_variants, and family_blockers match the current policy.
• policy_denied with details.reason=policy_unavailable means policy configuration or checker wiring is missing; it is not a missing-translation task for editors.
• The CMS guide covers the operational contract and troubleshooting workflow.

Wiring example:

policyCfg := quickstart.TranslationPolicyConfig{
	Required: map[string]quickstart.TranslationPolicyEntityConfig{
		"articles": {
			"publish": {Locales: []string{"en", "es"}},
		},
	},
}

if _, err := quickstart.ValidateTranslationPolicyCoverage(policyCfg, []string{"articles"}); err != nil {
	return err
}

adm, _, err := quickstart.NewAdmin(
	cfg,
	hooks,
	quickstart.WithTranslationPolicyConfig(policyCfg),
	// Use explicit services when go-cms checkers are not auto-discoverable.
	quickstart.WithTranslationPolicyServices(quickstart.TranslationPolicyServices{
		Pages:   pageService,
		Content: contentService,
	}),
)
if err != nil {
	return err
}

Theme selector + manifest

When using go-theme, pass the selector + manifest into quickstart so the Preferences UI can list available variants. The theme guide covers the full theme contract, resolution order, and payload shape.

selector, manifest, err := quickstart.NewThemeSelector(
	cfg.Theme,
	cfg.ThemeVariant,
	cfg.ThemeTokens,
	quickstart.WithThemeAssets(path.Join(cfg.BasePath, "assets"), map[string]string{
		"logo":    "logo.light.svg",
		"icon":    "icon.light.svg",
		"favicon": "favicon.svg",
	}),
)
if err != nil {
	return err
}

adm, _, err := quickstart.NewAdmin(
	cfg,
	hooks,
	quickstart.WithThemeSelector(selector, manifest),
)
if err != nil {
	return err
}
_ = adm

If you build the admin manually, call adm.WithAdminTheme(selector) and adm.WithThemeManifest(manifest) after initialization. Public-site theme selection is separate; attach it with quicksite.WithSiteTheme(selector) or SiteConfig.ThemeProvider.

The default quickstart manifest also exposes these sidebar brand aliases:

• sidebar-brand-max-height → admin.sidebar.brand-max-height
• sidebar-brand-max-width → admin.sidebar.brand-max-width
• sidebar-brand-collapsed-size → admin.sidebar.brand-collapsed-size
• sidebar-brand-align → admin.sidebar.brand-align

New manifests should prefer the canonical dotted keys. The aliases remain for compatibility and lose when the matching canonical key is present.

Use WithThemeAssets(...) for manifest-relative theme assets and WithThemeAssetURLs(...) / admin.Config.ThemeAssets for final resolved URL overrides supplied by host config.

If you have local CSS that forces the sidebar logo to width: 100%, remove that override and configure branding through logo, icon, and the sidebar brand tokens instead.

WithThemeManifest(...), WithThemeAssets(...), and WithThemeVariants(...) above are ThemeOption values passed to NewThemeSelector; WithThemeSelector(...) is the separate AdminOption passed to NewAdmin. Existing registered or explicit manifests win. Asset/variant options fill missing manifest fields and do not overwrite populated ones.

For explicit variants:

selector, manifest, err := quickstart.NewThemeSelector(
	cfg.Theme,
	cfg.ThemeVariant,
	cfg.ThemeTokens,
	quickstart.WithThemeVariants(map[string]theme.Variant{
		"light": {},
		"dark": {
			Tokens: map[string]string{
				"color.surface.canvas":     "#09090b",
				"color.surface.default":    "#18181b",
				"color.text.primary":       "#fafafa",
				"color.border.default":     "#3f3f46",
				"color.action.primary":     "#38bdf8",
				"admin.sidebar.background": "#09090b",
			},
		},
	}),
)

A base-only theme should provide a manifest with no named variants and a selector/provider that resolves an empty variant. The attached manifest is the Preferences option authority, so stale stored or preview variants are cleared to the base.

Quickstart propagates the same request-scoped query/header selection to admin views, DataGrid, dashboard pages/charts, panel and settings forms, and CMS content forms. Content-entry and roles rendering pass adm.FormTheme(ctx) to go-formgen, so portable and form.* semantic tokens cover container width, focus, invalid, disabled, readonly, loading, label/help/error, and responsive states. No semantic tokens preserve the existing renderer output.

Navigation may reference asset:<role> or theme:<role> and resolves the theme asset icon-<role>. Normal icon names also try icon-<normalized-name> before falling back to Iconoir/library/emoji rendering. Host sidebar overrides should preserve renderThemeMenuIcon(item.icon, theme.assets).

Shell-specific presentation options live on admin.Config:

• SidebarHideSearch removes the shared sidebar search slot.
• ExternalAssets overrides the Iconoir, simple-datatables, and ECharts document URLs while empty fields retain their published defaults.

NewStaticAssets separately mounts admin assets, go-formgen runtime/renderer assets, and go-dashboard ECharts/shell assets. Manifest paths are metadata; a prefix still needs a mounted route. See docs/GUIDE_THEME.md, docs/GUIDE_FORMGEN.md, and docs/GUIDE_DASHBOARD_WIDGETS.md for the complete semantic API and diagnostics contract.

Public-site theme precedence

For quickstart/site, the packaged theme should be the primary public-site HTML source and host-local wrappers should stay limited to compatibility glue. The supported diagnostics surfaces are:

• site_theme.manifest_partials plus site_theme.partials in request/view context
• site_theme.baseline for selected-versus-approved variant checks
• site.ResolveSiteThemeTemplateDiagnostics(...) for concrete template winner and shadowed-source reporting

When mounting template filesystems, label them so precedence diagnostics stay readable:

siteCfg.Views.TemplateFS = []fs.FS{
	site.LabelTemplateFS(themeFS, "garchen-archive-site", site.TemplateSourcePackagedTheme),
	site.LabelTemplateFS(hostOverlayFS, "host-overlay", site.TemplateSourceHostOverlay),
}

Use site.home.page when the public root route needs a dedicated homepage. If the host leaves SiteThemeConfig.Variant empty, the selector resolves the theme package defaultVariant; use SiteThemeConfig.BaselineVariant to warn when a downstream app forces a non-approved public baseline.

Public-site error rendering policy

quickstart/site supports ordered concrete and theme-backed HTML error templates while preserving the legacy ErrorTemplate, ErrorTemplatesByStatus, and ErrorTemplatesByCode fields. Explicit policy references run before the matching legacy candidates; selection remains code-specific, then status-specific, then generic fallback.

siteCfg.Views.ErrorPolicy = site.SiteErrorTemplatePolicy{
	ByStatus: map[int][]site.SiteTemplateRef{
		http.StatusNotFound: {
			{
				ThemeKey:        "site.error.404_page",
				DefaultTemplate: "site/error/404",
			},
		},
	},
	Fallback: []site.SiteTemplateRef{
		{Template: "site/error"},
	},
}

Theme keys resolve after request theme context is available through site_theme.manifest_partials and the existing aliases. A stable default is used only when the key is absent; unsafe or invalid resolved targets advance to the next reference. Every template attempt is rendered into an isolated router response capture, so missing templates and nested include failures cannot leak partial bytes into the selected fallback.

• site.RenderSiteErrorHTML is the HTML-only host API. Keep application-specific JSON negotiation and payloads in the host, then call the shared renderer for HTML.
• site.SiteErrorContextProvider lets registered site modules add safe localized fields after normal request context has run. Normal SiteModule.ViewContext methods are not rerun.
• Mutable map, slice, and array view data is recursively isolated between the request, providers, and render candidates. Opaque pointer/service values are passed through as read-only capabilities.
• Host-owned calls inherit the complete middleware request state; explicit State and ViewContext values overlay prepared theme, preview, locale, channel, and path context instead of replacing it wholesale.
• The base site_error model contains only normalized code, status, and locale/base-path-aware home_href. Providers own any visitor copy or compatibility projections.
• site.SiteErrorRenderObserver receives sanitized attempt/selection provenance without view data, rendered bytes, tokens, or stack traces. Observer panics cannot change the visitor response.
• site.ResolveSitePublicPath converts a canonical path into the configured locale/base-path public path and avoids duplicate locale prefixes.
• Locale-like single-segment canonical slugs are preserved when they belong to a different locale, so /bo remains a valid default-locale path while multi-segment localized inputs still normalize predictably.
• HEAD preserves the requested status and headers without a body. If every candidate fails, the response contains only the requested status.

Legacy configuration remains valid. Use ErrorPolicy when candidate ordering needs theme keys or multiple fallbacks; existing single-template fields do not require migration.

Public-site render cache

quickstart/site.NewRenderCacheRuntime(...) plus WithRenderCacheRuntime(...) is the canonical setup for anonymous rendered HTML caching on public CMS delivery routes. quickstart/site owns backend construction for the built-in memory and Valkey modes, policy, keying, eligibility, generation fencing, response replay, and unsafe-header filtering; host apps own rollout, host-specific policy inputs, and application-specific invalidation wiring.

• Use site.NewRenderCacheRuntime(ctx, cfg, policy) and carry the returned runtime through WithRenderCacheRuntime. This keeps the store, generation fence, policy, diagnostics, and request observers together. WithRenderCache(store, policy) remains available for compatible legacy integrations, but it cannot provide the complete generation-fence contract.
• site.RenderCacheConfig controls backend setup (memory or valkey), debug flags, fail-open/fail-closed startup behavior, tag-index requirements, capture limits, render version, and sanitized diagnostic config. site.RenderCachePolicy remains the public-site eligibility and keying policy.
• When runtime config and policy overlap, the runtime config is authoritative in the returned RenderCacheRuntime.Policy; use the incoming policy for host-specific eligibility inputs such as namespaces not represented in config, allowlists, auth cookie names, bypass predicates, template renderers, and stale revalidators.
• Valkey setup supports URL parsing, address fallback, username/password, DB selection, TLS, TLS skip verify, single-client mode, and disabled client-side cache. Startup diagnostics redact URL userinfo and credential-bearing query values.
• site.RegisterRenderCacheDebugPanel(runtime) registers the built-in site-render-cache debug panel backend. The debug console and toolbar include the matching built-in client renderer, so enabled hosts get the purpose-built panel instead of generic JSON.
• The runtime snapshot is process-local by design. It reports configured/active state, backend, status, scope, startup errors, sanitized config, capabilities, counters, latest cached metadata, observed key metadata, recent operations/errors, and the last clear command.
• Clear commands use the existing debug clear-panel transport and record results in the follow-up snapshot. Shared invalidation targets are exported as site.RenderCacheAllSiteTag and site.RenderCacheKeyPrefix; app-specific CMS invalidation should use the same values as the debug clear path.
• Standard go-router Fiber and HTTPRouter site contexts use router-backed response capture by default, so hosts do not need to provide RenderCachePolicy.TemplateRenderer for the common path.
• RenderCachePolicy.TemplateRenderer remains an optional override for tests, custom render stacks, and router contexts that cannot use non-committing template capture. Unsupported contexts bypass storage with an observable reason unless an override is configured.
• RenderCachePolicy.MaxCaptureBodySize defaults to router.DefaultMaxCapturedBodySize; oversized captures bypass storage and then use the normal template response path without committing a partial response.
• Cache hits replay stored site.RenderedSiteResponse values through the site-owned replay path. quickstart/site does not store or replay raw router.CapturedResponse values, so safe-header filtering, HEAD handling, debug headers, and freshness metadata stay under site-cache policy.
• RenderCachePolicy.StaleTTL enables stale-while-revalidate. Entries are stored for FreshTTL + StaleTTL; hits before FreshUntil report hit, hits through StaleUntil report stale and replay the stale response, and entries past StaleUntil are deleted and refreshed as misses. Use RenderCachePolicy.StaleRevalidator to schedule host-owned background regeneration without reusing a live router context. Stale revalidation is keyed per process so duplicate stale hits do not stampede one runtime, and callback panics are recovered.
• RenderCachePolicy.ExpirationMode and RenderCacheConfig.ExpirationMode accept site.RenderCacheExpirationFixed or site.RenderCacheExpirationSliding. Empty mode is fixed, preserving existing hit-time behavior with no renewal writes. Invalid values fail NewRenderCacheRuntime validation and are also rejected when a direct policy is passed to RegisterSiteRoutes.
• Sliding mode renews only fresh hits. It preserves the original CreatedAt, moves FreshUntil and StaleUntil using the effective policy, and resets the backend TTL to FreshTTL + StaleTTL. GET and HEAD hits renew the shared representation; stale hits keep their original deadlines and continue through stale-while-revalidate without renewal.
• Sliding renewal adds one backend write per fresh hit and can keep frequently accessed entries fresh indefinitely. Use it only with active mutation invalidation through tags, prefixes, render versions, or handler generation fences; fixed mode remains preferable when write amplification or natural expiry matters more.
• Built-in memory and Valkey runtimes support sliding renewal. A direct custom store must implement site.RenderCacheSetIfPresentStore; fail-open policy bypasses an unsupported store, while fail-closed policy returns the configured service-unavailable response. Renewal failures are reported separately from ordinary cache writes.
• Use RenderCachePolicy.AuthCookieNames for host-specific auth cookies and RenderCachePolicy.BypassPredicates for application-specific auth, session, tenant, cart, A/B, or personalization signals. Built-in checks already cover Authorization, admin authenticated request context, go-auth claims/actor context, and common session/JWT cookie names such as session_id and jwt.
• quickstart/render_cache_gocache_compat_test.go compiles and exercises a real github.com/goliatone/go-cache/stores/memory store as a site.RenderCacheStore, including local tag API compatibility. The higher-level runtime API imports go-cache so hosts do not need to duplicate memory/Valkey construction.
• Use RenderCachePolicy.RequireTagIndex: true only with a shared non-memory backend for production tag invalidation. With this guard enabled, memory backends bypass caching, stores must implement site.RenderCacheBackendDescriber with a non-memory backend kind, stores without site.RenderCacheTagInvalidator bypass caching, and tag attachment failures remove the just-written entry before it can be served.
• Every runtime includes a generation store. Generic public delivery automatically keys against site.RenderCacheSharedFenceScope, which covers shared navigation, theme, widget, and locale dependencies. Arbitrary handlers can combine that shared scope with bounded surface-specific RenderCacheHandlerDecision.FenceScopes. The generations are read before lookup and immediately before storage, preventing an in-flight pre-mutation render from becoming a current entry.
• An enabled memory runtime is rejected unless RenderCacheConfig.AllowProcessLocalFence is explicitly true. Use that escape hatch only for a single serving process in development or tests; the decision-level AllowProcessLocalFence cannot override runtime authorization. Multi-instance staging and production must use a shared backend such as Valkey.
• Concurrent cold GET misses for the same representation are coalesced within one process. Followers re-run cache eligibility, generation reads, and key construction after the leader completes. The coordinator is bounded and is not a distributed lock; cross-instance correctness comes from the shared generation fence.
• Request snapshots aggregate bounded counters by host surface. Surface labels are normalized and bounded; request paths, queries, entity IDs, bodies, and raw keys are not added to observations.
• Single-process development defaults: memory backend, explicit AllowProcessLocalFence: true, FreshTTL around 30s-60s, DebugHeaders: true, and DebugKeys only where key exposure is safe.
• Production defaults: shared backend or shared render-version source, FreshTTL around 5m-10m, active invalidation through render-version bumps or tag/prefix-capable stores before broad rollout.
• Static asset caching is separate from rendered HTML caching and should stay on the asset/CDN path.

Example:

policy := quicksite.RenderCachePolicy{
	Enabled:              true,
	ApplicationNamespace: "archive-admin",
	EnvironmentNamespace: "staging",
	SiteNamespace:        "public-site",
	FreshTTL:             30 * time.Second,
	DebugHeaders:         true,
	AuthCookieNames:      []string{"admin_session", "debug_session"},
}

runtime, err := quicksite.NewRenderCacheRuntime(ctx, quicksite.RenderCacheConfig{
	Enabled:         true,
	Backend:         quicksite.RenderCacheBackendValkey,
	ExpirationMode:  quicksite.RenderCacheExpirationSliding,
	DebugHeaders:    true,
	RequireTagIndex: true,
	Valkey: quicksite.RenderCacheValkeyConfig{
		Address:   "127.0.0.1:6379",
		Namespace: "archive:staging:site-render-cache",
	},
}, policy)
if err != nil {
	return err
}
if err := quicksite.RegisterRenderCacheDebugPanel(runtime); err != nil {
	return err
}
quicksite.RegisterSiteRoutes(router, siteCfg, quicksite.WithRenderCacheRuntime(runtime))

For a process-local built-in runtime, select memory and keep fixed mode or opt into sliding explicitly:

runtime, err := quicksite.NewRenderCacheRuntime(ctx, quicksite.RenderCacheConfig{
	Enabled:                  true,
	Backend:                  quicksite.RenderCacheBackendMemory,
	AllowProcessLocalFence:   true, // single-process development/tests only
	FreshTTL:                 5 * time.Minute,
	StaleTTL:                 time.Minute,
	ExpirationMode:           quicksite.RenderCacheExpirationFixed,
}, quicksite.RenderCachePolicy{})

Host-owned deterministic HTML handlers use the same runtime and may combine the shared fence with a domain fence. Search remains bypassed by generic site delivery; only an explicit wrapper with normalized query material opts it in.

eventHandler := quicksite.WrapRenderCacheHandler(runtime, func(c router.Context) error {
	event, err := loadPublishedEvent(quicksite.RequestContext(c), c.Params("slug"))
	if err != nil {
		return err
	}
	quicksite.SetRenderCacheHandlerTags(c, "site:archive", "site:event:"+event.ID)
	return c.Render("event", event)
}, quicksite.RenderCacheHandlerOptions{
	ObservationSurface: func(router.Context) string { return "archive_event" },
	Decide: func(c router.Context) (quicksite.RenderCacheHandlerDecision, error) {
		return quicksite.RenderCacheHandlerDecision{
			Cacheable:     true,
			Surface:       "archive_event",
			CanonicalPath: canonicalEventPath(c.Params("slug")),
			FenceScopes: []string{
				quicksite.RenderCacheSharedFenceScope,
				"site:archive",
			},
			RequireFence: true,
		}, nil
	},
})
router.Get("/events/:slug", eventHandler)

CanonicalPath and CanonicalQuery are hashed before entering the backend key, but hosts must still normalize them deterministically and reject unknown or unsafe query state. A GET miss is captured once; a hit skips the handler. GET and HEAD share a representation, while a HEAD-first miss is never stored. After an authoritative mutation commits, advance each affected generation before returning success, then invalidate tags to reclaim old entries:

if _, err := quicksite.AdvanceRenderCacheGeneration(ctx, runtime, "site:archive"); err != nil {
	return err
}
invalidator, ok := runtime.Store.(quicksite.RenderCacheTagInvalidator)
if !ok {
	return errors.New("site render cache does not support tag invalidation")
}
if err := invalidator.InvalidateTags(ctx, []string{
	"site:archive",
	"site:event:" + eventID,
}); err != nil {
	return err
}

Runtime store wrappers preserve supported invalidation capabilities, so the type assertion above works for the built-in Valkey runtime. Advance every affected generation before invalidating tags. The generation change prevents a concurrent pre-mutation render from becoming current; tag invalidation then reclaims entries from older generations.

A custom store used directly with sliding mode must satisfy both local contracts:

var store interface {
	quicksite.RenderCacheStore
	quicksite.RenderCacheSetIfPresentStore
} = customStore

option := quicksite.WithRenderCache(store, quicksite.RenderCachePolicy{
	Enabled:        true,
	FreshTTL:       5 * time.Minute,
	StaleTTL:       time.Minute,
	ExpirationMode: quicksite.RenderCacheExpirationSliding,
})

Routing migration notes

When migrating a host from the old shared-root quickstart/site setup to the explicit ownership model:

• register system, internal-ops, admin UI, admin API, public API, public site, and static routes through quickstart.NewHostRouter(...); do not rely on calling RegisterSiteRoutes(...) before or after admin wiring to make ownership work
• replace callback matchers or magic fallback mode strings with quicksite.SiteFallbackPolicy plus the exported mode constants (SiteFallbackModeDisabled, SiteFallbackModePublicContentOnly, SiteFallbackModeExplicitPathsOnly)
• remove handler-level prefix guards for /admin, /api, /.well-known, /assets, and /static; reserved-prefix enforcement now belongs in the grouped router surfaces and the declarative fallback policy
• migrate old shared theme wiring from adm.WithGoTheme(...) to adm.WithAdminTheme(...), and attach the public-site selector separately with quicksite.WithSiteTheme(...) or SiteConfig.ThemeProvider
• keep /healthz and /status on the internal-ops surface when enabled so those endpoints never resolve through site fallback

Recommended QA after migration:

• GET /search renders with the site theme surface
• an allowed unknown public content path resolves through site fallback
• GET /admin/missing returns the admin 404 behavior rather than a site page
• GET /.well-known/... bypasses site templates entirely
• enabled /healthz and /status endpoints return host-owned diagnostics payloads

The search guide covers route ownership and request/response contracts.

Onboarding + secure links

Quickstart wires onboarding routes and securelink helpers so hosts can opt in with minimal setup.

Feature gate keys (system scope) used by onboarding flows:

• users.invite
• users.password_reset
• users.signup

Enable these via gate defaults (for example WithFeatureDefaults) or runtime overrides. Alias policy: users.self_registration is not supported; use users.signup.

Securelink config defaults:

• quickstart.DefaultSecureLinkConfig(basePath) returns:
• SigningKey="" (manager disabled until a key is provided)
• BaseURL="http://localhost:8080"
• QueryKey="token"
• AsQuery=true
• Expiration=72h

Route helpers:

• RegisterOnboardingRoutes (API endpoints under /admin/api/onboarding by default)
• RegisterAuthUIRoutes + RegisterRegistrationUIRoutes (UI pages)

See docs/GUIDE_ONBOARDING.md for token lifecycle details, error response shape, and override hook examples.

User migrations

Quickstart registers the combined profile by default (go-auth -> go-users -> go-notifications):

if err := quickstart.RegisterUserMigrations(client); err != nil {
	return err
}

Canonical profiles:

• quickstart.UserMigrationsProfileAuthOnly -> go-auth -> go-notifications
• quickstart.UserMigrationsProfileCombined -> go-auth -> go-users -> go-notifications
• quickstart.UserMigrationsProfileUsersStandalone -> go-users-auth -> go-users-auth-extras -> go-users -> go-notifications

Canonical source labels:

• quickstart.UserMigrationsSourceLabelAuth
• quickstart.UserMigrationsSourceLabelUsersCore
• quickstart.UserMigrationsSourceLabelUsersAuthBootstrap
• quickstart.UserMigrationsSourceLabelUsersAuthExtras
• quickstart.UserMigrationsSourceLabelNotifications

The wrapper uses source-stable ordered migration identity. Source keys and order values are durable migration ABI:

• go-auth: key go-auth, order 10
• go-users-auth: key go-users-auth, order 20
• go-users-auth-extras: key go-users-auth-extras, order 30, depends on go-users-auth when present
• go-users: key go-users, order 40, depends on go-auth in combined mode or go-users-auth-extras in standalone mode
• go-notifications: key go-notifications, order 50, depends on the nearest enabled built-in source

When optional sources are disabled, dependency edges are pruned to the selected source graph. Existing databases with positional ord_* markers must run the go-persistence-bun stable-marker backfill before deploying wrapper behavior that generates ordsrc_* names.

Disable notifications explicitly only when that runtime is not used:

quickstart.WithUserMigrationsNotificationsEnabled(false)

For a fresh persistent runtime, migrate before constructing or bootstrapping the admin:

if err := quickstart.RegisterUserMigrations(client); err != nil {
	return err
}
if err := client.Migrate(ctx); err != nil {
	return err
}
notificationRuntime, err := admin.NewBunNotificationRuntime(ctx, client.DB())
if err != nil {
	return err
}
deps.NotificationRuntime = notificationRuntime

The manual retention endpoint is global and requires affirmative trusted system authority in addition to its permission. In trusted host middleware, wrap the authenticated request context with admin.WithNotificationSystemAuthority(ctx), or set the boolean admin.NotificationSystemAuthorityMetadataKey in authenticated actor metadata. Never derive this marker from request payload or query data. It intentionally overrides quickstart's injected single-tenant default only for the trusted system operator; ordinary tenant actors remain denied.

For an existing persisted graph that already ends at order 50 or later, do not insert notifications at its default order. Take a database backup, choose a permanent order after the last persisted source, depend on that source with WithUserMigrationsNotificationPlacement or WithServiceMigrationsNotificationPlacement, then run notifications.AdoptAdditiveOrderedMigrationGraph before migrating. Adoption is suffix-only and is not a drift-repair tool. Rollback for applied forward-only or destructive migrations is restore from the pre-adoption backup.

Example: register users standalone mode (no go-auth migrations):

if err := quickstart.RegisterUserMigrations(
	client,
	quickstart.WithUserMigrationsProfile(quickstart.UserMigrationsProfileUsersStandalone),
); err != nil {
	return err
}

Services module migration registration uses services-stack (go-auth -> go-users -> go-services -> go-notifications -> app-local) by default via modules/services.RegisterServiceMigrations; app-local sources remain at order 100+ and depend on notifications in fresh graphs.

Static assets (opt-in disk fallback)

diskAssetsDir := quickstart.ResolveDiskAssetsDir(
	"output.css",
	"path/to/pkg/client/assets",
	"assets",
)
host := quickstart.NewHostRouter(r, cfg)
quickstart.NewStaticAssets(host.Static(), cfg, client.Assets(), quickstart.WithDiskAssetsDir(diskAssetsDir))
quickstart.RegisterContentTypeBuilderUIRoutes(
	host.AdminUI(),
	cfg,
	adm,
	authn,
	quickstart.WithContentTypeBuilderUIStaticAssetOptions(cfg, quickstart.WithDiskAssetsDir(diskAssetsDir)),
)

Durable authenticated exports

NewDurableExportHost composes the normal export bundle with go-export's SQL replay/tracker, filesystem artifacts, atomic completion publication, receipt webhooks and go-job's SQL queue, native worker and recurring ledger. The workspace selects sibling go-job and go-export sources while module release pins remain unchanged.

Supply DurableExportHostConfig with the host Bun database, artifact directory, current guard/actor provider, trusted namespace, authorized transaction and record policy. AcceptBackground must explicitly authorize and persist bounded delegation in the supplied transaction. ResolveBackground receives only work kind and export/schedule IDs: recover current authority, safe correlation and scope from trusted durable state. Overwrite message actor hints; never copy browser cookies, bearer tokens or role claims into background authority. Recheck account, membership, exact grant, delegation expiry/revocation, parent delegation and destination policy in guards/transactions. A valid independent delegation can survive browser logout/expiry; account, permission or delegation revocation must stop effects. Child grants must not widen parent lifetime or capabilities.

1. Apply the host-owned native export_records migration, including request_payload; call host.Migrate(ctx) for additive replay/queue/ownership/recurrence and optional webhook schemas. Startup readiness fails closed on missing tables.
2. Register definitions/row sources/renderers on host.Bundle.Runner (or supply WithExportRunner). Sources must reuse the authorized transaction. Pass Bundle.Registry, Bundle.Registrar and Bundle.Metadata through the existing admin dependencies and authenticated route wrapper. Durable creation requires CSRF-protected POST and async delivery; sync/GET creation is rejected. History applies trusted ownership/namespace predicates in SQL, with a 200-record limit.
3. Run host.Run(applicationContext) under the host lifecycle. It owns a dedicated native task registry and one queue retry policy; cancel and await it before closing the database. Reserve this queue for the registered export tasks. For shared/fleet consumers, use separate queue storage/tables and the same identity policy. ExecuteMessage leaves receipt ACK/NACK to its caller.
4. Install immutable native schedule definitions through trusted operator configuration with an ExportRequest JSON payload and explicit bounded schedule delegation. TickSchedule atomically admits occurrence/export/delegation/plan/job/cursor and emits ordinary activity after commit. Optional RecurringNamespaces enables bounded polling; OnPollError is mandatory and must report failed scopes. Pausing retains backlog and does not cancel already accepted exports.

Optional Webhooks requires a receipt sender, immutable destination selector, current destination authorizer and safe download-link policy. External delivery remains at least once; matching transactional receiver inbox receipts prevent duplicate effects for that receiver. Ordinary activity is postcommit and is not a durable outbox. Tracker migration, delegation provisioning/renewal, credentials, legacy-data backfill, coordinated retention/backup/restore and deployment remain application/operator responsibilities. This opt-in composition does not automatically change the legacy demo host.

Reviewed legacy export adoption

Enable LegacyAdoption only for a controlled cutover. Its Authorize callback must verify current operator identity, authoritative legacy ownership, the versioned profile and a maintenance fence before record reads. Its Select callback resolves an immutable reviewed endpoint/credential profile inside the supplied transaction. Both callbacks must reuse that transaction without network I/O, nested transactions or commits. Provision profile versions through host policy; commands carry only a profile reference and digests. Existing native Webhooks.AuthorizeTarget must reject revoked destinations and credential versions at acceptance and sending. Keep Webhooks.Link stable, as required by native delivery.

Apply native tracker migrations and host.Migrate(ctx) before adoption. Fence old admission, pollers and workers for the reviewed records. Preview a queued record with retained executable request_payload, or a completed record whose checksummed durable envelope and tracker metadata still match. Arbitrary raw artifact formats and unknown schemas need a separate migration.

func adoptLegacy(ctx context.Context, host *quickstart.DurableExportHost, operator export.Actor) error {
    review, err := host.PreviewLegacyExport(ctx, operator, "legacy-export-id", "approved-profile-v2")
    if err != nil { return err }
    // Review both digests before applying; persist this request for response-loss retry.
    request := quickstart.LegacyExportAdoptionRequest{
        ExportID: review.ExportID, ProfileRef: review.ProfileRef,
        RecordSHA256: review.RecordSHA256, PlanSHA256: review.PlanSHA256,
    }
    handler := quickstart.AdoptLegacyExportHandler{Service: host}
    _, err = handler.Run(ctx, quickstart.AdoptLegacyExport{Actor: operator, Request: request})
    return err
}

The typed command ID is admin.export.legacy.adopt.v1. Register its handler on an operator-owned command bus if needed; no public HTTP/RPC factory is installed. Bind operator identity from current authentication, never a decoded actor claim. Preview exposes no endpoints or credential bytes. Review hashes bind exact retained request bytes and the profile version/plan; changed records, profiles or credentials require a new review before first adoption. Queued request numbers must also survive native tracker/job JSON decoding without changing value. Preview, inventory and apply reject lossy values in query, selection and template data; equivalent decimal/exponent spellings and exact typed integers remain valid. Such records need an explicit lossless input mapping or native decoder support before cutover.

For read-only cutover preparation, optionally provide LegacyAdoption.Inventory. It must authorize the current operator, profile and maintenance fence before enumerating IDs from authoritative application ownership, using only the supplied transaction. Return at most the supplied limit, with unique IDs in increasing UTF-8 byte order after the cursor; the host asks for page size plus one (at most 101). Do not derive authority from stored legacy actor hints or perform writes/network calls in the callback. Without this policy inventory is disabled.

host.InventoryLegacyExports(ctx, operator, LegacyExportInventoryQuery{ProfileRef: "approved-profile-v2", Limit: 50}) returns at most 100 entries, safe review digests and blockers (already_adopted, notification_intent, unsupported_state). Follow NextAfter only when HasMore is true. Current per-record policy also authorizes the lookahead ID; only actual page records are read/reviewed. Failures discard the entire page. Completed artifacts and queued generation guards are checked before a review is returned. Inventory does not create owners, delegations, receipts, queue work or profiles. The operator-only typed command is admin.export.legacy.inventory.v1; its handler delegates to the service and keeps Actor out of JSON. No public factory/route is installed.

Each page is a current read, not a frozen inventory attestation. Keep the real old-writer fence across cutover, explicitly review ready entries, and pass their digests to the existing adoption command. Apply rechecks records, plans and current policy; published credentials/receiver identities remain immutable. RecoveryGate admission/drain covers the whole inventory page.

First adoption commits private namespace ownership, explicit bounded delegation, native completion/delivery intent, queue acceptance and an admin_export_legacy_adoptions receipt together. Queued records retain their export identity; completed records retain artifact bytes and never query the source again. Adoption adds one recoverable generation message; retained old at-least-once messages may also arrive through the new worker. Native generation serializes by export ID and reuses completion, rather than regenerating or repeating publication. Resume only through workers that reconstruct current background authority. Existing notification plans or target receipts are rejected, not rebound to new credentials.

Retry the original reviewed request after a lost response. Replays reauthorize current policy without renewing delegation or adding generation work. Keep versioned profile content stable and retain the receipt with owner/delegation, complete host SQL, native queue, plans, sender/receiver receipts and artifacts through every allowed retry/restore horizon. Missing retained plans/receipts deny. Replay of a still-queued adoption also requires the original reviewed record. Retained plan ownership, namespace and digest must match; a queued record cannot have a publication marker. Once a queued adoption completes, its marker, artifact, native operation and full target set must remain intact before replay can acknowledge it. Replay does not reconstruct pruned publication state. INT13 evidence covers its frozen earlier graph; deployments adopting this additive table must include it in coordinated backup/restore checks. SQLite regressions restore the full SQL snapshot/artifacts; PostgreSQL regressions reopen the same isolated durable state.

This is an opt-in code path verified with synthetic records. Live profile provisioning/cutover, rotation or rebinding of already-published identities, receiver endpoint changes, operational fences and deployment signoff remain consuming-host work. No startup scan or automatic adoption occurs.

Recovery of adopted exports

Retain admin_export_legacy_adoptions with the entire host SQL, durable artifact tree, native completion/sender receipts and transactional receiver inbox/effects. Restore them as one quiescent, catalog-anchored set and compare every canonical table and artifact before enabling workers. CheckReady checks schema availability; the consuming application must enforce the recovery gate, stop all writers and reconcile post-snapshot revocations before replay.

durable_export_recovery_test.go provides the current-host reference gate and SQLite/PostgreSQL full-restore checks for pending adoption, generated exports and uncertain receiver responses. It verifies adoption receipt/owner/delegation/plan closure before capture and rejects pruned or mixed recovery state. This is controlled recovery verification; production distributed fences, catalog custody and deployment RPO/RTO remain application responsibilities.

Runtime maintenance and recovery interlock

Set DurableExportHostConfig.RecoveryGate to a new NewDurableExportRecoveryGate for opt-in sealed startup. Supply trusted Authorize, VerifyCatalog and Reconcile policies. ExportRecoveryCheckpoint contains reviewed set/catalog/policy references; callbacks must verify the complete restored set against independent catalog custody and reconcile authoritative post-snapshot revocations. A successful callback cannot be replaced by a caller-supplied approval flag. Every process restart needs a new sealed gate and a new successful resume.

Construct and migrate the host while sealed, then call gate.Resume(ctx, currentOperator, checkpoint) and start host.Run under the application lifecycle. Before backup, call gate.Seal(ctx, currentOperator); only a nil result means admitted facade work, native worker shutdown and outstanding queue operations have drained. Timeout/cancellation leaves admission sealed and unfinished work counted. Resume the gate and explicitly restart host.Run after maintenance. Operator adapters may register the typed admin.export.recovery.seal.v1 and admin.export.recovery.resume.v1 handlers; no public route/message factory is installed, and actor claims are omitted from command JSON.

Use the host facade for export services, history, legacy adoption, schedules and native Run/ExecuteMessage. Share one gate across all host instances in this process. Migrations require an idle sealed gate; CheckReady remains a schema probe. Raw queue, scheduler, tracker, runner, worker and webhook handles are trusted integration ports and require separate maintenance discipline. The gate does not fence another process, an external receiver, another database client or work escaping trusted callback lifetimes. Fence authentication/session and other application writers separately as well. Stop those writers independently before capturing a recovery set; deployment-wide fencing, catalog custody, revocation-feed availability and recovery objectives remain consuming-host policy.

Usage example

cfg := quickstart.NewAdminConfig("/admin", "Admin", "en")
exportBundle := quickstart.NewExportBundle()
adm, adapters, err := quickstart.NewAdmin(cfg, quickstart.AdapterHooks{
	PersistentCMS: func(ctx context.Context, defaultLocale string) (admin.CMSOptions, string, error) {
		return admin.CMSOptions{}, "in-memory CMS", nil
	},
}, quickstart.WithAdminDependencies(admin.Dependencies{
	ExportRegistry:  exportBundle.Registry,
	ExportRegistrar: exportBundle.Registrar,
	ExportMetadata:  exportBundle.Metadata,
}))
if err != nil {
	return err
}

// Register definitions and row sources on exportBundle.Runner.
// exportBundle.Runner.Definitions.Register(...)
// exportBundle.Runner.RowSources.Register(...)

// List export is advertised only after Initialize successfully registers the
// export routes and the requested panel definition exists in this registry.

views, err := quickstart.NewViewEngine(os.DirFS("./web"))
if err != nil {
	return err
}

srv, r := quickstart.NewFiberServer(views, cfg, adm, true)
host := quickstart.NewHostRouter(r, cfg)
quickstart.NewStaticAssets(host.Static(), cfg, os.DirFS("./web"))
_ = quickstart.NewModuleRegistrar(adm, cfg, []admin.Module{}, true)
if err := adm.Initialize(host.Admin()); err != nil {
	return err
}

_ = adapters
_ = srv

cfg := quickstart.NewAdminConfig(
	"/admin",
	"Admin",
	"en",
)

flags := config.Admin.AdapterFlags
adm, adapters, err := quickstart.NewAdmin(
	cfg,
	hooks,
	quickstart.WithAdapterFlags(flags),
	quickstart.WithMinimalFeatures(),
)
if err != nil {
	return err
}
_ = adapters
_ = adm

err = quickstart.NewModuleRegistrar(
	adm,
	cfg,
	modules,
	isDev,
)
if err != nil {
	return err
}

authn, authz := quickstart.WithGoAuth(
	adm,
	routeAuth,
	authConfig,
	admin.GoAuthAuthorizerConfig{DefaultResource: "admin"},
	&admin.AuthConfig{
		LoginPath:    "/admin/login",
		LogoutPath:   "/admin/logout",
		RedirectPath: "/admin",
	},
)
_ = authn
_ = authz

if err := quickstart.WithDefaultDashboardRenderer(adm, views, cfg); err != nil {
	return err
}

formgen, err := quickstart.NewFormGenerator(os.DirFS("./openapi"), os.DirFS("./forms"))
if err != nil {
	return err
}
_ = formgen

registry := components.New()
registry.MustRegister("permission-matrix", components.Descriptor{
	Renderer: permissionMatrixRenderer,
})

formgen, err := quickstart.NewFormGenerator(
	os.DirFS("./openapi"),
	os.DirFS("./forms"),
	quickstart.WithComponentRegistryMergeDefaults(registry),
	quickstart.WithVanillaOption(formgenvanilla.WithStylesheet("/admin/assets/forms.css")),
)
if err != nil {
	return err
}
_ = formgen

WithVanillaOption(...) is applied last, so it can override templates/styles/registry. Use WithComponentRegistry(...) instead of the merge option to replace defaults entirely.

The formgen guide covers full customization guidance.

Debug quickstart

Debug is opt-in and requires module registration plus middleware/log wiring. Configure panels before constructing the admin; attach middleware/log helpers after the debug module is registered so the collector is available.

Use explicit option structs:

• quickstart.WithDebugOptions(quickstart.DebugOption{...}) for debug fields.
• quickstart.WithErrorOptions(quickstart.ErrorOption{...}) for error presentation fields.

cfg := quickstart.NewAdminConfig(
	"/admin",
	"Admin",
	"en",
	quickstart.WithDebugOptions(quickstart.DebugOption{
		Enabled:     admin.BoolPtr(true),
		LayoutMode:  "admin",
		ReplEnabled: admin.BoolPtr(true),
	}),
	quickstart.WithErrorOptions(quickstart.ErrorOption{
		DevMode:               admin.BoolPtr(true),
		IncludeStackTrace:     admin.BoolPtr(true),
		ExposeInternalMessage: admin.BoolPtr(true),
	}),
)

quickstart.ConfigureDebugPanels(&cfg, quickstart.DebugPanelDeps{}, quickstart.DefaultDebugPanelCatalog())

adm, _, err := quickstart.NewAdmin(cfg, hooks, quickstart.WithAdminDependencies(deps))
if err != nil {
	return err
}

modules := []admin.Module{
	// core modules...
}
if cfg.Debug.Enabled {
	modules = append(modules, admin.NewDebugModule(cfg.Debug))
}

if err := quickstart.NewModuleRegistrar(
	adm,
	cfg,
	modules,
	isDev,
); err != nil {
	return err
}

if cfg.Debug.Enabled {
	quickstart.AttachDebugMiddleware(r, cfg, adm)
	quickstart.AttachDebugLogHandler(cfg, adm)
}

repoOptions := adm.DebugQueryHookOptions()
repo := repository.MustNewRepositoryWithOptions[*MyModel](db, handlers, repoOptions...)

Go-only rich debug panels

Go applications can register operator-friendly debug panels without shipping app-side JavaScript by adding a declarative debug.PanelUI schema to debug.PanelConfig.

_ = debug.RegisterPanel("queue", debug.PanelConfig{
	Label:           "Queue",
	SnapshotKey:     "queue",
	SupportsToolbar: admin.BoolPtr(true),
	UI: debug.NewPanelUI(
		debug.TableView("jobs"),
		debug.MetricsView("summary"),
	),
	Snapshot: func(ctx context.Context) any {
		return map[string]any{
			"summary": map[string]any{"pending": 3},
			"jobs": []map[string]any{
				{"id": "job-1", "status": "pending"},
			},
		}
	},
})

Supported schema renderers are metrics, key_value, table, status_list, timeline, json, and stack. count, filters, and events configure badges, console filtering, and live-event update behavior. actions render buttons that post to /admin/debug/api/panels/:panel/actions/:action and must be backed by debug.PanelActionHandler entries in the same registration.

The panel ID must still be present in DebugConfig.Panels; toolbar rendering also requires supports_toolbar plus the toolbar panel configuration. Panels without a schema, malformed schema, or unsupported renderer names fall back to escaped JSON rendering. Use a TypeScript panelRegistry.register(...) renderer when a panel needs bespoke browser interaction beyond the declarative catalog.

Scope debug (optional)

Scope debug captures the raw/resolved tenant/org scope for requests, adds an X-Admin-Resolved-Scope header, and exposes a JSON snapshot endpoint. When enabled through ConfigureDebugPanels, it also registers a Go-only rich debug panel using the declarative schema described above.

Scope debug is explicit:

• choose whether scope capture is enabled in your host config
• set a ring buffer size (default 200)

scopeDebugEnabled := true
var scopeDebugBuffer *quickstart.ScopeDebugBuffer
if scopeDebugEnabled {
	scopeDebugBuffer = quickstart.NewScopeDebugBuffer(200)
}

quickstart.ConfigureDebugPanels(
	&cfg,
	quickstart.DebugPanelDeps{ScopeBuffer: scopeDebugBuffer},
	quickstart.DefaultDebugPanelCatalog(),
)

wrapAuthed := authn.WrapHandler
if scopeDebugEnabled {
	wrapAuthed = quickstart.ScopeDebugWrap(authn, &cfg, scopeDebugBuffer)
}

r.Get(path.Join(cfg.BasePath, "api", "debug", "scope"), wrapAuthed(quickstart.ScopeDebugHandler(scopeDebugBuffer)))

Preferences quickstart

• FeaturePreferences remains opt-in: pass EnablePreferences() or supply WithFeatureOverrides(map[string]bool{"preferences": true}) when building the admin gate.
• A 403 on /admin/api/panels/preferences usually means the default permissions are missing (admin.preferences.view, admin.preferences.edit).
• Read query params: levels, keys, include_traces, include_versions, tenant_id, org_id.
• Clear/delete semantics: send clear_raw_keys or clear: true (for all raw keys), plus empty values for known keys to delete user-level overrides.
• Non-user writes (tenant/org/system) require admin.preferences.manage_tenant, admin.preferences.manage_org, admin.preferences.manage_system.
• Dashboard preferences endpoints default to preferences permissions; override with cfg.DashboardPreferencesPermission / cfg.DashboardPreferencesUpdatePermission if needed.
• The preferences guide covers module behavior, traces, and clear semantics.
• If you want quickstart to build the repo (for example, to enable caching), pass WithGoUsersPreferencesRepositoryFactory to NewAdmin.
• Use NewPreferencesModule with WithPreferencesSchemaPath to override the form schema (file path or a directory containing schema.json).
• Use WithPreferencesJSONEditorStrict(true) to enforce client-side JSON validation of raw_ui (default is lenient; server-side validation still applies).

prefsStore, err := quickstart.NewGoUsersPreferencesStore(preferenceRepo)
if err != nil {
	return err
}

adm, err := admin.New(cfg, admin.Dependencies{
	PreferencesStore: prefsStore,
})
if err != nil {
	return err
}
_ = adm

adm, _, err := quickstart.NewAdmin(
	cfg,
	adapterHooks,
	quickstart.WithGoUsersPreferencesRepositoryFactory(func() (types.PreferenceRepository, error) {
		return preferences.NewRepository(
			preferences.RepositoryConfig{DB: client.DB()},
			preferences.WithCache(true),
		)
	}),
	quickstart.EnablePreferences(),
)
if err != nil {
	return err
}
_ = adm

err := quickstart.RegisterPreferencesPermissions(func(def quickstart.PermissionDefinition) error {
	return permissions.Register(def.Key, def.Description)
})
if err != nil {
	return err
}

modules := []admin.Module{
	quickstart.NewPreferencesModule(
		cfg,
		"",
		quickstart.WithPreferencesSchemaPath("./configs/preferences"),
		quickstart.WithPreferencesJSONEditorStrict(true),
	),
}
if err := quickstart.NewModuleRegistrar(adm, cfg, modules, isDev); err != nil {
	return err
}

Stage 1 minimal flow

• Build config with NewAdminConfig(...) and pass WithMinimalFeatures() or WithFeatureSet(DefaultMinimalFeatures()) to NewAdmin.
• Resolve adapter flags from config and pass via WithAdapterFlags(...).
• Register modules with NewModuleRegistrar (uses adm.FeatureGate() by default).
• Wire auth with WithGoAuth(...) (include *admin.AuthConfig when needed).
• Enable dashboard SSR with WithDefaultDashboardRenderer(...) (override templates as needed).

Translation Profile Operational Runbook

Config-based Configuration

Configure translation profiles via WithTranslationProductConfig(...):

Field	Values	Default	Description
Profile	none, core, core+exchange, core+queue, full	Empty (resolves to core when CMS enabled)	Sets the baseline translation capability profile
Exchange.Enabled	true, false	Profile default	Overrides exchange module enablement
Queue.Enabled	true, false	Profile default	Overrides queue module enablement

Profile capability matrix:

Profile	Exchange	Queue	Use Case
none	-	-	Translation disabled
core	-	-	Basic translation readiness only
core+exchange	Yes	-	Import/export workflows
core+queue	-	Yes	Assignment management
full	Yes	Yes	Complete translation operations

Verification Checklist

1. Start the host app with the intended profile and overrides.
2. Validate the startup capability event and module flags.
3. Validate module route exposure for enabled modules.
4. Validate disabled modules are not exposed.

Example startup:

adm, _, err := quickstart.NewAdmin(
	cfg,
	hooks,
	quickstart.WithTranslationProductConfig(quickstart.TranslationProductConfig{
		SchemaVersion: quickstart.TranslationProductSchemaVersionCurrent,
		Profile:       quickstart.TranslationProfileFull,
		Exchange:      &quickstart.TranslationExchangeConfig{Enabled: true},
		Queue:         &quickstart.TranslationQueueConfig{Enabled: true},
	}),
)
if err != nil {
	return err
}

Check startup logs for translation.capabilities.startup and verify:

• profile is the expected resolved value.
• modules.exchange.enabled and modules.queue.enabled match the final intended state.
• routes includes enabled module routes only.
• resolver_keys include route keys expected by UI entrypoints.

Route/Capability Expectations

Expected runtime routes when modules are enabled:

• Exchange UI route: /admin/translations/exchange
• Queue UI route: /admin/translations/queue
• Queue compatibility alias: /admin/content/translations
• Exchange API routes: /admin/api/translations/exchange/export, /admin/api/translations/exchange/import/validate, /admin/api/translations/exchange/import/apply
• Queue API routes: /admin/api/translations/queue, /admin/api/translations/my-work
• Queue panel API route: /admin/api/panels/translations

When a module is disabled:

• Exchange UI route is not registered.
• Exchange API endpoints are not registered.
• Queue panel/API routes are not registered.
• Capability metadata (TranslationCapabilities(adm)) reports the module as disabled.

Troubleshooting

Symptom	Likely Cause	Resolution
translation product config invalid at startup	Missing CMS feature for non-none profile	Enable cms feature or use profile none
Exchange routes not registered	Exchange module not enabled	Set TranslationProductConfig.Exchange.Enabled=true or use core+exchange/full profile
exchange.handlers_missing error	Exchange store not configured	Provide TranslationExchangeConfig.Store implementation
queue.locales_invalid error	Queue enabled without supported locales	Set TranslationQueueConfig.SupportedLocales or configure translation policy
quickstart.translation_policy.services_missing warning/error	Policy has explicit requirements but no page/content checker service was resolved	Expose go-cms services through CMSOptions.GoCMSConfig or pass WithTranslationPolicyServices
Family row shows Policy unavailable	Family sync could not resolve policy/checker wiring for that content type	Cover the content type in TranslationPolicyConfig, provide checker services, then rerun family sync
Translation UI not visible	Feature gate disabled	Check FeatureTranslationExchange in feature gate

Runtime Validation

After admin initialization, call quickstart.TranslationCapabilities(adm) to get resolved capabilities:

caps := quickstart.TranslationCapabilities(adm)
log.Printf("Translation profile: %s", caps["profile"])
log.Printf("Exchange enabled: %v", caps["modules"].(map[string]any)["exchange"].(map[string]any)["enabled"])
log.Printf("Registered routes: %v", caps["routes"])

Compatibility note

If you previously imported quickstart as part of the root module, keep the same import path but add a direct require on github.com/goliatone/go-admin/quickstart in your go.mod (or use a local replace/go.work entry during dev). The APIs are unchanged; only the module boundary moved.

What’s included

• Navigation: slug-derived menu IDs/lookup, parent scaffolder for grouped/collapsible defaults, canonical content-parent permission helper (DefaultContentParentPermissions), idempotent seeding (SeedNavigation), deterministic ordering, permission filtering, collapsible state, and view helpers (WithNav, BuildNavItems).
• Sidebar: embedded templates/partials and assets (CSS/JS) with pre-paint desktop collapse restoration, collapse + submenu persistence, and a separate narrow drawer; stock layouts need no configuration. Apps can override by adding their own template/assets FS ahead of the defaults.
• Error handling: Fiber error handler that returns JSON for API paths and renders the branded error page (with nav/theme/session) for HTML routes.
• Adapters: explicit AdapterFlags wiring for persistent CMS, go-options settings, and go-users activity sink with safe in-memory fallbacks.
• Auth debug: GoAuthAuthorizer supports explicit config debug mode for structured decision logging (logger injectable).

Adapter and runtime toggles

• Set adapter switches with quickstart.WithAdapterFlags(quickstart.AdapterFlags{...}).
• For navigation reset/debug behavior, pass explicit host runtime config to your setup layer (for example examples/web/setup.ConfigureRuntime(...)).
• For authz diagnostics, set admin.GoAuthAuthorizerConfig.Debug explicitly when constructing the authorizer.

Overrides

• Templates/Assets: WithViewTemplatesFS values are first-wins overlays in call order, followed by the host base and quickstart fallbacks. Pass WithViewAdmin(adm) so theme-selected admin.shell.sidebar, admin.page.breadcrumbs, and admin.shell.footer identifiers are checked against that exact stack; absent lookup, unsafe paths, and unavailable files use packaged defaults. WithSidebarAssetsFS is a partial first-wins override, so omitted files continue to fall back to packaged sidebar assets. Full layout.html overrides must keep the render-blocking assets/sidebar-state.js tag from asset_base_path before shell stylesheets, place sidebar.js immediately after the sidebar markup and before main content, and continue serving both assets. Do not defer the state script; if asset_base_path uses a CDN, allow its origin in script-src.
• Navigation seed: pass custom items to SeedNavigation; module menu contributions flow through BuildMenuSeedPlan and generated-menu reconciliation.
• Module gating: WithModuleFeatureGates(customGate) with optional WithModuleFeatureDisabledHandler.
• Translation nav seeding: WithTranslationCapabilityMenuMode(TranslationCapabilityMenuModeTools) adds dashboard/queue/exchange links into a dedicated Translations menu group in server-seeded navigation.
• Dashboard SSR: DashboardTemplatesFS() is the canonical client template set. Provide WithDashboardTemplatesFS for first-wins overlays; disabling packaged templates via WithDashboardEmbeddedTemplates(false) requires a complete compatible shell and fails explicitly for incomplete stacks.
• Dashboard widget contract: handlers should return typed admin.WidgetPayload models consumed by both SSR and client hydration; avoid render-mode payload branching and disallow chart_html/full-document/script blobs in payload data.
• Typed authenticated pages: build admin.AdminPageChrome and call admin.EnrichLayoutViewContextWithChrome; keep arbitrary actions in page_header_actions. Import shared browser presentation from @goliatone/go-admin-client/components.css, then mount product CSS with WithExtraAssetsFS and link it from head_extra.
• Error handler: swap quickstart.NewFiberErrorHandler with your own if needed.

Generated navigation reconciliation

NewModuleRegistrar computes the expected primary and utility menu rows with BuildMenuSeedPlan, then calls SeedNavigation in reconciliation mode. This keeps quickstart-owned menu rows current without replacing host-authored rows.

Generated rows are normalized before persistence:

• target._generated_by is set to quickstart.
• target._generated_id stores the stable generated identity.
• request-scoped target state such as enabled, disabled, disabled_reason, and missing_permission is removed before comparison.

Use seed-plan options when a host owns the sidebar layout but still wants quickstart to collect module and translation menu contributions:

quickstart.NewModuleRegistrar(
    adm, cfg, modules, isDev,
    quickstart.WithMenuSeedParents(admin.MenuItem{
        ID:          "host.nav",
        Type:        admin.MenuItemTypeGroup,
        GroupTitle:  "Host Navigation",
        Collapsible: true,
    }),
    quickstart.WithMenuSeedTargetParentOverride("translation_queue", "host.nav"),
    quickstart.WithMenuSeedBaseItemTransform(func(item *admin.MenuItem) {
        if item == nil || item.Target == nil || item.Target["key"] != "translation_dashboard" {
            return
        }
        item.Label = "Translations"
        item.LabelKey = "menu.translations.overview"
        item.Target["name"] = "admin.translations.overview"
        item.Target["breadcrumb_label"] = "Translation Center"
    }),
    quickstart.WithMenuSeedModuleParentOverride("reports", "host.nav"),
    quickstart.WithMenuSeedItemTransform(func(moduleID string, item *admin.MenuItem) {
        if moduleID == "reports" && item != nil {
            item.Label = "Analytics"
        }
    }),
)

Use WithMenuSeedBaseItemTransform for quickstart-owned base/capability rows, including translation capability links. Use WithMenuSeedItemTransform for rows returned by module MenuItems(locale) contributors. Hosts that pin github.com/goliatone/go-admin and github.com/goliatone/go-admin/quickstart separately should upgrade both modules together when adopting base-item transforms so the seed-plan API and generated navigation reconciliation stay in sync.

Use ReconcileGeneratedNavigation directly when you need a dry-run report before applying changes:

report, err := quickstart.ReconcileGeneratedNavigation(ctx, quickstart.NavigationReconcileOptions{
    MenuSvc:  adm.MenuService(),
    MenuCode: cfg.NavMenuCode,
    Locale:   cfg.DefaultLocale,
    Items:    expectedItems,
    Apply:    false,
    RawInventory: admin.NavigationRawInventoryOptions{
        MenuCode:          cfg.NavMenuCode,
        Environment:       cfg.NavEnvironment,
        EnvironmentSource: "config.nav_environment",
    },
})

Generated navigation treats admin.MenuItem.Position as a sparse sort weight. This lets independent modules reserve ordering bands without knowing current sibling counts. Before writing to CMS-backed menu storage, quickstart sorts siblings by sparse weight and stable identity, then writes compact per-parent 0..n-1 positions because CMS/menu-builder APIs treat position as an insertion index. Generated leaf targets keep the original sparse weight in _generated_sort_order for diagnostics.

The report separates normal updates from operational diagnostics:

• Creates and Updates are generated rows that would be inserted or updated.
• PreservedUserRows are non-generated rows that are intentionally left alone.
• DuplicateIdentities reports duplicate or ambiguous generated identities; in apply mode ambiguous legacy matches are skipped.
• DestructiveCandidates reports stale generated rows whose identity no longer appears in the expected plan. They are not deleted unless the caller opts into destructive behavior.
• StaleTargetStateCleanup reports generated rows that carried transient request/permission state and will be cleaned by an update.
• CapabilityOmissions, PermissionFilteredItems, ParentPrunedItems, and RouteResolutionFailures are diagnostics for missing capabilities, permission-filtered rows, empty generated parents, or unresolved route data.
• RawInventoryUnavailable records scoped raw inventory failures. In dry-run mode this is a diagnostic; in apply mode a raw-inventory error returns before any create, update, delete, or managed-exclusion mutation.
• RawPresentButNotRendered reports generated rows present in raw storage but absent from the rendered menu, usually because render filtering or malformed target data hid a row that still affects convergence.
• CoordinationBackend, CoordinationScope, CoordinationSupported, and CoordinationWarning describe whether the menu backend coordinated convergence beyond this process. Treat unsupported coordination as an operational warning for multi-process or blue-green startup.

Set Apply: true to converge rows. Keep AllowDestructive off unless the host has explicitly reviewed the destructive candidates; generated rows are update-safe by default, but deleting or replacing rows can affect host-specific navigation customizations.

Durable activity ingestion

Use ConfigureActivityIngestion(ctx, adm, options) before adm.Initialize, then RegisterActivityIngestionRoutes(ctx, rootRouter, adm) outside browser auth groups. The bundle reuses NewAdminConfig scope options and URLKit activity.ingest; adm.ActivityIngestionURL() reports the sole mounted producer URL. Explicitly migrate go-users activity/scopes and admin.EnsureActivityIngestionSchema first. Provide producer/current-policy ports, browser authenticator, reader authorizer and access policy. The widget and full feed share durable authorized reads. See the canonical setup and contract, including its dependency and persistence contracts. Disabled hosts retain legacy behavior; the helper performs no DDL and registers no implicit route alias.