feat(auth): reduce login hop friction without lowering the security bar

[PeterGuy326]

schemaVersion: requirement-record.v1
revision: R1
status: needs-design
priority: P1
productOwner: "@PeterGuy326"
technicalOwner: "unassigned"
userOutcome: "A non-technical first-time user completes doc login with fewer cognitive hops, while the magic-link security model remains the authoritative mechanism."
requirements:
  - REQ-001
  - REQ-002
acceptanceCriteria:
  - AC-001
  - AC-002
parent: null
dependencies: []
supersedes: []
lastDecisionAt: null

User problem and observable outcome

Ops dogfood (2026-08-29): login requires email → Mailpit(8025) retrieval of the magic link → return to 3100; a first-time non-technical user must understand what Mailpit is before logging in. Multi-hop friction is real; the security model (magic link via mail) is not itself the defect. Design space intentionally left open at needs-design.

Requirements

• REQ-001: Hop reduction within the security baseline — reduce the cognitive hops of first-time login (design space: dev/local-mode link surfacing, first-run guidance, or equivalent) without weakening the magic-link mechanism or introducing shared/static credentials.
• REQ-002: Security baseline unchanged — no new credential surface, no bypass of the mail-verification flow; any convenience path is mode-gated and documented as such.

Acceptance criteria

• AC-001: Acceptance anchor — a non-technical user completes login within the documented reduced-hop path (step count defined at design time); magic link remains the authority.
• AC-002: Security fixture — the convenience path introduces no bypass; mode gating asserted.

Non-goals and forbidden shortcuts

• No replacement of the magic-link model; no shared/static credentials; no production-mode convenience that lowers the security bar.

Lifecycle, status, priority, blockers, and open decisions

• status=needs-design; priority P1; technicalOwner unassigned; design space open (mechanism to be proposed).
• Blockers: none.

Evidence plan

• Design-time definition of the hop-count anchor; security fixtures.

Decisions

• DEC-DOC-29-001 (2026-08-29T02:26:00Z): issue created per founder-approved dogfood intake (2026-08-29); design space deliberately open; security baseline frozen as a requirement, not a goal.

Revision history

• R1 (2026-08-29T02:26:00Z): initial record created per founder-approved draft D (dogfood P1 login hop reduction).