# easel — brief

> Project genesis. What this project is, who it's for, why it exists.
> Update as scope is decided; leave TODOs for anything unknown so future
> sessions know to resolve them.

## What
A tool for **sending mockups to clients and collecting feedback on them** —
the job InVision used to do for us before it shut down.

The working shape (locked 2026-09-01 — see Open questions for the decisions):

- A **project** per client engagement, containing **screens** (Home, About,
  Services…), each screen holding one or more **design options**.
- The design itself is a **real HTML page**, shown full-size and scrollable —
  not a flattened image. Clients see the actual thing.
- Clients **leave comments pinned to a spot on the design**, and we reply.
  Pins have an open/resolved state so a round of feedback can be worked
  through and closed out.
- We get **notified when feedback lands** so we can act on it the same day.
- Clients can **pick an option** ("this one") to lock a direction.

## Why
Two goals in tension, and getting the balance right *is* the product:

1. **Cost the client as little time as possible.** They should be able to
   open a link, sign in once with their BW account, and understand what
   they're looking at with no instructions and no learning curve.
2. **Still get real, specific feedback.** Vague or absent feedback is what
   makes mockup rounds drag. We need enough detail to know what to change and
   to **lock in a final direction** before the remaining pages are designed.

That second goal is why this is more than a screenshot in an email: the
feedback has to be structured enough to act on, and the client has to be
actively nudged toward giving it.

### The usual engagement shape (drives the design)
We send the **home page first**, get it approved, then design the **remaining
2–4 pages** against the direction it settled. So the tool's most important
moment is the *first* send — one page, possibly two or three options of it,
to a client who has never seen the tool before. Everything after that is
easier. Optimise for that first send.

## Who
- Owner: rian
- **Adi** — owns the build from 2026-09-01 (M2 onward); author of the
  `Proto Preview` prototype this is based on
  (see `.logs/planning/inputs-2026-08-28.md`).
- End users: **us** (creating and sending concepts, triaging feedback) and
  **our clients** (viewing concepts, leaving feedback). The client side is the
  side that has to be effortless.

## Prior art we're drawing on
Three inputs, written up in full in `.logs/planning/inputs-2026-08-28.md`:

1. **InVision** — the thing we're replacing. Pinned comments on a design,
   threads, resolve.
2. **Adi's `Proto Preview` prototype** (`notes/adi-invision-app-idea.mp4`,
   transcript alongside it) — a working WordPress plugin with the
   project/screen/option model, pinned comments, and a play-vs-comment mode
   toggle. This is the closest thing to a spec that exists.
3. **The hartlingowners welcome walkthrough** — a guided, spotlit coach-mark
   tour. rian's idea: use this *presentation* pattern to walk a client through
   a concept, rather than dropping them on a page and hoping they know what to
   look at. See "The walkthrough idea" in the inputs doc.

## Domain
- Dev/prod: <https://easel.bowden.works> (no separate dev/staging split —
  Pattern B apps are never gated; see Stack)

## Stack
FastAPI + React SPA, scaffolded via the one-prompt BW app standard
(`/srv/system/id-auth/app-auth/new-bw-app.sh`) — "Sign in with BW" (Pattern B)
for user accounts, rather than hand-rolled auth. `has_instances = false`
(`bw-app.toml`): app-wide levels only, no per-instance "projects" — turn on
by setting `instance_noun` in `bw-app.toml` and re-running the scaffolder if
that's needed later.

**Note:** Adi's prototype is a WordPress plugin; decided 2026-09-01: rebuild
on this stack, treating his plugin as spec. The `has_instances` flip to `true`
happens as part of the rebuild (`/goal`).

## Open questions
~~Resolved 2026-09-01 by rian~~ — the five original forks are settled; see
`.claude/commands/goal.md` §2 for the binding form:

1. **Client accounts: YES — members only.** No anonymous commenting. Clients
   are external BW accounts granted per-instance.
2. **Rebuild, adapting Adi's design** (his plugin is spec, not code).
3. **Presentation: both** — overview grid AND the guided walkthrough (with
   per-step approvals) survive into easel.
4. **Email:** outbound delivery stays the Interaction Standard's unbuilt seam;
   in-app bell embryo only for now.
5. **Instances: ON** (`instance_noun = "project"`).

Still genuinely open: whether mockups get their own serving subdomain
(defense-in-depth beyond CSP-sandbox; needs rian for DNS/Caddy).

**Reopened for M2** (rian, 2026-09-01) — a concept is now **two options plus
toggleable variants** (brand decoration, header config), not one option per
combination. The model questions that follow are in
`.logs/planning/next-milestone-onboarding-and-variants.md`.

## Not doing
- **Anonymous/guest commenting** — members only (rian, 2026-09-01).
- **Absorbing `review` or `scout`** — easel is the mockup presentation &
  feedback step; review (build signoff) is a separate future caddie app;
  scout owns research (rian, 2026-09-01).
- **Staging-URL review** — that's review's job, not easel's.