Create flow: Community + custom rule UI, template review, facet recommendations, and app/docs reorg #46

2026-04-21T04:51:59Z

an.di commented

2026-04-21 04:51:59 +00:00

Overview

This branch delivers the Create Community and Create Custom CommunityRule wizard experiences end-to-end in the UI: structured screens under a single [screenId] route, facet-driven “recommended” ordering for custom-rule method cards (backed by new API + seed data), a tightened Final Review flow with chip edit modals, and a cleaner template review path (customize / use without changes, read-only template detail, navigation fixes).

It also reorganizes the app into route groups ((app), (marketing), (admin), (dev)), adds Cursor rules and AGENTS.md for contributors, and refreshes docs (create-flow canon, backend Linear tracker, CONTRIBUTING API table, roadmap) plus broad test coverage for new helpers and routes.

Why: Align the repo with Figma/product intent for the custom create journey, template entry from marketing, and recommendation matrix work already specified in docs—while keeping drafts, auth, and publish behavior consistent with existing APIs.

Changes

Create flow (custom path)

Screen registry + navigation: FLOW_STEP_ORDER, useCreateFlowNavigation (URL as source of step), CreateFlowScreenView, and layout/footer behavior (proportion bar, confirm footer steps, skip community-save when signed in → redirect to review).
Community stage: Updates to structure/size/select screens, community review (CommunityReviewScreen) and related state.
Custom rule stage: Core values screen with modals and local detail storage; card screens (communication, membership, conflict management) and right-rail decision approaches with useFacetRecommendations, rankMethodsByScore, deriveCompactCards.
Review & complete: Final Review rework (FinalReviewChipEditModal, applyFinalReviewChipEditPatch, buildFinalReviewCategoriesFromState); Completed tweaks; finalize/publish via useCreateFlowFinalize + existing POST /api/rules.

Template flow

/create/review-template/[slug]: useTemplateReviewActions, prefill/customize routing, pendingTemplateAction handling in community review, clearCreateFlowPersistedDrafts for marketing vs in-flow entry.
Template review UI: TemplateReviewCard + TemplateChipDetailModal; read-only / chip interactions per product cleanup.

Backend / data

