freshcontext-mcp 0.3.13 → 0.3.15

package/METHODOLOGY.md

@@ -0,0 +1,277 @@
+# FreshContext Data Intelligence Methodology
+**Version 1.1 — April 2026**
+*Authored by Immanuel Gabriel (Prince Gabriel) — Grootfontein, Namibia*
+
+---
+
+## What This Document Is
+
+This document formally describes the data collection, scoring, and provenance methodology underlying the FreshContext intelligence platform.
+
+It exists for three audiences:
+
+1. **Technical integrators** — teams embedding FreshContext into their agent infrastructure who need to understand what the data represents and how it is scored.
+2. **Acquirers and licensing partners** — entities evaluating FreshContext as an asset, who need to audit the methodology that makes the data defensible.
+3. **Regulators and auditors** — who may need to verify that the platform's data claims are substantiated by documented, reproducible methodology.
+
+---
+
+## Section 1: Data Collection
+
+### 1.1 Architecture
+
+FreshContext operates a continuous data collection pipeline running on Cloudflare's global edge infrastructure. The pipeline executes every 6 hours via a scheduled cron job and queries 18 watched query definitions stored in the platform's D1 database.
+
+Each watched query specifies:
+- **Adapter** — the data source to query (e.g., `hackernews`, `jobs`, `reposearch`)
+- **Query** — the search term or URL
+- **User ID** — the profile this query serves
+- **Filters** — optional parameters (location, exclusion terms, etc.)
+
+### 1.2 Adapters
+
+FreshContext implements 11 production adapters covering the following sources:
+
+| Adapter | Source | Auth Required | Update Frequency |
+|---|---|---|---|
+| `hackernews` | Hacker News Algolia API | None | Real-time |
+| `jobs` | Remotive API | None | Continuous |
+| `reposearch` | GitHub Search API | Optional (rate limit) | Real-time |
+| `github` | GitHub Repository API | Optional | Real-time |
+| `reddit` | Reddit JSON API | None | Real-time |
+| `yc` | YC Open Source API | None | Per batch cycle |
+| `packagetrends` | npm Registry + npm Downloads API | None | Per publish |
+| `finance` | Yahoo Finance API | None | Market hours |
+| `hackernews` | HN Algolia Full-Text Search | None | Real-time |
+
+All adapters operate exclusively on **publicly accessible data**. No credentials are required or used for data access. All fetch requests include a `User-Agent` header identifying the FreshContext crawler.
+
+### 1.3 Content Hash Deduplication
+
+Before any signal is stored, the platform computes a 32-bit rolling hash of the raw content. If the most recent stored result for a given watched query carries an identical hash, the current result is discarded. This prevents storing unchanged content across cron cycles.
+
+### 1.4 Semantic Deduplication
+
+Beyond exact-match deduplication, FreshContext implements semantic deduplication to prevent the same underlying story appearing as multiple signals because it was covered by multiple sources (e.g., the same GitHub release appearing in both HN and Reddit).
+
+The semantic fingerprint is computed as follows:
+
+1. Extract the first canonical URL from the raw content
+2. Extract the first ISO 8601 publication date from the raw content
+3. Extract and normalise the first substantive line (title) — lowercased, punctuation stripped, truncated to 80 characters
+4. Concatenate: `normalised_title|canonical_url|publication_date`
+5. Compute SHA-256 of the concatenated string
+6. Retain the first 16 hex characters as the fingerprint
+
+If any signal stored within the preceding 48 hours carries an identical fingerprint, the new result is discarded. The 48-hour window is configurable.
+
+---
+
+## Section 2: Temporal Scoring — The DAR Engine
+
+### 2.1 Overview
+
+The Decay-Adjusted Relevancy (DAR) engine scores every collected signal on two axes:
+
+- **R_0 (Base Score)** — semantic relevancy of the content against the user's profile, independent of time
+- **R_t (Decay-Adjusted Score)** — R_0 adjusted for how much time has elapsed since the content was published
+
+The final stored `rt_score` is what drives signal ranking in briefings and the intelligence feed.
+
+### 2.2 Base Score Calculation (R_0)
+
+R_0 is computed by matching content against the user profile:
+
+```
+R_0 = baseline (40)
+    + vital_keyword_matches × 15   [capped at +35]
+    + skill_keyword_matches × 3    [capped at +15]
+    + location_accessibility_bonus  [+8 if remote/accessible]
+    - error_penalty                 [−40 if content is empty/error]
+```
+
+Vital keywords are drawn from the `targets` field of the user profile — job titles, company names, and technology domains the user is specifically tracking.
+
+Skill keywords are drawn from the `skills` field — the user's technical competencies. A match here adds relevancy signal but at lower weight than a direct target match.
+
+The location accessibility bonus is applied when the content explicitly mentions "remote", "worldwide", "anywhere", or the user's stated location. This is not a geographic filter — it is a signal boost for content that is accessible to the user regardless of their physical location.
+
+**Hard exclusions:** If any term from the `exclusion_terms` list appears in the content, R_0 is forced to zero. The result is still stored (for audit purposes) but marked `is_relevant = 0`.
+
+### 2.3 Decay Function (R_t)
+
+```
+R_t = R_0 · e^(-λt)
+```
+
+Where:
+- `λ` = source-specific decay constant (per hour)
+- `t` = hours elapsed since `published_at`
+
+If `published_at` cannot be extracted from the content, `t` is assumed to equal one half-life for that source (conservative assumption — signal is treated as partially decayed but not dead).
+
+### 2.4 Source Decay Constants (λ)
+
+These constants represent the platform's proprietary calibration of how quickly signals from each source class lose intelligence value:
+
+| Source | λ (per hour) | Half-life |
+|---|---|---|
+| Hacker News | 0.050 | ~14 hours |
+| Reddit | 0.010 | ~3 days |
+| Product Hunt | 0.010 | ~3 days |
+| Job listings | 0.005 | ~6 days |
+| Financial data | 0.001 | ~29 days |
+| YC companies | 0.001 | ~29 days |
+| Package trends | 0.0005 | ~58 days |
+| GitHub repositories | 0.0002 | ~5 months |
+| Academic papers | 0.00005 | ~1.6 years |
+
+These constants are calibrated against observed information decay rates across source types. They are the platform's primary trade secret and are not exposed in API responses.
+
+### 2.5 Entropy Classification
+
+Each signal is classified into one of three entropy states based on its position on the decay curve:
+
+| State | Condition | Interpretation |
+|---|---|---|
+| `low` | `t < half_life / 2` | Signal near peak value — act now |
+| `stable` | `t < 1.5 × half_life` | Usable signal — monitor |
+| `high` | `t ≥ 1.5 × half_life` | Significantly degraded — verify before acting |
+
+### 2.6 Relevancy Threshold
+
+Signals with `rt_score < 35` are stored with `is_relevant = 0`. They remain in the database for audit and historical analysis but are excluded from briefings and the intelligence feed by default. The threshold is configurable per profile.
+
+---
+
+## Section 3: Provenance and Auditability
+
+### 3.1 The Ha-Pri Audit Signature
+
+Every signal stored in the FreshContext database carries a `ha_pri_sig` — a SHA-256 audit signature computed as:
+
+```
+SHA-256( result_id + ":" + content_hash + ":" + "FRESHCONTEXT_DAR_V1" )
+```
+
+This signature serves three purposes:
+
+1. **Tamper detection** — the signature binds the content hash to the result ID and the engine version. Any modification to the stored content would invalidate the signature.
+2. **Provenance chain** — every row in the `scrape_results` table is cryptographically linked to the moment it was scored by the DAR engine.
+3. **Licensing audit** — when FreshContext data is provided to a third party under licence, the `ha_pri_sig` column provides an immutable record of exactly what was delivered and when.
+
+### 3.2 D1 Historical Ledger
+
+The `scrape_results` table functions as a **Contextual Ledger** — not merely a cache, but a time-series record of intelligence signals with full provenance.
+
+Key properties of the ledger:
+- Every row is immutable once written (no UPDATE operations on scored rows)
+- Every row carries a `scraped_at` timestamp with second precision
+- Every row carries a `published_at` date extracted from content (where available)
+- The ledger accumulates continuously at 6-hour intervals regardless of active user sessions
+- The ledger enables time-travel queries: "what was the intelligence landscape for topic X at date Y?"
+
+### 3.3 Schema Reference
+
+```sql
+scrape_results (
+  id                  TEXT PRIMARY KEY,    -- sr_{timestamp}_{random}
+  watched_query_id    TEXT,                -- FK → watched_queries.id
+  adapter             TEXT,                -- source adapter name
+  query               TEXT,                -- the search term used
+  raw_content         TEXT,                -- scraped content (max 8000 chars)
+  result_hash         TEXT,                -- 32-bit rolling hash of raw_content
+  semantic_fingerprint TEXT,               -- 16-char SHA-256 of normalised title|url|date
+  is_new              INTEGER,             -- 1 until consumed by briefing
+  scraped_at          TEXT,                -- ISO 8601 UTC timestamp
+  published_at        TEXT,                -- extracted content publication date
+  relevancy_score     INTEGER,             -- = round(rt_score), 0-100
+  is_relevant         INTEGER,             -- 1 if rt_score >= 35, else 0
+  base_score          INTEGER,             -- R_0 semantic score, 0-100
+  rt_score            REAL,                -- R_t decay-adjusted score, 0-100
+  ha_pri_sig          TEXT,                -- SHA-256 audit signature (64 hex chars)
+  entropy_level       TEXT                 -- 'low' | 'stable' | 'high'
+)
+```
+
+---
+
+## Section 4: The Intelligence Feed
+
+### 4.1 Endpoint
+
+```
+GET /v1/intel/feed/{profile_id}
+```
+
+Optional parameters:
+- `limit` — maximum signals to return (default: 20)
+- `min_rt` — minimum rt_score filter (default: 0)
+
+### 4.2 Response Structure
+
+```json
+{
+  "feed_metadata": {
+    "profile_id": "default",
+    "generated_at": "2026-04-14T09:00:00Z",
+    "signal_count": 18,
+    "version": "freshcontext-1.1"
+  },
+  "signals": [
+    {
+      "signal_id": "sr_1744628412_a3f7b",
+      "source": "hackernews",
+      "label": "HN: MCP Servers",
+      "content": {
+        "preview": "...",
+        "url": "mcp server 2026"
+      },
+      "intelligence_stamps": {
+        "scraped_at": "2026-04-14T08:12:00Z",
+        "published_at": "2026-04-14",
+        "base_score": 78,
+        "rt_score": 61.4,
+        "entropy_level": "stable",
+        "ha_pri_sig": "a3f7b2c1d4e5f6a7b8c9d0e1f2a3b4c5..."
+      }
+    }
+  ]
+}
+```
+
+### 4.3 LLM Integration
+
+The intelligence feed is designed to be consumed directly by any language model or AI agent without modification. The `intelligence_stamps` block gives the agent everything it needs to reason about data freshness:
+
+- `rt_score` — a single number representing current signal value
+- `entropy_level` — human-readable decay state
+- `published_at` — the actual content date (not the retrieval date)
+- `ha_pri_sig` — provenance reference the agent can cite
+
+This is the core value proposition: **AI agents get grounded, timestamped, scored intelligence rather than undated web content of unknown age.**
+
+---
+
+## Section 5: Asset Summary
+
+For acquirers, investors, and licensing partners:
+
+**What FreshContext owns:**
+
+1. **The FreshContext Specification v1.1** (MIT licence, open standard) — defines the envelope format, confidence levels, and structured JSON form. Timestamped in the public GitHub repository.
+
+2. **The DAR Engine** (proprietary) — the exponential decay scoring methodology with source-specific λ constants. These constants are not published and constitute trade secret IP.
+
+3. **The Semantic Fingerprinting Method** (proprietary) — the three-field normalisation and SHA-256 fingerprinting approach for cross-adapter deduplication.
+
+4. **The Ha-Pri Audit Signature scheme** (proprietary) — the provenance binding method that makes the historical ledger tamper-evident.
+
+5. **The Historical D1 Ledger** (data asset) — the continuously accumulating time-series dataset. As of the date of this document, the ledger has been running since early 2026 with 6-hour collection intervals across 18 watched queries. The dataset grows in defensibility with every passing day.
+
+6. **The Reference Implementation** — `freshcontext-mcp@0.3.15`, listed on the official MCP Registry and npm. Deployed globally on Cloudflare's edge infrastructure.
+
+---
+
+*"The work isn't gone. It's just waiting to be continued."*
+*— Prince Gabriel, Grootfontein, Namibia*

