diff --git a/.agents/skills/quantmind-dev/SKILL.md b/.agents/skills/quantmind-dev/SKILL.md
index 9e01dfc..50391fa 100644
--- a/.agents/skills/quantmind-dev/SKILL.md
+++ b/.agents/skills/quantmind-dev/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: quantmind-dev
-description: Contributor workflow for the QuantMind codebase. Covers commit format, pull request format, and component development across quantmind/ modules (knowledge, configs, preprocess, rag, flows, mind, utils) with tests, examples, and verification. Use when committing, opening a PR, or implementing/refactoring QuantMind code.
+description: Contributor workflow for the QuantMind codebase. Covers contributor setup (environment + hooks), filing issues, commit format, pull request format, and component development across quantmind/ modules (knowledge, configs, preprocess, rag, flows, mind, utils) with tests, examples, and verification. Use when setting up as a contributor, filing an issue, committing, opening a PR, or implementing/refactoring QuantMind code.
 ---
 
 # QuantMind Dev
@@ -24,6 +24,10 @@ Development workflow for contributing to the QuantMind codebase.
 
 ## Select Workflow
 
+- Setting up as a contributor (environment, hooks, first verify) →
+  `references/setup.md`
+- Filing an issue for a bug or a missing capability →
+  `references/setup.md` ("File an Issue" section)
 - Committing staged work → `references/commit.md`
 - Opening or updating a pull request → `references/pull-request.md`
 - Implementing or refactoring anything under `quantmind/` →
