From 1ca065e711081e29ee3a76c98a75e82fdfbc6a80 Mon Sep 17 00:00:00 2001 From: Frank Tovar Date: Fri, 6 Feb 2026 19:45:10 +0100 Subject: [PATCH] Updated Agents --- AGENTS.md | 2 +- FAQ-en.md | 206 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ FAQ.md | 55 --------------- 3 files changed, 207 insertions(+), 56 deletions(-) create mode 100644 FAQ-en.md delete mode 100644 FAQ.md diff --git a/AGENTS.md b/AGENTS.md index 5fac1b6..430c1b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Also see the other related files: API.md, IIS.md, SPEC.md ## Rules -- This is a Windows environment, WSL is not installed (i.e. sed is not available). You're running under PowerShell 7.5.4 (e.g. Get-Content with the -First and -Skip options are available). +- This is a Windows environment, WSL is not installed (i.e. sed is not available). You're running under PowerShell 7.5.4. Due to platform restrictions, file deletions are not possible. Replacing the entire file content via a context diff is a viable alternative. - If complex scripts need to be executed, consider using python. It's installed. - web.config in the server is different than locally, it must be exluded from deployment. - After every iteration, evaluate if the test coverage would fall below 100%, and write tests if necessary. diff --git a/FAQ-en.md b/FAQ-en.md new file mode 100644 index 0000000..7338651 --- /dev/null +++ b/FAQ-en.md @@ -0,0 +1,206 @@ +# FAQ & Tips + +Pick'n'play helps groups fairly and transparently choose what game to play next. Players can suggest options, score them independently, and move through structured phases that keep the process organized and anonymous. It solves the classic “what should we play?” chaos by turning group decision-making into a clear, balanced, and drama-free flow. + +## Accounts & Login + +### How do I create an account? + +Register with: +- A **unique username** (max 24 characters) +- A **password** +- A **display name** (max 16 characters) + +Your display name is required --- it appears next to all of your suggestions and scores. + +### Do I need admin privileges? + +If you've been given an **admin key**, enter it during registration. If the key is invalid, the request is rejected. +Admin access cannot be added later. To become an admin, you must re-register with the correct key. + +------------------------------------------------------------------------ + +## Phases at a Glance + +### Personal phases + +Each player progresses independently through the phases: + +**Suggest → Vote → Results** + +Click **"Next"** to move forward. Admins can move themselves backward if needed. + +------------------------------------------------------------------------ + +## Suggesting Games + +### How many games can I suggest? + +Up to **5 suggestions per player**. + +### Required fields and limits + +- **Name** --- required (max 100 characters) +- **Genre** --- optional (max 50 characters) +- **Description** --- optional (max 500 characters) +- **Links** --- optional (URLs up to 2048 characters) + +**Min/Max players:** +- Must be filled together (or both left empty) +- Values must be between **1 and 32** +- Minimum must be ≤ maximum + +### Screenshot rules + +If you include a screenshot URL, it must: + - Use **http or https** + - End with a valid image extension (`png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`) + - Be directly accessible (no redirects) + - Load within \~3 seconds + - Be under **5 MB** + - Not point to local or private hosts + +Screenshots are optional. + +### Other links + +Game links and YouTube links must use **http or https**. Other URL schemes are rejected. + +### Editing a suggestion + +Click the **edit (pencil) icon** on a game card to update any field at any time. + +### Deleting a suggestion + +Click the **delete (cross) icon** on a game card to remove it --- unless you're already in the Vote phase (see below). + +### Why was my suggestion blocked? + +Common reasons: +- Missing display name +- Already reached the 5-suggestion limit +- Name exceeds character limit +- Screenshot URL is invalid, unreachable, or too large +- Min/max players missing or invalid +- Attempting to add a suggestion in the wrong phase + +Check the bottom-right corner of the screen for error messages. + +------------------------------------------------------------------------ + +## Jokers (Late Additions) + +### What is a joker? + +A **joker** is a one-time extra suggestion slot available only during the **Vote phase**. An admin must grant it to you. + +### How it works + +If you receive a joker: + - A button appears in the top bar allowing you to add one more game. + - Once used, the joker is consumed immediately. + - Your ballot becomes unfinalized. + - All players are unfinalized so the new game can be scored. + +Admins may grant additional jokers if necessary. + +------------------------------------------------------------------------ + +## Voting + +### Who can vote? + +Authenticated players during the **Vote phase**. + +### How do I score games? + +Use the slider to assign a whole number from **0 to 10**. + +### Editing during Vote + +- You can still edit most game details. +- The **game name becomes locked** during the Vote phase. +- You can no longer delete your own suggestions. +- Admins may delete suggestions if necessary. + +### Linked duplicates + +If an admin links duplicate games: + - Changing the score for one updates all linked entries. + - Scores are stored per group, not per individual entry. + +### Finalizing your ballot + +Toggling **"Finalize"** locks your scores. Toggle it off to edit again. + +Finalize is only available during the Vote phase and will automatically reset if: + - A joker adds a new game + - An admin links or unlinks games + +### Voting after changes + +If new games are added or links are modified: + - Affected votes are cleared + - You are automatically unfinalized + +Review your list and rescore before finalizing again. + +------------------------------------------------------------------------ + +## Results + +### When are results visible? + +Results are hidden until an admin opens them. When opened, all players are automatically moved to the **Results phase**. +If needed, an admin can close the Results: everyone returns to the Vote phase, and all ballots are unfinalized for adjustments. + +### Can I edit anything in Results? + +No. Suggestions and votes are read-only. Contact an admin for assistance. + +------------------------------------------------------------------------ + +## Admin Tools (For Hosts) + +### What can admin accounts do? + +- Grant jokers during Vote +- Link or unlink duplicate suggestions +- View vote readiness (who has finalized) +- Delete a player (removes their suggestions and votes) +- Reset the database to factory defaults +- Move backward to previous phases + +### What can't admin accounts do? + +- View individual player votes + +Voting remains anonymous and fair. + +------------------------------------------------------------------------ + +## Common Errors & Fixes + +### "Screenshot URL must be http(s) and end with an image file extension." + +Make sure: +- The link is direct (not a page or html content) +- It ends with a valid image extension +- The file is under 5 MB +- There are no redirects + +### "You have reached the 5 suggestion limit." + +Wait for the Vote phase and request a joker if needed. + +### "Invalid admin key." + +Register again using the correct key from the host --- or leave it blank to create a regular account. + +------------------------------------------------------------------------ + +## Data & Privacy + +- Suggestions, votes, and phase states are stored in a shared **SQLite database**. +- Logging out clears your authentication cookie. +- If an admin deletes your player account, your suggestions and votes are removed as well. diff --git a/FAQ.md b/FAQ.md deleted file mode 100644 index 3638c4d..0000000 --- a/FAQ.md +++ /dev/null @@ -1,55 +0,0 @@ -# FAQ & Tips - -Pick'n'Play helps a small group collect game ideas, score them, and reveal a ranked list without endless back-and-forth. Everything below is written in plain language and reflects the exact rules the backend enforces. - -## Accounts & login -- **How do I create an account?** Register with a unique username (max 24 characters), a password, and a display name (max 16 characters). The display name is required because it is shown beside every suggestion and score. -- **Do I need admin powers?** If you were provided with an admin key, enter it during registration. If the key is wrong the request is rejected; there is no way to “upgrade” yourself later without re‑registering with the correct key. -- **Can I change my display name later?** No. Pick it during registration and keep it; there is no UI or API to change it afterward. (Only legacy accounts that somehow lost a name are auto-filled from the username on next login.) - -## Phases at a glance -- **Personal phases.** Each player tracks their own position (Suggest → Vote → Results). Clicking “Next” moves you forward; admins can move themselves backward. Moving forward always clears any “finalized” vote flag. -- **Results gate.** You cannot enter Results until an admin opens them. When Results are opened, everyone is pushed to Results automatically. When Results are closed, everyone returns to Vote and all ballots are unfinalized so people can adjust scores again. - -## Suggesting games -- **How many can I add?** Up to 5 suggestions per player while you are in the Suggest phase. An admin-granted joker lets you add one extra game during Vote (see below). -- **Required fields and limits.** Name is required (max 100 characters). Genre (50), description (500), and links (URLs up to 2048) are optional. Min/max players must both be provided or both left empty; values must be between 1 and 32 with min ≤ max. -- **Image rules.** Screenshot URLs must be http/https, end with an image extension (png, jpg, jpeg, gif, webp, avif), be publicly reachable within ~3 seconds, avoid redirects, and be under 5 MB. Links to local/private hosts are rejected for safety. If you omit a screenshot, that’s fine. -- **Other links.** Game and YouTube links must be http or https; any other scheme is rejected. -- **What can I edit?** In Suggest you may edit any field. In Vote you may edit everything except the name (it stays locked). In Results nothing is editable. Admins can edit any suggestion at any time. -- **Deleting a suggestion.** You can delete your own suggestions while you are still in Suggest. Admins can delete any suggestion at any time. Deleting also removes its votes and breaks any duplicate links so nobody is stuck with orphaned data. -- **Why was my suggestion blocked?** Common reasons: no display name at registration, already at the 5-limit and no joker, name too long/empty, invalid or unreachable screenshot, min/max players missing or out of order, or trying to add while in the wrong phase. - -## Jokers (late additions) -- **What is a joker?** A one-time extra suggestion slot that only works while you are in the Vote phase. An admin must grant it to you. -- **How it works.** When you use the joker to add a game, the joker is consumed immediately, your ballot is unfinalized, and every player is also unfinalized so the new game can be scored. Admins can grant another joker later if needed. - -## Voting -- **Who can vote?** Only authenticated players in the Vote phase. Because display names are fixed at registration, there is no “set name first” step during voting. -- **How to score.** Use the slider to pick a whole number from 0 to 10. Anything outside that range is rejected. -- **Linked duplicates.** If an admin linked duplicate games, changing the score on one updates all linked siblings automatically. Scores are stored per linked group, not per individual card. -- **Finalizing.** Toggling “Finalize” locks your scores so you cannot change them. Toggle it off to edit again. Finalize is only available in Vote; it is cleared automatically if a joker adds a new game, if an admin links/unlinks games, or if results are closed and you are sent back to Vote. -- **Voting after changes.** When new games appear or links change, your previous votes for the affected group are cleared and you are unfinalized. Check your list and rescore everything before finalizing again. - -## Results -- **When do results show?** Only after an admin opens them. Once open, everyone moves to the Results phase automatically. -- **What you see.** A leaderboard with averages, totals, vote counts, your own score, min/max players, and any links or media for each game. Linked games list their siblings so you can see which entries were merged. -- **Can I change anything here?** No. Suggestions and votes are read-only in Results. Admins must close results (which returns everyone to Vote) or use admin tools to make changes. - -## Admin tools (for hosts) -- Open or close results; closing results moves everyone back to Vote and clears finalize flags. -- Grant jokers during Vote; granting one also clears that player’s finalize flag. -- Link or unlink duplicate suggestions during Vote; this clears votes for the affected group and unfinalizes impacted players. -- View vote readiness to see who has finalized. -- Delete a player (also deletes their suggestions and votes, and unlinks anything pointing to them). -- Reset (clears suggestions and votes, keeps players, resets phases to Suggest, closes results). Factory reset wipes everything and reseeds a fresh app state. -- Move yourself backward a phase if you need to adjust your own suggestions. - -## Common errors and how to fix them -- **“This endpoint is available in the X phase.”** You are in the wrong phase. Advance with “Next” or ask an admin to move you back. -- **“Screenshot URL must be http(s) and end with an image file extension.”** Fix the extension and make sure it is a direct link, not a page or redirect, and the file is smaller than 5 MB. -- **“You have reached the 5 suggestion limit.”** Wait for Vote and request a joker if you need to add more. -- **Admin key errors.** If you see “Invalid admin key,” register again with the correct key provided by the host, or leave it empty to create a non-admin account. - -## Data and privacy -- Suggestions, votes, and phases live in a shared SQLite database. Logging out clears your auth cookie; deleting your player (admin action) also removes your suggestions and votes.