@opendirectory.dev/skills 0.1.71 → 0.1.73

package/skills/domain-expired-opportunity-finder/references/guardrails.md

@@ -0,0 +1,125 @@
+# Guardrails — domain-expired-opportunity-finder
+
+This document defines the ethical, policy, and anti-abuse constraints
+that govern how this skill frames its output and recommendations.
+
+---
+
+## Core Principle
+
+This skill is a **research and triage tool**, not an acquisition engine.
+It surfaces candidates for human review. It does not make buying decisions,
+guarantee SEO outcomes, or encourage manipulative domain practices.
+
+---
+
+## Anti-Abuse Policy
+
+### What This Skill Must NOT Encourage
+
+1. **Private Blog Network (PBN) construction.** The skill must never suggest
+   acquiring expired domains to build link networks. If the user's stated
+   intent suggests PBN use, the skill should note the risk and decline to
+   optimize for that use case.
+
+2. **Deceptive redirects.** The skill must never recommend redirecting an
+   expired domain to an unrelated site without clearly flagging this as
+   high-risk and likely ineffective. The `redirect_mismatch` flag exists
+   specifically to enforce this constraint.
+
+3. **Unrelated domain repurposing.** Acquiring a domain with no topical
+   connection to the user's niche purely for its metrics is a pattern
+   the skill must actively discourage through scoring (topical relevance
+   is the highest-weighted dimension at 30%).
+
+4. **Spam domain recycling.** The skill must flag domains with spammy
+   anchor profiles, suspicious registrar history, or deindex signals
+   rather than presenting them as opportunities.
+
+---
+
+## Redirect Analysis Constraints
+
+Redirect suitability is only rated `high` or `medium` when:
+
+- The historical topic of the expired domain **closely matches** the
+  target niche (topic continuity score ≥ 5/10)
+- The content type is compatible (e.g., blog to blog, tool to tool)
+- The anchor text profile is primarily branded or generic (not spammy)
+
+If ANY of these conditions fail, redirect suitability is rated `low` or
+`not-recommended`, and the `redirect_mismatch` flag is applied.
+
+The skill must explicitly state in output when a domain is better suited
+for rebuild than redirect, and explain why.
+
+---
+
+## Framing Rules
+
+### Language to USE in output:
+- "This domain appears worth reviewing for..."
+- "Based on available evidence, this candidate shows..."
+- "Manual due diligence is recommended before any acquisition decision."
+- "The historical topic appears adjacent to your niche, but further
+  verification is needed."
+- "This assessment is based on publicly available signals and may not
+  reflect the domain's current state in search engines."
+
+### Language to AVOID in output:
+- ~~"Guaranteed rankings"~~
+- ~~"Link equity transfer"~~
+- ~~"This domain will boost your SEO"~~
+- ~~"Safe to redirect"~~ (always qualified)
+- ~~"High authority domain"~~ (authority metrics are not our primary signal)
+- ~~"Easy win"~~
+- ~~"No-brainer acquisition"~~
+- ~~"Free backlinks"~~
+- ~~"Instant traffic"~~
+- ~~"SEO hack"~~
+
+---
+
+## Required Disclaimer
+
+Every output — in both shortlist and audit mode — must include this
+disclaimer at the end:
+
+> **Disclaimer:** These results are research recommendations, not guarantees
+> of SEO value. Redirect analysis should only be considered when strong
+> topic continuity exists between the expired domain and your target site.
+> Search engine algorithms change frequently. Always perform manual due
+> diligence — including checking current index status, reviewing the full
+> backlink profile with a commercial tool, and verifying domain history —
+> before making any acquisition decision. This skill does not endorse or
+> facilitate manipulative SEO practices.
+
+---
+
+## User Intent Handling
+
+If the user describes an intended use that conflicts with these guardrails:
+
+| User Intent | Skill Response |
+|---|---|
+| "I want to build a PBN" | Note the SEO risk, explain why PBN patterns are increasingly detected, and proceed with scoring but add a warning to every output. Do not optimize for PBN use. |
+| "I want to redirect unrelated domains" | Apply `redirect_mismatch` flag to all candidates where topic continuity is weak. Explain why unrelated redirects are unreliable. Still provide rebuild recommendations if applicable. |
+| "I want cheap domains for link building" | Clarify that expired domain acquisition for link building carries inherent risk. Score normally but ensure `why_risky` explanations are thorough. |
+| "I want to find domains in my niche to rebuild" | This is the ideal use case. Proceed normally with full scoring. |
+
+---
+
+## Transparency Requirements
+
+1. Every shortlisted domain must include BOTH `why_selected` AND `why_risky`.
+   Even the best candidates have some level of risk or uncertainty.
+
+2. The `scoring_mode` field must indicate whether LLM-enhanced or rule-based-only
+   scoring was used, so the user understands the depth of analysis.
+
+3. If data sources were unavailable or returned no results for a candidate,
+   this must be reflected in the `confidence` level and `signal_completeness`
+   dimension.
+
+4. The skill must never present a score without the ability for the user
+   to understand how it was computed (by referencing `references/scoring-model.md`).

