descrybe/docs/admin-roles-support/19-defaults-alignment.md

19 — Plan / role defaults alignment (agent 19/20)

Status: Implemented end-to-end defaults for public ladder, custom enable-all, Legacy (A1), and staff role ceilings.
Sources: 03-roles-matrix.md / .json, docs/plan-permissions/06-defaults-matrix.md.

---

PROBLEM

Public ladder defaults, custom enable-all, and Legacy (A1) limited nav must agree across API resolve, seeds, admin UI profiles, and demo assignment — without treating A1 as custom all-ON.

---

Effective matrices

Profile	Source of truth	Default behavior
Free	freePlanFeatureOff	AI / API keys / BYOK / campaigns off
Starter	starterPlanFeatureOff	BYOK off
Growth / Business	all registry ON	empty sparse overrides
Enterprise	is_custom=true ? custom path	all ON
Custom deals (Merkur, …)	IsCustomPackage	all ON (create materializes enable-all)
Legacy (A1)	legacyFeatureAllowlist / 03-roles-matrix	image-nav allow-list only; processing.monitor OFF
Staff admin / developer	DefaultStaffRoleAllows	all feature keys ON; full /admin
Staff support_staff	denied set in staff_role_defaults.go	support queue + assist; no billing mutation routes

Resolve order for plans: Legacy ? Custom enable-all ? Free/Starter denials ? Growth+.

---

A1 / Local Demo Co

Piece	Behavior
Plan name patterns	Legacy, A1*, contains legacy / a1 slovenija
Company cohort	legacy_company_id = 97e1a309-3d23-4aa2-b518-8e8d7afdfec7 or name Local Demo Co / A1
Seed	EnsureLegacyDefaults upserts plan Legacy (Enterprise credit pack, unlimited SKUs, is_legacy=true)
Assignment	A1 cohort companies get Legacy when missing or on non-legacy profile
Demo	seed-demo assigns Legacy (not Enterprise) so capabilities match limited nav
Repair	Full enable-all plans.features on legacy-named rows ? SparseLegacyOverrides (idempotent)

ASSUMPTION: Empty {} still resolves via DefaultPlanFeatures by name; seeder writes sparse false keys so admin UIs show an explicit matrix.

---

Implementation map

Piece	Path
Legacy detect + allow-list	apps/api/internal/billing/legacy_plan.go
Legacy plan row + A1 assign	apps/api/internal/billing/legacy_plan_seed.go (EnsureLegacyDefaults)
Sparse legacy helpers	apps/api/internal/billing/legacy_plan_features.go
Feature seed hook	EnsureDefaultFeatureSeeds ? EnsureLegacyPlanFeatureSeeds; EnsureDefaultPlans ? EnsureLegacyDefaults
Custom vs legacy	IsCustomPackage excludes legacy names
Staff role defaults	apps/api/internal/auth/staff_role_defaults.go
Schema	apps/api/sql/schema/028_plan_is_legacy.sql (plans.is_legacy)
Admin UI profiles	apps/web/src/lib/admin-plan-permissions.ts (LEGACY_FEATURE_ALLOWLIST, profiles)
Billing display	isLegacyPlan in apps/web/src/lib/billing-display.ts

---

Idempotency

• EnsureDefaultPlans / EnsureLegacyDefaults / EnsureLegacyPlanFeatureSeeds are safe to re-run.
• Non-empty partial admin feature maps on legacy plans are not wiped (only empty or full enable-all).
• Global section gates use ON CONFLICT DO NOTHING.

---

Verification

cd apps/api
go test ./internal/billing/ ./internal/auth/ -count=1 -run "DefaultPlanFeatures|Legacy|IsCustom|Sparse|StaffRole|Normalize|PlanAllows"

Integration (after migrate 028 + seed-demo):

• TestLocalDemoCoLegacyCredits — Local Demo Co on Legacy with 1M credits
• Capabilities: processing.monitor false; catalog.products / feeds.list true

---

Coordination notes

• Agent 5 owns overlapping legacy seed docs (05-legacy-seed.md); this file is the alignment checklist for agent 19/20.
• Agent 6 wires staff_role schema/middleware; defaults here are the ceiling until that lands (StaffRoleFromPlatformAdmin bridges the boolean).
• Agent 8 admin profiles should match LEGACY_FEATURE_ALLOWLIST ? Go legacyFeatureAllowlist (66 ON keys from 03-roles-matrix.json).