GET /api/create-flow/methods — facet-scored methods per section.
GET /api/templates — optional facet.* query params + ranked templates/scores.
Prisma / seed: MethodFacet (and related) + data/create/customRule/*.json facet matrices; lib/server/templateMethods, methodSlugFromTitle, validation schemas.
Drafts: Adjustments on PUT/GET /api/drafts/me where needed for persisted shape.

App structure & tooling

Move create, login, profile under app/(app)/; marketing and admin layouts; components-preview under (dev).
New/updated UI primitives: e.g. Incrementer, IncrementerBlock, InlineTextButton, ModalTextAreaField, ApplicableScopeField, method edit field building blocks.

Docs & contributor experience

AGENTS.md, .cursor/rules/*.mdc (create-flow, API, components, i18n, tests, etc.).
docs/create-flow.md, docs/guides/backend-linear-tickets.md, docs/guides/backend-roadmap.md, docs/guides/template-recommendation-matrix.md, CONTRIBUTING.md (API table includes templates facets, create-flow methods, web vitals).

Tests

New/updated Vitest coverage: facet schemas, methods route, template methods/mapping, final review builders, template prefill, compact cards, migrate legacy state, Storybook/page tests as touched.

Screenshots

Screenshot 2026-04-20 at 10.49.16 PM.png

Screenshot 2026-04-20 at 10.50.17 PM.png

Screenshot 2026-04-20 at 10.50.38 PM.png

Screenshot 2026-04-20 at 10.51.09 PM.png

How to Test

Setup: docker compose up -d postgres mailhog, copy .env.example → .env, npx prisma migrate dev, optional npx prisma db seed, npm run dev. Enable sync if testing drafts: NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true.
Create (anonymous): From home, Create rule → walk Community steps → Review → Custom steps (core values, four card areas, decision approaches) → Confirm stakeholders → Final review → Publish (confirm 401/sign-in if anonymous) → Completed.
Signed-in: Confirm Save & Exit / draft behavior; community-save skipped (lands on review); profile placeholder still loads; sign-out from profile.
Templates: Home / /templates → open review-template → Customize / Use without changes (including from /templates?fromFlow=1 vs fresh marketing click).
Recommendations: After choosing community facet chips, open custom-rule card steps and confirm recommended ordering / badges when facets match seeded data.
API smoke: GET /api/templates, GET /api/create-flow/methods?section=communication&facet.size=… (with session if required by route).
Tests: npx vitest run (and npx tsc --noEmit / npx next build per AGENTS.md if you want CI parity).

Notes

Large diff (~400 files): mostly create-flow screens, tests, messages, and route moves; review by area (create → API → data → docs) if splitting isn’t an option.
Profile / “my rules” / public rule detail remain largely placeholder or separate tickets (see CR-86, CR-81); this PR does not complete Figma profile.
Stakeholder invites and Final Review + affordance product gaps are unchanged vs main (documented elsewhere).
Web vitals remain file-based; external RUM still future (CR-80).
Follow-ups: CR-93 (pass facets into marketing template fetches), profile-driven draft resume (CR-86), CR-84/CR-85 hygiene tickets.

You can shorten the Changes bullets further for the Gitea UI if the body is too long; the structure matches the template sections.

## Overview This branch delivers the **Create Community** and **Create Custom CommunityRule** wizard experiences end-to-end in the UI: structured screens under a single `[screenId]` route, **facet-driven “recommended” ordering** for custom-rule method cards (backed by new API + seed data), a tightened **Final Review** flow with **chip edit modals**, and a cleaner **template review** path (customize / use without changes, read-only template detail, navigation fixes). It also **reorganizes the app** into route groups (`(app)`, `(marketing)`, `(admin)`, `(dev)`), adds **Cursor rules** and **AGENTS.md** for contributors, and **refreshes docs** (create-flow canon, backend Linear tracker, CONTRIBUTING API table, roadmap) plus **broad test coverage** for new helpers and routes. **Why:** Align the repo with Figma/product intent for the custom create journey, template entry from marketing, and recommendation matrix work already specified in docs—while keeping drafts, auth, and publish behavior consistent with existing APIs. --- ## Changes ### Create flow (custom path) - **Screen registry + navigation:** `FLOW_STEP_ORDER`, `useCreateFlowNavigation` (URL as source of step), `CreateFlowScreenView`, and layout/footer behavior (proportion bar, confirm footer steps, **skip `community-save` when signed in** → redirect to `review`). - **Community stage:** Updates to structure/size/select screens, **community review** (`CommunityReviewScreen`) and related state. - **Custom rule stage:** **Core values** screen with modals and local detail storage; **card** screens (communication, membership, conflict management) and **right-rail** decision approaches with **`useFacetRecommendations`**, `rankMethodsByScore`, `deriveCompactCards`. - **Review & complete:** **Final Review** rework (**`FinalReviewChipEditModal`**, `applyFinalReviewChipEditPatch`, `buildFinalReviewCategoriesFromState`); **Completed** tweaks; **finalize/publish** via **`useCreateFlowFinalize`** + existing `POST /api/rules`. ### Template flow - **`/create/review-template/[slug]`:** `useTemplateReviewActions`, prefill/customize routing, **`pendingTemplateAction`** handling in community review, **`clearCreateFlowPersistedDrafts`** for marketing vs in-flow entry. - **Template review UI:** **`TemplateReviewCard`** + **`TemplateChipDetailModal`**; read-only / chip interactions per product cleanup. ### Backend / data - **`GET /api/create-flow/methods`** — facet-scored methods per section. - **`GET /api/templates`** — optional **`facet.*`** query params + ranked templates/scores. - **Prisma / seed:** `MethodFacet` (and related) + **`data/create/customRule/*.json`** facet matrices; **`lib/server/templateMethods`**, **`methodSlugFromTitle`**, validation schemas. - **Drafts:** Adjustments on **`PUT/GET /api/drafts/me`** where needed for persisted shape. ### App structure & tooling - Move **create**, **login**, **profile** under **`app/(app)/`**; marketing and admin layouts; **components-preview** under `(dev)`. - **New/updated UI primitives:** e.g. **Incrementer**, **IncrementerBlock**, **InlineTextButton**, **ModalTextAreaField**, **ApplicableScopeField**, method **edit field** building blocks. ### Docs & contributor experience - **`AGENTS.md`**, **`.cursor/rules/*.mdc`** (create-flow, API, components, i18n, tests, etc.). - **`docs/create-flow.md`**, **`docs/guides/backend-linear-tickets.md`**, **`docs/guides/backend-roadmap.md`**, **`docs/guides/template-recommendation-matrix.md`**, **`CONTRIBUTING.md`** (API table includes templates facets, create-flow methods, web vitals). ### Tests - New/updated **Vitest** coverage: facet schemas, methods route, template methods/mapping, final review builders, template prefill, compact cards, migrate legacy state, Storybook/page tests as touched. --- ## Screenshots <img width="895" alt="Screenshot 2026-04-20 at 10.49.16 PM.png" src="attachments/af2f7e0e-c6c3-45f3-82af-f8628023eead"> <img width="895" alt="Screenshot 2026-04-20 at 10.50.17 PM.png" src="attachments/836d738f-c4b2-40d6-a6ef-aaa4bd4f8cc6"> <img width="895" alt="Screenshot 2026-04-20 at 10.50.38 PM.png" src="attachments/1458b25c-0fc1-42fb-9f6e-d64892c8db18"> <img width="895" alt="Screenshot 2026-04-20 at 10.51.09 PM.png" src="attachments/3b6a2285-1094-4f1b-ba71-6703280170cf"> ## How to Test 1. **Setup:** `docker compose up -d postgres mailhog`, copy `.env.example` → `.env`, `npx prisma migrate dev`, optional `npx prisma db seed`, `npm run dev`. Enable sync if testing drafts: `NEXT_PUBLIC_ENABLE_BACKEND_SYNC=true`. 2. **Create (anonymous):** From home, **Create rule** → walk **Community** steps → **Review** → **Custom** steps (core values, four card areas, decision approaches) → **Confirm stakeholders** → **Final review** → **Publish** (confirm 401/sign-in if anonymous) → **Completed**. 3. **Signed-in:** Confirm **Save & Exit** / draft behavior; **community-save** skipped (lands on **review**); profile placeholder still loads; sign-out from profile. 4. **Templates:** Home / `/templates` → open **review-template** → **Customize** / **Use without changes** (including from **`/templates?fromFlow=1`** vs fresh marketing click). 5. **Recommendations:** After choosing **community facet** chips, open custom-rule card steps and confirm **recommended** ordering / badges when facets match seeded data. 6. **API smoke:** `GET /api/templates`, `GET /api/create-flow/methods?section=communication&facet.size=…` (with session if required by route). 7. **Tests:** `npx vitest run` (and `npx tsc --noEmit` / `npx next build` per AGENTS.md if you want CI parity). --- ## Notes - **Large diff (~400 files):** mostly create-flow screens, tests, messages, and route moves; review by area (create → API → data → docs) if splitting isn’t an option. - **Profile / “my rules” / public rule detail** remain largely **placeholder or separate tickets** (see **CR-86**, **CR-81**); this PR does not complete Figma profile. - **Stakeholder invites** and **Final Review `+` affordance** product gaps are unchanged vs main (documented elsewhere). - **Web vitals** remain **file-based**; external RUM still future (**CR-80**). - **Follow-ups:** **CR-93** (pass facets into marketing template fetches), profile-driven **draft resume** (**CR-86**), **CR-84**/**CR-85** hygiene tickets. --- You can shorten the **Changes** bullets further for the Gitea UI if the body is too long; the structure matches the template sections.

Screenshot 2026-04-20 at 10.49.16 PM.png

192 KiB

Screenshot 2026-04-20 at 10.50.17 PM.png

248 KiB

Screenshot 2026-04-20 at 10.50.38 PM.png

203 KiB

Screenshot 2026-04-20 at 10.51.09 PM.png

334 KiB

an.di added 15 commits 2026-04-21 04:51:59 +00:00

Skip create save page when logged in 92149d9fb0

Align DB with create community stage b15f0d6226

Implement core-values screen beae150f02