Lesson 4 - Improve Intake and Review Pages

Taylor already has the right core record, but the first version still feels like a generic request tracker. The next step is to make the pages fit how HarborFlow’s team actually submits, reviews, and works with exception requests.

Keep editing in the Playground’s Editor tab. In this lesson, you are refining the pages that already point at ExceptionRequest, and checking each change against the Preview tab as you go.

A note on auth: the examples below keep auth = "optional" for now. Lesson 5 adds the [auth] block and a working sign-in page. Switch to auth = "required" there, once there is an actual login flow behind it — flipping it now would lock you out of every page you are about to test.

The Goal

By the end of this lesson, the app should feel usable for:

• account managers who submit exception requests
• ops managers who review them
• directors who need enough context to approve unusual cases

Improve The Intake Form

The first form should ask for what the team really needs to make a decision.

For HarborFlow, that usually means:

• a clearer title
• the customer name
• the exception type
• the priority
• a justification that explains why the exception is needed

Practical improvements:

• use labels that match the team’s language
• make required fields truly required
• remove any field that does not affect triage or approval
• add success messaging that tells submitters what happens next

For HarborFlow, the intake form might evolve into something like:

[[pages]]
path = "/requests/new"
title = "Submit Exception Request"
layout = "form"
auth = "optional"

[pages.form]
entity = "ExceptionRequest"
method = "create"

[[pages.form.fields]]
name = "title"
type = "text"
label = "Request Title"
required = true

[[pages.form.fields]]
name = "customerName"
type = "text"
label = "Customer Name"
required = true

[[pages.form.fields]]
name = "exceptionType"
type = "select"
label = "Exception Type"
required = true
options = [
  { value = "shipping_delay", label = "Shipping Delay" },
  { value = "pricing_adjustment", label = "Pricing Adjustment" },
  { value = "custom_terms", label = "Custom Terms" },
  { value = "other", label = "Other" }
]

[[pages.form.fields]]
name = "priority"
type = "select"
label = "Priority"
required = true
options = [
  { value = "low", label = "Low" },
  { value = "medium", label = "Medium" },
  { value = "high", label = "High" }
]

[[pages.form.fields]]
name = "justification"
type = "textarea"
label = "Business Justification"
required = true
rows = 6

[pages.form.onSuccess]
redirect = "/requests/{id}"
message = "Request submitted. Operations will review it next."

Make The List Page Useful

The list page is the ops team’s working queue. It should help them answer:

• what is new?
• what is urgent?
• what is still waiting on review?

For HarborFlow, that means tuning the list toward operational triage instead of generic display.

Typical improvements:

• sort by newest or highest priority
• make the status and priority fields visible
• make titles and page labels more specific
• reduce visual noise so the queue is easy to scan

That list page might look like:

[[pages]]
path = "/"
title = "Customer Exception Requests"
layout = "list"
auth = "optional"

[pages.queries.requests]
entity = "ExceptionRequest"
orderBy = { createdAt = "desc" }

Make The Detail Page Reviewer-Friendly

The detail page should tell the reviewer whether they can make a decision immediately.

For HarborFlow, the detail page should make it easy to understand:

• what the request is
• who submitted it
• why it matters
• how urgent it is
• what decision needs to happen next

A simple detail page baseline is:

[[pages]]
path = "/requests/:id"
title = "Exception Request"
layout = "detail"
auth = "optional"

[pages.queries.request]
entity = "ExceptionRequest"
where = { id = "{id}" }

HarborFlow Example Changes

By the end of this lesson, Taylor would make these changes:

• rename the home page from Requests to Customer Exception Requests
• add customerName and exceptionType to the form
• change details to Business Justification
• show priority and status prominently in the list and detail pages
• tighten the success message so submitters know the request is now in review

Lesson Output

By the end of this lesson, you should have:

• a better intake form
• a more useful queue page
• a detail page that supports actual review work

Use the Blueprint Reference if you need to look up form fields, queries, or detail-page options while refining these pages.

What Changes In blueprint.toml

In this lesson, you are mainly editing the page sections:

• update the list page title and query (auth stays optional until Lesson 5)
• update the form page fields, labels, and success behavior
• update the detail page so reviewers can inspect one request clearly

The entity stays mostly stable here. The emphasis is on page configuration and form design.

Checkpoint Blueprint

Use lesson-4-blueprint.toml if you want a complete, working file with the refined intake form, queue page, and detail page.

The checkpoint should validate cleanly:

zebric validate --blueprint lesson-4-blueprint.toml

Zebric Concepts In This Lesson

• Pages: list, form, and detail layouts become more specific to the workflow
• Forms: field labels, required rules, and success behavior start mattering
• Queries: list ordering and detail lookups define what each page shows

Next Lesson

Continue to Lesson 5 - Add Permissions and Guardrails.