feat: enhance project guidelines and architectural patterns documentation (#157)

Author: ZerGo0

AGENTS.md

@@ -38,11 +38,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ### Ftv Extension (root)
 - Language: TypeScript
 - Framework/Runtime: WXT + Svelte 5 (runes), Vite
-- Package Manager: pnpm
+- Package Manager: pnpm (Note: `pnpm` is the primary package manager; `npm` can be used as fallback)
 - Important Packages: `wxt`, `@wxt-dev/module-svelte`, `svelte`, `vite`, `tailwindcss`, `bits-ui`, `lucide-svelte`, `zod`, `clsx`, `tailwind-merge`, `cmdk-sv`, `embla-carousel-svelte`, `svelte-sonner`.
 - Checks:
-  - Syntax Check: `pnpm check`
-  - Lint: `pnpm lint`
+  - Syntax Check: `pnpm check` (or `npm run check`)
+  - Lint: `pnpm lint` (or `npm run lint`) - uses Prettier with Svelte and Tailwind plugins
   - **ALWAYS** run these after you are done making changes
 - Rules / Conventions:
   - **ALWAYS** use Svelte 5 runes (`$state`) for reactive state files under `src/lib/**.svelte.ts`.
@@ -55,6 +55,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   - **ALWAYS** add `dark` to shadow UI containers for consistent Tailwind theming (`ui.uiContainer.classList.add('dark')`).
   - **NEVER** assume page reloads; rely on `MutationObserver` + path whitelists.
   - **NEVER** scatter API URLs; use the API modules in `src/lib/api/`.
+  - **ALWAYS** follow Prettier configuration (2 spaces, single quotes, no trailing commas, 100 char width).
 - Useful files:
   - `wxt.config.ts` — WXT configuration, MV3/MV2 host permissions.
   - `src/entrypoints/chat.content.ts` — Chat page bootstrapping and feature orchestration.
@@ -65,142 +66,66 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   - `src/lib/api/*` — Fansly and ZerGo0 API wrappers.
   - `src/lib/utils/*` — Request de‑duplication and Promise caches.
   - `src/assets/fanslyStyleFixes.css` — Injected CSS adjustments.
+  - `.prettierrc` — Formatting configuration with Svelte and Tailwind plugins.
 
 ## Key Architectural Patterns
 - MutationObserver + URL whitelist for single‑page routing, with idempotent attachment via classes.
 - Provider pattern for emote sources; one interface, multiple platform implementations.
 - Svelte 5 runes for state; stores as lightweight classes with `$state` fields.
 - WXT UI mounting into shadow roots; CSS injected via dedicated helper and `cssInjectionMode: 'ui'`.
 - Request de‑duplication and Promise‑based caching to minimize redundant network calls.
+- Class-based data models (e.g., `Emote`, `ChatPronoun`) with constructor-based initialization.
+- Content script orchestration through entrypoint modules that handle feature-specific logic.
+- Extension supports both Manifest V3 (Chromium) and Manifest V2 (Firefox) with different permission models.
 
 <answer-structure>
-## Presenting your work and final message
+## MANDATORY Answer Format
 
-**IMPORTANT:** You always need to follow the final answer formatting guidelines when you are presenting your work and final message!
+**CRITICAL:** You MUST follow these exact formatting rules for ALL responses. No exceptions.
 
-Your final message should read naturally, like an update from a concise teammate. For casual conversation, brainstorming tasks, or quick questions from the user, respond in a friendly, conversational tone. You should ask questions, suggest ideas, and adapt to the user’s style. If you've finished a large amount of work, when describing what you've done to the user, you should follow the final answer formatting guidelines to communicate substantive changes. You don't need to add structured formatting for one-word answers, greetings, or purely conversational exchanges.
-
-You can skip heavy formatting for single, simple actions or confirmations. In these cases, respond in plain sentences with any relevant next step or quick option. Reserve multi-section structured responses for results that need grouping or explanation.
-
-The user is working on the same computer as you, and has access to your work. As such there's no need to show the full contents of large files you have already written unless the user explicitly asks for them. Similarly, if you've created or modified files using `apply_patch`, there's no need to tell users to "save the file" or "copy the code into a file"—just reference the file path.
-
-ALWAYS end your response with a task-related follow-up question or suggestion. Focus on logical next steps for the feature or problem domain—such as extending functionality, handling edge cases, reviewing related code, or exploring alternative approaches. **NEVER** suggest procedural actions like running tests, committing changes, or building the project. Frame it as a thoughtful continuation of the work rather than leaving the conversation hanging.
-
-Brevity is very important as a default. You should be very concise (i.e. no more than 10 lines), but can relax this requirement for tasks where additional detail and comprehensiveness is important for the user's understanding.
-
-### Final answer structure and style guidelines
-
-You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
-
-**Section Headers**
-
-- Use only when they improve clarity — they are not mandatory for every answer.
-- Choose descriptive names that fit the content
-- Keep headers short (1–3 words) and in `**Title Case**`. Always start headers with `**` and end with `**`
-- Leave no blank line before the first bullet under a header.
-- Section headers should only be used where they genuinely improve scanability; avoid fragmenting the answer.
-
-**Bullets**
-
-- Use `-` followed by a space for every bullet.
-- Merge related points when possible; avoid a bullet for every trivial detail.
-- Keep bullets to one line unless breaking for clarity is unavoidable.
-- Group into short lists (4–6 bullets) ordered by importance.
-- Use consistent keyword phrasing and formatting across sections.
-
-**Monospace**
-
-- Wrap all commands, file paths, env vars, and code identifiers in backticks (`` `...` ``).
-- Apply to inline examples and to bullet keywords if the keyword itself is a literal file/command.
-- Never mix monospace and bold markers; choose one based on whether it’s a keyword (`**`) or inline code/path (`` ` ``).
-
-**File References**
-When referencing files in your response, make sure to include the relevant start line and always follow the below rules:
-
-- Use inline code to make file paths clickable.
-- Each reference should have a stand alone path. Even if it's the same file.
-- Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
-- Line/column (1‑based, optional): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
-- Do not use URIs like file://, vscode://, or https://.
-- Do not provide range of lines
-- Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5
-
-**Structure**
-
-- Place related bullets together; don’t mix unrelated concepts in the same section.
-- Order sections from general → specific → supporting info.
-- For subsections (e.g., “Binaries” under “Rust Workspace”), introduce with a bolded keyword bullet, then list items under it.
-- Match structure to complexity:
-  - Multi-part or detailed results → use clear headers and grouped bullets.
-  - Simple results → minimal headers, possibly just a short list or paragraph.
-
-**Tone**
-
-- Keep the voice collaborative and natural, like a coding partner handing off work.
-- Be concise and factual — no filler or conversational commentary and avoid unnecessary repetition
-- Use present tense and active voice (e.g., “Runs tests” not “This will run tests”).
-- Keep descriptions self-contained; don’t refer to “above” or “below”.
-- Use parallel structure in lists for consistency.
-
-**Don’t**
-
-- Don’t use literal words “bold” or “monospace” in the content.
-- Don’t nest bullets or create deep hierarchies.
-- Don’t output ANSI escape codes directly — the CLI renderer applies them.
-- Don’t cram unrelated keywords into a single bullet; split for clarity.
-- Don’t let keyword lists run long — wrap or reformat for scanability.
-
-Generally, ensure your final answers adapt their shape and depth to the request. For example, answers to code explanations should have a precise, structured explanation with code references that answer the question directly. For tasks with a simple implementation, lead with the outcome and supplement only with what's needed for clarity. Larger changes can be presented as a logical walkthrough of your approach, grouping related steps, explaining rationale where it adds value, and highlighting next actions to accelerate the user. Your answers should provide the right level of detail while being easily scannable.
-
-For casual greetings, acknowledgements, or other one-off conversational messages that are not delivering substantive information or structured results, respond naturally without section headers or bullet formatting.
-
-### Example Final Answer
-
-Here's an example of a well-structured final answer for a complex, multi-step task:
+**ABSOLUTE Requirements:**
+- ALWAYS use the exact structure below
+- NEVER deviate from the specified format
+- ALWAYS end with a task-related follow-up question
+- ALWAYS keep responses concise (≤10 lines unless technical details require more)
 
+**EXACT Structure Template:**
 ```
-Completed the {task_description} the way you asked.
+Completed {task}.
 
 **What I Changed**
-- {high_level_summary_of_changes}
-- Approach:
-  - {action_1}
-  - {action_2}
-  - {maintained_behavior_or_compatibility}
+- {high_level_summary}
+- {key_approach_points}
 
 **Key Files**
-- Updated: `{file_path}` ({brief_change_description})
-- Updated: `{file_path}` ({brief_change_description})
+- Updated: `{file_path}` ({brief_change})
 - Added: `{file_path}` ({purpose})
-- Added: {category_of_files}:
-  - `{file_1}`, `{file_2}`, `{file_3}`
-- Removed: {description_of_removed_items}
 
 **Implementation Details**
-- {key_technical_approach_or_pattern_used}
-- Each {component} is {how_it_works}, e.g.:
-  - `{code_example}`
-- {additional_technical_detail}
-- {compatibility_or_integration_note}
+- {technical_approach}
+- {key_code_example}
 
 **Validation**
-- Build: `{build_command}` passes
 - Types: `{typecheck_command}` passes
 - Lint: `{lint_command}` passes
 - {additional_validation_step}
 
-Should I implement error handling for this next? {task_related_follow_up_question_about_extending_or_exploring_the_feature}
+{task_related_follow_up_question}
 ```
 
-This example demonstrates:
-
-- Opening with the outcome and what was accomplished
-- **What I Changed**: High-level summary and approach details
-- **Key Files**: Organized list of file changes with brief descriptions
-- **Implementation Details**: Technical approach and patterns (when relevant)
-- **Validation**: Proof that checks pass
-- Closing with a task-related follow-up question (**NEVER** about tests/commits/builds)
-
-Adapt sections based on task complexity. Simple tasks need fewer sections; complex refactors benefit from all sections. ALWAYS include a follow-up question at the end that explores the feature domain, edge cases, or logical extensions—never procedural steps.
-
+**NON-NEGOTIABLE Formatting Rules:**
+- Headers: EXACTLY `**Title Case**` (1-3 words only)
+- Bullets: ALWAYS start with `- ` (dash, space)
+- Monospace: ALWAYS use backticks for commands, paths, code
+- File references: ALWAYS use `path:line` format
+- NEVER use conversational tone outside the follow-up question
+- NEVER mention saving files or copying code
+- NEVER suggest procedural actions (tests, commits, builds)
+
+**MANDATORY Follow-up Questions:**
+- MUST relate to extending functionality
+- MUST explore edge cases or alternatives
+- MUST be task-related (never procedural)
+
+**NO EXCEPTIONS** to these rules regardless of request type, complexity, or perceived user intent.
 </answer-structure>