diff --git a/.agents/skills/quantmind-dev/references/setup.md b/.agents/skills/quantmind-dev/references/setup.md
new file mode 100644
index 0000000..e4130de
--- /dev/null
+++ b/.agents/skills/quantmind-dev/references/setup.md
@@ -0,0 +1,69 @@
+# Contributor Setup and Issue Filing
+
+How to set a working copy up for contribution, and how to file an issue.
+Human-readable equivalent: root `CONTRIBUTING.md` (same steps, same order).
+
+## Set Up as a Contributor
+
+1. Get a working copy. External contributors fork on GitHub and clone the
+   fork; maintainers branch directly off `master`:
+
+   ```bash
+   git clone https://github.com/<you>/quant-mind.git && cd quant-mind
+   git checkout -b <type>/<short-topic>   # e.g. feat/sec-collection
+   ```
+
+2. Create the environment with [uv](https://github.com/astral-sh/uv):
+
+   ```bash
+   uv venv && source .venv/bin/activate
+   uv pip install -e ".[dev]"
+   ```
+
+3. Install the git hooks (pre-commit lint/format stage plus the pre-push
+   verify stage):
+
+   ```bash
+   ./scripts/pre-commit-setup.sh
+   ```
+
+4. Confirm the checkout is green before changing anything:
+
+   ```bash
+   bash scripts/verify.sh
+   ```
+
+   Verify is the single deterministic gate — format, lint, types, import
+   boundaries, tests with coverage. CI runs the exact same script, so a green
+   local run means a green PR. If it fails on a fresh checkout, stop and report
+   that instead of working around it.
+
+5. Continue with the workflow references: `develop-components.md` before
+   writing code, then `commit.md` and `pull-request.md`.
+
+## File an Issue
+
+1. Requires an authenticated GitHub CLI (`gh auth status`; if missing, ask the
+   user to run `gh auth login` themselves).
+2. Pick the shape that matches the request:
+   - Defect in existing behavior → `.github/ISSUE_TEMPLATE/bug_report.md`
+   - Missing source, knowledge type, flow, or capability →
+     `.github/ISSUE_TEMPLATE/feature_request.md`
+3. Write the body in English following `contexts/dev/github-writing.md`
+   (no hard-wrapping), and apply labels per `contexts/dev/labels.md`.
+4. Search for duplicates first (`gh issue list --search "<keywords>"`), then:
+
+   ```bash
+   gh issue create --title "<imperative summary>" --body-file <tmpfile> \
+     --label "<label>"
+   ```
+
+5. If the need came out of work in progress, link the issue from the related
+   branch or PR so the discussion has code context.
+
+## Boundaries
+
+- Setup here targets contributing to QuantMind itself. Library-only users can
+  stop after `uv pip install -e .` and do not need hooks.
+- Do not file issues that encode product decisions as settled; state the need
+  and let maintainer discussion pick the design (see SKILL.md Boundaries).
diff --git a/.claude/skills/quantmind-dev/SKILL.md b/.claude/skills/quantmind-dev/SKILL.md
index 9e01dfc..50391fa 100644
--- a/.claude/skills/quantmind-dev/SKILL.md
+++ b/.claude/skills/quantmind-dev/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: quantmind-dev
-description: Contributor workflow for the QuantMind codebase. Covers commit format, pull request format, and component development across quantmind/ modules (knowledge, configs, preprocess, rag, flows, mind, utils) with tests, examples, and verification. Use when committing, opening a PR, or implementing/refactoring QuantMind code.
+description: Contributor workflow for the QuantMind codebase. Covers contributor setup (environment + hooks), filing issues, commit format, pull request format, and component development across quantmind/ modules (knowledge, configs, preprocess, rag, flows, mind, utils) with tests, examples, and verification. Use when setting up as a contributor, filing an issue, committing, opening a PR, or implementing/refactoring QuantMind code.
 ---
 
 # QuantMind Dev
@@ -24,6 +24,10 @@ Development workflow for contributing to the QuantMind codebase.
 
 ## Select Workflow
 
+- Setting up as a contributor (environment, hooks, first verify) →
+  `references/setup.md`
+- Filing an issue for a bug or a missing capability →
+  `references/setup.md` ("File an Issue" section)
 - Committing staged work → `references/commit.md`
 - Opening or updating a pull request → `references/pull-request.md`
 - Implementing or refactoring anything under `quantmind/` →
diff --git a/.claude/skills/quantmind-dev/references/setup.md b/.claude/skills/quantmind-dev/references/setup.md
new file mode 100644
index 0000000..e4130de
--- /dev/null
+++ b/.claude/skills/quantmind-dev/references/setup.md
@@ -0,0 +1,69 @@
+# Contributor Setup and Issue Filing
+
+How to set a working copy up for contribution, and how to file an issue.
+Human-readable equivalent: root `CONTRIBUTING.md` (same steps, same order).
+
+## Set Up as a Contributor
+
+1. Get a working copy. External contributors fork on GitHub and clone the
+   fork; maintainers branch directly off `master`:
+
+   ```bash
+   git clone https://github.com/<you>/quant-mind.git && cd quant-mind
+   git checkout -b <type>/<short-topic>   # e.g. feat/sec-collection
+   ```
+
+2. Create the environment with [uv](https://github.com/astral-sh/uv):
+
+   ```bash
+   uv venv && source .venv/bin/activate
+   uv pip install -e ".[dev]"
+   ```
+
+3. Install the git hooks (pre-commit lint/format stage plus the pre-push
+   verify stage):
+
+   ```bash
+   ./scripts/pre-commit-setup.sh
+   ```
+
+4. Confirm the checkout is green before changing anything:
+
+   ```bash
+   bash scripts/verify.sh
+   ```
+
+   Verify is the single deterministic gate — format, lint, types, import
+   boundaries, tests with coverage. CI runs the exact same script, so a green
+   local run means a green PR. If it fails on a fresh checkout, stop and report
+   that instead of working around it.
+
+5. Continue with the workflow references: `develop-components.md` before
+   writing code, then `commit.md` and `pull-request.md`.
+
+## File an Issue
+
+1. Requires an authenticated GitHub CLI (`gh auth status`; if missing, ask the
+   user to run `gh auth login` themselves).
+2. Pick the shape that matches the request:
+   - Defect in existing behavior → `.github/ISSUE_TEMPLATE/bug_report.md`
+   - Missing source, knowledge type, flow, or capability →
+     `.github/ISSUE_TEMPLATE/feature_request.md`
+3. Write the body in English following `contexts/dev/github-writing.md`
+   (no hard-wrapping), and apply labels per `contexts/dev/labels.md`.
+4. Search for duplicates first (`gh issue list --search "<keywords>"`), then:
+
+   ```bash
+   gh issue create --title "<imperative summary>" --body-file <tmpfile> \
+     --label "<label>"
+   ```
+
+5. If the need came out of work in progress, link the issue from the related
+   branch or PR so the discussion has code context.
+
+## Boundaries
+
+- Setup here targets contributing to QuantMind itself. Library-only users can
+  stop after `uv pip install -e .` and do not need hooks.
+- Do not file issues that encode product decisions as settled; state the need
+  and let maintainer discussion pick the design (see SKILL.md Boundaries).
diff --git a/AGENTS.md b/AGENTS.md
index e940329..accb431 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,18 @@ finance, built **on top of** the OpenAI Agents SDK. It is a domain library,
 not an agent framework: runtime, tracing, tool scaffolding, and multi-agent
 handoff all come from `openai-agents`.
 
+## Positioning
+
+QuantMind is an **agent-native workbench for financial knowledge extraction** —
+its primary consumer is a coding agent working inside this checkout, not only a
+human importing a package (workbench-first, library-second). Two engineering
+dimensions structure it: **context engineering** (any source → typed, cited,
+as-of-correct knowledge) and **harness engineering** (any agent → domain
+specialist, via this repo's contracts, `contexts/`, skills, hooks, and
+deterministic verify).
+The canonical, always-current statement lives in
+[`contexts/design/positioning.md`](contexts/design/positioning.md).
+
 ## Module Map
 
 | Module | Role |
diff --git a/README.md b/README.md
index 7e72749..3fc8e7d 100644
--- a/README.md
+++ b/README.md
@@ -19,144 +19,108 @@
   </a>
 </p>
 <p align="center">
-  <a href="#-why-quantmind">Why QuantMind</a> •
-  <a href="#system-architecture">Architecture</a> •
+  <a href="#-knowledge-engineering">Knowledge Engineering</a> •
+  <a href="#-the-vision">The Vision</a> •
   <a href="#-quick-start">Quick Start</a> •
-  <a href="#-usage-examples">Usage</a> •
+  <a href="#-evaluation-in-design">Evaluation</a> •
+  <a href="#-in-production-llmquant-data">In Production</a> •
   <a href="#%EF%B8%8F-roadmap">Roadmap</a> •
-  <a href="#the-vision-an-intelligent-research-agent">Vision</a> •
   <a href="#-contributing">Contributing</a>
 </p>
 
----
 
-**QuantMind** is an intelligent knowledge extraction and retrieval framework for quantitative finance. It transforms unstructured financial content—papers, news, blogs, reports—into a queryable knowledge base, enabling AI-powered research at scale.
+QuantMind is an information processor for quantitative finance: it refines raw financial information — papers, news, filings — into structured financial knowledge that downstream retrieval and reasoning can trust. Every piece of knowledge is typed, keeps its citation, and knows its timestamp, so it persists and time-queries standalone.
+
+The people who build these refinement flows are increasingly agents — coding agents, with humans behind them. So the repository is designed agent-oriented: you open the checkout, describe the pipeline you want, and an agent builds it here against the repo's contracts, skills, and deterministic verification. It is also a perfectly good importable Python library.
 
 ### 📰 News
 | 🗞️ News        | 📝 Description                                                                 |
 |----------------|-------------------------------------------------------------------------------|
+| 🛠️ 2026-07 | Rebuilding the repo **agent-native** — contexts, skills, hooks — so a coding agent can do QuantMind-quality work inside the checkout. |
 | 🎉 Accepted at NeurIPS 2025 Workshop | Our paper **[Quant-Mind](#)** has been accepted to the **[NeurIPS 2025 GenAI in Finance Workshop](https://sites.google.com/view/neurips-25-gen-ai-in-finance/home)** !🚀 |
 | 📢 First Release on GitHub  | **Quant-Mind** is now live on GitHub — please check it out and join us! 🤗 |
 
-### 🧐 Overview
-
-QuantMind is a next-generation AI platform that ingests, processes, and structures **every** new piece of quantitative-finance research, including papers, news, blogs, and SEC filings into a **semantic knowledge graph**. Institutional investors, hedge funds, and research teams can now explore the frontier of factor strategies, risk models, and market insights in **seconds**, unlocking alpha that would otherwise remain buried.
-
-### ✨ Why QuantMind?
-
-The financial research landscape is overwhelming. Every day, hundreds of papers, articles, and reports are published.
-
-#### 🌐 The Opportunity
 
-- **Information Overload**: 500 new research papers & reports published daily. Manual review takes weeks—costly, error-prone, and non-scalable
-- **Massive Market**: Financial data & analytics market ≫ expected to grow to US$961.89 billion by 2032, with a compound annual growth rate of 13.5%. Tens of thousands of quant teams & asset managers hungry for speed
-- **High ROI**: 1% improvement in research efficiency can translate to millions saved or earned in trading performance
+### 🧩 Knowledge Engineering
 
----
+**Any source → typed knowledge.**
 
-#### 💡 **QuantMind** solves this by
+<p align="center"><img src="assets/v1-context-engineering.png" width="920" alt="any source through preprocess and flows into typed knowledge and applications"></p>
 
-- 🔍 **Extracting** structured knowledge from any source (PDFs, web pages, APIs)
-- 🧠 **Understanding** content with domain-specific LLMs fine-tuned for finance
-- 💾 **Storing** information in a semantic knowledge graph
-- 🚀 **Retrieving** insights through natural language queries
+*The target surface — shipping today: `PaperFlow` · `collect_news`; see Roadmap.*
 
----
+- **Deterministic preprocess** — `fetch` / parse / `format` + `clean` produce source-faithful values with no model in the loop, so provenance is exact and replayable.
+- **Config-driven operations** — `PaperFlow(cfg).build(input)` binds an immutable build config once and applies it per input; `collect_news` collects a replayable source window; `batch_run` fans any operation across a list of inputs. You never write `asyncio.gather` boilerplate.
+- **Typed knowledge shapes** — a `Paper` structure tree for whole documents, and flat cards for `News` / `Earnings` / `Factor` / `Thesis`. Every artifact is self-contained: it carries its own text, an `as_of` timestamp, and a light source ref, so it persists and time-queries standalone.
+- **Retrieval over that knowledge** — `rag/` (chunking + BM25 / similarity), `library/` (local persistence + meaning-based search), and `mind/` (agentic, reasoning-based retrieval). Together they serve RAG and Agentic RAG, deep research, and data-MCP serving.
 
-### System Architecture
+This is the substance shipped as the NeurIPS 2025 GenAI-in-Finance workshop paper (**arXiv:2509.21507**). The always-current statement lives in [`contexts/design/positioning.md`](contexts/design/positioning.md).
 
-![quantmind-outline](assets/quantmind-stage-outline.png)
+### 🧠 The Vision
 
-QuantMind is built on a decoupled, two-stage architecture. This design separates the concerns of data ingestion from intelligent retrieval, ensuring both robustness and flexibility.
+**Harness engineering — any agent → domain specialist.**
 
-#### **Stage 1: Knowledge Extraction**
+<p align="center"><img src="assets/v2-harness-engineering.png" width="920" alt="the quant-mind harness: context layer, code layer, workspace, deterministic verify, deliverables"></p>
 
-This layer is responsible for collecting, parsing, and structuring raw information into standardized knowledge units.
+> **Don't import it. Open it.**
 
-```text
-Source APIs (arXiv, News, Blogs) → Intelligent Parser → Workflow/Agent → Structured Knowledge Base
-```
-
-- **Source**: Connects to various sources (academic APIs, news feeds, financial blogs, perplexity search source) to pull content
-- **Parser**: Extracts text, tables, and figures from PDFs, HTML, and other formats
-- **Tagger**: Automatically categorizes content into research areas and topics
-- **Workflow/Agent**: Orchestrates the extraction pipeline with quality control and deduplication
+The repository itself is the product surface — we call this **harness engineering**. Its `AGENTS.md` / `CLAUDE.md` contracts, progressive-disclosure `contexts/`, portable skills, and Claude + Codex hooks, all gated by a deterministic verify, upgrade a general coding agent into one that reliably does QuantMind-quality work. The bet: **a weak model in a good harness beats a strong model running bare.**
 
-#### **Stage 2: Intelligent Retrieval**
+- **Repo-level contracts** — `AGENTS.md` / `CLAUDE.md` state the always-on rules once, in one source, for every agent that opens the repo.
+- **Progressive-disclosure `contexts/`** — agent-facing pages with a Quick Summary / Contents preview, so an agent loads only the one page a task needs.
+- **Portable skills** — `quantmind-dev` ships today (contributor setup / commit / PR / component workflow), mirrored for Claude and Codex.
+- **Claude + Codex hooks** — shared hook scripts give both agents identical hard guarantees without maintaining two copies of a rule.
+- **Deterministic verify** — `scripts/verify.sh` runs lint + types + import boundaries + tests, fast-failing in a fixed order; CI runs the exact same script.
 
-This layer transforms structured knowledge into actionable insights through various retrieval mechanisms.
+See [`contexts/dev/harness-engineering.md`](contexts/dev/harness-engineering.md) for the enforcement mechanics.
 
-```
-Knowledge Base → Embeddings → Solution Scenarios (DeepResearch, RAG, Data MCP, ...)
-```
-
-- **Embedding Generation**: Converts knowledge units into high-dimensional vectors for semantic search
-
-- Solution Scenarios: Multiple retrieval patterns including:
-
-  - **DeepResearch**: Complex multi-hop reasoning across documents
-  - **RAG**: Retrieval-augmented generation for Q&A
-  - **Data MCP**: Structured data access protocols
-  - Custom retrieval patterns based on use case
-
----
 
 ### 🚀 Quick Start
 
-We use [uv](https://github.com/astral-sh/uv) for fast and reliable Python package management.
-
-**Prerequisites:**
+#### The agent path (recommended)
 
-- Python 3.8+
-- Git
+QuantMind is meant to be opened, not imported. Point a coding agent at the checkout and describe the pipeline you want:
 
-**Installation:**
-
-1. **Install uv (if not already installed):**
+```bash
+git clone https://github.com/LLMQuant/quant-mind.git
+cd quant-mind && claude      # or: codex
+```
 
-   ```bash
-   # On macOS and Linux
-   curl -LsSf https://astral.sh/uv/install.sh | sh
+Then, in the agent session:
 
-   # On Windows
-   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+> "Build me a source-first paper artifact for arXiv 1706.03762, then persist it and search the summary."
 
-   # Or using pip
-   pip install uv
-   ```
+The agent reads the repo's contracts (`AGENTS.md`), loads the relevant `contexts/` pages, writes the pipeline, and runs `scripts/verify.sh` before it hands the change back.
 
-2. **Clone the repository:**
+#### The library path
 
-   ```bash
-   git clone https://github.com/LLMQuant/quant-mind.git
-   cd quant-mind
-   ```
+QuantMind is still a normal Python package. We use [uv](https://github.com/astral-sh/uv) for package management.
 
-3. **Create and activate virtual environment:**
+```bash
+uv venv && source .venv/bin/activate
+uv pip install -e .
+```
 
-   ```bash
-   # Create a virtual environment
-   uv venv
+`PaperFlow` refines one arXiv PDF into a self-contained paper artifact. The cfg **type** selects the knowledge shape (`PaperStructureCfg` → `PaperStructureTree`, `PaperSemanticCfg` → `PaperSemanticResult`). Bind a `PaperStructureCfg` to build a source-native **structure tree** — a hierarchy of page-cited nodes:
 
-   # Activate it
-   # On macOS/Linux:
-   source .venv/bin/activate
+```python
+import asyncio
 
-   # On Windows:
-   .venv\Scripts\activate
-   ```
+from quantmind.configs import PaperStructureCfg
+from quantmind.configs.paper import ArxivIdentifier
+from quantmind.flows import PaperFlow
 
-4. **Install dependencies:**
 
-   ```bash
-   uv pip install -e .
-   ```
+async def main() -> None:
+    flow = PaperFlow(PaperStructureCfg(model="gpt-5.6-luna"))
+    tree = await flow.build(ArxivIdentifier(id="1706.03762v7"))
+    print(tree.id, len(tree.nodes))
 
-### 📚 Usage Examples
 
-Component-specific guides and architecture notes live under [`docs/`](docs/).
+asyncio.run(main())
+```
 
-#### Build an exact paper source, chunks, and cited summary
+Prefer the **semantic** shape — a page-aware chunk set plus one cited global summary you can embed and retrieve over? Bind a `PaperSemanticCfg` instead — same class, different cfg:
 
 ```python
 import asyncio
@@ -167,9 +131,8 @@ from quantmind.flows import PaperFlow
 
 
 async def main() -> None:
-    result = await PaperFlow(
-        PaperSemanticCfg(model="gpt-5.6-luna"),
-    ).build(ArxivIdentifier(id="1706.03762v7"))
+    flow = PaperFlow(PaperSemanticCfg(model="gpt-5.6-luna", chunk_size=512))
+    result = await flow.build(ArxivIdentifier(id="1706.03762v7"))
     print(result.global_summary.summary)
     print(result.source_revision.id, result.chunk_set.id)
 
@@ -177,10 +140,6 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-`PaperFlow` binds an immutable `PaperSemanticCfg` once; the cfg **type** selects
-the shape (`PaperStructureCfg` → `PaperStructureTree`, `PaperSemanticCfg` →
-`PaperSemanticResult`).
-
 #### Fan out a batch with `batch_run`
 
 ```python
@@ -236,70 +195,53 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-Paper Flow V1 is source-first: code preserves the exact PDF revision and
-page-aware chunks before accepting a bounded, cited model summary. See the
-[complete persist/reopen/search example](examples/flows/paper.py) and
-[design contract](contexts/design/flow/paper.md).
+More examples live under [`examples/`](examples/); design contracts live under [`contexts/design/`](contexts/design/).
 
----
+### 🔬 Evaluation (In Design)
 
-### 🗺️ Roadmap
+> [!NOTE]
+> Evaluation is in the **design phase** — no results are claimed yet. Our framing follows Anthropic's [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents).
 
-- [x] Better `flow` design for user-friendly usage
-- [x] First production level example (Quant Paper Agent)
-- [ ] Migrate Agent layer to OpenAI Agents SDK
-- [x] Standardize knowledge format with `knowledge/` (Pydantic-based)
-- [ ] Additional content sources (financial news, blogs, reports)
-- [ ] Cross-step working memory (`mind/memory`) for batch document processing
+**quantmind-bench** measures the harness bet directly. Following the SWE-bench model, it runs **paired trials on the same model and the same task set**: once against a bare checkout, once against the QuantMind repo mounted with its contracts, contexts, skills, and hooks. The reported deltas are **cost-to-green, pass@1, pass^k across seeds, and wall-clock** — how much a good harness moves a fixed model. Run instrumentation (tokens / cost / duration / a verify oracle) already ships; the protocol that consumes it is being designed, and no numbers are published.
 
----
+A separate **llmquant-data-bench** will score knowledge quality (correctness, citation precision/recall, point-in-time correctness); it is likewise in design.
 
-### The Vision: An Intelligent Research Framework
+### 🏭 In Production: LLMQuant Data
 
-> [!IMPORTANT]
-> **This section describes our long-term vision, not current capabilities.** While QuantMind today provides a solid knowledge extraction framework, the features described below represent our aspirational goals for future development.
+LLMQuant Data is QuantMind in production. The hosted data platform runs extraction pipelines powered by QuantMind: QuantMind is the open engine, LLMQuant Data is the operated product on top of it. The dependency direction is one-way — `llmquant-data` imports `quantmind`, never the reverse.
 
-QuantMind is designed with a larger vision: to become a comprehensive intelligence layer for all financial knowledge. We're building toward a system that understands the interconnections between academic research, market news, analyst reports, and social sentiment—creating a unified knowledge base that powers better financial decisions.
+<p align="center"><img src="assets/llmquant-data-cards.png" width="860"></p>
 
-The foundation we're building today—starting with papers—will expand to encompass the entire financial information ecosystem.
 
-> [!NOTE]
-> The current source-first paper path produces independently versioned source,
-> chunk-set, and cited-summary artifacts. Future agent memory and cross-document
-> reasoning can build on `LocalKnowledgeLibrary.search()` without changing
-> those canonical artifacts.
+### 🗺️ Roadmap
 
-This future state represents our commitment to moving beyond simple data aggregation and toward genuine machine intelligence in the financial domain.
+Directions we are actively pushing on (not yet shipped):
 
-------
+- **More agent-native** — a `quantmind-best-practice` skill alongside the shipped `quantmind-dev`, and an agent-first contributing path.
+- **Broader coverage** — a SEC / filings collection flow and a prediction-market knowledge type, beyond today's papers and news.
+- **Evaluation** — land the `quantmind-bench` protocol and publish its first paired runs.
 
-### 🤝 Contributing
+Development is moving fast. If you need a source, a knowledge type, or a flow we do not have yet, [open an issue](https://github.com/LLMQuant/quant-mind/issues) — we welcome the request.
 
-We welcome contributions of all forms, from bug reports to feature development.
 
-> [!IMPORTANT]
-> **For Contributors**: Please read [CONTRIBUTING.md](CONTRIBUTING.md) for essential development setup including pre-commit hooks, coding standards, and testing requirements.
+### 🤝 Contributing
 
-**Quick Start for Contributors:**
+Prefer manual steps? See [`.claude/skills/quantmind-dev/references/setup.md`](.claude/skills/quantmind-dev/references/setup.md).
 
-1. **Fork** the repository
-2. **Setup development environment**:
+The fastest path is to let a coding agent drive. Inside the checkout, tell Claude Code:
 
-   ```bash
-   uv venv && source .venv/bin/activate
-   uv pip install -e .
-   ./scripts/pre-commit-setup.sh
-   ```
+```text
+/quantmind-dev set me up as a contributor
+/quantmind-dev file an issue: <what you need>
+/quantmind-dev I want to contribute <your change>
+```
 
-3. **Create feature branch** (`git checkout -b feat/my-feature`)
-4. **Follow conventional commits** (`feat: add new feature`)
-5. **Submit PR** with our template
+Codex users say the same thing in words — the skill is mirrored under `.agents/skills/quantmind-dev/`, so both agents follow one workflow: contributor setup, filing an issue, and developing a change with tests, verification, commit, and PR.
 
-**Before Contributing:**
+> [!IMPORTANT]
+> **For Contributors**: [CONTRIBUTING.md](CONTRIBUTING.md) covers the same setup for humans — environment, pre-commit hooks, coding standards, and testing. `scripts/verify.sh` is the single deterministic check; CI runs the exact same script.
 
-- Open an [issue](https://github.com/LLMQuant/quant-mind/issues) to discuss significant changes
-- Use our issue templates for bug reports and feature requests
-- Ensure all pre-commit hooks pass before submitting PR
+We welcome contributions of all forms, from bug reports to feature development. Open an [issue](https://github.com/LLMQuant/quant-mind/issues) to discuss significant changes before you start, and make sure `bash scripts/verify.sh` is green before you open a PR.
 
 ### License
 
@@ -309,3 +251,5 @@ QuantMind is released under the MIT License—see `LICENSE` for details.
 
 - **arXiv** for providing open access to a world of research.
 - The **open-source community** for the tools and libraries that make this project possible.
+</content>
+</invoke>
diff --git a/assets/llmquant-data-cards.png b/assets/llmquant-data-cards.png
new file mode 100644
index 0000000..bf83243
Binary files /dev/null and b/assets/llmquant-data-cards.png differ
diff --git a/assets/v1-context-engineering.png b/assets/v1-context-engineering.png
new file mode 100644
index 0000000..f85706f
Binary files /dev/null and b/assets/v1-context-engineering.png differ
diff --git a/assets/v2-harness-engineering.png b/assets/v2-harness-engineering.png
new file mode 100644
index 0000000..e4f5987
Binary files /dev/null and b/assets/v2-harness-engineering.png differ
diff --git a/contexts/CONTEXT_MAP.md b/contexts/CONTEXT_MAP.md
index 37c48d6..d68abcc 100644
--- a/contexts/CONTEXT_MAP.md
+++ b/contexts/CONTEXT_MAP.md
@@ -20,6 +20,7 @@ contexts/
 ├── README.md                   ← routing entry point (dev / usage / design)
 ├── design/                     ← accepted design decisions and planned behavior
 │   ├── README.md               ← design index
+│   ├── positioning.md          ← canonical positioning: workbench, V1/V2, eval
 │   ├── flow/
 │   │   ├── paper.md            ← source-first Paper Flow V1
 │   │   └── news.md             ← news collection design and behavior
@@ -48,6 +49,7 @@ contexts/
 | I want to | Open |
 |---|---|
 | Understand the whole `contexts/` layout | the [Directory Map](#directory-map) above |
+| Understand what QuantMind is (positioning, V1/V2) | [`design/positioning.md`](design/positioning.md) |
 | Develop, fix, test, or review code | [`dev/README.md`](dev/README.md) |
 | Use QuantMind as a library | [`usage/README.md`](usage/README.md) |
 | Read or change a design decision | [`design/README.md`](design/README.md) |
diff --git a/contexts/design/README.md b/contexts/design/README.md
index dd35d88..4d9ecee 100644
--- a/contexts/design/README.md
+++ b/contexts/design/README.md
@@ -18,6 +18,7 @@ This directory records QuantMind engineering decisions. Use it to understand whi
 
 | Domain | Design |
 |---|---|
+| Positioning | [What QuantMind is: workbench, V1/V2 bets, evaluation, production](positioning.md) |
 | Flow | [Source-first paper flow](flow/paper.md) |
 | Knowledge | [Paper sources, artifacts, citations, and locators](knowledge/paper.md) |
 | Flow | [News collection](flow/news.md) |
diff --git a/contexts/design/positioning.md b/contexts/design/positioning.md
new file mode 100644
index 0000000..2628949
--- /dev/null
+++ b/contexts/design/positioning.md
@@ -0,0 +1,79 @@
+# QuantMind Positioning
+
+## Quick Summary
+
+- **Purpose**: State what QuantMind is, who its consumer is, and the two engineering dimensions (context and harness) that everything else — README, slides, skills, decks — derives from. This is the single canonical positioning source; when prose elsewhere disagrees with this page, this page wins.
+- **Read when**: Writing or reviewing any outward-facing description of QuantMind (README, a talk, a skill, an issue), or deciding whether a feature belongs to the shipped story or the roadmap.
+- **Load next**: For the harness mechanics, [`../dev/harness-engineering.md`](../dev/harness-engineering.md); for operation naming used throughout, [`operations/naming.md`](operations/naming.md).
+- **Authority**: Current as of July 2026. This page **supersedes** `docs/superpowers/specs/2026-04-16-quantmind-positioning/` (the April "personal knowledge base / MCP product" framing), which is kept only for history. Do not cite the April spec.
+
+## Contents
+
+- [Positioning and Hero](#positioning-and-hero)
+- [Context Engineering](#context-engineering)
+- [Harness Engineering](#harness-engineering)
+- [The Bet](#the-bet)
+- [Evaluation In Design](#evaluation-in-design)
+- [LLMQuant Data In Production](#llmquant-data-in-production)
+- [Roadmap](#roadmap)
+
+## Positioning and Hero
+
+QuantMind is **an agent-native workbench for financial knowledge extraction**. The primary consumer of this repository is not a human importing a package — it is a coding agent working inside the checkout. You describe the pipeline you want; the agent builds it here, against the repo's contracts, skills, and verification.
+
+Hero line: **"Don't import it. Open it."** The intended first move is `cd quant-mind && claude` (or `codex`), not `pip install`. QuantMind remains a perfectly good importable library — `PaperFlow(cfg).build(input)`, `collect_news`, `batch_run` are real Python operations — but the framing is workbench-first, library-second. The workbench is where an agent turns a loose request into a typed, cited, reproducible extraction pipeline.
+
+Two engineering dimensions structure the whole project — dimensions of one repository, not versions of a product. **Context engineering** turns any source into typed knowledge. **Harness engineering** turns any agent into a domain specialist. The first is what the library does; the second is what the repository is. (The July 2026 poster labels the pair "V1 / V2" as a contrast device; serious prose uses the dimension names, never the version labels.)
+
+## Context Engineering
+
+**Any source → typed knowledge.** This dimension lands unstructured financial content in typed, cited, as-of-correct knowledge that downstream retrieval can trust.
+
+- **Deterministic preprocess** — `fetch` / parse / `format` + `clean` produce source-faithful values with no model in the loop, so the provenance is exact and replayable.
+- **Config-driven operations** — `PaperFlow(cfg).build(input)` binds an immutable build config once and applies it per input; `collect_news` collects a replayable source window; `batch_run` fans any operation across a list of inputs under one unified setting. Callers do not write `asyncio.gather` boilerplate.
+- **Typed knowledge shapes** — a `Paper` structure **tree** for whole-document artifacts, and flat **cards** for `News` / `Earnings` / `Factor` / `Thesis`. Every artifact is self-contained: it carries its own text, an `as_of` timestamp, and a light source ref, so it persists and time-queries standalone.
+- **Retrieval over that knowledge** — `rag/` (deterministic chunking + BM25 / similarity), `library/` (local persistence + meaning-based search), and `mind/` (agentic, reasoning-based retrieval where an LLM decides). Together they serve RAG and Agentic RAG, deep research, and data-MCP serving.
+
+Context engineering is the substance shipped as the NeurIPS 2025 GenAI-in-Finance workshop paper (arXiv:2509.21507).
+
+## Harness Engineering
+
+**Any agent → domain specialist.** Harness engineering is the claim that the repository itself — its contracts, disclosure structure, skills, hooks, and verification — is what upgrades a general coding agent into one that reliably does QuantMind-quality work.
+
+- **Repo-level contracts** — `AGENTS.md` / `CLAUDE.md` state the always-on rules once, in one source, for every agent that opens the repo.
+- **Progressive-disclosure `contexts/`** — agent-facing reference pages with a Quick Summary / Contents preview, so an agent loads only the one page a task needs instead of the whole design corpus.
+- **Portable skills** — `quantmind-dev` ships today (commit / PR / component-development workflow); `quantmind-best-practice` is planned.
+- **Claude + Codex hooks** — shared hook scripts give both agents identical hard guarantees (for example, no verification bypass) without maintaining two copies of a rule's content.
+- **Deterministic verify** — `scripts/verify.sh` runs lint + types + import boundaries + tests, fast-failing in a fixed order. CI runs the exact same script, so a green local run means a green PR.
+
+The mechanics — which enforcement layer catches whom, how one rule reaches both Claude and Codex — are detailed in [`../dev/harness-engineering.md`](../dev/harness-engineering.md).
+
+## The Bet
+
+The wager behind harness engineering, stated plainly: **a weak model in a good harness beats a strong model running bare.** If that holds, the durable asset is not the model of the month but the repository that mounts around it — the contracts, contexts, skills, and verification that keep any agent on the rails.
+
+## Evaluation In Design
+
+Evaluation is in the **design phase**. No results are claimed here; two benchmarks are being designed, one per dimension.
+
+- **Knowledge eval** (context engineering) — correctness (EM / F1), citation precision and recall, point-in-time correctness (no look-ahead), and task lift. Protocol anchors under consideration: FinanceBench, FailSafeQA, and RAGAS faithfulness.
+- **Harness eval** (harness engineering) — SWE-bench-style paired runs: the same model and the same tasks, run bare versus run inside the mounted repo. Metrics: cost-to-green, pass@1, pass^k across seeds, and wall-clock.
+
+Run instrumentation — tokens, cost, duration, and a verify oracle — already ships. The benchmarks that consume it do not yet exist; treat any evaluation claim as a plan until this section says otherwise.
+
+## LLMQuant Data In Production
+
+**LLMQuant Data is QuantMind in production.** The hosted data platform runs extraction pipelines powered by QuantMind; QuantMind is the open engine, LLMQuant Data is the operated product on top of it.
+
+- The dependency direction is one-way: `llmquant-data` imports `quantmind`, never the reverse. Nothing in this repo may depend on the hosted platform.
+- "The knowledge harness for AI-native finance" is **LLMQuant Data's** slogan, not QuantMind's. Do not attach it to QuantMind.
+
+## Roadmap
+
+The following are planned, not shipped. Describe them as roadmap; never present them as current capability.
+
+- `quantmind-best-practice` skill (companion to the shipped `quantmind-dev`).
+- SEC / filings collection flow.
+- Prediction-market knowledge type.
+- Concrete `GraphKnowledge` types (today a placeholder).
+- The two evaluation benchmarks described in [Evaluation In Design](#evaluation-in-design).
diff --git a/contexts/dev/github-writing.md b/contexts/dev/github-writing.md
index b438304..3bd77c3 100644
--- a/contexts/dev/github-writing.md
+++ b/contexts/dev/github-writing.md
@@ -12,7 +12,7 @@
 - [Do Not Wrap Prose at a Fixed Width](#do-not-wrap-prose-at-a-fixed-width)
 - [Write Workflow](#write-workflow)
 
-This guide's workflow (Issue/PR templates, `--body-file`, the raw-body read-back) is specific to text submitted to GitHub. Its prose rule — do not hard-wrap at a fixed width — also governs contexts pages stored in the repository; see the contexts authoring standard.
+This guide's workflow (Issue/PR templates, `--body-file`, the raw-body read-back) is specific to text submitted to GitHub. Its prose rule — do not hard-wrap at a fixed width — also governs the repository `README.md` and contexts pages stored in the repository; see the contexts authoring standard.
 
 ## Do Not Wrap Prose at a Fixed Width