Keystone Onboarding
Grounded Different conceptual frame — viable within existing product constraints
Alternative A Grounded

Risk-First Ordering

Incremental
Frame

Tasks ordered by security risk severity instead of workflow dependency

Concept

The checklist leads with audit logging (disabled = compliance risk, hardest to retroactively fix), then auth method (insecure default = security risk), then policy (overly permissive = data risk), then secrets engine (no secrets yet = low risk). Each task label includes its risk tier (Critical / High / Medium / Low). The organizing principle is "fix the most dangerous gaps first."

Satisfies job stories
  • JS1 (know what to configure): Addresses it - tasks are ordered and labeled, reducing documentation dependence
  • JS2 (readiness signal): Addresses it - all four checked = ready
  • JS3 (auth-secrets dependency): Partially - audit logging first means secrets engine and auth method are adjacent (items 2 and 4), but the dependency rationale is weaker since they're not sequential
  • JS4 (audit logging visibility): Strong - audit logging is item 1, most prominent position
  • JS5 (policy premature): Partially addressed by placing it third rather than first, but not fully resolved
Key difference from recommended

Organizing principle shifts from dependency order (what unlocks what) to risk order (what breaks you if skipped). Addresses the Compliance Overseer persona more directly - their primary concern (audit logging) leads the list.

Tradeoff

The dependency between auth method and testing secrets engine is weaker with this ordering - operators may still hit the backtrack problem from JS3. Risk labels may alarm operators without giving them actionable context.

Alternative B Grounded

Progressive Disclosure by Persona Role

Incremental
Frame

Checklist adapts its presentation based on the detected operator role

Concept

On first load, the Cluster Overview asks a single question: "What best describes your role on this cluster?" (Platform Admin / Security Lead / Application Team). Platform Admin gets the full four-task checklist in dependency order. Security Lead sees audit logging and policy prominently first with auth method and secrets engine secondary. Application Team sees auth method and secrets engine only (the components they need to use the cluster without caring about compliance). The readiness signal reflects only the tasks relevant to the logged-in role.

Satisfies job stories
  • JS1 (know what to configure): Strong - role-specific guidance reduces noise for each persona
  • JS2 (readiness signal): Weaker - "ready for whom?" becomes ambiguous when different roles see different tasks
  • JS3 (auth-secrets dependency): Addresses it for Platform Admin path
  • JS4 (audit logging visibility): Strong for Security Lead path; absent for Application Team path
  • JS5 (policy premature): Partially - Security Lead sees policy earlier, Platform Admin sees it in dependency order
Key difference from recommended

Shifts the organizing principle from "everyone does the same four tasks" to "different roles have different definitions of ready." Requires a role-selection step that the PRD does not include and that could fragment the readiness signal.

Tradeoff

Role selection adds friction upfront and fragments the "cluster ready" signal across personas. Operators in multi-role organizations may not fit neatly into one category. Engineering complexity of conditional checklist logic is meaningfully higher.

Ambitious Fewer constraints — challenges PRD assumptions to reveal what's possible
Alternative C Ambitious

Cluster Bootstrapping Service

Transformative
Frame

KCP provisions a minimum viable Keystone configuration on cluster creation, eliminating first-time setup as a manual task (challenges PRD constraint: "no new backend service" and "no new infrastructure dependencies")

Concept

When an operator creates a Keystone Enterprise cluster, KCP automatically provisions: Key-Value Store v2 at `secrets/`, Service Account auth at `auth/service-account/`, a scoped operator policy, and a managed audit device. The Cluster Overview shows "Auto-configured on [date]" with annotation badges on each component. Operators can modify or delete any component; the bootstrapped defaults are a starting point. The Cluster Overview readiness indicator says "Configured" from day one, with a "Customize configuration" prompt rather than an "incomplete setup" warning.

