docs: add MVP user flows (7 flows with screen IDs and error paths, plus grant and Serverpod demo paths)

[XxHugheadxX]

Closes #22

Summary

Adds docs/blueprints/flows.md: what the user does in each MVP flow, step by step, including what happens when something fails. #23 (wireframes), #8 (API contract) and #25–#28 (app screens) can now derive from it.

• 7 flows, each with a Mermaid flowchart and a step table (screen ID, user action, system response, error or edge path):
  F1 connect wallet · F2 discover agents · F3 view agent detail · F4 create and register an agent · F5 hire and pay · F6 track a hire and see its result · F7 rate an agent (P1)
• Grounded in decisions already merged:
  • F4 follows the deploy steps of ADR-0004 (store the version, create the agent wallet, builder signs register_full, builder signs the set_agent_wallet authorization entry)
  • F5 follows ADR-0003 (USDC transfer to the agent's muxed address; the server's six checks before the agent runs)
  • F7 follows ADR-0002 (give_feedback needs the authorization of a verified paid hire; one rating per hire)
  • Field validations reuse the domain invariants from feat: core domain model (Agent, Skill, Hire, Payment, Reputation) #9 (I6–I11, I16, I17)
• Screen IDs reuse the app's existing screens: S01 landing, S02 marketplace, S03 agent detail, S04 hire sheet, S07 studio and S08 deploy sheet exist today. S05 my hires, S06 hire detail, S09 wallet connect and S10 rate sheet are new.
• Two demo paths:
  • the under-15-second grant video (feat: clickable demo shell for HackMeridian grant video #32): find, pay, result with the mock wallet
  • the under-2-minute Serverpod video (docs: Serverpod hackathon submission package #4): each segment mapped to one of the vision's five demo criteria

Acceptance criteria

• Every "In" item of the MVP scope in docs/vision.md is covered by at least one flow (coverage table at the top of the doc)
• Every flow has at least one error path (F1: 3 · F2: 2 · F3: 3 · F4: 6 · F5: 5 · F6: 3 · F7: 4 steps with an error or edge path)
• Every step references a screen ID, and the list of screen IDs is consolidated at the end of the doc
• Every Mermaid diagram renders (checked below; please confirm on GitHub)
• Both demo paths are defined
• The frontend owner and the backend owner approve this PR

Verification evidence

Structure, checked with a script over the Markdown:

step rows: 37 | without a screen ID: none
screen IDs used but not listed at the end: none | listed but unused: none
flows: F1..F7 | mermaid diagrams: 7
'#' or ';' inside mermaid blocks: 0 in all 7

Rendering: each diagram was sent to the Kroki Mermaid renderer and all 7 returned an SVG (HTTP 200; 15 to 31 SVG nodes each). F1, F6 and F7 first returned an intermittent HTTP 500 from the service and rendered unchanged on retry.

All relative links (vision anchors #in, #out, #7-demo-success-criteria, ADRs, domain model) resolve.

Notes for reviewers

• Agent Studio details (drafts, test run, edit, my agents) are left to docs: Agent Studio flows and wireframes #36, as the issue says; F4 covers creating and registering.
• Refunds for failed hires are out of the MVP (vision); F6 says so on screen instead of promising one.
• F5 step 2 blocks Confirm when the payer has no USDC or no trustline, so the wallet never signs a transfer that will fail.

[cloudflare-workers-and-pages]

Deploying puls3 with    Cloudflare Pages

Latest commit:	d37bcda
Status:	✅  Deploy successful!
Preview URL:	https://4c346a5e.puls3-4lw.pages.dev
Branch Preview URL:	https://docs-22-mvp-user-flows.puls3-4lw.pages.dev

View logs