docs(contexts): organize design guidance for agents

.agents/skills/quantmind-dev/references/develop-components.md

@@ -86,7 +86,7 @@ apply throughout.
 
 A public operation is complete only when all of these agree:
 
-1. A stage and name consistent with `docs/design/en/operations.md`.
+1. A stage and name consistent with `contexts/design/operations/naming.md`.
 2. Typed input and config models, exported from `quantmind.configs`.
 3. One intent-oriented `async def` operation exported from `quantmind.flows`,
    with its result contract exported from the canonical owning layer.

.claude/skills/quantmind-dev/references/develop-components.md

@@ -86,7 +86,7 @@ apply throughout.
 
 A public operation is complete only when all of these agree:
 
-1. A stage and name consistent with `docs/design/en/operations.md`.
+1. A stage and name consistent with `contexts/design/operations/naming.md`.
 2. Typed input and config models, exported from `quantmind.configs`.
 3. One intent-oriented `async def` operation exported from `quantmind.flows`,
    with its result contract exported from the canonical owning layer.

.gitattributes

@@ -0,0 +1 @@
+tests/fixtures/paper/golden/*.pdf binary

.gitignore

@@ -25,7 +25,6 @@ demo_data/
 
 # Local-only development scratch notes (not tracked)
 new_feature.md
-docs/design/zh/next-step-architecture.md
 docs/superpowers/
 
 # Coverage artifacts (generated by pytest --cov)

AGENTS.md

@@ -6,6 +6,21 @@ aligned with `CLAUDE.md` (same core rules); update both in the same change.
 Use [`contexts/README.md`](contexts/README.md) as the repository information
 entry point for either development or library-usage work.
 
+## Progressive Context Loading
+
+Pages under `contexts/` are agent-facing references designed for progressive
+disclosure:
+
+1. Read lines 1-80 first. The preview contains `Quick Summary` and `Contents`
+   sections that explain the page's purpose, authority, and scope.
+2. Use that preview to decide whether the page applies. Do not preload sibling
+   pages or follow unrelated links.
+3. When a page applies, read the entire page before changing code, contracts,
+   or repository guidance. The preview routes work; it does not replace the
+   detailed contract.
+4. Follow directly linked canonical sources only as the task requires. Avoid
+   deep reference chains and duplicate guidance in working context.
+
 ## What This Is
 
 QuantMind is a knowledge extraction and retrieval library for quantitative
@@ -73,8 +88,8 @@ the user explicitly authorizes it — fix the underlying issue instead.
 6. **No meaningless wrappers** — a method must add logic, abstraction, or a
    side effect beyond the call it wraps; otherwise inline it.
 7. **Name public operations by intent** — follow
-   `docs/design/en/operations.md`; use stage verbs, and reserve `pipeline` for
-   deliberate multi-stage composition.
+   `contexts/design/operations/naming.md`; use stage verbs, and reserve
+   `pipeline` for deliberate multi-stage composition.
 
 ## Tests and Examples
 

CLAUDE.md

@@ -7,6 +7,21 @@ update both in the same change.
 Use [`contexts/README.md`](contexts/README.md) as the repository information
 entry point for either development or library-usage work.
 
+## Progressive Context Loading
+
+Pages under `contexts/` are agent-facing references designed for progressive
+disclosure:
+
+1. Read lines 1-80 first. The preview contains `Quick Summary` and `Contents`
+   sections that explain the page's purpose, authority, and scope.
+2. Use that preview to decide whether the page applies. Do not preload sibling
+   pages or follow unrelated links.
+3. When a page applies, read the entire page before changing code, contracts,
+   or repository guidance. The preview routes work; it does not replace the
+   detailed contract.
+4. Follow directly linked canonical sources only as the task requires. Avoid
+   deep reference chains and duplicate guidance in working context.
+
 ## What This Is
 
 QuantMind is a knowledge extraction and retrieval library for quantitative
@@ -74,8 +89,8 @@ the user explicitly authorizes it — fix the underlying issue instead.
 6. **No meaningless wrappers** — a method must add logic, abstraction, or a
    side effect beyond the call it wraps; otherwise inline it.
 7. **Name public operations by intent** — follow
-   `docs/design/en/operations.md`; use stage verbs, and reserve `pipeline` for
-   deliberate multi-stage composition.
+   `contexts/design/operations/naming.md`; use stage verbs, and reserve
+   `pipeline` for deliberate multi-stage composition.
 
 ## Tests and Examples
 

contexts/README.md

@@ -1,18 +1,44 @@
 # QuantMind Repository Context
 
-This directory is the public repository routing layer for coding agents. Start
-with the index that matches the work you are doing:
+## Quick Summary
+
+- **Purpose**: Route agents to the smallest set of context pages needed for a
+  QuantMind task.
+- **Read when**: Starting repository development, library usage, or design
+  work.
+- **Load next**: Choose exactly one primary route below, then follow only links
+  required by the task.
+- **Authority**: Design pages record agreed behavior; code and tests show what
+  the current version implements.
+
+## Contents
+
+- [Routes](#routes)
+- [Where Information Lives](#where-information-lives)
+
+## Routes
+
+This directory is the public repository context system for coding agents and
+maintainers. Start with the index that matches the work you are doing:
 
 - [Develop QuantMind](dev/README.md) for architecture, contribution, testing,
   and verification guidance.
 - [Use QuantMind](usage/README.md) for public operations, examples, and usage
   documentation.
+- [Design QuantMind](design/README.md) for accepted design decisions and
+  planned behavior that spans packages.
 
-## Source of Truth and Ownership
+## Where Information Lives
 
-- Context pages curate links and route readers; they do not copy full guidance.
-- Code, public contracts, design documents, `AGENTS.md` / `CLAUDE.md`, and
-  workflow skills remain canonical for their stated domains.
+- Keep each kind of information in one place so agents do not have to compare
+  competing versions.
+- `contexts/design/` records accepted design decisions and planned behavior.
+- `contexts/dev/` and `contexts/usage/` route readers to existing rules and
+  examples instead of copying them.
+- Code and tests show current behavior. Design pages list any planned behavior
+  that is not implemented yet.
+- `docs/` remains the home for user-facing guides, examples, and catalogs. It
+  may link to a design page but must not maintain a second copy of the design.
 - Update a component's context index only when its discoverable entry points
   change, not for every implementation change.
 - Repository maintainers own this shared structure. Component contributors own

contexts/design/README.md

@@ -0,0 +1,48 @@
+# QuantMind Design
+
+## Quick Summary
+
+- **Purpose**: Find accepted designs for QuantMind packages and public
+  operations.
+- **Read when**: A task changes architecture, package responsibilities, public
+  behavior, or a required validation rule.
+- **Load next**: Open only the domain design that matches the task, then read
+  that page in full before implementation.
+- **Authority**: These pages explain agreed behavior. Each page lists any part
+  that is not implemented yet.
+
+## Contents
+
+- [Design Index](#design-index)
+- [Organization Rules](#organization-rules)
+
+This directory records QuantMind engineering decisions. Use it to understand
+which package owns each step, how packages work together, and what behavior an
+implementation must preserve.
+
+## Design Index
+
+| Domain | Design |
+|---|---|
+| Flow | [Paper extraction from input to validated result](flow/paper.md) |
+| Flow | [News collection](flow/news.md) |
+| Library | [Local knowledge storage and meaning-based search](library/local.md) |
+| Operations | [Public operation naming](operations/naming.md) |
+
+## Organization Rules
+
+- Organize designs directly by package or feature, such as `flow/`, `knowledge/`,
+  `library/`, `operations/`, or `preprocess/`. Do not add an intermediate
+  `components/` directory.
+- Keep this page as the single global design index. Domain directories do not
+  need their own index.
+- Add a design page only for real design content. Do not create empty
+  directories, placeholders, or speculative component pages.
+- State whether a document describes current behavior, planned behavior, or
+  both. List current gaps so readers can distinguish a plan from working code.
+- Write headings and summaries as an action plus a concrete object. Avoid
+  unexplained project shorthand and define any necessary domain term when it
+  first appears.
+- Use code and tests to check current behavior. Keep `docs/` focused on
+  user-facing guides, examples, and catalogs; those pages may link here but
+  must not maintain a second copy of a design.