Satisfies job stories
  • JS1 (know what to configure): Eliminates it - the cluster arrives pre-configured
  • JS2 (readiness signal): Addresses it - cluster is always "ready" by baseline definition on day one
  • JS3 (auth-secrets dependency): Eliminates it - both are configured before the operator lands
  • JS4 (audit logging visibility): Addresses it - audit logging is always on (managed device)
  • JS5 (policy premature): Eliminates it - a scoped default policy is bootstrapped; operator customizes it with context
Key difference from recommended

Inverts the model from "guide the operator to configure" to "pre-configure and let the operator modify." Eliminates first-time setup friction at its root. Requires product and platform decisions outside the current initiative's scope.

Tradeoff

Challenges the PRD constraint that the solution requires no new backend service. Auto-provisioned defaults (especially Service Account) may not match what enterprises want - some have strict requirements about what auth methods are enabled. Requires an opt-out mechanism. Changes the product responsibility model: Meridian is now responsible for the default configuration choices, not just the platform.

Alternative D Ambitious

Setup-as-IaC Export

Innovative
Frame

The onboarding checklist generates a Terraform configuration that the operator can apply to this cluster (and future clusters), rather than guiding manual UI-based setup (challenges PRD assumption that operators configure via UI)

Concept

Instead of an interactive checklist, the Cluster Overview shows a "Configure via Terraform" panel. The operator answers four questions (what auth method type, what secrets engine type, policy scope, audit device type) and the system generates a complete Terraform module for Keystone with all four components configured. The operator applies it with `terraform apply` or uses Keystone's IaC runner. Once the module is applied, the Cluster Overview shows "Configured via Terraform" with a link to the Terraform module for future reference. All subsequent clusters in the same organization can reuse the module.

Satisfies job stories
  • JS1 (know what to configure): Strong for IaC-native operators - the Terraform module makes explicit what needs to exist
  • JS2 (readiness signal): Addresses it - applied module = ready; cluster state check confirms
  • JS3 (auth-secrets dependency): Addresses it - Terraform resource dependencies make the order explicit in code
  • JS4 (audit logging visibility): Addresses it - audit device is in the module
  • JS5 (policy premature): Partially - policy is in the module, but the same wildcard risk exists unless the path configuration question is specific enough
Key difference from recommended

Shifts the interaction model from UI-guided manual configuration to IaC-generated declarative configuration. Addresses the Repeat Operator's frustration (repeat setup = reapply the module) and creates a reusable artifact. Does not serve operators who are UI-native or who avoid Terraform.

Tradeoff

Challenges the PRD assumption that setup happens in the Keystone portal. Excludes operators who are not Terraform users (P6, P9 from research were not IaC-primary). Requires Keystone IaC integration or at least a Terraform download + apply workflow. Operators who configure via UI and operators who configure via IaC end up with different mental models of cluster management.

