writing-context-rtfm 0.5.0__tar.gz

writing_context_rtfm-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    name: Run Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies and run tests
+        run: |
+          uv sync --all-extras --dev
+          uv run pytest
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    # This environment name should match the environment defined in your PyPI trusted publisher config (optional, but recommended)
+    environment: release
+    permissions:
+      # CRITICAL: This permission is required for Trusted Publishing (OIDC) authentication
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

writing_context_rtfm-0.5.0/.gitignore

@@ -0,0 +1,58 @@
+# Environments
+.env
+.venv
+venv/
+env/
+ENV/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+uv.lock
+
+# SQLite / Local Databases
+*.db
+*.sqlite
+*.sqlite3
+
+# OS / IDE
+.DS_Store
+.idea/
+.vscode/
+.gemini/
+
+# Generated outputs
+tests/fixtures/output/
+prompt_a_full.txt
+prompt_b_pack.txt
+result_a.txt
+result_b.txt
+
+# RTFM / Writing Context Cache
+.rtfm/
+.writing-context/context_cache.sqlite
+*.log
+
+# Simulation Sandbox
+sandbox/
+
+# Local configuration and guidelines
+.claude/
+GEMINI.md

writing_context_rtfm-0.5.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.5.0] - 2026-05-22
+
+### Added
+- **Enhanced Project Initialization**: `init` command now auto-configures and updates `.gitignore` to ignore the local database, `.mcp.json` to register the MCP server (auto-detecting `uv`), and guideline files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`) with rules blocks.
+- **Rules Anchoring**: Guidelines are updated non-destructively using comments `<!-- writing-context-rtfm MCP tools -->` to prevent duplication.
+- **Self-Documenting Configuration**: The generated config template is fully commented, explaining how to configure default budgets, reserved margins, and role budget allocations.
+- **Unified Token Budget Tuning**: Spans dropped due to token limit caps calculate and recommend a minimum target budget size to allow LLM client agents to self-correct dynamically.
+
+### Changed
+- **Dynamic Server Versioning**: Server initialization dynamically returns the package version instead of a hardcoded string.
+
+### Fixed
+- **UnboundLocalError in Context Packer**: Corrected variable naming to prevent referencing unbound variables when checking target source spans.
+
+---
+
+## [0.1.0] - 2026-05-20
+
+### Added
+- **Interactive Scaffolding**: Added `initialize_section_cards` tool and CLI subcommand to auto-scan `.tex`/`.md` files and populate `.writing-context/section_cards.yaml`.
+- **Context Pagination**: Added support for progressive retrieval with `request_more_context` and SQLite schema integration (`selected` flag) to load remaining background context spans.
+- **Feedback Loops**: Added evaluation recording using `submit_generation_feedback` to persist metric scores (`helpfulness`, `hallucinations`, `constraint_violated`) into `evaluation_records`.
+- **Terminology Auditing**: Added `audit_manuscript_terminology` tool to cross-examine key terms in section cards against index occurrences and detect undeclared usage or missing definitions.
+- **Native Prompts Integration**: Exposed standard MCP prompt endpoints (`write_section`, `proofread_section`).
+- **Cache Management CLI**: Added subcommands `writing-context-rtfm cache stats` and `writing-context-rtfm cache clear`.
+
+### Changed
+- **Robust Cache Invalidation**: Migrated static caching hashes to SHA-256 content hashes.
+- **Dynamic Fingerprinting**: Replaced the static index fingerprint with a dynamic SHA-256 value computed from the modification time and file size of `.rtfm/library.db`.
+- **Dependency Classification**: Classify retrieved key terms for dependencies under `"dep_key_term"`.
+
+### Fixed
+- **Proofreading Bounds Clamping**: Swapped and clamped invalid line numbers early during proofread context generation.
+- **Path Normalization**: Resolved relative paths to absolute paths before validating file matches.
+- **Search Resilience**: Wrapped terminology searches in try-except blocks.

writing_context_rtfm-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joao Carlos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

writing_context_rtfm-0.5.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: writing-context-rtfm
+Version: 0.5.0
+Summary: MCP extension for writing-context retrieval relying on RTFM
+Author: João Carlos N. Bittencourt
+License: MIT
+License-File: LICENSE
+Keywords: context-reduction,llm-writing,mcp,mcp-server,rtfm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: pylatexenc
+Requires-Dist: pyyaml
+Requires-Dist: rtfm-ai
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: writing-context-rtfm -->
+<div align="center">
+
+***Surgical Context for Writing Agents***
+
+Stop giving your AI agent the entire manuscript to write one section. Give it the exact paragraphs, constraints, and dependencies it needs to succeed. No token bloat. No hallucinations.
+
+**`Lightweight · Task-Focused · Extension · MIT`**
+
+<br>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/) [![MCP](https://img.shields.io/badge/MCP-2026-green.svg)](https://modelcontextprotocol.io/) [![Powered by RTFM](https://img.shields.io/badge/Powered%20by-RTFM-purple.svg)](https://github.com/roomi-fields/rtfm)
+
+</div>
+
+---
+
+<!-- ─────────── TIER 1 — Pain & promise ─────────── -->
+
+Your writing agent is drowning in tokens.
+
+You ask Claude or Cursor to "Write the methodology section." To give it context, you feed it your 50-page manuscript, your related works, and your notes. The agent gets overwhelmed by the global narrative, loses track of the specific hyper-parameters you wanted to include, and writes a generic, repetitive summary that reads like a high-school essay. 
+
+The bottleneck isn't the model's writing ability — it's the **noise**.
+
+**`writing-context-rtfm` fixes the noise.** It is a lightweight MCP extension built on top of `rtfm-ai`. Instead of letting the agent grep freely, it acts as a gatekeeper. It takes the agent's task, queries the underlying RTFM index, aggressively filters out background noise, and packs only the *essential* and *supporting* source chunks into a tight, highly-focused prompt.
+
+```bash
+python3 src/writing_context_rtfm/cli.py pack \
+  --task "Write the methodology section detailing dataset and quantization" \
+  --target section_approach
+```
+
+3 seconds later, the agent receives an 800-token context pack containing exactly the 3 paragraphs about the dataset, the 1 paragraph about quantization, and the stylistic constraints for the section. The agent writes perfectly.
+
+> **Token budgets respected. Constraints enforced. Progressive disclosure over context dumps.**
+
+---
+
+## Installation & MCP Integration
+
+`writing-context-rtfm` functions as an MCP (Model Context Protocol) server. You can run it dynamically using `uvx` (recommended) or install it globally on your system.
+
+### Option A: Dynamic Run (Recommended)
+You do not need to install the package manually. You can prefix commands with `uvx` (or `npx` equivalent) to run the server on demand.
+
+### Option B: Global Installation
+If you prefer a static global installation:
+
+```bash
+# Using uv
+uv tool install writing-context-rtfm
+
+# Using pipx
+pipx install writing-context-rtfm
+```
+
+Once installed, use `writing-context-rtfm serve` as the server command instead of `uvx writing-context-rtfm serve`.
+
+---
+
+### 1. Claude Desktop
+Add this to your `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "writing-context-rtfm": {
+      "command": "uvx",
+      "args": [
+        "writing-context-rtfm",
+        "serve"
+      ]
+    }
+  }
+}
+```
+
+### 2. Cursor IDE
+1. Open Cursor Settings (`Cmd + ,`).
+2. Navigate to **Features** > **MCP** and click **+ Add New MCP Server**.
+3. **Name:** `writing-context-rtfm`
+4. **Type:** `command`
+5. **Command:** `uvx writing-context-rtfm serve`
+
+### 3. VS Code Extensions (Cline, Roo Code)
+Update your MCP settings file (e.g., `cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "writing-context-rtfm": {
+      "command": "uvx",
+      "args": [
+        "writing-context-rtfm",
+        "serve"
+      ]
+    }
+  }
+}
+```
+
+### 4. Claude Code (Anthropic CLI Agent)
+You can configure the server globally for Claude Code using:
+
+```bash
+claude mcp add --scope user --transport stdio writing-context-rtfm -- uvx writing-context-rtfm serve
+```
+
+Or for a specific project/repository:
+
+```bash
+claude mcp add --scope local --transport stdio writing-context-rtfm -- uvx writing-context-rtfm serve
+```
+
+### 5. Codex (CLI & Desktop)
+To add the server using the Codex CLI:
+
+```bash
+codex mcp add writing-context-rtfm -- uvx writing-context-rtfm serve
+```
+
+Alternatively, you can manually append it to your Codex configuration file (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.writing-context-rtfm]
+command = "uvx"
+args = ["writing-context-rtfm", "serve"]
+enabled = true
+```
+
+*(If testing locally before publishing, you can use `uvx --from /absolute/path/to/writing-context-rtfm writing-context-rtfm serve` or `uv run python -m writing_context_rtfm.cli serve` instead).*
+
+---
+
+<!-- ─────────── TIER 2 — Positioning & buzz ─────────── -->
+
+## The Core Philosophy: RTFM Retrieves, We Pack
+
+| **Tool** | **Role** | **Action** | **Output** |
+|----------|----------|------------|------------|
+| `rtfm-ai` | The Retrieval Layer | Indexes everything, runs FTS/Semantic search, returns raw hits. | 25 raw chunks |
+| `writing-context-rtfm` | The Curation Layer | Filters noise, applies constraints, ranks by structural priority. | 4 essential chunks |
+
+We do **not** replace or fork RTFM. We wrap it. RTFM is built to fetch memory. `writing-context-rtfm` is built to decide *what is enough memory to write a specific section*. 
+
+---
+
+## The Section Cards Pattern
+Writing agents need rules. We enforce them using a `.writing-context/section_cards.yaml` file. 
+
+```yaml
+version: 1
+document:
+  title: "TinyML Fault Detection"
+sections:
+  section_approach:
+    title: "Proposed approach"
+    path: "sections/03_approach.tex"
+    key_terms: ["CNN", "quantization"]
+    must_preserve:
+      - "The train-test split is fixed and reproducible."
+    avoid:
+      - "real-time deployment claims"
+```
+
+When the agent asks for context to write `section_approach`, we:
+1. **Expand the query**: We don't just search the agent's prompt. We search the section title and key terms.
+2. **Post-filter Avoids**: If an RTFM result matches an `avoid` term, it is instantly discarded.
+3. **Inject Constraints**: The returned context pack explicitly feeds the `must_preserve` rules directly to the LLM.
+
+> [!IMPORTANT]
+> **Modular documents are required.** This extension's noise-reduction algorithms heavily rely on the `path` defined in your section cards to perform "Target Boosts" and semantic scoping. If your entire manuscript is just a single monolithic `main.tex` or `main.md` file, the packer won't be able to distinguish the target section from background noise. Keep your writing modular (e.g., `sections/01_intro.tex`, `sections/02_methodology.tex`) for optimal results.
+
+---
+
+## What we measured: A/B Testing
+
+We tested a Gemini 2.5 agent trying to write a methodology section using two context strategies:
+
+| Strategy | Context Size | Result Quality |
+|----------|--------------|----------------|
+| **Agent A (Full Repo Context)** | 3,000+ tokens | Wrote a generic paper summary. Hallucinated an introduction. Skipped hyperparameters entirely because it lost focus. |
+| **Agent B (MCP Context Pack)** | **~600 tokens** | Jumped straight to the methodology. Correctly documented the CNN architecture, Adam optimizer, and learning rates. Followed all constraints. |
+
+When you restrict an agent's vision to exactly what matters, its writing becomes sharper, more structured, and deeply accurate.
+
+---
+
+<!-- ─────────── TIER 3 — Technical depth ─────────── -->
+
+### Intelligent Scoring & Priority
+Raw search scores aren't enough for structural writing. We combine semantic relevance with manuscript structure:
+- **RTFM Score**: Baseline semantic/FTS relevance.
+- **Target Boost**: Chunks coming from the file the agent is supposed to be writing (`03_approach.tex`) get an automatic +0.8 boost.
+- **Key-Term Scoping**: If a chunk matches a key term (e.g., "CNN") but comes from the *Conclusion* file, it receives a severe 75% score penalty to prevent background noise from polluting the context.
+
+Chunks are finally classified as `[Priority: essential]`, `supporting`, or `background` so the LLM knows what to focus on.
+
+### CLI Reference
+```bash
+# Initialize project config and SQLite cache
+writing-context-rtfm init
+writing-context-rtfm init-db
+
+# Sync the underlying RTFM index
+writing-context-rtfm sync --corpus manuscript
+
+# Generate a context pack directly in the terminal
+writing-context-rtfm pack \
+  --task "Update the introduction" \
+  --target section_intro \
+  --budget 4000
+
+# Start MCP Server
+writing-context-rtfm serve
+```
+
+---
+
+## Where this fits
+
+```
+┌─────────────────────────────────┐
+│       AI Agent / LLM Client     │  ← Execution (Cursor, Claude)
+├─────────────────────────────────┤
+│     writing-context-rtfm        │  ← Curation (Packs, Filters, Rules)
+├─────────────────────────────────┤
+│           rtfm-ai               │  ← Retrieval (Index, FTS, Semantic)
+└─────────────────────────────────┘
+```
+
+Without the context packer, your agent retrieves 50 documents and hopes for the best. With it, the agent receives a surgically precise, prioritized briefing.
+
+## License
+[MIT License](LICENSE) — use it, fork it, extend it.

