canonicalizing-urls

Use when working with any URL that may contain tracking parameters, redirect wrappers, locale prefixes, or opaque share links — to produce a clean, canonical form. Triggers proactively when the agent uses a URL in a context where cleanliness matters (saving to Notion, quoting in a document, creating a hyperlink). Also triggers explicitly when the user says "canonicalize", "clean this URL", "strip tracking params", or invokes /canonicalize.

canonicalizing-urls

Canonicalize URLs by running scripts/canonicalize.py (requires uv).

Proactive use

When a URL appears in a context where it will be saved, shared, or cited:

uv run scripts/canonicalize.py <url> (offline, static rules only)
If the URL matches an opaque short-link pattern (e.g. /share/p/), add --online
If the result differs from the input, substitute the canonical form
Note the change inline: "(canonicalized: removed fbclid)"

Explicit use

When the user asks to canonicalize a URL:

uv run scripts/canonicalize.py <url>
If unchanged and URL looks non-canonical, run --probe to discover rules

Adding a new rule

When the script returns unchanged output but the URL is clearly non-canonical:

uv run scripts/canonicalize.py --probe <url> — review suggested actions
Ask user: generalize to a pattern, or keep domain-specific?
Add a failing UAT row to tests/test_uat.py (BEFORE→AFTER)
Add the confirmed Rule(...) to RULES in scripts/rules.py
- Insert before HostGlob rules if the rule rewrites the host for a specific domain (the specific Host(...) rule must fire first to prevent the generic glob from also running)
- Otherwise insert after similar-domain rules, before the closing bracket
uv run scripts/canonicalize.py <original_url> — verify output
uv run --group dev pytest tests/ -v — confirm all tests pass
Commit: feat: add <domain> canonicalization rule