How the pipeline works
Eight stages turn a PRD and research study into a committed design. Each stage produces a specific artifact that the next stage depends on.
01
PRD
What we're building and why. Defines the problem space, requirements, constraints, and explicit non-goals. The agent reads it to understand what is in scope before touching any other artifact.
Validated requirements + constraints
02
Research
What users actually do. Behavioral patterns, verbatim quotes, and unmet needs from real sessions. Research is not summarized — it is indexed so the synthesis step can cite specific findings.
Behavioral patterns + direct quotes
03
Synthesis
Where PRD and research agree, where they conflict, and what research found that the PRD didn't anticipate. The job stories that frame the design opportunity emerge here — grounded in evidence, not assumption.
Job stories + validated / conflicting signals + gaps
04
Strategy
The design opportunity framed for this product's context. Which user segments to prioritize, which surface to use, and the design philosophy that should guide decisions downstream.
Strategic framing + persona priority
05
Journey Map
The experience sequence from the user's point of view — the moments where friction appears, where setup dependencies create backtrack risk, and where handoffs between surfaces occur.
Stage-by-stage experience map
06
Solutions
Each job story is explored through three innovation lenses: Conventional (incremental, within current constraints), AI/ML-Enabled (what becomes possible with behavioral inference), and Step Eliminator (what if we removed the problem entirely). A recommended direction is chosen with explicit rationale. Four alternative approaches challenge PRD assumptions. With --with-rigor: a Recommendation Defense section is required before PDR-001 — assumption inventory, per-alternative justification against the job stories, and research grounding.
Recommended direction + 4 alternatives (+ defense with --with-rigor)
PDR
Design Decision Records
Four records commit the key choices before wireframing begins: Architecture (which UI pattern), Scenario (which user paths to design for), Journey Map (updated from solutions), WireframePlan (what to build and to what quality targets). Each PDR is a gate.
Committed architecture + wireframe plan
WF
Wireframes
Screens built to the wireframe plan in Storybook, then compiled into a single-file interactive showcase. Alternative approaches get their own screens alongside the recommended direction.
Interactive showcase + alternative mocks
The evidence for this run
5 job stories surfaced from synthesis. Each was explored through three innovation lenses before a direction was chosen.
Job Story 1
When I provision a new Keystone cluster and land on the Cluster Overview, I want to know what I need to configure before my team can use it, so I can complete setup without reading external documentation.
P1: "I know how Keystone works. What I don't know is what this specific thing expects me to do first"; all 9 opened docs within 5 minutes
Lens 1
Conventional
Incremental
Add an onboarding checklist panel to the Cluster Overview page with four items: auth method, secrets engine, policy, and audit logging. Each item shows its completion state (checked / unchecked), a label, and a link to the relevant configuration surface. A progress counter (e.g., "2 of 4 complete") gives a sense of advancement. The panel is dismissable and state persists per cluster.
Tradeoff
The checklist surfaces the tasks but provides no guidance on why the order matters or what each task does. First-time operators still need documentation to understand what they're enabling.
Lens 2
AI/ML-Enabled
Innovative
The system observes completed setup patterns across all Keystone clusters created in the last 90 days - specifically, which task order leads to successful cluster handoff (first non-admin auth method in use within 7 days) versus which task order leads to partial setup or abandoned clusters. The checklist presents the statistically optimal setup path for this operator based on their cluster tier, the auth methods they have used in previous clusters, and their team's existing Keystone configuration patterns. The inline rationale is specific: "Teams on the Starter tier most often start with OIDC auth - you have an existing OIDC provider configured in your Keystone organization." The step suggestion is personalized, not generic.
Tradeoff
Requires cross-cluster behavioral data that may raise privacy concerns for enterprise customers. Personalized suggestions may be confusing if the recommendation differs from a team's established runbook. Cold start problem: new organizations with no prior clusters get generic suggestions.
Lens 3
Step Eliminator
Transformative
The system detects that a new cluster has been provisioned and automatically bootstraps a safe minimum configuration before the operator lands on Cluster Overview: enables Key-Value Store v2 at `secrets/`, enables Service Account auth at `auth/service-account/`, attaches a scoped operator policy, and enables a file audit device at a default path. The operator lands on a cluster that is already usable. They can reconfigure any component, but the "start from zero" gap is eliminated. The Cluster Overview shows what was auto-configured with a clear "auto-bootstrapped on provisioning" annotation and links to customize each component.
Recommended
Lens 1 (Conventional), informed by Lens 2 insights for rationale content
The PRD explicitly requires no new backend service and no changes to existing configuration surfaces; Lens 3 requires platform-level write permissions at provisioning time that exceed current scope; Lens 2 personalization insights can be partially incorporated into the static rationale copy without requiring cross-cluster ML infrastructure (the insight about auth method ordering is already surfaced by research and can be hardcoded as guidance rather than learned).
Job Story 2
When I've completed the core setup tasks on a new cluster, I want a signal that the cluster is ready to hand off, so I can stop second-guessing whether I've missed something.
P3: "Healthy and ready aren't the same thing... something that says here are the things that need to be true"; P6 expressed same uncertainty post-task
Lens 1
Conventional
Incremental
When all four checklist tasks are complete, the checklist transitions to a "Setup complete" state with a success indicator (checkmark, green accent) and a "Cluster is ready" label. The Cluster Overview header or status area updates to reflect readiness alongside the existing health status.
Tradeoff
Binary ready/not-ready misses cases where an operator has completed the minimum but hasn't configured the cluster for their specific use case (e.g., only a KV engine when they actually need PKI). Also doesn't address the Compliance Overseer who arrives after dismissal.
Lens 2
AI/ML-Enabled
Innovative
The system infers "ready" based on signals beyond binary task completion: it observes whether the configured auth method has been used to authenticate at least once (a successful `sys/auth/{method}/login` call), whether any secrets have been written to the mounted secrets engine, and whether the policy has been bound to an entity or token. A cluster where all four tasks are checked but no authentication has occurred in 48 hours is flagged as "configured but not yet active" rather than "ready." The readiness signal communicates real operational confidence - the cluster isn't just set up, it's being used.
Tradeoff
Creates a chicken-and-egg problem - readiness requires audit logging to be on, but audit logging is one of the four setup tasks. Operators may find a "configured but not active" state confusing if they've legitimately finished setup and not yet onboarded their team.
Lens 3
Step Eliminator
No viable step eliminator identified - the completion signal is the outcome of the setup process, not a task in itself. The underlying job story is about confidence, not elimination. Making the operator confident without them doing the setup work would require auto-bootstrapping (addressed in Job Story 1, Lens 3). The completion signal is an inherent artifact of a guided flow, not a friction to be eliminated.
Recommended
Lens 1
Binary ready/not-ready covers the research-validated need (P3: "something that says here are the things that need to be true"); Lens 2 introduces dependency on audit log analysis that isn't reliable before audit logging itself is enabled, and adds a post-task waiting period that conflicts with the First-Time Operator's goal of completing setup in one session.
Job Story 3
When I'm setting up a new cluster and I start configuring secrets engines before auth methods, I want the UI to tell me the dependency, so I can avoid having to backtrack when I go to test access.
P5: "I went to Secrets Engines first... I didn't think about auth until I tried to test it and realized I had nothing to authenticate as"
Lens 1
Conventional
Incremental
Present the four checklist tasks in a fixed order: (1) Auth Method, (2) Secrets Engine, (3) Policy, (4) Audit Logging. Add a one-sentence rationale below the Auth Method item: "Complete this first - you'll need an auth method to test your secrets engine and validate your policies." The order itself is the guidance; the rationale explains why.
Tradeoff
Operators can still navigate to Secrets Engines before Auth Methods via the sidebar - the checklist order is advisory, not enforced. The rationale note helps only operators who read it.
Lens 2
AI/ML-Enabled
Innovative
The system detects when an operator has navigated to Secrets Engines without completing Auth Method setup. It tracks the navigation sequence in real time - specifically, the pattern "Secrets Engines visited before any auth method configured" - and surfaces a contextual nudge on the Secrets Engines List: "You haven't set up an auth method yet. Once you enable a secrets engine, you'll need an auth method to test access to it." The nudge is triggered only when the operator is mid-setup (checklist not dismissed, auth method not complete) and navigates away from the recommended order.
Tradeoff
Inline nudges on configuration surfaces (Secrets Engines List) require placing onboarding-context-aware UI on surfaces that are explicitly out of scope for this initiative. Engineering boundary between onboarding component and existing surfaces becomes harder to maintain.
Lens 3
Step Eliminator
No viable step eliminator identified - the dependency exists because secrets engine testing requires authentication, which requires an auth method. This is not a UX problem that can be eliminated; it is a real technical constraint. The best available solution is surfacing the dependency before the operator encounters it, which is addressed by Lens 1 and 2.
Recommended
Lens 1
Lens 2's real-time nudge requires instrumenting navigation events on existing surfaces that are out of PRD scope; the checklist order with inline rationale is sufficient to surface the dependency for the First-Time Operator before they leave the Cluster Overview.
Job Story 4
When I'm reviewing a cluster I recently provisioned, I want audit logging status to be visible on the Cluster Overview, so I can confirm compliance requirements are met without navigating to a separate surface.
P4: "I didn't even know that was a thing I had to turn on"; P7: "I found the audit log setting in the docs, not the UI. That's backwards"
Lens 1
Conventional
Incremental
Add an audit logging status badge to the Cluster Overview page - visible at all times, independent of the onboarding checklist. Shows "Audit logging: Enabled" or "Audit logging: Disabled" with a clear visual treatment (green/amber or a warning icon for disabled). Derives state from `GET /api/v1/audit` on every Cluster Overview load.
Tradeoff
Status badge is read-only for non-admin visitors. Compliance Overseer can see the state but not act on it. Does not tell them how long audit logging has been enabled or what device type is configured.
Lens 2
AI/ML-Enabled
Innovative
The system tracks audit logging continuity over time - not just whether it is currently enabled, but whether it has been consistently enabled since cluster creation. If audit logging was disabled at any point after initial setup, the status surfaces a warning: "Audit logging was disabled on [date] and re-enabled on [date]. There is a gap in the audit trail." The system infers compliance risk by comparing audit logging history against the cluster's activity log (requests processed during the gap). This gives the Compliance Overseer not just current state but audit trail integrity.
Tradeoff
Requires KCP platform to store audit device state change history, which is a new data requirement. Compliance Overseer receiving a "gap in audit trail" warning may trigger escalation responses that the design needs to support (e.g., what does the operator do with this information?).
Lens 3
Step Eliminator
Transformative
The audit trail is always on by default. Keystone Enterprise automatically enables a managed audit device for every cluster at provisioning time, writing to a Meridian-managed log store. Operators can add additional audit devices but cannot disable the managed one. The compliance gap disappears because the system guarantees audit continuity - the job story no longer exists.
Recommended
Lens 1, with the insight from Lens 2 used to inform future iteration
Lens 3 is the right long-term answer but requires a platform-level product decision outside the scope of this initiative; Lens 2's audit trail integrity signal is valuable but requires historical state storage that is a new engineering dependency; Lens 1 solves the immediate high-severity research finding (8/9 operators missed audit logging entirely) within the current constraints.
Job Story 5
When I'm creating a policy on a new cluster before I've defined my secrets layout, I want the UI to tell me that policy configuration benefits from knowing my paths first, so I don't write a placeholder policy I'll forget to update.
P8: "I'm writing a wildcard... this is a placeholder"; P5 created same pattern
Lens 1
Conventional
Incremental
The policy checklist item includes a contextual note below the task label: "Most useful after you know your secrets paths. If you haven't decided what to store yet, consider completing this step after enabling your secrets engine." The note is inline - it doesn't block or reorder anything. Operators can still click the policy link and create a policy immediately.
Tradeoff
Operators who ignore the note (or skim the checklist) will still create placeholder policies. The note is advisory, not procedural.
Lens 2
AI/ML-Enabled
Innovative (though the intelligence is rule-based, not ML - rating adjusted to Incremental given the implementation is deterministic)
The system detects when an operator creates a policy containing only wildcard paths (e.g., `path "secrets/*"` with `capabilities = ["create", "read", "update", "delete", "list"]`). On saving a wildcard policy while the operator is in the onboarding flow (checklist not dismissed), the Policies editor surfaces an inline warning: "This policy grants broad access. If you haven't defined your secrets paths yet, consider narrowing this policy before using it in production." The system infers "overly broad" from the policy policy DSLstructure - no ML required; this is rule-based analysis of the policy path patterns.
Tradeoff
Wildcard policies are sometimes intentional (admin policy templates, emergency access policies). A blanket warning on wildcard paths will produce false positives for experienced operators. The warning must be dismissable and not block saving.
Lens 3
Step Eliminator
Transformative (by elimination - removes the problem through ordering, not through UI intervention)
The checklist reorders policy to the fourth position (after auth method, secrets engine, and audit logging) instead of the third. By the time the operator reaches policy, they have already configured a secrets engine and know their mount paths. The dependency on secrets layout is resolved by task ordering - operators naturally arrive at policy creation with the context they need. No UI warning or inline note is required.
Recommended
Lens 3 - reorder policy to fourth position
Moving policy after audit logging resolves the premature-policy problem through sequencing rather than UI warnings, which reduces cognitive load; by the time operators reach policy (task 4), they have secrets engines configured and know their mount paths; this also moves audit logging - the highest-severity gap from research - to an earlier position (task 3) where it is less likely to be skipped.
Strategic Recommendation

