Troubleshooting & Lessons Learned

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• CHANGELOG.md
• extension/src/background/index.ts
• backend/config/prompts.json
• extension/src/content/export-pdf.ts

This documentation outlines known issues, architectural constraints, and development patterns identified during the implementation of the Oddity 1 platform. It focuses on resolving common failures in authentication, annotation rendering, and PDF handling.

Developers should refer to this guide when encountering environment-specific errors or when implementing new features that touch the core annotation engine or Google Docs integration.

Extension & Content Script Issues

PDF Injection and File Access

The content script does not automatically inject into file:// URLs. Users must manually enable "Allow access to file URLs" in chrome://extensions for local PDF files to be annotated. Programmatic injection is required to handle edge cases where isPdfPage() detection fails in the built-in Chrome PDF viewer.
Sources: README.md:143-152, extension/src/background/index.ts:103-125

Annotation Rendering Failures

If annotations do not appear, the system follows a detection fallback chain:

1. Adapter Match: Checks site_adapters for hostname patterns.
2. Readability: Detects article-like content using Mozilla Readability.
3. Heuristic: Scores text density and semantic tags.

If no reading region is detected, the extension logs [Oddity] No reading regions detected and makes no API requests.
Sources: README.md:188-193, README.md:213-219

The diagram shows the fallback logic used to identify annotatable content on a webpage.
Sources: README.md:213-219

Authentication & Authorization

Common Auth States

The extension uses icon badges to communicate authentication and system status.

• Red "!" Badge: The user is not signed in.
• Gray "OFF" Badge: The extension is globally disabled via the popup toggle.
• In-Page Toast: Prompts the user to sign in if they attempt to view annotations while logged out.
  Sources: README.md:112-124, CHANGELOG.md:12-15

Google Docs Auth Errors

Google Docs integration requires specific OAuth token handling. Errors often result from misconfigured Client IDs or required user interaction.
Sources: extension/src/background/index.ts:130-153, extension/src/background/index.ts:795-805

Error Prefix	Description	Resolution
GDocsAuthConfigError	OAuth client is misconfigured.	Verify Client ID in Google Cloud Console.
GDocsAuthRequiredError	User interaction required.	Use getInteractiveGoogleToken to prompt user.
HTTP 401	Token rejected by Docs API.	Refresh token via chrome.identity.

Sources: extension/src/background/index.ts:130-153, extension/src/background/index.ts:983-993

Technical Lessons & Best Practices

Workflow Orchestration

Development follows a "Plan First" strategy to reduce ambiguity in complex architectural decisions.

• Plan Mode: Required for any task with 3+ steps.
• Subagents: Used for parallel analysis and research to keep the main context window clean.
• Verification: No task is marked complete without logs, tests, or behavior diffs proving correctness.
  Sources: CLAUDE.md:3-31

Data Flow and Concurrency

To prevent rate limiting, the background worker implements a per-tab concurrency limiter.
Sources: extension/src/background/index.ts:33-51

This diagram illustrates the concurrency limiting mechanism and streaming flow for annotations.
Sources: extension/src/background/index.ts:33-51, extension/src/background/index.ts:250-280

PDF Export Sanitization

PDF exports strip host-page artifacts to ensure clean rendering.

• Removals: Scripts, styles, SVGs, and UI roles (e.g., [role="navigation"]).
• Attribute Preservation: Keeps essential content attributes like src, href, alt, and title.
• Absolute URLs: Converts relative image paths to absolute URLs using the current window location.
  Sources: extension/src/content/export-pdf.ts:96-126

AI Prompting Constraints

The backend requires valid system prompts in backend/config/prompts.json. If placeholders remain, the LLM will return invalid data, though the backend will not crash.
Sources: README.md:87-92, README.md:162-164

{
  "chunking_rules": {
    "min_words": 150,
    "target_words": "250-350",
    "total_coverage": "Every word must belong to exactly one chunk"
  }
}

Sources: backend/config/prompts.json:25-32

Summary of Findings

Maintaining system stability requires strict adherence to the concurrency limits in the background worker and the fallback detection chain in the content script. Effective troubleshooting starts with verifying the extension badge state and checking the chrome.storage.local preferences for site-specific overrides.
Sources: README.md:126-136, extension/src/background/index.ts:850-865