diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a4d6e84
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# QQsci
+
+QQsci is a Codex skill for materials-science manuscript writing, submission-package
+audit, literature-grounded revision, and Word DOI-only citation comments.
+
+It is designed for workflows that combine:
+
+- manuscript and Supporting Information `.docx` files
+- main figures, SI figures, and TOC `.pptx` files
+- Zotero literature items and AI-generated Zotero child notes
+- QQnote-generated literature summaries or comparison tables
+- target-journal positioning and reviewer-style pre-submission audit
+
+## Scope
+
+QQsci owns the manuscript-facing reasoning:
+
+- extract manuscript keywords from topic, draft, figures, SI, or cover material
+- classify strongly and weakly related papers
+- compare the manuscript with strongly related papers
+- audit missing experiments, controls, mechanisms, benchmarks, and statistics
+- check figures, captions, SI consistency, formatting, spelling, and terminology
+- produce Markdown reviewer reports
+- add Word native citation comments containing DOI strings only
+
+QQsci does not directly insert Zotero Word fields. For Word manuscripts, citation
+suggestions are added as native comments with one DOI per line.
+
+## QQnote Relationship
+
+QQnote is used only as the literature-note input tool.
+
+QQnote may:
+
+- generate or refresh Zotero child-note summaries
+- summarize selected Zotero papers into Markdown comparison tables
+
+QQsci then consumes those notes/tables and makes the manuscript decisions. QQnote
+should not decide whether a paper is strongly related, weakly related, necessary
+for citation, or sufficient as reviewer evidence.
+
+When QQsci calls QQnote, use:
+
+```powershell
+py "$env:USERPROFILE\.codex\skills\qqsci\scripts\run_qqnote_with_qqsci_config.py" --script summarize_zotero_table -- --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627"
+```
+
+## Configuration
+
+Use `config/config.template.json` as the public template and create a private
+local file:
+
+```text
+config/config.local.json
+```
+
+Do not commit `config/config.local.json`.
+
+QQsci is the top-level configuration owner for manuscript workflows. It maps its
+DeepSeek and Zotero settings into QQnote-compatible environment variables when
+calling QQnote:
+
+- `deepseek.api_key` -> `AWESOMEGPT_API_KEY`
+- `deepseek.base_url` -> `AWESOMEGPT_BASE_URL`
+- `deepseek.model` -> `AWESOMEGPT_MODEL`
+- `zotero.web_api_key` -> `ZOTERO_API_KEY`
+- `zotero.user_id` -> `ZOTERO_USER_ID`
+
+QQnote remains independently usable through its own environment variables, vault
+`.env`, or AwesomeGPT/Zotero preferences.
+
+## Submission Package Audit
+
+For a full submission package, QQsci checks files in this order:
+
+1. `Manuscript.docx`
+2. `Figures.pptx`
+3. `Supplementary Information.docx`
+4. `Supplementary Information.pptx`
+5. `Highlights.docx`
+6. `CoverLetter.docx`
+7. `TOC.pptx`
+
+The manuscript and main figures define the story. SI, highlights, cover letter,
+and TOC must stay consistent with that story.
+
+## Installed Location
+
+For Codex discovery, install under:
+
+```text
+C:\Users\qyh15\.codex\skills\qqsci
+```
+
+The source repository is maintained separately and can be pushed to Gitea.