ai-research-toolkit 1.1.0__tar.gz

ai_research_toolkit-1.1.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 AI Research Toolkit contributors
+
+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.
+
+---
+Upstream asset audit (2026-11-07): this repository contains no copied third-party
+code or assets. Runtime dependencies are used under their own licenses
+(pydantic MIT, PyYAML MIT, httpx BSD-3, pandas BSD-3, openpyxl MIT,
+python-docx MIT, PyMuPDF AGPL-3.0 / commercial, jinja2 BSD-3, pytest MIT).
+NOTE: PyMuPDF is AGPL-licensed. If you redistribute a closed-source product
+built on this toolkit, review the PyMuPDF licence or swap the PDF backend.

ai_research_toolkit-1.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: ai-research-toolkit
+Version: 1.1.0
+Summary: Local-first, skill-based research workflow toolkit for Claude Code and OpenAI Codex (10 Agent Skills + deterministic Python engine).
+Author: Mrkomiljon
+License: MIT
+Project-URL: Homepage, https://github.com/Mrkomiljon/AI-Research-Toolkit
+Project-URL: Issues, https://github.com/Mrkomiljon/AI-Research-Toolkit/issues
+Keywords: research,agent-skills,claude-code,codex,literature-review
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: PyYAML<7,>=6.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: openpyxl<4,>=3.1
+Requires-Dist: python-docx<2,>=1.1
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: jinja2<4,>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# AI Research Toolkit (v1.1)
+
+Local-first, skill-based research workflow toolkit for **Claude Code** and **OpenAI Codex**: nine specialist Agent
+Skills plus a mandatory `research-orchestrator`, backed by a deterministic Python engine (`rtk`). It helps a researcher
+find papers, analyze them with locators, build evidence-linked reviews, shortlist candidate gaps, structure manuscripts,
+audit citations, check integrity, simulate peer review and track progress — **without inventing papers, results or
+completion marks**. It is an assistant, not an autonomous researcher and not a publication guarantee.
+
+UI languages: Uzbek, English, Russian (skills are written in English; the agent answers in your language).
+
+## Skills
+
+| Skill | Does | Key gate |
+|---|---|---|
+| `research-orchestrator` | plans a dependency-aware workflow, previews it, gets approvals, runs/delegates, checkpoints, reports what is on disk | never fabricates outputs, never bypasses human review |
+| `literature-search` | OpenAlex/Crossref/(Semantic Scholar) search, query log, dedup, ranking, access levels | never invents articles; reports coverage |
+| `paper-analyzer` | objective/methods/sample/outcomes/limitations with page locators and verbatim excerpts | explicit `ABSTRACT_ONLY` if no full text |
+| `literature-review` | comparison matrix + evidence-linked synthesis | every claim linked to `ev-`/`src-` ids |
+| `research-gap-finder` | candidate gaps, hypotheses, feasibility | candidate gap ≠ proven novelty |
+| `manuscript-builder` | IMRaD outline, author-reviewed draft, missing-info list | no fictitious methods/results |
+| `citation-verifier` | DOI format + resolution, mismatches, missing/unused references | metadata check ≠ claim support |
+| `academic-integrity` | attribution/provenance audit, AI-use disclosure draft, submission checklist | no plagiarism-free certificates, no detector evasion |
+| `peer-reviewer` | section-wise major/minor comments, revision plan, response draft | simulated; no acceptance guarantee |
+| `research-progress` | status from artifacts on disk, blockers, next actions | no evidence-free completion marks |
+
+## Requirements
+
+Python 3.11+, pip, Claude Code or Codex (authenticated), internet for the free metadata APIs. Node.js only for the
+`npx skills` route. Windows 11 / Linux tested.
+
+## Costs and subscriptions
+
+The toolkit itself is free (MIT) and OpenAlex/Crossref need no key or payment. What you pay for is the **agent**:
+
+| Agent | What you need | Notes |
+|---|---|---|
+| Claude Code | Claude Pro or Max subscription, **or** an Anthropic API key (pay per token) | Pro has tighter hourly limits; long research sessions fit Max better |
+| Codex | ChatGPT Plus / Pro / Business / Edu / Enterprise, **or** an OpenAI API key | sign in with `codex login` |
+
+One agent is enough; the skills behave the same in both. Semantic Scholar is optional (free public tier, rate
+limited; a free API key raises limits). Prices and limits change often: check claude.com/pricing and
+openai.com/chatgpt/pricing before advising users.
+
+## 1-minute quickstart
+
+```bash
+# engine (no clone needed)
+python -m pip install "git+https://github.com/Mrkomiljon/AI-Research-Toolkit.git"
+# skills into your research folder (pick the agent you use; both is fine)
+cd /path/to/your/research-folder
+npx skills add Mrkomiljon/AI-Research-Toolkit -a claude-code
+npx skills add Mrkomiljon/AI-Research-Toolkit -a codex
+rtk --help
+```
+
+Without Node.js, clone and use the Python installer instead:
+
+```bash
+git clone https://github.com/Mrkomiljon/AI-Research-Toolkit.git
+cd AI-Research-Toolkit
+python -m pip install -e .
+python scripts/install.py --agent all --scope project --project-dir /path/to/your/research-folder
+python scripts/doctor.py
+```
+
+Open Claude Code or Codex **in `/path/to/your/research-folder`** and type:
+
+> Use research-orchestrator. Initialize my PhD research on machine learning for cotton yield prediction.
+
+Then ask for deliverables in plain language: "Find 20 papers since 2021", "Compare these papers", "Find research gaps",
+"Prepare my article", "Audit this manuscript", "Where am I?".
+
+## Install with the Skills CLI (after publishing on GitHub)
+
+```bash
+npx skills add Mrkomiljon/AI-Research-Toolkit                 # interactive: choose skills and agent(s)
+npx skills add Mrkomiljon/AI-Research-Toolkit -a claude-code  # Claude Code only
+npx skills add Mrkomiljon/AI-Research-Toolkit -a codex        # Codex only
+npx skills add Mrkomiljon/AI-Research-Toolkit --all -g        # all skills, all agents, user-level
+```
+
+Flags checked against `skills` 1.7.6 (`npx skills add --help`, 2026-11-07). The Python engine must still be installed
+(`python -m pip install -e .` from a clone, or the package once published) because every skill calls `rtk`.
+Full details, Windows PowerShell steps, update and uninstall: [docs/installation.md](docs/installation.md).
+
+### Claude Code
+
+Skills are read from `<project>/.claude/skills/<skill>/SKILL.md` (or `~/.claude/skills`). `python scripts/install.py
+--agent claude --scope project --project-dir <project>` creates them. Invoke by natural language; `CLAUDE.md` in this
+repo carries the reliability rules.
+
+### Codex
+
+Skills are read from `<project>/.agents/skills/<skill>/SKILL.md` (or `~/.codex/skills`). `python scripts/install.py
+--agent codex --scope project --project-dir <project>`. `AGENTS.md` carries the same rules. No vendor-specific slash
+syntax is required by any skill (tested).
+
+## Watching what happens
+
+In an interactive session (`claude` or `codex` in a terminal or the VS Code extension) you see every step live: the
+plan preview, approval questions, each `rtk` call and the files it writes. The non-interactive forms (`claude -p`,
+`codex exec`) print only the final answer. Either way everything is written to disk, so a second terminal can follow
+the run:
+
+```bash
+rtk log -p workspace/<slug> --follow     # tails workflow/runs.jsonl: step_started, step_completed, blocked, ...
+rtk status -p workspace/<slug>           # stage table derived from artifacts
+```
+
+Outputs are ordinary files (`.md`, `.xlsx`, `.docx`, `.json`) under the workspace; open them in VS Code or Excel/Word.
+
+## Sample prompts
+
+- `Use research-orchestrator. Find 15 papers on Sentinel-2 wheat yield prediction 2020-2025, then find research gaps.`
+- `Use paper-analyzer. Analyze papers/PDFs/smith2023.pdf for the question "which features drive accuracy?"`
+- `Use citation-verifier. Check manuscript/draft.docx against sources/references.bib.`
+- `Use research-progress. What is done, what is blocked, what next?`
+- Uzbek: `Use research-orchestrator. Paxta hosildorligi va ML bo'yicha 20 ta maqola top va bo'shliqlarni aniqla.`
+- Russian: `Use research-orchestrator. Найди 20 статей о прогнозировании урожайности хлопка и пробелы в исследованиях.`
+
+## What a run looks like (engine only, no LLM needed)
+
+```bash
+rtk init --workspace ./workspace --slug crop-yield --topic "machine learning crop yield prediction" --year-from 2021 --ack-cloud
+rtk plan -p workspace/crop-yield "Find 5 papers about ML crop yield prediction since 2021 and find research gaps"
+rtk --json run -p workspace/crop-yield        # runs literature-search; next steps are host-skill steps
+rtk status -p workspace/crop-yield
+rtk report -p workspace/crop-yield            # lists only files that exist on disk
+```
+
+`examples/agriculture-research/` contains a real run (live OpenAlex + Crossref, 2026-11-07) with 16 deduplicated,
+DOI-bearing sources, an abstract-only example analysis with tool-verified excerpts, a matrix, status files and the
+workflow log. See its README for what is and is not demonstrated.
+
+## Workspace layout
+
+```
+workspace/<slug>/
+├── project.yaml                 # topic, goals, years, journal, privacy, budget, limits
+├── sources/sources.json|references.bib
+├── papers/PDFs/                 # your PDFs (git-ignored)
+├── evidence/evidence.jsonl
+├── literature/ analysis/ manuscript/ reviews/
+├── progress/project-status.json|artifacts.json|research-progress.xlsx|next-actions.md
+├── workflow/plan.yaml|runs.jsonl|history/
+└── exports/
+```
+
+## Data privacy
+
+- Artifacts, registries and PDFs stay on your disk. Metadata APIs receive only query strings and DOIs.
+- Claude Code / Codex send prompts and the text they read to their providers; **local-first is not offline inference**.
+- `privacy.allow_external_apis: false` in `project.yaml` (or `RTK_ALLOW_EXTERNAL_APIS=0`) forbids all outbound calls.
+- `rtk privacy-check <files>` blocks external transmission of restricted or sensitive files until you authorize it.
+- Never commit `workspace/`, PDFs, `.env`. See [docs/security.md](docs/security.md).
+
+## Testing and status
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+rtk validate-skills --skills-dir skills
+pytest -q
+```
+
+74 tests (unit, integration, acceptance) pass offline on Windows 11 / Python 3.11.9 (2026-11-07); CI runs them on
+Ubuntu and Windows with Python 3.11 and 3.12. Acceptance criteria from the specification:
+
+| # | Criterion | Status |
+|---|---|---|
+| 1 | multi-step request → validated plan and sequential artifacts | pass (`test_1_…`) |
+| 2 | verified paper not re-analyzed without reason | pass |
+| 3 | missing PDF → abstract-only / full-text claims blocked | pass |
+| 4 | invalid DOI does not pass citation verification | pass |
+| 5 | stops before external transmission of confidential files | pass |
+| 6 | failed API step → partial artifacts + truthful `blocked` | pass |
+| 7 | interruption persists state; resume skips valid steps | pass |
+| 8 | injected instruction in a PDF does not change orchestration | pass |
+| 9 | Claude Code and Codex run the same skill workflow | installer/manifest part passes (`test_cross_agent.py`). Conversational run verified in **Claude Code** (2026-11-07: `claude -p` with `Use research-orchestrator. Initialize … then find 3 papers` created the workspace, ran the plan and reported only on-disk files; a second run `… 10 ta maqola top va bo'shliqlarni aniqla` completed the full search → analyzer → review → gap-finder chain with 26 artifacts, all labelled ABSTRACT_ONLY/METADATA_ONLY because no PDFs were supplied). **Codex** conversational run still pending (account/model login issue on the test machine) |
+| 10 | workflow summary matches artifacts on disk | pass |
+
+## Known limitations
+
+- Full texts are never downloaded; you supply PDFs. Scanned PDFs without a text layer are not OCR'd.
+- Author-year citation matching is heuristic; use `\cite{}`, `[@key]` or `[src-…]` for reliable audits.
+- Intent routing is keyword-based; ambiguous requests produce an empty plan and a question, by design.
+- Semantic Scholar public tier is rate-limited; it is optional.
+- Templates in `templates/` are starting points, not journal-specific formats. No LaTeX/pandoc pipeline yet.
+- PyMuPDF is AGPL-licensed (see `LICENSE` note).
+
+## Repository map
+
+`skills/` canonical skills · `research_toolkit/` engine · `scripts/` install, doctor, init_project, validate_sources,
+export_report, build_templates · `templates/` · `examples/agriculture-research/` · `tests/` · `docs/` (installation,
+user-guide-uz, architecture, security) · `.github/workflows/ci.yml`.
+
+## Releasing to PyPI (maintainers)
+
+1. Create a PyPI API token (pypi.org → Account settings → API tokens) and store it as the GitHub secret `PYPI_API_TOKEN`.
+2. Bump `version` in `pyproject.toml`, commit, then tag and push: `git tag v1.1.0 && git push origin v1.1.0`.
+3. `.github/workflows/release.yml` runs lint + tests, checks the tag matches the version, builds, uploads to PyPI and
+   creates a GitHub release. Users can then `python -m pip install ai-research-toolkit`.
+
+## License
+
+MIT (see `LICENSE`, including the dependency licence audit note).