package/skills/domain-expired-opportunity-finder/references/output-format.md

@@ -0,0 +1,200 @@
+# Output Format — domain-expired-opportunity-finder
+
+This document defines the exact output schema for both Shortlist and Audit modes.
+All output must follow this structure precisely.
+
+---
+
+## Output Modes
+
+### Shortlist Mode (default)
+Returns only candidates with `recommended_action` of `high-priority-review`,
+`review`, or `rebuild-only-review`. Rejected candidates are excluded.
+Optimized for operator review — compact, decision-ready.
+
+### Audit Mode
+Returns ALL candidates, including rejected ones. Each candidate includes
+full dimension breakdowns. Use this mode to understand why candidates were
+rejected or down-ranked.
+
+To request audit mode, the user says: "run in audit mode" or "show all candidates including rejects."
+
+---
+
+## JSON Schema — Shortlist Mode
+
+```json
+{
+  "skill": "domain-expired-opportunity-finder",
+  "run_date": "YYYY-MM-DD",
+  "target_niche": "string — the niche used for scoring",
+  "seed_keywords": ["array of seed keywords used, if any"],
+  "intended_use": "rebuild | redirect | either",
+  "candidates_evaluated": 0,
+  "candidates_shortlisted": 0,
+  "candidates_rejected": 0,
+  "scoring_mode": "llm-enhanced | rule-based-only",
+  "shortlist": [
+    {
+      "domain": "example.com",
+      "opportunity_score": 81,
+      "confidence": "high | medium | low",
+      "recommended_action": "high-priority-review | review | rebuild-only-review",
+      "redirect_suitability": "high | medium | low | not-recommended",
+      "topical_fit_summary": "One or two sentences on niche alignment evidence.",
+      "activity_level_summary": "One or two sentences on historical snapshot density.",
+      "content_quality_summary": "One or two sentences on historical title/meta quality.",
+      "history_summary": "One or two sentences on prior use and cleanliness.",
+      "risk_flags": ["topic_mismatch", "spam_content_risk"],
+      "why_selected": "Human-readable rationale for why this domain made the shortlist.",
+      "why_risky": "Human-readable rationale for caution, even for selected domains."
+    }
+  ],
+  "guardrails_disclaimer": "These results are research recommendations, not guarantees of SEO value. Redirect analysis should only be considered when strong topic continuity exists between the expired domain and your target site. Search engine algorithms change frequently. Always perform manual due diligence — including checking current index status, reviewing the full backlink profile with a commercial tool, and verifying domain history — before making any acquisition decision. This skill does not endorse or facilitate manipulative SEO practices."
+}
+```
+
+---
+
+## JSON Schema — Audit Mode
+
+Includes all fields from Shortlist Mode, plus:
+
+```json
+{
+  "all_candidates": [
+    {
+      "domain": "example.com",
+      "opportunity_score": 34,
+      "confidence": "low",
+      "recommended_action": "reject",
+      "redirect_suitability": "not-recommended",
+      "dimension_breakdown": {
+        "topical_relevance": { "score": 5, "max": 30, "notes": "No keyword match, historical content unrelated" },
+        "historical_activity_level": { "score": 12, "max": 25, "notes": "Consistent snapshots but large gap in 2021" },
+        "historical_content_quality": { "score": 3, "max": 15, "notes": "Heavy exact-match money keywords in titles" },
+        "history_cleanliness": { "score": 8, "max": 15, "notes": "3 years of snapshots, some gaps" },
+        "redirect_suitability": { "score": 2, "max": 10, "notes": "Historical topic does not match target niche" },
+        "signal_completeness": { "score": 4, "max": 5, "notes": "RDAP lookup failed" }
+      },
+      "risk_flags": ["topic_mismatch", "spam_content_risk"],
+      "rejection_reason": "Topic mismatch (High severity) combined with spammy historical content.",
+      "topical_fit_summary": "...",
+      "activity_level_summary": "...",
+      "content_quality_summary": "...",
+      "history_summary": "...",
+      "why_selected": null,
+      "why_risky": "Domain has no topical overlap with target niche and titles show signs of keyword stuffing."
+    }
+  ]
+}
+```
+
+---
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | string | Yes | Candidate domain name (no protocol, no trailing slash) |
+| `opportunity_score` | integer | Yes | Final weighted score, 0–100 |
+| `confidence` | enum | Yes | `high`, `medium`, or `low` — reflects evidence completeness |
+| `recommended_action` | enum | Yes | `high-priority-review`, `review`, `rebuild-only-review`, or `reject` |
+| `redirect_suitability` | enum | Yes | `high`, `medium`, `low`, or `not-recommended` |
+| `topical_fit_summary` | string | Yes | 1–2 sentence explanation of niche alignment |
+| `activity_level_summary` | string | Yes | 1–2 sentence explanation of snapshot/activity density |
+| `content_quality_summary` | string | Yes | 1–2 sentence explanation of historical title quality |
+| `history_summary` | string | Yes | 1–2 sentence explanation of prior use and cleanliness |
+| `risk_flags` | array | Yes | Array of flag strings (empty array if none) |
+| `why_selected` | string | Yes* | Rationale for inclusion. *Null for rejected candidates in audit mode. |
+| `why_risky` | string | Yes | Rationale for caution, present even for selected domains |
+| `dimension_breakdown` | object | Audit only | Per-dimension score, max, and notes |
+| `rejection_reason` | string | Audit only | Why the candidate was rejected |
+
+---
+
+## Redirect Suitability Mapping
+
+| Score (out of 10) | Label |
+|---|---|
+| 8–10 | `high` |
+| 5–7 | `medium` |
+| 2–4 | `low` |
+| 0–1 | `not-recommended` |
+
+---
+
+## Example Complete Output — Shortlist Mode
+
+```json
+{
+  "skill": "domain-expired-opportunity-finder",
+  "run_date": "2026-05-10",
+  "target_niche": "developer tools",
+  "seed_keywords": ["devops", "CI/CD", "code editor", "IDE"],
+  "intended_use": "either",
+  "candidates_evaluated": 8,
+  "candidates_shortlisted": 3,
+  "candidates_rejected": 5,
+  "scoring_mode": "llm-enhanced",
+  "shortlist": [
+    {
+      "domain": "devtoolsweekly.com",
+      "opportunity_score": 86,
+      "confidence": "high",
+      "recommended_action": "high-priority-review",
+      "redirect_suitability": "high",
+      "topical_fit_summary": "Domain name contains 'devtools'. Wayback snapshots confirm it was a weekly newsletter covering developer tools and IDE plugins from 2019 to 2024.",
+      "activity_level_summary": "High snapshot frequency across 6 consecutive years, indicating sustained active use.",
+      "content_quality_summary": "Historical page titles are predominantly branded ('DevTools Weekly') and natural. No keyword stuffing detected.",
+      "history_summary": "6 years of consistent Wayback snapshots (2019–2024). All snapshots show real content. No parking pages or sudden drop-offs detected.",
+      "risk_flags": [],
+      "why_selected": "Strong topical match to developer tools niche with a healthy activity history. Suitable for both rebuild and redirect analysis.",
+      "why_risky": "No significant risk signals detected. Standard due diligence recommended before acquisition."
+    },
+    {
+      "domain": "codeshipnews.io",
+      "opportunity_score": 63,
+      "confidence": "medium",
+      "recommended_action": "review",
+      "redirect_suitability": "medium",
+      "topical_fit_summary": "Domain suggests CI/CD or shipping code. Wayback shows a blog about deployment automation, adjacent to developer tools.",
+      "activity_level_summary": "Moderate activity. Captures exist but are clustered rather than continuous.",
+      "content_quality_summary": "Titles are somewhat generic but generally readable. Not alarming but worth noting.",
+      "history_summary": "3 years of snapshots (2020–2023). Clean content, no parking pages. Relatively short history.",
+      "risk_flags": ["short_history"],
+      "why_selected": "Adjacent to developer tools with a reasonable history. Worth manual review for rebuild potential.",
+      "why_risky": "Relatively short active history (3 years). Some boilerplate titles present."
+    },
+    {
+      "domain": "stackforgeapp.com",
+      "opportunity_score": 58,
+      "confidence": "medium",
+      "recommended_action": "rebuild-only-review",
+      "redirect_suitability": "low",
+      "topical_fit_summary": "Domain suggests a developer platform. Wayback shows a SaaS landing page for a project management tool — partially related to dev tools but not a direct match.",
+      "activity_level_summary": "Consistent snapshots over a 4-year period.",
+      "content_quality_summary": "Mostly branded ('StackForge') titles. Clean pattern.",
+      "history_summary": "4 years of snapshots. Clean, real product pages throughout.",
+      "risk_flags": ["redirect_mismatch"],
+      "why_selected": "Clean history makes it worth reviewing as a rebuild candidate in the developer tools space.",
+      "why_risky": "Historical topic (project management SaaS) does not closely match developer tools. Redirect not recommended — topic continuity is weak."
+    }
+  ],
+  "guardrails_disclaimer": "These results are research recommendations, not guarantees of SEO value. Redirect analysis should only be considered when strong topic continuity exists between the expired domain and your target site. Search engine algorithms change frequently. Always perform manual due diligence — including checking current index status, reviewing the full backlink profile with a commercial tool, and verifying domain history — before making any acquisition decision. This skill does not endorse or facilitate manipulative SEO practices."
+}
+```
+
+---
+
+## Save Location
+
+Output is saved to:
+```
+docs/expired-domain-intel/YYYY-MM-DD.json
+```
+
+Create the directory if it does not exist:
+```bash
+mkdir -p docs/expired-domain-intel
+```