writing_context_rtfm-0.5.0/README.md

@@ -0,0 +1,236 @@
+<!-- mcp-name: writing-context-rtfm -->
+<div align="center">
+
+***Surgical Context for Writing Agents***
+
+Stop giving your AI agent the entire manuscript to write one section. Give it the exact paragraphs, constraints, and dependencies it needs to succeed. No token bloat. No hallucinations.
+
+**`Lightweight · Task-Focused · Extension · MIT`**
+
+<br>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/) [![MCP](https://img.shields.io/badge/MCP-2026-green.svg)](https://modelcontextprotocol.io/) [![Powered by RTFM](https://img.shields.io/badge/Powered%20by-RTFM-purple.svg)](https://github.com/roomi-fields/rtfm)
+
+</div>
+
+---
+
+<!-- ─────────── TIER 1 — Pain & promise ─────────── -->
+
+Your writing agent is drowning in tokens.
+
+You ask Claude or Cursor to "Write the methodology section." To give it context, you feed it your 50-page manuscript, your related works, and your notes. The agent gets overwhelmed by the global narrative, loses track of the specific hyper-parameters you wanted to include, and writes a generic, repetitive summary that reads like a high-school essay. 
+
+The bottleneck isn't the model's writing ability — it's the **noise**.
+
+**`writing-context-rtfm` fixes the noise.** It is a lightweight MCP extension built on top of `rtfm-ai`. Instead of letting the agent grep freely, it acts as a gatekeeper. It takes the agent's task, queries the underlying RTFM index, aggressively filters out background noise, and packs only the *essential* and *supporting* source chunks into a tight, highly-focused prompt.
+
+```bash
+python3 src/writing_context_rtfm/cli.py pack \
+  --task "Write the methodology section detailing dataset and quantization" \
+  --target section_approach
+```
+
+3 seconds later, the agent receives an 800-token context pack containing exactly the 3 paragraphs about the dataset, the 1 paragraph about quantization, and the stylistic constraints for the section. The agent writes perfectly.
+
+> **Token budgets respected. Constraints enforced. Progressive disclosure over context dumps.**
+
+---
+
+## Installation & MCP Integration
+
+`writing-context-rtfm` functions as an MCP (Model Context Protocol) server. You can run it dynamically using `uvx` (recommended) or install it globally on your system.
+
+### Option A: Dynamic Run (Recommended)
+You do not need to install the package manually. You can prefix commands with `uvx` (or `npx` equivalent) to run the server on demand.
+
+### Option B: Global Installation
+If you prefer a static global installation:
+
+```bash
+# Using uv
+uv tool install writing-context-rtfm
+
+# Using pipx
+pipx install writing-context-rtfm
+```
+
+Once installed, use `writing-context-rtfm serve` as the server command instead of `uvx writing-context-rtfm serve`.
+
+---
+
+### 1. Claude Desktop
+Add this to your `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "writing-context-rtfm": {
+      "command": "uvx",
+      "args": [
+        "writing-context-rtfm",
+        "serve"
+      ]
+    }
+  }
+}
+```
+
+### 2. Cursor IDE
+1. Open Cursor Settings (`Cmd + ,`).
+2. Navigate to **Features** > **MCP** and click **+ Add New MCP Server**.
+3. **Name:** `writing-context-rtfm`
+4. **Type:** `command`
+5. **Command:** `uvx writing-context-rtfm serve`
+
+### 3. VS Code Extensions (Cline, Roo Code)
+Update your MCP settings file (e.g., `cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "writing-context-rtfm": {
+      "command": "uvx",
+      "args": [
+        "writing-context-rtfm",
+        "serve"
+      ]
+    }
+  }
+}
+```
+
+### 4. Claude Code (Anthropic CLI Agent)
+You can configure the server globally for Claude Code using:
+
+```bash
+claude mcp add --scope user --transport stdio writing-context-rtfm -- uvx writing-context-rtfm serve
+```
+
+Or for a specific project/repository:
+
+```bash
+claude mcp add --scope local --transport stdio writing-context-rtfm -- uvx writing-context-rtfm serve
+```
+
+### 5. Codex (CLI & Desktop)
+To add the server using the Codex CLI:
+
+```bash
+codex mcp add writing-context-rtfm -- uvx writing-context-rtfm serve
+```
+
+Alternatively, you can manually append it to your Codex configuration file (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.writing-context-rtfm]
+command = "uvx"
+args = ["writing-context-rtfm", "serve"]
+enabled = true
+```
+
+*(If testing locally before publishing, you can use `uvx --from /absolute/path/to/writing-context-rtfm writing-context-rtfm serve` or `uv run python -m writing_context_rtfm.cli serve` instead).*
+
+---
+
+<!-- ─────────── TIER 2 — Positioning & buzz ─────────── -->
+
+## The Core Philosophy: RTFM Retrieves, We Pack
+
+| **Tool** | **Role** | **Action** | **Output** |
+|----------|----------|------------|------------|
+| `rtfm-ai` | The Retrieval Layer | Indexes everything, runs FTS/Semantic search, returns raw hits. | 25 raw chunks |
+| `writing-context-rtfm` | The Curation Layer | Filters noise, applies constraints, ranks by structural priority. | 4 essential chunks |
+
+We do **not** replace or fork RTFM. We wrap it. RTFM is built to fetch memory. `writing-context-rtfm` is built to decide *what is enough memory to write a specific section*. 
+
+---
+
+## The Section Cards Pattern
+Writing agents need rules. We enforce them using a `.writing-context/section_cards.yaml` file. 
+
+```yaml
+version: 1
+document:
+  title: "TinyML Fault Detection"
+sections:
+  section_approach:
+    title: "Proposed approach"
+    path: "sections/03_approach.tex"
+    key_terms: ["CNN", "quantization"]
+    must_preserve:
+      - "The train-test split is fixed and reproducible."
+    avoid:
+      - "real-time deployment claims"
+```
+
+When the agent asks for context to write `section_approach`, we:
+1. **Expand the query**: We don't just search the agent's prompt. We search the section title and key terms.
+2. **Post-filter Avoids**: If an RTFM result matches an `avoid` term, it is instantly discarded.
+3. **Inject Constraints**: The returned context pack explicitly feeds the `must_preserve` rules directly to the LLM.
+
+> [!IMPORTANT]
+> **Modular documents are required.** This extension's noise-reduction algorithms heavily rely on the `path` defined in your section cards to perform "Target Boosts" and semantic scoping. If your entire manuscript is just a single monolithic `main.tex` or `main.md` file, the packer won't be able to distinguish the target section from background noise. Keep your writing modular (e.g., `sections/01_intro.tex`, `sections/02_methodology.tex`) for optimal results.
+
+---
+
+## What we measured: A/B Testing
+
+We tested a Gemini 2.5 agent trying to write a methodology section using two context strategies:
+
+| Strategy | Context Size | Result Quality |
+|----------|--------------|----------------|
+| **Agent A (Full Repo Context)** | 3,000+ tokens | Wrote a generic paper summary. Hallucinated an introduction. Skipped hyperparameters entirely because it lost focus. |
+| **Agent B (MCP Context Pack)** | **~600 tokens** | Jumped straight to the methodology. Correctly documented the CNN architecture, Adam optimizer, and learning rates. Followed all constraints. |
+
+When you restrict an agent's vision to exactly what matters, its writing becomes sharper, more structured, and deeply accurate.
+
+---
+
+<!-- ─────────── TIER 3 — Technical depth ─────────── -->
+
+### Intelligent Scoring & Priority
+Raw search scores aren't enough for structural writing. We combine semantic relevance with manuscript structure:
+- **RTFM Score**: Baseline semantic/FTS relevance.
+- **Target Boost**: Chunks coming from the file the agent is supposed to be writing (`03_approach.tex`) get an automatic +0.8 boost.
+- **Key-Term Scoping**: If a chunk matches a key term (e.g., "CNN") but comes from the *Conclusion* file, it receives a severe 75% score penalty to prevent background noise from polluting the context.
+
+Chunks are finally classified as `[Priority: essential]`, `supporting`, or `background` so the LLM knows what to focus on.
+
+### CLI Reference
+```bash
+# Initialize project config and SQLite cache
+writing-context-rtfm init
+writing-context-rtfm init-db
+
+# Sync the underlying RTFM index
+writing-context-rtfm sync --corpus manuscript
+
+# Generate a context pack directly in the terminal
+writing-context-rtfm pack \
+  --task "Update the introduction" \
+  --target section_intro \
+  --budget 4000
+
+# Start MCP Server
+writing-context-rtfm serve
+```
+
+---
+
+## Where this fits
+
+```
+┌─────────────────────────────────┐
+│       AI Agent / LLM Client     │  ← Execution (Cursor, Claude)
+├─────────────────────────────────┤
+│     writing-context-rtfm        │  ← Curation (Packs, Filters, Rules)
+├─────────────────────────────────┤
+│           rtfm-ai               │  ← Retrieval (Index, FTS, Semantic)
+└─────────────────────────────────┘
+```
+
+Without the context packer, your agent retrieves 50 documents and hopes for the best. With it, the agent receives a surgically precise, prioritized briefing.
+
+## License
+[MIT License](LICENSE) — use it, fork it, extend it.