# agents.md This file is the single source of truth for codebase obstacles, oddities, and their resolutions. Do not scatter this knowledge in comments, commit messages, or memory. --- ## Rules for agents 1. **Before solving a problem**, check this file. If the problem is documented, use the recorded solution or workaround. Do not re-derive it. 2. **After solving a new problem**, document it here before moving on. Keep entries concise. 3. **Do not deviate** from a recorded solution without first confirming with the user. Once confirmed, update this file with the new approach and reason before proceeding. --- ## Entry format ```text ### [Short problem title] **Area:** [file, module, or system this affects] **Obstacle:** What the problem is and where it appears. **Solution/Workaround:** What was done to fix or work around it. **Preference:** If multiple approaches exist, which was chosen and why. ``` --- ## Documented obstacles ### TypeScript composite builds fail with no output **Area:** packages/cli/tsconfig.json, tsconfig.base.json **Obstacle:** When `composite: true` is set in tsconfig, TypeScript requires proper project references to build. The CLI package was building but producing no output files, causing "cannot find module" errors. **Solution:** Remove `composite: true` from packages/cli/tsconfig.json. Also removed `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` from tsconfig.base.json as they caused strict type issues with dynamic config objects. **Preference:** Use simple tsconfig without composite mode for CLI package. ### verify.ts overly complex abstraction **Area:** packages/cli/src/commands/verify.ts **Obstacle:** Code had too many layers: collectResults → addResult (inner function) → displayDiagnosticResults/verifyResults. Made it hard to trace and debug. **Solution:** Rewrote to be flatter: verifyCommand → runDiagnosticMode/runVerifyMode. Used simple inline logic instead of adding functions for everything. **Preference:** KISS - keep functions small but avoid over-abstraction. ### Error messages in forgejo-checks too generic **Area:** packages/cli/src/utils/forgejo-checks.ts **Obstacle:** Network errors showed "fetch failed" with no context. HTTP errors showed just status codes. Not actionable for users. **Solution:** Added getErrorMessage() helper to detect: timeouts, connection refused, host not found. Improved HTTP error messages to include status text. Added context prefixes like "cannot reach server", "cannot connect to API". **Preference:** Actionable messages that tell users what to fix. ### ENV_MAPPING duplicated inline in verify.ts **Area:** packages/cli/src/commands/verify.ts **Obstacle:** Had duplicate object with same keys as ENV_MAPPING from config.ts. Two sources of truth. **Solution:** Import ENV_MAPPING and use it. Change display to show env var names (SNAKE_CASE) instead of internal keys. **Preference:** Single source of truth in config.ts. ### Display verbiage redundancy **Area:** packages/cli/src/commands/verify.ts **Obstacle:** Displayed "MYST_PUBLIC_URL set" - "set" is redundant, icon already shows status. **Solution:** Just show env var name, remove "set". Shows "MYST_PUBLIC_URL configured" or "MYST_PUBLIC_URL missing". **Preference:** Cleaner, let icon indicate status. ### loadConfig returning wrong type for error case **Area:** packages/cli/src/commands/verify.ts **Obstacle:** loadConfig() threw error when .env not found, but caught and re-threw in verifyCommand. This caused process to exit with stack trace instead of clean message. **Solution:** Return null on ENOENT, handle null in verifyCommand. Return type: `Record | null`. **Preference:** Explicit null handling over exceptions for user-facing errors. ### process.exit(0) prevents finally blocks **Area:** CLI commands using process.exit() **Obstacle:** process.exit(0) stops execution immediately, never runs cleanup code. **Solution:** Use process.exitCode = 1 and return instead of process.exit(). **Preference:** Set exitCode and return to allow cleanup. ### Logout cookie not reaching browser **Area:** web/app/routers/auth.py, web/app/auth/session.py **Obstacle:** `revoke_session` set cookies on the injected `Response` parameter, but the logout handler returned a new `RedirectResponse` — so `Set-Cookie` was discarded. **Solution:** Create `RedirectResponse` first, then pass it into `revoke_session`. Same pattern used in `callback_forgejo` for `create_session`. **Preference:** Pass the actual response object that will be returned. ### Dashboard leaking ORM session object **Area:** web/app/main.py **Obstacle:** `/dashboard` returned the full ORM `Session` object (`sess`), leaking `token_hash`, `revoked_at`, etc. to the client. **Solution:** Return a plain dict with only safe fields: `user_id`, `display_name`, `email`, `session_id`, `created_at`. **Preference:** Never return ORM objects directly in API responses. ### crypto.py decrypt functions kept proactively **Area:** web/app/auth/crypto.py **Obstacle:** CodeRabbit flagged missing decryption functions and key validation. Added `decrypt_token`/`decrypt_optional` + key format validation in `fernet_from_encryption_key`. **Solution:** Added the functions even though no consumer exists yet. They will be used for PAT decryption in share link flow. **Preference:** Keep dead code if it's small, symmetric (`encrypt`/`decrypt`), and has an obvious future consumer. ### User model Session import direct instead of TYPE_CHECKING **Area:** web/app/models/user.py **Obstacle:** `Session` was imported directly (`from .session import Session`) while `Grant` used `TYPE_CHECKING`. Inconsistent and risked circular imports. **Solution:** Moved `Session` import under `TYPE_CHECKING`, changed relationship to string ref `"Session"`. **Preference:** Always use `TYPE_CHECKING` for model references within models to avoid circular imports. ### Boilerplate UI must follow attached light vault system **Area:** web/app/static/css/input.css, web/app/templates/*.html **Obstacle:** Existing boilerplate used dark-mode pink tokens that conflicted with the attached "Mystique Minimalist Security" design system. **Solution/Workaround:** Use light Geist/JetBrains Mono typography, glacier-blue primary actions, white/off-white tonal surfaces, hairline slate borders, compact labels, mono technical strings, and pill status badges. **Preference:** Keep visual changes in Tailwind tokens and boilerplate templates; avoid backend route changes for design-only updates. ### Tailwind design tokens should use paired semantic roles **Area:** web/app/static/css/input.css, web/app/templates/*.html **Obstacle:** Early UI templates mixed old role names (`background-*`, `text-*`, `stroke`) and hardcoded `white` values inside component classes, which made dark mode and future theming brittle. **Solution/Workaround:** Use Tailwind v4 `@theme` tokens with semantic pairs such as `background/foreground`, `card/card-foreground`, `primary/primary-foreground`, `secondary/secondary-foreground`, `border`, `input`, and `ring`. Keep shared component structure in base classes like `.btn`, with variant classes only setting semantic colors. **Preference:** Prefer semantic token names over appearance-based names; add dark mode by overriding CSS variables under `.dark`. ### Dark-only Tailwind tokens live at root **Area:** web/app/static/css/input.css, web/app/templates/*.html **Obstacle:** The Firebreak UI is currently dark-only, but stale light theme tokens and scattered literal palette values made the active design system harder to change safely. **Solution/Workaround:** Define Firebreak brand primitives and dark semantic roles in the root Tailwind v4 `@theme`; templates and component classes use token-backed utilities/classes instead of raw theme colors. **Preference:** Keep palette values centralized in `@theme`; avoid arbitrary color utilities in templates. Reintroduce light mode only after defining a full paired token set. ### Button hover states belong to variants **Area:** web/app/static/css/input.css, web/app/templates/*.html **Obstacle:** Buttons mixed shared variants with page-specific hover utilities and ID selectors, causing inconsistent hover colors across pages. **Solution/Workaround:** Add explicit variants such as `btn-danger` and `btn-link`; templates should choose the correct variant instead of stacking custom hover color utilities. **Preference:** Keep hover behavior in component variants. Use `btn-link` for low-emphasis navigation actions such as returning home from an error page. ### Vercel web guideline fixes should stay template-scoped **Area:** web/app/templates/*.html, web/app/static/css/input.css **Obstacle:** Vercel Web Interface Guidelines flagged accessibility/theming issues such as missing skip links, missing dark `color-scheme`, non-locale date formatting, form inputs without autocomplete metadata, and motion without reduced-motion handling. **Solution/Workaround:** Add global `color-scheme: dark`, keep form metadata in templates, format visible dates with `Intl.DateTimeFormat`, confirm destructive forms client-side, and provide `prefers-reduced-motion` CSS fallbacks. **Preference:** Prefer lightweight template/CSS fixes for UI guideline compliance; avoid backend route changes unless the issue requires server state. ### Header brand SVG inherits unwanted icon styling **Area:** web/app/templates/base.html, web/app/templates/index.html, web/app/static/css/input.css **Obstacle:** The inline Firebreak header wordmark uses hardcoded SVG fills, and page-level header rules can accidentally apply icon `stroke` styles to the brand SVG. On forced-dark landing headers, the `#17191C` wordmark fill disappears against the obsidian nav. **Solution/Workaround:** Give the header brand link a stable `brand-link` class, prevent inherited SVG strokes on `.brand-link svg`, and override only the hardcoded wordmark fill in dark contexts or forced-dark page headers. **Preference:** Scope icon stroke rules to nav icons; do not apply broad `header svg` stroke styles. ### Landing video poster caused logo flash **Area:** web/app/templates/index.html, web/app/static/img/ **Obstacle:** Using a logo SVG as the `