The five job stories point to a single organizing idea: cluster configuration state as a surface-level contract. The current Cluster Overview shows cluster health (is this machine working?) but not cluster readiness (is this cluster usable by my team?). The recommended solutions collectively reframe the Cluster Overview as a place that answers both questions - health and readiness - and keeps those answers visible beyond the initial setup session.

The most impactful design decision in this set is not the checklist itself but the persistent status layer: readiness indicator and audit logging status that remain on Cluster Overview after the onboarding is dismissed. These give the Compliance Overseer a reading surface, give the First-Time Operator a confidence signal, and give the Repeat Operator a quick-scan overview on any return visit.

The reordering of policy to fourth position (Lens 3 on Job Story 5) is the only transformative recommendation and the most structurally interesting one - it eliminates the placeholder-policy problem by ordering tasks so the context for policy creation is available when the operator reaches it. This is worth a PDR-001 design decision note, as it departs from both the journey map sequence and the PRD's assumed order.

The feature brief should frame this effort around one idea: readiness as a product state, not just a UI pattern. The checklist is the onboarding mechanism. The persistent status indicators are the product behavior.

---

Recommendation Defense
--with-rigor
What this recommendation assumes
First-Time Operators will read the inline rationale copy in the checklist before navigating away from Cluster Overview — if they skim past it, the auth-before-secrets dependency (JS3) surfaces only as friction, not prevention.
The Keystone API exposes reliable, consistent state for all four setup tasks (auth method, secrets engine, policy, audit logging) via `GET /api/v1/auth`, `GET /api/v1/mounts`, `GET /api/v1/policy`, and `GET /api/v1/audit` without requiring additional instrumentation or new backend dependencies.
The platform preferences API can persist checklist dismissal state across sessions per cluster, as stated in the PRD — dismissal UX depends on this without a fallback.
A visible ordered checklist on Cluster Overview is sufficient to surface the auth-before-secrets dependency for the majority of first-time operators, without requiring changes to the Secrets Engines or Auth Methods surfaces themselves.
Research grounding
Ordered checklist with inline rationale
P2 — "I'd love something that says: here are the four things you need to do, in this order, and here's why each one matters." 7/9 participants had no clear setup order (Research: Key Findings). Directly validates both the checklist format and the per-item rationale.
Auth-first task ordering
P5 — "I went to Secrets Engines first... I didn't think about auth until I tried to test it and realized I had nothing to authenticate as." Confirms the auth-before-secrets dependency is a real backtrack that occurs in practice, not a theoretical concern.
Persistent audit logging status indicator
8/9 participants missed audit logging entirely. P7 — "I found the audit log setting in the docs, not the UI. That's backwards." Confirms the gap is surface-level visibility, not discoverability in the nav — supports a persistent indicator independent of the checklist.
Policy reordered to fourth position
P8 — "I'm writing a wildcard... this is a placeholder." P5 created the same pattern. 5/9 participants created wildcard placeholder policies before their secrets layout was defined. Supports moving policy to last — after secrets engine — so operators have paths before writing policy rules.
Readiness signal distinct from health
P3 — "It says the cluster is healthy but I have no idea if it's actually ready." P3 and P6 expressed the same uncertainty post-task. Directly validates a persistent readiness indicator that survives checklist dismissal.
--