Walkthroughs

This section holds per-feature, step-by-step walkthroughs of Pinley flows. Each page is a narrative test plan: open X, click Y, see Z, verify W.

New here? Start with End-to-End — Preconstruction Lifecycle instead of jumping into a per-feature page — it tells the whole real business story (Bid Invite through Award, including the exits) with the reasoning behind each stage, and links out to the per-feature pages below for exact click-by-click steps.

Audiences

Three groups read these pages — and each one gets value from the same content:

Audience	What they do with it
Internal engineers	Run the flow end-to-end before merging a fix. Catch regressions that unit tests don't cover (modals, status transitions, deep links).
QA + estimators	Test new features when they hit dev. Each walkthrough's Verification Checklist is the pre-merge smoke pass.
Conor + client demos	Same page rendered to PDF (via make docs-pdf) and sent. Same content — no "demo doc" vs "test doc" divergence.

A walkthrough is not a high-level product spec (that's functional-specification/) and not a user story (that's user-journey-planning/). It's the procedural how — the exact clicks, fields, and expected results.

When to write a new walkthrough

• Whenever a feature ships that has a non-trivial multi-step user flow
• When a feature has hidden affordances (e.g. right-click context menus, keyboard shortcuts, deep links via query params)
• When testing a flow requires setup data that isn't obvious (e.g. "you need a bid in status X with a takeoff PDF in folder 06")
• When a flow has role-gated behavior that's easy to miss (e.g. profit visible only to Sr.PM+)

Naming + structure

• Filename: <feature>.md in kebab-case (takeoff.md, handoff-scope.md, change-orders.md). Flat — no numbered prefix. If/when the list grows, subdirectories by domain (preconstruction/, project-mgmt/) are the next step.
• Frontmatter: every page starts with metadata (see _template.md). Important fields: owner, linear (ticket refs), status, last_verified.
• Sections (in order):
  1. Prerequisites — role required, bid/project state, test data needed
  2. Numbered steps ## 1. Do X, ## 2. Do Y, …
  3. Verification Checklist — checkbox list of "must be true after walk"
  4. Known issues / current gaps — what's intentionally not working yet, with ticket refs
  5. Related docs — cross-links to other walkthroughs

Copy _template.md when starting a new one.

Updating an existing walkthrough

• Update the doc in the same PR as the code change. A walkthrough that drifts from reality is worse than no walkthrough.
• Bump last_verified: in frontmatter every time someone runs the flow end-to-end and it passes.
• Move outdated steps to Known issues with :warning: and a ticket ref — don't delete history; the audit trail helps reviewers.

Export workflow

• make docs-serve → live preview at http://localhost:8000
• make docs-pdf → renders entire site (or a section) to PDF for client send
• make docs-docx → Word export

PDF/Word both honor frontmatter and tables. Mermaid diagrams render in browser preview only — they show as code blocks in PDF.

Test data

Large test PDFs, drawings, Excel files, and other binary fixtures live on the Cara Shared Drive, in test-app-files/:

Cara Shared Drive — test-app-files

Subfolders are organized by feature area (matching walkthrough naming):

Subfolder	Contents	Used by
drawings/	PDF + DWG plan sets (Battery Park, Sheetmetal Shop, 390 Park Ave, Lever House, E25-1474 ME IFB.pdf)	Takeoff, Project Drawings
estimates-xlsx/	Takeoff / estimate spreadsheets (duct + pipe examples), HVAC Bids Log	Excel Imports
daily-log-photos/	Site photos for Daily Log photo uploads	Daily Logs
docs-pdfs/	Sample POs, subcontracts, recap reports	Documents / attachments
sample-project-A/	A complete real bid set (E25-1474: IFB plan set, estimate xlsx, takeoff drawing, recap, vendor quotes) used across the preconstruction lifecycle	End-to-End — Preconstruction Lifecycle, Detailed Reference — Sample Project A

When you reference a file in a walkthrough's Prerequisites section, name it explicitly so QA knows what to download. Example:

- **Test data**: `drawings/E25-1474 ME IFB.pdf` from the [test-app-files Drive folder](index.md#test-data)

Access: the folder lives on the Cara Shared Drive — ask Marko to add you if you can't open it.

Why not in repo?

Test PDFs are large (multi-MB), client-sensitive, and change rarely. Storing them in Git would bloat clone times and risk sensitive content in version-control history. Drive gives a single source-of-truth that anyone (including non-engineers) can curate, while keeping the repo lean.

CI tests that need a PDF upload

If a Playwright / integration test needs to actually upload a PDF in CI, don't point at the Drive file — commit a tiny synthetic PDF in tests/fixtures/ next to the test. Drive is for manual QA + local dev runs; CI gets self-contained fixtures.

Conventions

• Bold UI labels: button names, field labels, menu items, status chips — wrap in **…**. Example: click Open takeoff viewer.
• Italic for in-app terminology (*Pending* status, *Spec library*) — distinguishes terms from regular prose.
• Code blocks for URLs, console commands, JSON.
• Emoji for callouts: :warning: for caution, :check: for confirmation, :link: for deep-links.
• Tables for multi-column reference (tool buttons, status mappings, role permissions). Better than bulleted lists once columns ≥ 3.
• Routes as code: /projects/:projectId/detail?tab=budget.