ai_research_toolkit-1.1.0/README.md

@@ -0,0 +1,206 @@
+# AI Research Toolkit (v1.1)
+
+Local-first, skill-based research workflow toolkit for **Claude Code** and **OpenAI Codex**: nine specialist Agent
+Skills plus a mandatory `research-orchestrator`, backed by a deterministic Python engine (`rtk`). It helps a researcher
+find papers, analyze them with locators, build evidence-linked reviews, shortlist candidate gaps, structure manuscripts,
+audit citations, check integrity, simulate peer review and track progress — **without inventing papers, results or
+completion marks**. It is an assistant, not an autonomous researcher and not a publication guarantee.
+
+UI languages: Uzbek, English, Russian (skills are written in English; the agent answers in your language).
+
+## Skills
+
+| Skill | Does | Key gate |
+|---|---|---|
+| `research-orchestrator` | plans a dependency-aware workflow, previews it, gets approvals, runs/delegates, checkpoints, reports what is on disk | never fabricates outputs, never bypasses human review |
+| `literature-search` | OpenAlex/Crossref/(Semantic Scholar) search, query log, dedup, ranking, access levels | never invents articles; reports coverage |
+| `paper-analyzer` | objective/methods/sample/outcomes/limitations with page locators and verbatim excerpts | explicit `ABSTRACT_ONLY` if no full text |
+| `literature-review` | comparison matrix + evidence-linked synthesis | every claim linked to `ev-`/`src-` ids |
+| `research-gap-finder` | candidate gaps, hypotheses, feasibility | candidate gap ≠ proven novelty |
+| `manuscript-builder` | IMRaD outline, author-reviewed draft, missing-info list | no fictitious methods/results |
+| `citation-verifier` | DOI format + resolution, mismatches, missing/unused references | metadata check ≠ claim support |
+| `academic-integrity` | attribution/provenance audit, AI-use disclosure draft, submission checklist | no plagiarism-free certificates, no detector evasion |
+| `peer-reviewer` | section-wise major/minor comments, revision plan, response draft | simulated; no acceptance guarantee |
+| `research-progress` | status from artifacts on disk, blockers, next actions | no evidence-free completion marks |
+
+## Requirements
+
+Python 3.11+, pip, Claude Code or Codex (authenticated), internet for the free metadata APIs. Node.js only for the
+`npx skills` route. Windows 11 / Linux tested.
+
+## Costs and subscriptions
+
+The toolkit itself is free (MIT) and OpenAlex/Crossref need no key or payment. What you pay for is the **agent**:
+
+| Agent | What you need | Notes |
+|---|---|---|
+| Claude Code | Claude Pro or Max subscription, **or** an Anthropic API key (pay per token) | Pro has tighter hourly limits; long research sessions fit Max better |
+| Codex | ChatGPT Plus / Pro / Business / Edu / Enterprise, **or** an OpenAI API key | sign in with `codex login` |
+
+One agent is enough; the skills behave the same in both. Semantic Scholar is optional (free public tier, rate
+limited; a free API key raises limits). Prices and limits change often: check claude.com/pricing and
+openai.com/chatgpt/pricing before advising users.
+
+## 1-minute quickstart
+
+```bash
+# engine (no clone needed)
+python -m pip install "git+https://github.com/Mrkomiljon/AI-Research-Toolkit.git"
+# skills into your research folder (pick the agent you use; both is fine)
+cd /path/to/your/research-folder
+npx skills add Mrkomiljon/AI-Research-Toolkit -a claude-code
+npx skills add Mrkomiljon/AI-Research-Toolkit -a codex
+rtk --help
+```
+
+Without Node.js, clone and use the Python installer instead:
+
+```bash
+git clone https://github.com/Mrkomiljon/AI-Research-Toolkit.git
+cd AI-Research-Toolkit
+python -m pip install -e .
+python scripts/install.py --agent all --scope project --project-dir /path/to/your/research-folder
+python scripts/doctor.py
+```
+
+Open Claude Code or Codex **in `/path/to/your/research-folder`** and type:
+
+> Use research-orchestrator. Initialize my PhD research on machine learning for cotton yield prediction.
+
+Then ask for deliverables in plain language: "Find 20 papers since 2021", "Compare these papers", "Find research gaps",
+"Prepare my article", "Audit this manuscript", "Where am I?".
+
+## Install with the Skills CLI (after publishing on GitHub)
+
+```bash
+npx skills add Mrkomiljon/AI-Research-Toolkit                 # interactive: choose skills and agent(s)
+npx skills add Mrkomiljon/AI-Research-Toolkit -a claude-code  # Claude Code only
+npx skills add Mrkomiljon/AI-Research-Toolkit -a codex        # Codex only
+npx skills add Mrkomiljon/AI-Research-Toolkit --all -g        # all skills, all agents, user-level
+```
+
+Flags checked against `skills` 1.7.6 (`npx skills add --help`, 2026-11-07). The Python engine must still be installed
+(`python -m pip install -e .` from a clone, or the package once published) because every skill calls `rtk`.
+Full details, Windows PowerShell steps, update and uninstall: [docs/installation.md](docs/installation.md).
+
+### Claude Code
+
+Skills are read from `<project>/.claude/skills/<skill>/SKILL.md` (or `~/.claude/skills`). `python scripts/install.py
+--agent claude --scope project --project-dir <project>` creates them. Invoke by natural language; `CLAUDE.md` in this
+repo carries the reliability rules.
+
+### Codex
+
+Skills are read from `<project>/.agents/skills/<skill>/SKILL.md` (or `~/.codex/skills`). `python scripts/install.py
+--agent codex --scope project --project-dir <project>`. `AGENTS.md` carries the same rules. No vendor-specific slash
+syntax is required by any skill (tested).
+
+## Watching what happens
+
+In an interactive session (`claude` or `codex` in a terminal or the VS Code extension) you see every step live: the
+plan preview, approval questions, each `rtk` call and the files it writes. The non-interactive forms (`claude -p`,
+`codex exec`) print only the final answer. Either way everything is written to disk, so a second terminal can follow
+the run:
+
+```bash
+rtk log -p workspace/<slug> --follow     # tails workflow/runs.jsonl: step_started, step_completed, blocked, ...
+rtk status -p workspace/<slug>           # stage table derived from artifacts
+```
+
+Outputs are ordinary files (`.md`, `.xlsx`, `.docx`, `.json`) under the workspace; open them in VS Code or Excel/Word.
+
+## Sample prompts
+
+- `Use research-orchestrator. Find 15 papers on Sentinel-2 wheat yield prediction 2020-2025, then find research gaps.`
+- `Use paper-analyzer. Analyze papers/PDFs/smith2023.pdf for the question "which features drive accuracy?"`
+- `Use citation-verifier. Check manuscript/draft.docx against sources/references.bib.`
+- `Use research-progress. What is done, what is blocked, what next?`
+- Uzbek: `Use research-orchestrator. Paxta hosildorligi va ML bo'yicha 20 ta maqola top va bo'shliqlarni aniqla.`
+- Russian: `Use research-orchestrator. Найди 20 статей о прогнозировании урожайности хлопка и пробелы в исследованиях.`
+
+## What a run looks like (engine only, no LLM needed)
+
+```bash
+rtk init --workspace ./workspace --slug crop-yield --topic "machine learning crop yield prediction" --year-from 2021 --ack-cloud
+rtk plan -p workspace/crop-yield "Find 5 papers about ML crop yield prediction since 2021 and find research gaps"
+rtk --json run -p workspace/crop-yield        # runs literature-search; next steps are host-skill steps
+rtk status -p workspace/crop-yield
+rtk report -p workspace/crop-yield            # lists only files that exist on disk
+```
+
+`examples/agriculture-research/` contains a real run (live OpenAlex + Crossref, 2026-11-07) with 16 deduplicated,
+DOI-bearing sources, an abstract-only example analysis with tool-verified excerpts, a matrix, status files and the
+workflow log. See its README for what is and is not demonstrated.
+
+## Workspace layout
+
+```
+workspace/<slug>/
+├── project.yaml                 # topic, goals, years, journal, privacy, budget, limits
+├── sources/sources.json|references.bib
+├── papers/PDFs/                 # your PDFs (git-ignored)
+├── evidence/evidence.jsonl
+├── literature/ analysis/ manuscript/ reviews/
+├── progress/project-status.json|artifacts.json|research-progress.xlsx|next-actions.md
+├── workflow/plan.yaml|runs.jsonl|history/
+└── exports/
+```
+
+## Data privacy
+
+- Artifacts, registries and PDFs stay on your disk. Metadata APIs receive only query strings and DOIs.
+- Claude Code / Codex send prompts and the text they read to their providers; **local-first is not offline inference**.
+- `privacy.allow_external_apis: false` in `project.yaml` (or `RTK_ALLOW_EXTERNAL_APIS=0`) forbids all outbound calls.
+- `rtk privacy-check <files>` blocks external transmission of restricted or sensitive files until you authorize it.
+- Never commit `workspace/`, PDFs, `.env`. See [docs/security.md](docs/security.md).
+
+## Testing and status
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+rtk validate-skills --skills-dir skills
+pytest -q
+```
+
+74 tests (unit, integration, acceptance) pass offline on Windows 11 / Python 3.11.9 (2026-11-07); CI runs them on
+Ubuntu and Windows with Python 3.11 and 3.12. Acceptance criteria from the specification:
+
+| # | Criterion | Status |
+|---|---|---|
+| 1 | multi-step request → validated plan and sequential artifacts | pass (`test_1_…`) |
+| 2 | verified paper not re-analyzed without reason | pass |
+| 3 | missing PDF → abstract-only / full-text claims blocked | pass |
+| 4 | invalid DOI does not pass citation verification | pass |
+| 5 | stops before external transmission of confidential files | pass |
+| 6 | failed API step → partial artifacts + truthful `blocked` | pass |
+| 7 | interruption persists state; resume skips valid steps | pass |
+| 8 | injected instruction in a PDF does not change orchestration | pass |
+| 9 | Claude Code and Codex run the same skill workflow | installer/manifest part passes (`test_cross_agent.py`). Conversational run verified in **Claude Code** (2026-11-07: `claude -p` with `Use research-orchestrator. Initialize … then find 3 papers` created the workspace, ran the plan and reported only on-disk files; a second run `… 10 ta maqola top va bo'shliqlarni aniqla` completed the full search → analyzer → review → gap-finder chain with 26 artifacts, all labelled ABSTRACT_ONLY/METADATA_ONLY because no PDFs were supplied). **Codex** conversational run still pending (account/model login issue on the test machine) |
+| 10 | workflow summary matches artifacts on disk | pass |
+
+## Known limitations
+
+- Full texts are never downloaded; you supply PDFs. Scanned PDFs without a text layer are not OCR'd.
+- Author-year citation matching is heuristic; use `\cite{}`, `[@key]` or `[src-…]` for reliable audits.
+- Intent routing is keyword-based; ambiguous requests produce an empty plan and a question, by design.
+- Semantic Scholar public tier is rate-limited; it is optional.
+- Templates in `templates/` are starting points, not journal-specific formats. No LaTeX/pandoc pipeline yet.
+- PyMuPDF is AGPL-licensed (see `LICENSE` note).
+
+## Repository map
+
+`skills/` canonical skills · `research_toolkit/` engine · `scripts/` install, doctor, init_project, validate_sources,
+export_report, build_templates · `templates/` · `examples/agriculture-research/` · `tests/` · `docs/` (installation,
+user-guide-uz, architecture, security) · `.github/workflows/ci.yml`.
+
+## Releasing to PyPI (maintainers)
+
+1. Create a PyPI API token (pypi.org → Account settings → API tokens) and store it as the GitHub secret `PYPI_API_TOKEN`.
+2. Bump `version` in `pyproject.toml`, commit, then tag and push: `git tag v1.1.0 && git push origin v1.1.0`.
+3. `.github/workflows/release.yml` runs lint + tests, checks the tag matches the version, builds, uploads to PyPI and
+   creates a GitHub release. Users can then `python -m pip install ai-research-toolkit`.
+
+## License
+
+MIT (see `LICENSE`, including the dependency licence audit note).