forgejo-lila/lila
1
0
Fork 0
Code Issues 50 Pull requests Projects 1 Releases Packages Wiki Activity Actions

updating docs

Browse source
This commit is contained in:
lila 2026-05-30 03:47:52 +02:00
parent caa2f7d395
commit 37f6a55798
2 changed files with 93 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

24
documentation/ai-context/99-current-task.md → documentation/ai-context/99-current-task-blueprint.md
View file

@ -34,6 +34,7 @@ Example: "Implement guest play flow so users can try a 3-round quiz without crea
[List files you've identified. The LLM may ask for additional ones.] [List files you've identified. The LLM may ask for additional ones.]
Example: Example:
- `apps/api/src/controllers/gameController.ts` — needs guest variant - `apps/api/src/controllers/gameController.ts` — needs guest variant
- `apps/api/src/middleware/authMiddleware.ts` — needs optional auth path - `apps/api/src/middleware/authMiddleware.ts` — needs optional auth path
- `packages/shared/src/schemas/game.ts` — needs GuestGameRequestSchema - `packages/shared/src/schemas/game.ts` — needs GuestGameRequestSchema
@ -43,20 +44,24 @@ Example:
## Constraints & Requirements ## Constraints & Requirements
**Must have:** **Must have:**
- [ ] - [ ]
- [ ] - [ ]
**Nice to have:** **Nice to have:**
- [ ] - [ ]
- [ ] - [ ]
**Must NOT break:** **Must NOT break:**
- [ ] Existing auth flow (logged-in users still work normally) - [ ] Existing auth flow (logged-in users still work normally)
- [ ] WebSocket protocol (if applicable) - [ ] WebSocket protocol (if applicable)
- [ ] Database schema (additive changes only unless migration planned) - [ ] Database schema (additive changes only unless migration planned)
- [ ] Zod schemas in `packages/shared` (no silent drift) - [ ] Zod schemas in `packages/shared` (no silent drift)
**Known blockers or open questions:** **Known blockers or open questions:**
- [ ] - [ ]
--- ---
@ -80,17 +85,18 @@ After the task is complete, ask the LLM:
The LLM should check: The LLM should check:
| File | Check if... | | File | Check if... |
|------|-------------| | ---------------------------------- | ----------------------------------------------------------------------- |
| `documentation/STATUS.md` | Task changes what's working or what's blocked | | `documentation/STATUS.md` | Task changes what's working or what's blocked |
| `documentation/BACKLOG.md` | Task completes a backlog item or creates a new one | | `documentation/BACKLOG.md` | Task completes a backlog item or creates a new one |
| `documentation/DECISIONS.md` | Task involved choosing between alternatives with long-term consequences | | `documentation/DECISIONS.md` | Task involved choosing between alternatives with long-term consequences |
| `documentation/ARCHITECTURE.md` | Task changes monorepo structure, data flow, or layer boundaries | | `documentation/ARCHITECTURE.md` | Task changes monorepo structure, data flow, or layer boundaries |
| `documentation/ai-context/*.md` | Task changes schemas, endpoints, protocol, or pipeline stages | | `documentation/ai-context/*.md` | Task changes schemas, endpoints, protocol, or pipeline stages |
| `packages/shared/src/schemas/*.ts` | Task changes request/response shapes or WS message types | | `packages/shared/src/schemas/*.ts` | Task changes request/response shapes or WS message types |
| `README.md` | Task changes quickstart steps, stack, or current status | | `README.md` | Task changes quickstart steps, stack, or current status |
**Expected output format:** **Expected output format:**
``` ```
- FILE: [filename] — REASON: [what changed and why the doc needs updating] - FILE: [filename] — REASON: [what changed and why the doc needs updating]
``` ```

78
documentation/ai-context/99-current-task.md Normal file
View file

@ -0,0 +1,78 @@
# 99 — Current Task
## Task Description
Implement guest play flow so users can try a 3-round singleplayer quiz without creating an account. After completing the quiz, optionally prompt them to sign up to save progress.
## Context
**Which parts of the codebase does this touch?**
- [x] Frontend (`apps/web/`)
- [x] Backend API (`apps/api/`)
- [ ] Database schema (`packages/db/`) — no schema changes needed
- [x] Shared schemas (`packages/shared/`) — may need GuestGameRequestSchema
- [ ] WebSocket protocol (`apps/api/src/ws/`) — not touched (guest play is singleplayer only)
- [ ] Data pipeline (`data-pipeline/`)
- [ ] Infrastructure / deployment (`docker-compose.yml`, Caddyfile, etc.)
- [x] Documentation
**Relevant files I already know about:**
- `apps/api/src/middleware/authMiddleware.ts` — needs optional auth path
- `apps/api/src/controllers/gameController.ts` — needs guest variant of start/answer
- `apps/api/src/services/gameService.ts` — may need guest session logic
- `apps/api/src/routes/gameRouter.ts` — route definitions
- `apps/web/src/routes/play.tsx` — singleplayer route
- `apps/web/src/components/game/GameSetup.tsx` — start quiz UI
- `packages/shared/src/schemas/game.ts` — request/response schemas
- `apps/web/src/components/auth/AuthModal.tsx` — post-game auth prompt
## Constraints & Requirements
**Must have:**
- [ ] Guest users can start and complete a singleplayer quiz (3 or 10 rounds)
- [ ] No login required to reach `/play` or call `POST /api/v1/game/start`
- [ ] Server-side answer evaluation still works (correct answer never sent to frontend)
- [ ] Guest sessions are ephemeral (no database storage of guest progress)
- [ ] After quiz completion, show a friendly "Save your progress?" prompt with auth options
**Nice to have:**
- [ ] Guest sessions stored in-memory with a TTL (e.g., 24h) so refreshing the page doesn't lose the current quiz
- [ ] Post-game prompt includes a "Continue as guest" option to play again without signing up
**Must NOT break:**
- [x] Existing auth flow (logged-in users still work normally)
- [x] WebSocket protocol (if applicable)
- [x] Database schema (additive changes only unless migration planned)
- [x] Zod schemas in `packages/shared` (no silent drift)
**Known blockers or open questions:**
- [ ] Should guest sessions use the same `GameSessionStore` interface with a guest flag, or a separate store?
- [ ] Should the post-game auth prompt be a modal or a redirect to a dedicated page?
## Definition of Done
- [ ] Code implemented and tested
- [ ] No TypeScript errors (`pnpm typecheck` passes)
- [ ] Tests pass (`pnpm test`)
- [ ] Manual verification in dev environment (both logged-in and guest flows)
- [ ] Commit message follows convention
- [ ] Feature branch merged to main
## Post-Work Checklist
After the task is complete, ask the LLM:
> "Review the post-work checklist in prompts/meta.md. Which documentation files need updates based on what we just changed?"
Expected doc updates:
- `documentation/STATUS.md` — Guest play is now live
- `documentation/ai-context/03-api-contract.md` — New guest endpoint or schema changes
- `packages/shared/src/schemas/game.ts` — If GuestGameRequestSchema added
- `README.md` — Quickstart may mention guest play