package/README.md

@@ -8,12 +8,15 @@ That's the problem freshcontext fixes.
 
 [![npm version](https://img.shields.io/npm/v/freshcontext-mcp)](https://www.npmjs.com/package/freshcontext-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Listed-blue)](https://registry.modelcontextprotocol.io)
 
 ---
 
-## What it does
+## The Standard
 
-Every MCP server returns data. freshcontext returns data **plus when it was retrieved and how confident that date is** — wrapped in a FreshContext envelope:
+FreshContext is a **data freshness layer for AI agents** — an open standard and reference implementation that makes retrieved data trustworthy.
+
+Every piece of web data an AI agent retrieves has an age. Most tools ignore it. FreshContext surfaces it — wrapping every result in a structured envelope that carries three guarantees:
 
 ```
 [FRESHCONTEXT]
@@ -26,11 +29,13 @@ Confidence: high
 [/FRESHCONTEXT]
 ```
 
-Claude now knows the difference between something from this morning and something from two years ago. You do too.
+**When** it was retrieved. **Where** it came from. **How confident** we are the date is accurate.
+
+The FreshContext Specification v1.1 is published as an open standard under MIT license. Any tool, agent, or system that wraps retrieved data in this envelope is FreshContext-compatible. → [Read the spec](./FRESHCONTEXT_SPEC.md)
 
 ---
 
-## 13 tools. No API keys.
+## 20 tools. No API keys.
 
 ### Intelligence
 | Tool | What it gets you |
@@ -52,22 +57,69 @@ Claude now knows the difference between something from this morning and somethin
 ### Market data
 | Tool | What it gets you |
 |---|---|
-| `extract_finance` | Live stock data — price, market cap, P/E, 52w range |
+| `extract_finance` | Live stock data — price, market cap, P/E, 52w range. Up to 5 tickers. |
+| `search_jobs` | Remote job listings from Remotive, RemoteOK, HN "Who is Hiring" — every listing dated |
+
+### Composites — multiple sources, one call
+| Tool | Sources | What it gets you |
+|---|---|---|
+| `extract_landscape` | 6 | YC + GitHub + HN + Reddit + Product Hunt + npm in parallel |
+| `extract_idea_landscape` | 6 | HN + YC + GitHub + Jobs + npm + Product Hunt — full idea validation |
+| `extract_gov_landscape` | 4 | Gov contracts + HN + GitHub + changelog |
+| `extract_finance_landscape` | 5 | Finance + HN + Reddit + GitHub + changelog |
+| `extract_company_landscape` | 5 | **The full picture on any company** — see below |
+
+### Unique — not available in any other MCP server
+| Tool | Source | What it gets you |
+|---|---|---|
+| `extract_changelog` | GitHub Releases API / npm / auto-discover | Update history from any repo, package, or website |
+| `extract_govcontracts` | USASpending.gov | US federal contract awards — company, amount, agency, period |
+| `extract_sec_filings` | SEC EDGAR | 8-K filings — legally mandated material event disclosures |
+| `extract_gdelt` | GDELT Project | Global news intelligence — 100+ languages, every country, 15-min updates |
+| `extract_gebiz` | data.gov.sg | Singapore Government procurement tenders — open dataset, no auth |
 
-### Composite
-| Tool | What it gets you |
-|---|---|
-| `extract_landscape` | One call. YC + GitHub + HN + Reddit + Product Hunt + npm in parallel. Full timestamped picture. |
+---
 
-### Update intelligence — unique to FreshContext
-| Tool | What it gets you |
-|---|---|
-| `extract_changelog` | Update history from any GitHub repo, npm package, or website. Accepts a GitHub URL (uses the Releases API), an npm package name, or any website URL — auto-discovers `/changelog`, `/releases`, and `CHANGELOG.md`. Returns version numbers, release dates, and entry content, all timestamped. Use this to check if a dependency is still actively maintained, or to find out exactly when a feature shipped before referencing it. |
+## extract_idea_landscape
 
-### Government intelligence — unique to FreshContext
-| Tool | What it gets you |
-|---|---|
-| `extract_govcontracts` | US federal contract awards pulled live from USASpending.gov — the official US Treasury database, updated daily. Search by company name, keyword, or NAICS code. Returns award amounts, awarding agency, period of performance, and contract description, all timestamped. A company that just won a $10M DoD contract is actively hiring and spending — that is a buying intent signal no other MCP server surfaces. |
+Built for the moment before you start building. Six sources fired in parallel to answer: *should I build this?*
+
+1. **Hacker News** — what are developers actively complaining about (pain signal)
+2. **YC Companies** — who has already received funding in this space (funding signal)
+3. **GitHub** — how crowded the open source landscape is (crowding signal)
+4. **Job listings** — companies hiring around this problem = real budget = real market (market signal)
+5. **npm / PyPI** — ecosystem adoption and release velocity (ecosystem signal)
+6. **Product Hunt** — what just launched and how the market received it (launch signal)
+
+```
+Use extract_idea_landscape with idea "data freshness for AI agents"
+```
+
+---
+
+## extract_company_landscape
+
+The most complete single-call company analysis available in any MCP server. Five sources fired in parallel:
+
+1. **SEC EDGAR** — what did they legally just disclose (8-K filings)
+2. **USASpending.gov** — who is giving them government money
+3. **GDELT** — what is global news saying right now
+4. **Changelog** — are they actually shipping product
+5. **Yahoo Finance** — what is the market pricing in
+
+```
+Use extract_company_landscape with company "Palantir" and ticker "PLTR"
+```
+
+Real output from March 2026:
+
+> **Q4 2025:** Revenue $1.407B (+70% YoY). US commercial +137%. Rule of 40 score: **127%**.
+> **Federal contracts:** $292.7M Army Maven Smart System · $252.5M CDAO · $145M ICE · $130M Air Force · more
+> **SEC filing:** Q4 earnings 8-K filed Feb 3, 2026 — GAAP net income $609M, 43% margin
+> **GDELT:** ICE/Medicaid data controversy, UK MoD security warning, NHS opposition — all timestamped
+> **PLTR:** ~$154–157 · Market cap ~$370B · P/E 244x · 52w range $66 → $207
+
+Bloomberg Terminal doesn't read commit history as a company health signal. FreshContext does.
 
 ---
 
@@ -154,35 +206,53 @@ touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
 
 ## Usage examples
 
+**Should I build this idea?**
+```
+Use extract_idea_landscape with idea "procurement intelligence saas"
+```
+Returns funding signal, pain signal, crowding signal, market signal, ecosystem signal, and launch signal — all timestamped.
+
+**Full company intelligence in one call:**
+```
+Use extract_company_landscape with company "Palantir" and ticker "PLTR"
+```
+SEC filings + federal contracts + global news + changelog + market data. The complete picture.
+
 **Is anyone already building what you're building?**
 ```
 Use extract_landscape with topic "cashflow prediction saas"
 ```
 Returns who's funded, what's trending, what repos exist, what packages are moving — all timestamped.
 
-**What's the community actually saying right now?**
+**What's Singapore's government procuring right now?**
 ```
-Use extract_reddit on r/MachineLearning
-Use extract_hackernews to search "mcp server 2026"
+Use extract_gebiz with url "artificial intelligence"
 ```
+Returns live tenders from the Ministry of Finance open dataset — agency, amount, closing date, all timestamped.
 
-**Did that company actually ship recently?**
+**Did that company just disclose something material?**
 ```
-Use extract_github on https://github.com/some-org/some-repo
+Use extract_sec_filings with url "Palantir Technologies"
 ```
-Check `Published` vs `Retrieved`. If the gap is 18 months, Claude will tell you.
+8-K filings are legally mandated within 4 business days of any material event — CEO change, acquisition, breach, major contract.
 
-**Is this dependency still actively maintained?**
+**What is global news saying about a company right now?**
 ```
-Use extract_changelog with url "https://github.com/org/repo"
+Use extract_gdelt with url "Palantir"
 ```
-Returns the last 8 releases with exact dates. If the last release was 18 months ago, you'll know before you pin the version.
+100+ languages, every country, updated every 15 minutes. Surfaces what Western sources miss.
 
-**Which companies just won government contracts in AI?**
+**Which companies just won US government contracts in AI?**
 ```
 Use extract_govcontracts with url "artificial intelligence"
 ```
-Returns the largest recent federal contract awards matching that keyword — company name, amount, agency, and award date. Pure buying intent signal.
+Largest recent federal contract awards matching that keyword — company, amount, agency, award date.
+
+**Is this dependency still actively maintained?**
+```
+Use extract_changelog with url "https://github.com/org/repo"
+```
+Returns the last 8 releases with exact dates. If the last release was 18 months ago, you'll know before you pin the version.
 
 ---
 
@@ -190,14 +260,15 @@ Returns the largest recent federal contract awards matching that keyword — com
 
 Most AI tools retrieve data silently. No timestamp, no signal, no way for the agent to know how old it is.
 
-freshcontext treats **retrieval time as first-class metadata**. Every adapter returns:
+FreshContext treats **retrieval time as first-class metadata**. Every adapter returns:
 
 - `retrieved_at` — exact ISO timestamp of the fetch
 - `content_date` — best estimate of when the content was originally published
 - `freshness_confidence` — `high`, `medium`, or `low` based on signal quality
+- `freshness_score` — numeric 0–100 with domain-specific decay rates (financial data at 5.0, academic papers at 0.3)
 - `adapter` — which source the data came from
 
-When confidence is `high`, the date came from a structured field (API, metadata). When it's `medium` or `low`, freshcontext tells you why.
+When confidence is `high`, the date came from a structured field (API, metadata). When it's `medium` or `low`, FreshContext tells you why.
 
 ---
 
@@ -212,28 +283,111 @@ When confidence is `high`, the date came from a structured field (API, metadata)
 
 ## Roadmap
 
-- [x] GitHub, HN, Scholar, YC, Reddit, Product Hunt, Finance, arXiv adapters
-- [x] `extract_landscape` — 6-source composite tool
-- [x] Cloudflare Workers deployment
-- [x] KV-backed global rate limiting
-- [x] Listed on official MCP Registry
+- [x] 20 tools across intelligence, competitive research, market data, and composites
 - [x] `extract_changelog` — update cadence from any repo, package, or website
 - [x] `extract_govcontracts` — US federal contract intelligence via USASpending.gov
+- [x] `extract_sec_filings` — SEC EDGAR 8-K material event filings
+- [x] `extract_gdelt` — GDELT global news intelligence (100+ languages)
+- [x] `extract_gebiz` — Singapore Government procurement via data.gov.sg
+- [x] `extract_company_landscape` — 5-source company intelligence composite
+- [x] `extract_idea_landscape` — 6-source idea validation composite
+- [x] `freshness_score` numeric metric (0–100) with domain-specific decay rates
+- [x] Cloudflare Workers deployment — global edge with KV caching and rate limiting
+- [x] D1 database — 18 watched queries running on 6-hour cron with relevancy scoring
+- [x] Listed on official MCP Registry
 - [x] Listed on Apify Store
-- [x] FreshContext Specification v1.0 published
-- [ ] TTL-based caching layer
-- [ ] `freshness_score` numeric metric (0–100)
-- [ ] `extract_devto` — developer article sentiment
-- [ ] `extract_npm_releases` — package release velocity
+- [x] FreshContext Specification v1.1 published (MIT) — composite adapters, decay rate table, compatibility levels
+- [x] GitHub Actions CI/CD — auto-publish to npm on every push
+- [x] **DAR engine** — exponential decay scoring with proprietary λ constants (v0.3.15)
+- [x] **Ha-Pri audit signatures** — SHA-256 provenance stamps on every signal
+- [x] **Semantic deduplication** — cross-adapter fingerprinting
+- [x] **Intelligence feed endpoint** — `/v1/intel/feed/:profile_id`
+- [x] **METHODOLOGY.md** — formal IP documentation
+- [ ] Webhook triggers — push high-entropy signals on threshold
+- [ ] Domain-specific watched queries for mining/industrial sector
+- [ ] Subscription tier with profile customization
+- [ ] GKG upgrade for `extract_gdelt` — tone scores, goldstein scale, event codes
+- [ ] Dashboard — React frontend for the D1 intelligence pipeline
 
 ---
 
 ## Contributing
 
-PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern.
+PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern and `FRESHCONTEXT_SPEC.md` for the contract any adapter must fulfill.
+
+If you're building something FreshContext-compatible, open an issue and we'll add you to the ecosystem list.
 
 ---
 
 ## License
 
 MIT
+
+---
+
+*Built by Prince Gabriel — Grootfontein, Namibia 🇳🇦*
+*"The work isn't gone. It's just waiting to be continued."*
+
+---
+
+**Also on:** [Apify Store](https://apify.com/prince_gabriel/freshcontext-mcp) · [MCP Registry](https://registry.modelcontextprotocol.io) · [npm](https://www.npmjs.com/package/freshcontext-mcp)
+
+---
+
+## The Intelligence Layer (v0.3.15)
+
+FreshContext is no longer just a pull tool. The infrastructure now runs a continuous **Decay-Adjusted Relevancy (DAR)** engine that scores every signal with exponential decay and provenance signatures.
+
+### The math
+
+```
+R_t = R_0 · e^(-λt)
+```
+
+- `R_0` — base semantic score against your profile (0–100)
+- `λ` — source-specific decay constant (per hour)
+- `t` — hours since the content was published
+- `R_t` — final relevancy at query time
+
+Source half-lives are calibrated empirically: Hacker News ≈14h, Reddit ≈3d, jobs ≈6d, GitHub ≈5mo, academic papers ≈1.6y.
+
+### What every signal carries
+
+Every row in the D1 ledger is stamped with:
+
+- `base_score` — R_0, semantic match against profile
+- `rt_score` — R_t, decay-adjusted relevancy
+- `entropy_level` — `low` / `stable` / `high` on the decay curve
+- `ha_pri_sig` — SHA-256 provenance signature (tamper-evident)
+- `semantic_fingerprint` — cross-adapter deduplication hash
+- `published_at` — extracted content publication date
+
+### The intelligence feed
+
+```
+GET /v1/intel/feed/:profile_id?limit=20&min_rt=0
+```
+
+Returns scored, deduplicated, provenance-stamped signals ranked by R_t — ready for direct consumption by any LLM or agent. No synthesis needed.
+
+### Methodology
+
+The full data collection, scoring, and provenance methodology is formally documented in [METHODOLOGY.md](./METHODOLOGY.md) — written as an audit trail for acquirers, integrators, and regulators. Version 1.1, April 2026.
+
+---
+
+## Live endpoints
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/` | GET | Service info + endpoint list |
+| `/health` | GET | Liveness check |
+| `/mcp` | POST | MCP JSON-RPC transport |
+| `/briefing` | GET | Latest stored briefing |
+| `/briefing/now` | POST | Force scrape + synthesize |
+| `/v1/intel/feed/:profile_id` | GET | DAR-scored intelligence feed |
+| `/watched-queries` | GET | List all watched queries |
+| `/debug/db` | GET | D1 counts + DAR engine coverage |
+| `/debug/scrape` | GET | Run a single adapter raw |
+
+Production: `https://freshcontext-mcp.gimmanuel73.workers.dev`