forgetrail 0.3.0

package/docs/BUSINESS_PLAN.md

@@ -0,0 +1,256 @@
+# [App Name]: Business Plan
+
+_Market analysis, pricing, monetization strategy, customer acquisition, virality playbook, and payment implementation._
+
+_For brand positioning, see [BRAND_AND_PRODUCT.md](BRAND_AND_PRODUCT.md). For technical reference, see [TECHNICAL_REFERENCE.md](TECHNICAL_REFERENCE.md). For deployment, see [DEPLOYMENT.md](DEPLOYMENT.md)._
+
+_Instructions: Write this document when you're thinking about other people using your app (Phase 7: Hardening, or earlier if you need to validate business viability). This is where you prove the business works on paper before building payment flows. Every section should be grounded in numbers, not hopes._
+
+---
+
+## Market Sizing
+
+### Total Addressable Market (TAM)
+
+[How many people have the problem you solve? Cite sources.]
+
+### Serviceable Addressable Market (SAM)
+
+[How many of those people would realistically use a SaaS tool for this? Filter by: tech literacy, willingness to pay, accessibility, geography.]
+
+### Initial Target Segment
+
+[Who are your first 100 users? Be specific. Where do they hang out? What do they already use?]
+
+> 💡 **Lesson learned:** Don't just cite total market numbers. Apply realistic filters. 13-14M total job seekers → only 500K-1M realistically reach a paid SaaS tool for this.
+
+## Unit Economics
+
+### Cost Per Action
+
+[What does it cost you to serve one user action? For AI-powered apps, this is your API cost per call.]
+
+| Action   | Model/Service | Input Cost | Output Cost | Total Per Action |
+| -------- | ------------- | ---------- | ----------- | ---------------- |
+| [action] | [model]       | [$X]       | [$X]        | [$X]             |
+
+### Typical User Cost Profile
+
+[How much does a typical active user cost you per month?]
+
+| Metric                               | Value    |
+| ------------------------------------ | -------- |
+| [Actions] per active user/month      | [N]      |
+| Average cost per [action]            | [$X]     |
+| Total API cost per active user/month | [$X]     |
+| Infrastructure cost per user/month   | [$X]     |
+| **Total cost per active user/month** | **[$X]** |
+
+### Margin Analysis
+
+[At your planned price point, what's the margin?]
+
+> 💡 **Lesson learned:** API costs were $0.03/tailoring run, ~$2.50/active user/month. At $119/month pricing, that's 95% margin. Unit economics were bulletproof. Validate this early; if margins are thin, your pricing model needs rethinking before you build payment flows.
+
+## Pricing Model
+
+### Pricing Philosophy
+
+[Why this pricing structure? What behavior does it incentivize? What does it discourage?]
+
+> 💡 **Lesson learned:** Monthly-only pricing matched the natural use cycle (6-9 month executive-level job searches). Annual plans would create churn friction.
+>
+> 💡 **Also:** Pure job-count limits feel arbitrary. Hybrid models (credits + job count) let power users self-select into higher tiers without feeling punished.
+>
+> 💡 **Also:** Consider eliminating the free tier entirely. After a time-limited trial (e.g., 7 days of full access), accounts expire to an "expired" state with ALL limits at zero. This forces a clear decision: subscribe, downgrade to Hold, or lose access. A persistent free tier creates a leaky bucket where users never convert. A 30-day data retention window after expiration creates urgency without being punitive. The Hold tier ($10/mo) becomes the only way to preserve data indefinitely without an active subscription.
+>
+> 💡 **Also:** Bridge tiers fill pricing cliffs. If your pricing jumps from a low-cost pause tier ($10/mo) to a full-featured tier ($120/mo), users who've finished their trial but aren't ready for full commitment will churn. A mid-price "bridge" tier ($40/mo) that gives meaningful ongoing value (e.g., profile editing, research, content creation) without the full pipeline (e.g., no per-item AI operations, no export) catches post-trial users and keeps them invested. When they're ready, they upgrade having already built their foundation. Model the bridge tier as: full access to X (the durable value), restricted from Y (the per-action AI cost center).
+>
+> 💡 **Also:** Trial design — usage caps create natural conversion moments. Instead of just a time limit (N days of full access), add a usage cap on the most valuable action (e.g., "download tailored documents for up to 5 items during trial"). Users get enough value to see the product's worth, then hit a clear conversion moment. Track usage with a JSON array field on the user record. Combined with a longer trial (10 days instead of 7), this gives users more time to explore while still creating purchase urgency at the moment they need the product most.
+
+### Tiers
+
+| Tier     | Price   | Includes                         | Target User                    |
+| -------- | ------- | -------------------------------- | ------------------------------ |
+| Expired  | $0      | All blocked                      | Post-trial default             |
+| Hold     | $[X]/mo | Data preserved, features blocked | Users who completed their goal |
+| [Tier 2] | $[X]/mo | [includes]                       | [who this serves]              |
+| [Tier 3] | $[X]/mo | [includes]                       | [who this serves]              |
+
+### Entitlement Enforcement
+
+[Which API routes need to check entitlements? How does enforcement work technically?]
+
+> 💡 **Lesson learned:** Entitlements must be enforced on every LLM-consuming API route (12+ routes). A shared middleware or utility function prevents inconsistency. Client-side limits are for UX; server-side limits are for revenue protection.
+
+## Customer Acquisition
+
+### Channels (Ranked by Expected ROI)
+
+1. **[Channel]:** [Why this channel, expected CAC, how to execute]
+2. **[Channel]:** [Why this channel, expected CAC]
+3. **[Channel]:** [Why this channel, expected CAC]
+
+> 💡 **Lesson learned:** Pre-launch marketing optimization — run a systematic Cialdini influence audit on your landing page and pricing section before spending on paid channels. The seven principles (Social Proof, Authority, Scarcity, Reciprocity, Commitment/Consistency, Liking, Unity) provide a structured framework for identifying conversion gaps. Key findings:
+>
+> 1. Social Proof: The #1 conversion driver for SaaS. Don't launch with zero proof. Even aggregate counters ("N users have done X this month") work. Title-level specificity ("Built for VPs, Directors, and C-suite") is proof by association.
+> 2. Authority: Domain expertise signals in feature copy (naming specific tools/platforms your audience uses) outperform generic descriptions.
+> 3. Scarcity: For professional audiences, loss-framing ("After trial, AI features lock — but everything you built stays") outperforms urgency timers. Name what stops working, don't just say "Upgrade now."
+> 4. Pricing layout: Cost anchors (competitor pricing, alternative costs) MUST appear above the price grid, not below it. Visitors anchor on the first number they see. Place the expensive reference point before your price.
+>
+> Run the audit as a reusable prompt (see prompts/cialdini-marketing-audit.md if available). Score each principle, prescribe specific copy/UI changes, and prioritize by implementation effort.
+
+### CAC/LTV Framework
+
+| Metric                      | Value      | Basis              |
+| --------------------------- | ---------- | ------------------ |
+| Target CAC                  | $[X]       | [how derived]      |
+| Average subscription length | [N] months | [basis]            |
+| LTV at [Tier]               | $[X]       | [price] x [months] |
+| LTV:CAC ratio               | [X]:1      | [target >3:1]      |
+
+## Churn Analysis
+
+### Expected Churn Pattern
+
+[Is churn a failure signal or a success signal in your business? How does the natural lifecycle of your users affect churn?]
+
+> 💡 **Lesson learned:** Job search tool churn is SUCCESS (user landed a job). This reframes economics: every churned user becomes word-of-mouth, a boomerang customer (job changes every 2-3 years), and an emotional testimonial. Anti-churn features should celebrate success, not cling to subscriptions.
+
+### Anti-Churn / Re-Engagement
+
+[What brings users back? What creates repeat revenue?]
+
+> 💡 **Lesson learned:** Consider a low-cost "Hold" or "Pause" tier ($10/mo) for users who complete their goal but may return. Key insights:
+> - Data preservation is the differentiator vs. expiration. Pair hold with a data retention limit on expired accounts (e.g., 30 days inactive → archived). No persistent free tier — expired accounts have zero limits, making Hold the only path to preserve data without a full subscription.
+> - Hold should block all expensive actions (AI, adding new items) but allow viewing everything. Sets maxActiveJobs high (preserve existing) but blocks new creation via a plan-level check.
+> - One-click resume to any paid tier. The resume path should go through Stripe Checkout, not require re-onboarding.
+> - Revenue math: $10/mo × 12 months of hold = $120 from a user who'd otherwise generate $0. If even 20% of churning users choose hold instead of cancel, that's meaningful recurring revenue.
+> - Implementation: same Stripe product/price/webhook pattern as other tiers. Just another entry in PLAN_LIMITS with zeros for all AI counters.
+
+## Virality Playbook
+
+_Features that create organic sharing should be designed into the product, not bolted on as marketing._
+
+### Built-In Sharing Triggers
+
+[What in-product moments naturally lead to sharing?]
+
+> 📝 **Example:**
+> - "I Landed" celebration creates a shareable moment
+> - Pipeline stats cards are inherently visual/shareable
+> - Resume diff views demonstrate value visually
+
+### Network Effects
+
+[Does the product get more valuable as more people use it? How?]
+
+### Content Virality
+
+[Does the product create content that attracts new users?]
+
+## Cost Estimates
+
+| Category               | Monthly Cost        | Notes                  |
+| ---------------------- | ------------------- | ---------------------- |
+| Infrastructure         | $[X]                | [provider, spec]       |
+| API/AI costs           | $[X] per [N] users  | [model, usage pattern] |
+| Payment processing     | [X]% + $[X] per txn | [provider]             |
+| Domain/DNS             | $[X]                |                        |
+| Monitoring             | $[X]                |                        |
+| **Total at [N] users** | **$[X]**            |                        |
+
+## Payment Implementation
+
+_Technical architecture for Stripe (or alternative). Fill in during Phase 7: Hardening._
+
+### Required Schema Changes
+
+[What database tables/fields need to exist for billing?]
+
+### Stripe Integration Points
+
+[Products, prices, checkout sessions, webhooks, customer portal. What needs to be built?]
+
+### Promo Code / Discount Strategy
+
+> 💡 **Lesson learned:** Promo codes as a growth lever:
+>
+> 1. Use cases to plan for:
+>    - Launch discounts (% off first N months)
+>    - Referral codes (fixed discount for referrer and referee)
+>    - Trial extensions (extra free days for specific audiences)
+>    - Partner/influencer codes (tracked via unique codes for attribution)
+>    - Win-back codes (for churned users, sent via email campaigns)
+>
+> 2. Unit economics check: Before offering discounts, model the impact.
+>    - A 50% discount at $119/mo = $59.50/mo. If API cost is $2.50/user/month, margin is still 96%. Safe.
+>    - But a 50% discount at $19/mo = $9.50/mo. If API cost is $5/user/month, margin is 47%. Risky.
+>    - Model your worst case: highest-discount code × heaviest-usage user × lowest-price tier.
+>
+> 3. Redemption limits prevent abuse:
+>    - Per-code max redemptions (e.g., "first 100 users")
+>    - Per-user single-use (promo_redemptions table)
+>    - Expiration dates on all promotional codes
+>    - Active/inactive flag for immediate kill-switch
+>
+> 4. Stripe mapping: Percent and fixed discounts map to Stripe Promotion Codes. Trial extensions map to Checkout Session trial_period_days. Don't mix — each discount type has its own Stripe mechanism.
+>
+> 5. For technical implementation details, see TECHNICAL_REFERENCE.md > Promo Code System.
+
+[What promo code types will you support? What's the discount budget? How will codes be distributed?]
+
+### Dynamic Pricing
+
+> 💡 **Lesson learned:** Never hardcode prices in UI components. Fetch prices from Stripe at runtime via stripe.prices.retrieve(), cache server-side (e.g., 1 hour TTL), and pass to components through layout data. This lets you change prices in the Stripe Dashboard without redeploying. Components should have hardcoded fallback values for when Stripe is unreachable, but the live values should always come from Stripe.
+
+[How will display prices be kept in sync with Stripe? Options: (1) fetch from Stripe and cache server-side (recommended), (2) public env vars (requires restart), (3) shared config file (requires redeploy).]
+
+### Implementation Phases
+
+[Break payment work into sequential phases with dependencies.]
+
+## Product Analytics & Success Metrics
+
+_Instrument your app to prove it works. Without analytics, you're guessing._
+
+> 💡 **Lesson learned:** PostHog Cloud (free tier: 1M events/month) is the right tool for early-stage product analytics. It covers funnels, retention cohorts, feature adoption, and session replay in one tool. Plausible/Umami are web analytics (pageviews) — they don't give you funnels or custom events. Rolling your own event capture is easy; building the analysis UI is weeks of work.
+>
+> Key pattern: Create a thin wrapper module ($lib/posthog.ts) that exports initPostHog(), identifyUser(), trackEvent(), trackPageView(). Initialize in root layout onMount. If the API key isn't set, all calls silently no-op (safe for local dev). Track SPA page views via afterNavigate, not PostHog's automatic capture (which double-counts in SPA frameworks).
+
+### SM0: Does The Product Work?
+
+[Define your core workflow funnel. What sequence of actions proves a user got value? Instrument each step.]
+
+| Event        | When It Fires | What It Proves             |
+| ------------ | ------------- | -------------------------- |
+| [event_name] | [trigger]     | [what this step validates] |
+
+### SM1: Net Promoter Score
+
+[When will you survey users? At what product moments? How will you use qualitative feedback?]
+
+> 💡 **Lesson learned:** NPS is most useful when triggered at moments of realized value, not random intervals.
+>
+> Implementation pattern:
+> 1. Identify 2-3 "value moments" — points where the user has received enough value to form an opinion (e.g., 3rd use of a core feature, first success outcome). Don't survey on first use.
+> 2. Build an in-app toast/bottom-sheet, NOT an email. Email NPS has low response rates. In-app catches the user in context.
+> 3. Standard 0-10 scale → follow-up qualitative question. Tailor the question to the score:
+>    - Detractors (0-6): "What's not working for you?"
+>    - Passives (7-8): "What would make this a 10?"
+>    - Promoters (9-10): "What do you love most?"
+> 4. Store responses in a dedicated collection (user, score, reason, trigger, created). Make records immutable (no update/delete) for audit integrity.
+> 5. Wire triggers via window events (CustomEvent) so components stay decoupled. The NPS component listens; feature components just dispatch events when milestones hit.
+> 6. Check server-side whether the user already responded for a given trigger before showing. One survey per trigger per user.
+> 7. Track nps_submitted and nps_dismissed in PostHog for response rate analysis.
+> 8. Target: NPS ≥ 40 before investing in retention/growth (SM2+).
+
+### SM2: Retention
+
+[What does healthy retention look like for your product? Is churn a failure signal or a success signal?]
+
+### SM3: CAC Doubling Time
+
+[How will you track acquisition cost and viral loops? What's your K-factor formula?]
+
+> 🔧 **Guidance:** These Success Metrics (SM0-SM4) are from Pablo Cruz's Venture Building framework (via Tim Connors, ex-Sequoia). They're sequential: don't optimize NPS before the product works, don't pour money into CAC before retention proves the product holds users. See: https://www.pscruz.com/p/venture-building-success-metrics

package/docs/CODE_QUALITY.md

@@ -0,0 +1,170 @@
+# Code Quality Review
+
+_Deep review of the codebase covering security, type safety, error handling, reactivity, performance, and consistency. Findings are rated Critical, Major, or Minor. Ask Claude to generate this during Phase 7: Hardening._
+
+_For exploitable security vulnerabilities (attacker-focused), see [BLACK_HAT_REPORT.md](BLACK_HAT_REPORT.md). For feature documentation see [TECHNICAL_REFERENCE.md](TECHNICAL_REFERENCE.md). For deployment readiness see [DEPLOYMENT.md](DEPLOYMENT.md)._
+
+_Instructions: Ask Claude to produce this document by running a systematic audit: "Audit the codebase for production readiness. Organize findings by category, rate them Critical/Major/Minor, and include specific file:line references with remediation steps." Update it as findings are fixed._
+
+_Note: This document covers **engineering quality** (type safety, error handling, consistency, maintainability). For **security vulnerabilities** (injection, IDOR, auth bypass, SSRF), use the black hat audit prompt (`_forgetrail/prompts/black-hat-audit.md`) and save results to [BLACK_HAT_REPORT.md](BLACK_HAT_REPORT.md). The two reports complement each other — some findings may appear in both with different framing._
+
+---
+
+## Audit Categories
+
+> 🔧 **Guidance:** These categories emerged from Exec Foundry's audit. Not all will apply to every project, but they're a solid starting checklist.
+>
+> Key lessons learned:
+> 1. FIELD SIZE LIMITS: Check all LLM output against database field size limits. PocketBase's default 5K text limit silently truncated LLM output with no error. Ask Claude: "Check all LLM function calls and their output sizes against field limits."
+> 2. SILENT FAILURES: Grep for catch blocks that return empty results. Functions that catch errors and return [] or null are invisible bugs.
+> 3. ERROR FORMAT CONSISTENCY: All API routes should return errors in the same format. Mixed { error } and { message } formats cause client-side handling bugs.
+> 4. TYPE SAFETY: Count `as any` casts. Each one is a potential silent failure when schemas change. LLM JSON responses need runtime validation. Prefer systematic replacement: **`unknown` at catch boundaries and JSON edges**, **typed mapper inputs** (e.g. PocketBase `RecordModel` instead of `as any`), and **literal unions** for UI state instead of widening to `any` for event handlers.
+>
+> 5. **LLM JSON parse hardening (verbatim-copy prompts):** Do not use bare `JSON.parse` on model output when strings contain user document text. Use a shared **`parseJsonFromLlmOutput`** (fence strip + leading-object extraction + **control-char sanitization inside string literals** as fallback). Strict parse first so valid output is unchanged. Add unit tests for raw-newline-in-string payloads.
+> 5. AUTHORIZATION: Check that auth checks are atomic. A delegation check followed by a separate data fetch can be exploited between the two calls.
+
+## Summary Table
+
+| Category         | Critical | Major | Minor | Fixed |
+| ---------------- | -------- | ----- | ----- | ----- |
+| Security         |          |       |       |       |
+| Type Safety      |          |       |       |       |
+| Error Handling   |          |       |       |       |
+| Reactivity/State |          |       |       |       |
+| Performance      |          |       |       |       |
+| Consistency      |          |       |       |       |
+| **Total**        |          |       |       |       |
+
+## Critical Findings
+
+_Must fix before launch. Each finding includes: what's wrong, where it is, why it matters, and how to fix it._
+
+### C1: [Finding Title]
+
+**File:** `[path/to/file.ts]:[line]`
+**Category:** [Security / Type Safety / etc.]
+**Impact:** [What could go wrong]
+
+**Problem:**
+[Specific description with code example if helpful]
+
+**Fix:**
+[Exact remediation steps]
+
+**Status:** [ ] Not started / [x] Fixed ([date])
+
+## Major Findings
+
+_Should fix before launch. Won't cause security incidents but will cause user-facing bugs or maintenance pain._
+
+### M1: [Finding Title]
+
+**File:** `[path/to/file.ts]:[line]`
+**Category:** [category]
+**Impact:** [What could go wrong]
+
+**Problem:**
+[Description]
+
+**Fix:**
+[Remediation]
+
+**Status:** [ ] Not started / [x] Fixed ([date])
+
+## Minor Findings
+
+_Fix when convenient. Code quality improvements that reduce future maintenance burden._
+
+### m1: [Finding Title]
+
+**File:** `[path/to/file.ts]:[line]`
+**Category:** [category]
+
+**Problem:**
+[Description]
+
+**Fix:**
+[Remediation]
+
+**Status:** [ ] Not started / [x] Fixed ([date])
+
+## Priority Actions
+
+_Sequenced by dependency. Do these in order._
+
+1. [ ] [Action]: [Which findings it resolves]
+2. [ ] [Action]: [Which findings it resolves]
+3. [ ] [Action]: [Which findings it resolves]
+
+## Audit Checklist for Future Reviews
+
+_Run through this list periodically, especially before releases._
+
+- [ ] Grep for `as any` casts and evaluate each one
+- [ ] Grep for `catch (` / `: any)` — prefer `unknown` plus shared helpers for user-facing messages and optional HTTP/status extraction
+- [ ] Confirm lint/typecheck (e.g. ESLint with `@typescript-eslint/no-explicit-any`, `svelte-check`) runs in CI or pre-release so type hygiene doesn’t regress silently
+- [ ] Grep for empty catch blocks (`catch (e) { }` or `catch { return [] }`)
+- [ ] Check all API routes return errors in the same format
+- [ ] Verify all LLM output fields have adequate database field sizes
+- [ ] Check all auth/permission checks are atomic (no TOCTOU vulnerabilities)
+- [ ] Verify all setTimeout/setInterval are cleaned up on component unmount
+- [ ] Check for stale closure captures in async functions with reactive state
+- [ ] Validate all user input before database queries (injection prevention)
+- [ ] Verify error messages are user-facing, not developer-facing
+- [ ] **User-facing copy (when adopted):** run `export:copy`; `audit:inline-copy` at **0 UI prose not in export**; run `user-facing-content-sync-audit.md` before major marketing pushes; grep `\bcan\b` for capability hedges (`can strengthen` → `strengthens`) per **`.cursor/rules/user-facing-content.mdc`**
+- [ ] Check that no secrets are hardcoded or logged
+- [ ] Verify all database filter strings use parameterized helpers (no string interpolation)
+- [ ] Check that promo code redemption and usage counter increments are atomic
+- [ ] Verify delegation/impersonation routes check access level before mutations
+- [ ] Check that rate limiting covers all expensive endpoints (LLM calls, scraping, file processing)
+- [ ] Verify untrusted content (user input, scraped pages, uploads) is fenced with an injection-guard wrapper before entering any LLM prompt
+- [ ] Verify LLM calls read all response text blocks (not `content[0]`), disable thinking for JSON tasks, and treat blank model-name env vars as unset
+- [ ] Verify Stripe webhook signatures are validated on all payment endpoints
+- [ ] Verify all `fetch` call sites check `res.ok` before calling `.json()` or assigning response data to state
+- [ ] Check that all `setInterval` polling loops handle 429 responses with exponential backoff (not just `!res.ok` → skip)
+- [ ] Verify optimistic UI updates (star toggles, status changes) revert on `!res.ok`, not only on thrown errors
+- [ ] Check that success indicators ("Saved", "Deleted", dialog closes) are gated on `res.ok`, not fired unconditionally
+- [ ] Verify async callbacks in long-running operations guard against stale context (entity ID changed during await)
+- [ ] Check that bulk/batch operations suppress per-item polling (no N×M interval storm)
+- [ ] Verify that third-party file parsing engines (such as `pdf-parse` or `mammoth`) are isolated behind a centralized server-side file utility boundary (`pbFiles.ts` or similar) to protect route endpoints from library-specific imports.
+- [ ] Check that all ISO timestamp string transformations are standardized using a shared formatter (`formatUtcTimestamp` or similar) rather than repeated ad-hoc string replacements.
+- [ ] Verify that all gated admin-only API endpoints proxying private edge nodes enforce strict admin checks (`requireAdmin`) and implement a short connection timeout to prevent hanging.
+- [ ] **URL host classification:** Grep for `hostname.includes('…com')` / `url.includes('…com')` used as board/ATS allowlists — prefer a shared `hostMatchesDomain` (exact or subdomain suffix match on parsed hostname), not substring checks (CodeQL `js/incomplete-url-substring-sanitization`).
+- [ ] **SSRF boundary:** Outgoing fetch / browser navigation validates http(s) allowlist, rejects userinfo, localhost, private IPs, and `.local`/`.internal` at the handler edge; re-check redirects.
+- [ ] **Address ranges are numeric, not string prefixes:** blocked ranges computed from octets/hextets (whole `127/8`, not `=== '127.0.0.1'`), IPv6 expanded before comparison (`::ffff:127.0.0.1` normalizes to `::ffff:7f00:1`), hostnames lowercased with brackets and the trailing FQDN dot stripped (`localhost.` is `localhost`).
+- [ ] **Guards have regression tests:** each blocked input class is asserted in a test that fails against the pre-fix code, and each branch of the guard is proven reachable (a regex that can never match is dead code, not a defense).
+- [ ] **Escaping matches the downstream parser:** compare against the vendor SDK's own escape helper before hand-rolling (e.g. PocketBase filters use backslash escapes, not SQL-style doubled quotes).
+- [ ] **Sanitizers run in one pass:** chained `.replace()` calls re-scan their own output (an entity decoder that expands `&` before named entities still double-decodes); use a single regex pass, or iterate to a fixed point when stripping nested constructs.
+- [ ] **Validate-then-connect is closed, not just narrowed:** the check and the socket must use the same address. In Node, an `undici` `Agent` with a filtering `connect.lookup` removes the rebinding window that a `resolve → validate → fetch` sequence leaves open; honor `options.all` so Happy Eyeballs still works.
+- [ ] **Headless browser navigation is guarded too:** a validated `goto` URL does not constrain 3xx, `<meta refresh>`, or script navigation. Abort navigation requests to blocked hosts via request interception and re-check the landed URL before reading content. Note the residual limit: the browser resolves DNS itself unless routed through a controlled proxy.
+- [ ] **Scheme allowlist:** Prefer `protocol === 'http:' || protocol === 'https:'` on a parsed `URL`, not only denying `javascript:`.
+- [ ] **GitHub Actions:** Workflows set top-level `permissions:` (least privilege). Never return `err.stack` / raw exception text in client JSON.
+
+> 💡 **Lesson learned:** **Host matching is not string `includes`.** Scrapers and board classifiers that use `hostname.includes('linkedin.com')` match lookalikes and generate dozens of identical CodeQL alerts. One shared helper (`host === domain || host.endsWith('.' + domain)`) plus call-site migration clears the storm and keeps regional subdomains (`uk.linkedin.com`, `boards.greenhouse.io`) working. Keep path checks on `pathname`. Sibling edge services that cannot import the app module should copy the helper with a sync comment.
+>
+> 📝 **Example:** `hostMatchesDomain('www.linkedin.com', 'linkedin.com')` → true; `hostMatchesDomain('evil-linkedin.com', 'linkedin.com')` → false.
+
+> 💡 **Lesson learned:** **A hardening fix is not done until you run the bypass inputs through it.** A codebase can pass a security audit, ship the recommended guard, and still be exploitable because the guard compares strings where it should compare ranges. Real examples from one Exec Foundry sweep: an SSRF check that blocked `127.0.0.1` but not `127.0.0.2` or `[::ffff:127.0.0.1]` or `localhost.`; a DNS-resolution check whose IPv4-mapped branch used `/^:ffff:/` and could never match the resolver's `::ffff:` output; a filter escaper using SQL-style doubled quotes against a parser that expects backslashes; and an "`&amp;` last" entity decoder that still double-decoded because numeric refs ran first. All four had been reviewed and credited as effective. Add an **AREA 0 fix-efficacy pass** to security re-audits, and land a regression test with every guard so the next refactor cannot quietly undo it.
+>
+> 📝 **Example:** `assert.throws(() => assertSafeUrl('http://[::ffff:169.254.169.254]/'))` is worth more than a paragraph in the audit report claiming metadata endpoints are blocked.
+
+> 💡 **Lesson learned:** **Tighten types at boundaries instead of sprinkling `any`.** Unchecked `any` makes refactors expensive: renamed API fields and mapper outputs fail silently until a user hits an edge case. Treat **`catch` clauses**, **`fetch().json()` results**, and **ORM/PocketBase rows passed into mappers** as the main places to invest — use `unknown`, narrow once, or cast to the framework’s record type (`RecordModel`) at the mapper input so greps stay honest. For UI toggles and segmented controls, model allowed values as a string union (or `typeof` existing state) instead of `as any` on click handlers.
+>
+> 📝 **Example:** A shared `errorMessage(e: unknown)` (and optional `getHttpStatus`) avoids duplicating `instanceof Error` checks across dozens of Svelte components; `pbEntityToApp(record as RecordModel)` documents the handoff from raw store to domain type better than `record as any`.
+
+> 💡 **Lesson learned:** Remediation tracking pattern — integrating findings with TODO:
+>
+> 1. After generating CODE_QUALITY.md and BLACK_HAT_REPORT.md, add ALL actionable findings to TODO.md under dedicated sections.
+> 2. Use priority tiers:
+>    - P0 (Critical/Immediate): Directly exploitable vulnerabilities, data loss risks. Fix before launch.
+>    - P1 (High/Short-term): Defense-in-depth, hardening, significant code quality issues. Fix next sprint.
+>    - P2 (Medium-Low/Backlog): Nice-to-haves, future-proofing, cosmetic code quality. Schedule when convenient.
+> 3. Annotate each finding in the report with its TODO status: `→ *Added to TODO (P0)*`
+> 4. As fixes are implemented, update BOTH:
+>    - The finding's status in this doc: `**Status:** [x] Fixed (date)`
+>    - The TODO checkbox
+> 5. This dual-tracking prevents findings from getting lost and provides an audit trail of what was fixed and when.
+
+> 💡 **Lesson learned:** **Audit for fetch/polling resilience as a class, not one-off.** After discovering that bulk import triggered a 429 request storm (N concurrent polling intervals × rate-limited API = frozen UI + cascading `TypeError`s from error objects assigned to array state), a systematic sweep of every `setInterval`-based polling loop and every `fetch` → `.json()` call site revealed the same anti-pattern in 6+ files: no `res.ok` guard, no 429-specific backoff, no timer cleanup on destroy. Treat these as a **category** during code review — anywhere `setInterval` + `fetch` appear together, verify the three guards (response check, backoff, lifecycle cleanup). Bulk operations are the stress test: if single-item import works fine, try 20+ items and watch the console for 429 cascades.
+>
+> 📝 **Example:** A skip-tick backoff pattern for `setInterval` polling: declare `let skipTicks = 0` outside the interval callback; on 429, set `skipTicks = Math.min((skipTicks || 1) * 2, maxSkip)`; at the start of each tick, if `skipTicks > 0`, decrement and return. This provides exponential backoff within the existing interval without replacing it with `setTimeout` chains.