# Known Pitfalls

## Trending HTML auth wrappers
Unauthenticated trending pages wrap star/fork counts in `/login?return_to=...`. Star counts in HTML are unreliable. Always revalidate via `/repos/{owner}/{repo}` API.

## Sponsor profile entries in trending HTML
Trending HTML may include sponsor/dashboard entries matching `/sponsors/<user>` hrefs. These are profile pages, not repositories, and will 404 on API repo endpoints. Detect and skip them before metadata fetch.

## README description extraction
READMEs often start with badges and nested HTML before the description. `<p[^>]*>\s*([^<]+)` fails if the element contains nested tags. Fix: use a fallback chain of regexes and default to API `description` when regex returns empty.

## Cron/autonomous context: `execute_code` blocked
Cron jobs and many environments block `execute_code` from invoking tools. Use `write_file` + `terminal python3` instead. Do not suggest `execute_code` as primary path in cron mode.

### Verified fallback: terminal heredoc
When `write_file` / `terminal script` chains are awkward, use `terminal` with an inline Python heredoc:
```bash
python3 - << 'PY'
# full script here
PY
```
This works reliably in cron shells and avoids tool friction. It is the preferred autonomous execution pattern in this environment.

## No local files rule
If the user restricts to read-only, do not write scratch files anywhere. Use the API directly for metadata/README instead of writing to `/tmp`.

## README base64 decode regex pitfall
Using `re.sub(r'\[([^\]]*)\]\([^)]*\)', r'\1', text)` to strip markdown links can raise `re.error: unbalanced parenthesis at position N` when the replacement string `r'\1'` is parsed as a regex backreference inside the replacement string. The safe fix is to either: (a) avoid backreference-based replacements, (b) use `re.escape(r'\1')`, or (c) strip links by a simpler pattern first. In practice, replacing links with their inner label via a non-regex approach or a simpler pattern avoids this entirely.

## HTML entity handling
Trending page descriptions often contain `&` instead of `&`. Use a small decode map or `html.unescape()` with tolerant preprocessing before regex extraction.

## Trending data completeness
Unauthenticated trending HTML may omit daily star-delta values. Treat the API `/search/repositories?q=pushed:yesterday` as a structured fallback when HTML blocks lack deltas or fail to parse. The fallback API for this user has returned broad top-star overall repos, not strictly "trending today," so prefer HTML deltas when available.

## HTML truncation due to `head -c`
Fetching the trending page with `curl ... | head -c N` can cut `<article>` blocks in half. Drop the byte limit; save the full response and parse whole blocks.

## Local file creation constraints under read-only restrictions
When the user restricts to read-only operations, do not write scratch files to `/tmp`. Use direct API calls (GitHub REST Composio tools) for metadata and README previews instead of scripts.

## HTML sanitization for Telegram/e-mail
Telegram safe rendering prefers unescaped text with anchoring via bullet paragraphs rather than tables when parse_mode markup is unreliable. For HTML e-mail, render full tables with trimmed columns and theme classification.

- Source fallback behavior
If `/trending` parsing yields fewer than 8 repos or blocks lack `stars/forks/delta`, fallback to the GitHub Search API instead of retrying the same source.

## Auth-wrapped HTML can corrupt repo names into arbitrary HTML
Unauthenticated trending pages can return 14 real `<article class="Box-row">` blocks while still wrapping action buttons in `/login?return_to=...`. If parser regex runs before sanitizing, the extracted "repo name" may contain an entire embedded SVG, `data-hydro-click-hmac`, quoted JSON fragments, and HTML entities. Always validate parsed `full_name` before API fetch; otherwise you’ll persist garbage like `trending",...` as repo identifiers. If a validate/generate step in a previous cron run only printed the input prompt or skill text as output, treat current machine state as **unknown** and rerun the whole pipeline instead of relying on prior `/tmp/*.json` artifacts.

## Cron delivery detection
Before trusting cron output files as a completed report, verify the delivered text actually contains structured report output (github links, theme sections, 10 numbered items). If it instead contains only the prompt/skill text or an unfinished placeholder sentence, the job did not finish and must be rerun or executed manually end-to-end.