# Sample Code/DX Audit

## Scope

- Target: public developer tool
- Goal: onboarding, DX, and safety review
- Depth: express audit

## Executive Summary

The product value is clear, but first-run confidence depends on tighter setup docs, a visible smoke test, and safer secret-handling language. Fastest useful fix: add one copy-paste quickstart path with expected output and a redacted `.env.example`.

## Findings

### F-001: Quickstart lacks expected output

- Severity: Medium
- Evidence: Setup commands are shown without success criteria.
- Impact: Buyer cannot tell whether install worked or failed silently.
- Fix: Add expected terminal output and one health-check command.
- Verification: Run fresh install and compare output against docs.

### F-002: Secret guidance needs stronger wording

- Severity: Medium
- Evidence: Docs mention API keys but do not say where not to paste them.
- Impact: Users may leak keys in issues, prompts, screenshots, or logs.
- Fix: Add "never paste secrets into chat/issues/logs" warning and `.env.example`.
- Verification: Search docs for secret-handling warning and redacted examples.

### F-003: No minimal troubleshooting table

- Severity: Low
- Evidence: Common setup failures are not mapped to fixes.
- Impact: Support load rises for predictable failures.
- Fix: Add table for missing env, wrong port, auth failure, and stale dependency lockfile.
- Verification: Confirm every known first-run error has one owner action.

## Handoff

1. Add smoke test.
2. Add expected output.
3. Add redacted config example.
4. Add troubleshooting table.