# ACCEPTANCE_TESTS.md

Codex should use this file as a checklist. Implement automated tests for as many as practical and document any manual checks.

## Smoke tests

- `docker compose up --build` starts backend and frontend.
- Backend health endpoint returns OK.
- Frontend loads without console-breaking errors.
- Seed data can be created with a documented command.

## Accountless join

Automated/backend:

- Creating invite stores only token hash.
- Valid invite preview returns group preview.
- Claiming invite creates/updates member, member device, and session.
- Expired/revoked invite cannot be claimed.
- Limited-use invite increments use count and blocks after max uses.

Manual/frontend:

- Opening invite link shows a polished mobile join screen.
- User can join without email/password.
- User can RSVP immediately after join.

## Structured group behavior

Automated/backend:

- Admin can create announcement.
- Member cannot create official announcement unless permitted.
- Admin can create event.
- Member can RSVP to event.
- Missing RSVP generates action item.
- Task assigned to member generates action item.
- Poll without member vote generates action item.

Manual/frontend:

- Group page defaults to dashboard, not raw chat.
- Announcements/events/files/tasks/polls appear as cards.
- Chat/discussions are available but secondary.

## Home dashboard

Automated/backend:

- `/api/home` returns sections for needs_me, today, changed, official_updates, catch_up.
- Action ordering prioritizes urgent/due items.
- Local and remote objects can be represented consistently.

Manual/frontend:

- Home answers “What needs me?”
- Seed demo shows at least three actionable items across groups.
- Remote items show source server/group badge.

## Multi-device

Automated/backend:

- Device link start creates pending pairing code.
- Existing session can approve pending device.
- New device completes pairing and receives session.
- Device list includes both devices.
- Revoked device cannot use session.

Manual/frontend:

- User can start “Link another device.”
- Code/QR screen is understandable.
- Existing device approval UI is clear.
- Device management page shows current and linked devices.

## Recovery

Automated/backend:

- Recovery request creates hashed recovery token/code.
- Recovery consume creates session or attaches to home profile.
- Expired/revoked recovery token fails.

Manual/frontend:

- Dev-mode recovery shows/logs a usable link or code.
- UI says “Save access”/“Recover access,” not mandatory account creation.

## Migration kit

Automated/backend:

- Admin can fetch migration dashboard.
- Migration status reflects member invite/open/join/verified fields.
- Reminder copy endpoint returns useful text with link and transition date.
- WhatsApp export import accepts a `.txt` file and stores read-only archive messages if implemented.

Manual/frontend:

- Admin migration dashboard is clear.
- Reminder copy is one-click copyable.
- UI explains legacy channel concept.

## Files

Automated/backend:

- Upload enforces auth and file size.
- Download enforces permission.
- Filename is sanitized.

Manual/frontend:

- Files page shows global and by-group files.
- File source group/server is visible.

## Remote/self-hosted aggregation

Automated/backend:

- `/.well-known/group-platform.json` returns manifest.
- `/api/sync` requires valid scoped token.
- Connection token has scopes and expiry.
- Home server can connect to remote server with URL + token.
- Sync stores/caches remote structured objects.
- `/api/home` includes remote action items after sync.

Manual/frontend:

- Connected servers page lists remote server.
- Sync status/errors are visible.
- Remote actions appear on Home.
- No UI claims full federation.

## Responsive UI

Manual:

- 375px-wide mobile viewport is usable.
- Bottom nav appears on mobile.
- Desktop layout uses more horizontal space without becoming sparse.
- Forms are readable and touch targets are adequate.
- Empty/loading/error states are implemented.

## Security checklist

Automated or code review:

- Invite/recovery tokens hashed.
- Sessions use HttpOnly cookies.
- Long-lived tokens not stored in localStorage.
- Role checks on admin endpoints.
- Remote tokens stored server-side.
- Upload validation implemented.
- `.env.example` exists and no secrets are committed.

## README checklist

Root README must include:

- product concept;
- architecture diagram/text;
- setup commands;
- seed demo instructions;
- invite flow instructions;
- device-linking instructions;
- remote aggregation demo instructions;
- known limitations;
- security notes;
- next-step roadmap.