package/skills/domain-expired-opportunity-finder/references/risk-flags.md

@@ -0,0 +1,135 @@
+# Risk Flags — domain-expired-opportunity-finder
+
+This document defines the risk flags that the skill can attach to any
+candidate domain. Risk flags serve two purposes:
+
+1. They explain WHY a domain may be risky despite looking attractive.
+2. They influence the recommendation logic (high-severity flags cap recommendations).
+
+---
+
+## Flag Definitions
+
+### `topic_mismatch`
+- **Severity:** High
+- **Trigger:** Historical topic and target niche overlap score < 30% (based on
+  Wayback content analysis and anchor text review)
+- **Effect:** Caps recommendation at `reject` for redirect use cases.
+  For rebuild use cases, caps at `review` (never `high-priority-review`).
+- **Why It Matters:** Acquiring a domain with no topical connection to your
+  niche is the most common and most damaging expired domain mistake. Search
+  engines increasingly detect and devalue unrelated redirects.
+
+---
+
+### `spam_content_risk`
+- **Severity:** High
+- **Trigger:** Historical page titles or meta descriptions consist predominantly of
+  exact-match money keywords, nonsensical text, or foreign-language spam unrelated to the
+  domain's apparent topic
+- **Effect:** Caps recommendation at `review` (never `high-priority-review`).
+  Adds explicit warning in `why_risky` field.
+- **Why It Matters:** Spammy historical content suggests the domain was used
+  for link schemes or low-quality affiliate sites. The historical value is unreliable.
+
+---
+
+### `weak_historical_activity`
+- **Severity:** Medium
+- **Trigger:** Wayback snapshot count is extremely low (e.g., < 10 total snapshots
+  across its lifetime) but avoids the `unclear_history` threshold.
+- **Effect:** Lowers `historical_activity_level` score. Does not automatically
+  reject but reduces overall opportunity_score.
+- **Why It Matters:** Expired domains with very low historical activity have had
+  less time to build natural authority. While not inherently spammy, they offer
+  less evidence of sustained value.
+
+---
+
+### `unclear_history`
+- **Severity:** Medium
+- **Trigger:** Fewer than 3 Wayback CDX snapshots exist for the domain,
+  OR all available snapshots resolve to parking pages (Sedo, GoDaddy parked,
+  domain-for-sale pages)
+- **Effect:** Reduces `history_cleanliness` score. Lowers confidence level
+  by one step (e.g., `high` → `medium`).
+- **Why It Matters:** Without verifiable history, there is no way to confirm
+  what the domain was previously used for. It could have been legitimate,
+  or it could have been a spam site that was cleaned. Ambiguity should
+  reduce confidence, not be ignored.
+
+---
+
+### `possible_deindex`
+- **Severity:** High
+- **Trigger:** Wayback CDX data shows years of regular snapshots followed by a
+  sudden complete stop (no snapshots for 2+ years before expiry), suggesting the
+  domain may have been deindexed or penalized before it expired
+- **Effect:** Caps recommendation at `review`. Adds explicit warning about
+  potential search engine penalties in `why_risky` field.
+- **Why It Matters:** A domain that was deindexed carries legacy penalties
+  that may transfer even after acquisition. This is one of the highest-risk
+  scenarios in expired domain acquisition.
+
+---
+
+### `redirect_mismatch`
+- **Severity:** Medium
+- **Trigger:** Redirect suitability score is below 4/10 (weak topic continuity
+  between historical use and intended target)
+- **Effect:** Changes recommendation from `review` to `rebuild-only-review`.
+  Explicitly notes in output that redirect analysis is not recommended.
+- **Why It Matters:** Redirecting a domain to an unrelated site is increasingly
+  treated as manipulative by search engines. Even when done with good intentions,
+  a topic-mismatched redirect is unlikely to pass meaningful value.
+
+---
+
+### `short_history`
+- **Severity:** Low
+- **Trigger:** Domain was actively used for less than 1 year before expiring
+  (based on Wayback first and last capture dates)
+- **Effect:** Minor reduction to `history_cleanliness` score. No recommendation
+  cap.
+- **Why It Matters:** Domains with very short histories have had less time to
+  build natural authority. They are not necessarily bad, but they offer less
+  evidence of sustained value.
+
+---
+
+### `suspicious_registrar`
+- **Severity:** Medium
+- **Trigger:** Registration data (RDAP) shows the domain was registered through a registrar
+  commonly associated with bulk domain spam operations (pattern-matched against
+  a known list of high-spam registrars)
+- **Effect:** Lowers confidence by one step. Adds note in `why_risky`.
+- **Why It Matters:** Domains registered through bulk-spam registrars have a
+  higher probability of having been used for link schemes, PBNs, or other
+  manipulative purposes, even if the current signals look clean.
+
+---
+
+## Severity Interaction Rules
+
+1. **Any High-severity flag** → recommendation is capped at `review` or lower.
+   A domain can never be `high-priority-review` with an active High flag.
+
+2. **Two or more Medium-severity flags** → treated as equivalent to one High
+   flag for recommendation capping purposes.
+
+3. **Low-severity flags** → informational only. They appear in output but do
+   not cap recommendations.
+
+4. **Flag stacking** → multiple flags of the same severity do not compound
+   further than the rules above. Two High flags are treated the same as one
+   High flag for capping purposes (the cap is already at `review`).
+
+---
+
+## Flag Presentation in Output
+
+Every flagged domain includes:
+- The flag name in the `risk_flags` array
+- A human-readable explanation in `why_risky`
+- The severity level is documented here but not repeated in output
+  (to keep output compact — operators can reference this file for severity details)

package/skills/domain-expired-opportunity-finder/references/scoring-model.md

@@ -0,0 +1,198 @@
+# Scoring Model — domain-expired-opportunity-finder
+
+This document defines the transparent, weighted scoring model used to evaluate
+expired domain candidates. Every score is explainable — no black-box ranking.
+
+---
+
+## Scoring Dimensions
+
+The skill scores each candidate across 6 dimensions. Each dimension has a
+defined weight, maximum point value, and the signals used to compute it.
+
+### 1. Topical Relevance (30 points, weight 30%)
+
+**Purpose:** Does this domain historically align with the user's target niche?
+
+**Signals:**
+- Domain string keyword match against `target_niche` and `seed_keywords`
+- Historical page titles from Wayback CDX snapshots
+- Historical meta descriptions and visible text (when available)
+- LLM niche-fit assessment (when LLM API key is configured)
+
+**Scoring Rules:**
+- 25–30: Strong keyword match in domain name AND historical content confirms niche
+- 18–24: Partial keyword match OR historical content is adjacent to niche
+- 10–17: Weak or indirect topical connection
+- 0–9: No meaningful topical overlap detected
+
+**Why Highest Weight:** Topical mismatch is the #1 trap in expired domain
+acquisition. A high-authority domain in the wrong niche is worse than a
+moderate domain in the right niche.
+
+---
+
+### 2. Historical Activity Level (25 points, weight 25%)
+
+**Purpose:** Does the domain have a sustained track record of active use?
+
+**Signals:**
+- Wayback CDX snapshot frequency over time
+- Density of snapshots during active years
+- Absence of prolonged dormant periods (excluding post-expiry)
+
+**Scoring Rules:**
+- 20–25: High snapshot frequency spanning multiple years continuously
+- 13–19: Moderate activity, some years with lower capture rates
+- 6–12: Low overall activity or large multi-year gaps
+- 0–5: Barely any snapshots, very sparse activity history
+
+**Key Principle:** A domain with a deep, sustained archive history provides
+more evidence of legitimate past use than a domain that only existed briefly.
+
+---
+
+### 3. Historical Content Quality (15 points, weight 15%)
+
+**Purpose:** Does the archived content look natural or keyword-stuffed?
+
+**Signals:**
+- Keyword stuffing in historical `<title>` tags
+- Unnatural phrasing in meta descriptions
+- Language consistency (sudden language shifts in history)
+
+**Scoring Rules:**
+- 12–15: Natural titles, branded focus, readable descriptions
+- 8–11: Some exact-match keywords but generally readable
+- 4–7: Heavy exact-match keywords or boilerplate titles
+- 0–3: Predominantly spammy, nonsensical, or foreign-language shifts
+
+**Red Flag:** If historical titles are heavily stuffed with money keywords, the
+`spam_content_risk` flag is triggered regardless of score.
+
+---
+
+### 4. History Cleanliness (15 points, weight 15%)
+
+**Purpose:** Was this domain used legitimately before it expired?
+
+**Signals:**
+- Wayback CDX snapshot count (more = longer verifiable history)
+- First and last capture dates (years of active use)
+- HTTP status code consistency across snapshots (200s vs 301s/404s)
+- Absence of parking page patterns (e.g., Sedo, GoDaddy parked pages)
+- No sudden activity drop-offs suggesting deindexing
+
+**Scoring Rules:**
+- 12–15: 5+ years of consistent snapshots, clean status codes, real content
+- 8–11: 2–5 years of history, mostly clean, minor gaps
+- 4–7: Short history OR significant gaps OR some parking page evidence
+- 0–3: Very sparse history, mostly parking pages, or suspicious patterns
+
+---
+
+### 5. Redirect Suitability (10 points, weight 10%)
+
+**Purpose:** If the user wants to redirect this domain, is the historical
+topic close enough to the target niche to make that plausible?
+
+**Signals:**
+- Topic continuity score (overlap between historical topic and target niche)
+- Content type match (was it a blog, tool, company site, etc.)
+- Audience overlap estimate (did the historical audience align with target?)
+
+**Scoring Rules:**
+- 8–10: Historical topic is the same or very closely adjacent to target niche
+- 5–7: Some topic overlap, partially plausible redirect
+- 2–4: Weak overlap, redirect would be a stretch
+- 0–1: No meaningful topic continuity — redirect not recommended
+
+**Key Constraint:** `redirect_suitability` is always included in `opportunity_score`
+regardless of `intended_use`. When `intended_use` is `rebuild`, a low
+`redirect_suitability` score does **not** trigger the `redirect_mismatch` flag
+or lower the recommendation — it is scored and summed normally. When
+`intended_use` is `redirect`, a score below 4/10 triggers the `redirect_mismatch`
+flag and caps the recommendation at `rebuild-only-review`.
+
+---
+
+### 6. Signal Completeness (5 points, weight 5%)
+
+**Purpose:** How much evidence do we actually have for this candidate?
+
+**Signals:**
+- Percentage of data sources that returned usable data
+- Whether Wayback and RDAP both succeeded
+- Whether LLM analysis was available (if API key configured)
+
+**Scoring Rules:**
+- 4–5: All available data sources returned data
+- 2–3: Most sources returned data, 1–2 gaps
+- 0–1: Significant data gaps — multiple sources failed or returned nothing
+
+**Why This Matters:** A domain that looks promising but has almost no
+verifiable data should not rank as highly as one with strong evidence.
+Missing signals reduce confidence, not boost it.
+
+---
+
+## Total Score Computation
+
+```
+opportunity_score = topical_relevance
+                  + historical_activity_level
+                  + historical_content_quality
+                  + history_cleanliness
+                  + redirect_suitability
+                  + signal_completeness
+```
+
+**Range:** 0–100 points.
+
+---
+
+## Confidence Mapping
+
+Confidence reflects how much evidence exists behind the score.
+
+| Condition | Confidence Level |
+|---|---|
+| ≥ 4 of 6 dimensions have strong data (non-zero signals) | `high` |
+| 3 of 6 dimensions have strong data | `medium` |
+| ≤ 2 dimensions have strong data | `low` |
+
+**Rule:** A domain with `low` confidence can never receive `high-priority-review`,
+regardless of its opportunity_score.
+
+---
+
+## Recommendation Logic
+
+| Score Range | Confidence | Recommended Action |
+|---|---|---|
+| ≥ 75 | `high` | `high-priority-review` |
+| ≥ 55 | `medium` or `high` | `review` |
+| ≥ 55 | any, BUT redirect_suitability < 4/10 | `rebuild-only-review` |
+| < 55 | any | `reject` |
+| any | any, WITH critical risk flag (severity = High) | `reject` (unless override) |
+
+**Override Rule:** A single High-severity risk flag (e.g., `topic_mismatch`,
+`spam_content_risk`, `possible_deindex`) automatically caps the recommendation
+at `review` or lower, even if the score is ≥ 75.
+
+---
+
+## Example Scoring Walkthrough
+
+**Candidate:** `devtoolsweekly.com` | **Target Niche:** `developer tools`
+
+| Dimension | Score | Rationale |
+|---|---|---|
+| Topical Relevance | 28/30 | "devtools" in domain, Wayback shows newsletter about dev tools |
+| Historical Activity | 18/25 | Consistent snapshot captures across multiple years |
+| Content Quality | 12/15 | Natural titles ("DevTools Weekly - Issue #45") |
+| History Cleanliness | 14/15 | 6 years of consistent snapshots, no parking pages |
+| Redirect Suitability | 9/10 | Direct topic match — dev tools to dev tools |
+| Signal Completeness | 5/5 | All sources returned data |
+
+**Total:** 86/100 | **Confidence:** `high` | **Action:** `high-priority-review`

package/.claude/skills/claude-md-generator/.env.example

@@ -1,7 +0,0 @@
-# claude-md-generator — Environment Variables
-# =============================================
-# Gemini is required for generating the CLAUDE.md content from analysis.
-
-# Required: Google Gemini API key for CLAUDE.md generation
-# Get it: aistudio.google.com, Get API key
-GEMINI_API_KEY=your_gemini_api_key_here