# Honest Scholar

> Research you can defend — keep your research honest, especially now that AI is in the loop.

## Docs

- [CLI reference](https://honest-scholar.science/cli-reference.md): The honest-scholar command tree, generated from the Typer app.
- [ADR-0001: Package the workflow as a standalone plugin, not in-mononet](https://honest-scholar.science/decisions/0001-separate-plugin-repo.md): The research-workflow skills were being designed inside mononet, but the workflow is domain-neutral and the author wants to share the same methodology across…
- [ADR-0002: Scientific scope only; engineering delegated via a contract](https://honest-scholar.science/decisions/0002-scientific-scope-only.md): The full research lifecycle includes both scientific work (claims, evidence, decisions, papers) and engineering (designing/building the code that produces…
- [ADR-0003: Agency principle — assistants, not researchers](https://honest-scholar.science/decisions/0003-agency-principle.md): An AI research-workflow tool could plausibly try to do research and make scientific decisions. The author insisted the opposite: the skills assist, keep…
- [ADR-0004: Understanding principle + the defend skill](https://honest-scholar.science/decisions/0004-understanding-principle-and-defend.md): The dual of agency (ADR-0003): if the skills won't do the research, the author must actually understand their work and methods to a mentor/reviewer standard…
- [ADR-0005: Three-level mirror; thesis as a partial mirror](https://honest-scholar.science/decisions/0005-three-level-mirror.md): We started with two levels (hypothesis within a paper; paper within a portfolio). The author then asked to incorporate the PhD thesis and to track progress…
- [ADR-0006: Two pipeline skills per level (generate / resolve)](https://honest-scholar.science/decisions/0006-two-skills-per-level.md): How to structure the lifecycle skills so hypothesis-level and paper-level are uniform, and so the "missing" stages (related-works, publish-decision) fit without…
- [ADR-0007: literature = one skill, scout/position modes](https://honest-scholar.science/decisions/0007-literature-one-skill-two-modes.md): Literature work spans generative idea-scouting (mining forward citations) and defensive positioning (related-works synthesis for a committed claim/paper). Two…
- [ADR-0008: Literature registry = standard bib + triage sidecar](https://honest-scholar.science/decisions/0008-literature-bib-plus-triage.md): Should the literature registry share the dataset manifest format? A field-level comparison showed literature and dataset registries are more different than…
- [ADR-0009: dataset one skill + thin datasets.yml (reject DVC/DataLad/lakeFS)](https://honest-scholar.science/decisions/0009-dataset-thin-manifest.md): Dataset management needs a registry + tiered retrieval + verification + a private mirror, under a light-dependency posture (mononet avoids heavy deps /…
- [ADR-0010: Tiers A/B/C by (license × access); mirror ≠ redistribution grant](https://honest-scholar.science/decisions/0010-storage-tiers.md): Datasets differ in whether they can be committed, auto-fetched, or only manually acquired. The author wants a private copy of every dataset regardless. A…
- [ADR-0011: rclone private mirror; SHA-256 authoritative fixity](https://honest-scholar.science/decisions/0011-rclone-mirror-sha256.md): The private mirror must support Google Drive now and other backends later, keep credentials out of the repo, and verify integrity across backends whose native…
- [ADR-0012: Shared asset substrate — share the mechanism, not the file](https://honest-scholar.science/decisions/0012-shared-substrate.md): literature and dataset both manage externally-sourced, identified, licensed, mirror-able assets. Are their registries the same? A field-level comparison found a…
- [ADR-0013: Experiment-backend contract + pluggable backend](https://honest-scholar.science/decisions/0013-experiment-backend-contract.md): The pipeline skills need experimental evidence, but how experiments run is project-specific (one project's GPU fan-out means nothing to another's). The testing…
- [ADR-0014: progress cross-cutting; semantic roll-up; anti-Goodhart](https://honest-scholar.science/decisions/0014-progress-cross-cutting.md): The author wants progress tracked at all levels (hypothesis/paper/thesis) with a markdown dashboard. A research pass grounded how to do this without perverse…
- [ADR-0015: defend cross-cutting; guardrail stop-and-confirm; teaching; non-grading](https://honest-scholar.science/decisions/0015-defend-cross-cutting.md): Given the Understanding principle (ADR-0004), how should examination be structured, invoked, and constrained — especially since the AI can't know the ground…
- [ADR-0016: Mentor personas author-selectable; no personality inference](https://honest-scholar.science/decisions/0016-mentor-personas.md): Not every mentor/reviewer voice suits every author. The question was how to pick a persona for the examine/advise voice and whether to match it to the author's…
- [ADR-0017: research-init one skill, init/adopt modes](https://honest-scholar.science/decisions/0017-research-init-one-skill.md): A repo must be set up to use honest-scholar — both fresh repos and existing ones with prior research artifacts (mononet has benchmarks, reference PDFs, informal…
- [ADR-0018: Git-native plain text as source of truth; cross-repo out of scope](https://honest-scholar.science/decisions/0018-git-native-source-of-truth.md): Where does the authoritative state live — external services (Zotero DB, MLflow, W&B) or git-tracked files? And should a thesis be able to aggregate papers…
- [ADR-0019: Public plugin, named honest-scholar](https://honest-scholar.science/decisions/0019-public-plugin-visibility.md): ADR-0001 chose a standalone plugin repo but left the name and visibility open. The audience is the author's own repos, company colleagues, PhD peers — and, the…
- [ADR-0020: CSL-JSON as source of truth; BibTeX exported on demand](https://honest-scholar.science/decisions/0020-bib-format-csl-json.md): The literature registry's bibliographic-facts layer (ADR-0008) needs a concrete format. BibTeX and CSL-JSON are losslessly inter-convertible (Zotero/pandoc), so…
- [ADR-0021: Thesis defensibility gate — per-gap acknowledged confirmation](https://honest-scholar.science/decisions/0021-thesis-gate-per-gap-confirmation.md): The defend guardrail is everywhere else a stop-and-confirm with a single logged override (ADR-0015), to honor agency. The thesis defense is the highest-stakes…
- [ADR-0022: License the honest-scholar plugin under Apache-2.0](https://honest-scholar.science/decisions/0022-license-apache-2.0.md): ADR-0019 made the plugin public and flagged that a license must be chosen before release. mononet is Apache-2.0.
- [ADR-0023: Delegate engineering via a contract, not a named tool](https://honest-scholar.science/decisions/0023-engineering-delegation-contract.md): ADR-0002 kept honest-scholar scientific-only and delegated engineering to a specific named tool. But naming a specific engineering tool couples the plugin to it…
- [ADR-0024: Supporting tooling ships as one package (Typer CLI, optional MCP), bootstrapped by a markdown ensure-tooling procedure](https://honest-scholar.science/decisions/0024-tooling-package-and-bootstrap.md): The supporting-script TODOs (literature citation-graph client, dataset manifest + retrieval/mirror, defend record, exploration backlog) were first drafted as…
- [ADR-0025: Honest AI-use disclosure + citation as the growth mechanism](https://honest-scholar.science/decisions/0025-disclosure-and-citation-growth.md): honest-scholar should become widely used. The mission-aligned growth vector is the honesty mission itself: research venues increasingly require an AI-use…
- [ADR-0026: Independent plugin/package versioning with a compatibility pin](https://honest-scholar.science/decisions/0026-independent-versioning-compat-pin.md): honest-scholar ships two artifacts on different release cadences: the plugin (markdown skills, distributed via the git self-marketplace) and the honest-scholar…
- [ADR-0027: Publish the package via GitHub Releases + PyPI Trusted Publishing](https://honest-scholar.science/decisions/0027-release-driven-oidc-publish.md): The honest-scholar package (ADR-0024) is distributed on PyPI, with release candidates validated on TestPyPI first. Publishing needs a trigger (when does a build…
- [ADR-0028: 100% statement + branch coverage gate on the package](https://honest-scholar.science/decisions/0028-100-percent-coverage-gate.md): The honest-scholar package (ADR-0024) is small, pure-functional at its core, and built for reproducibility and honesty — it is the tooling an integrity-focused…
- [ADR-0029: Unified API-key handling — a CLI-managed JSON store, not .env](https://honest-scholar.science/decisions/0029-api-key-handling.md): The skills reach external services that key-gate their useful rate limits — Semantic Scholar (S2_API_KEY), OpenAlex (OPENALEX_MAILTO, polite pool), private…
- [ADR-0030: Docs site on Mintlify, published from a generated docs repo](https://honest-scholar.science/decisions/0030-docs-site-mintlify.md): honest-scholar had no rendered docs site (#6) — the design record, README.md, docs/USER-GUIDE.md, and the CLI --help were the docs, all as in-repo markdown. A…
- [honest-scholar — Decision Log (ADRs)](https://honest-scholar.science/decisions/index.md): MADR-style Architecture Decision Records for the honest-scholar plugin. Each records the context, the options considered, the rejected alternatives and why, and…
- [honest-scholar — Scientific Research-Workflow Plugin (Meta-Spec)](https://honest-scholar.science/design/00-meta-spec.md): The honest-scholar skills are assistants, not researchers. They keep the accounts of a research program, advise as a mentor, and discuss as a colleague — but…
- [honest-scholar sub-spec 1 — Lifecycle, pipeline skills, rigor, progress & defend](https://honest-scholar.science/design/01-lifecycle.md): One object×action shape at three nested levels (meta-spec §3.1). Each level: a generate skill proposes candidates into a backlog; a resolve skill drives one…
- [honest-scholar sub-spec 2 — Literature capability (literature)](https://honest-scholar.science/design/02-literature.md): One skill, two modes over one citation-graph substrate. Each mode takes a level ∈ {hypothesis, paper, thesis} parameter (the three mirror levels) that tunes…
- [honest-scholar sub-spec 3 — Dataset capability (dataset)](https://honest-scholar.science/design/03-dataset.md): One skill, verbs init | register | fetch | verify | mirror | audit. It is upstream of the experiment backend: runs declare the datasets they need; the skill…
- [honest-scholar sub-spec 4 — Shared substrate & experiment-backend contract](https://honest-scholar.science/design/04-substrate-and-contract.md): Two things are shared across the plugin and therefore specified once, here:
- [Proposal: Cross-repo thesis aggregation](https://honest-scholar.science/design/proposals/cross-repo-thesis-aggregation.md): Status: draft (for discussion) · Date: 2026-07-18 · Tracks: mononet#132
- [Proposal: datasets.yml manifest tooling — loader/validator + Croissant interop](https://honest-scholar.science/design/proposals/dataset-manifest-tooling.md): Status: implemented (designed 2026-07-18) · Skill: dataset
- [Proposal: Dataset retrieval, private-mirror & fixity tooling](https://honest-scholar.science/design/proposals/dataset-retrieval-mirror-tooling.md): Status: implemented (designed 2026-07-18) · Skill: dataset
- [Proposal: defend record — a helper to persist understanding status + the accountability trail](https://honest-scholar.science/design/proposals/defend-record-helper.md): Status: implemented (designed 2026-07-18) · Skill: defend
- [Proposal: rendered docs site (Mintlify)](https://honest-scholar.science/design/proposals/docs-site.md): Status: designed 2026-07-19 · Skill: — (project infra) · Implements #6 · Decision ADR-0030
- [Proposal: Shared backlog helper for the two exploration skills](https://honest-scholar.science/design/proposals/exploration-backlog-helper.md): Status: implemented (designed 2026-07-18) · Skill: hypothesis-exploration / paper-exploration
- [Proposal: Citation-graph client (honest_scholar/literature/graph.py)](https://honest-scholar.science/design/proposals/literature-citation-graph-client.md): Status: implemented (designed 2026-07-18) · Skill: literature
- [Proposal: honest-scholar package (Typer CLI, optional MCP)](https://honest-scholar.science/design/proposals/tooling-package.md): Status: implemented (designed 2026-07-18) · Umbrella for the supporting-script proposals
- [Visual identity](https://honest-scholar.science/design/visual-identity.md): Honest Scholar's identity is built to read as rigorous, not decorative: a bold electric blue grounds the system with confidence, a single punchy red accent…
- [Disclosing AI use — and citing Honest Scholar](https://honest-scholar.science/disclosure.md): honest-scholar helps you use AI in research honestly: you (not the AI) make and sign off every material decision, you can defend the work, and evidence is…
- [User Guide](https://honest-scholar.science/get-started/user-guide.md): A hands-on guide for a researcher meeting honest-scholar for the first time. It walks you from install to a signed finding to a submitted paper, using one…
- [Honest Scholar](https://honest-scholar.science/index.md): Research you can defend — keep your research honest, especially now that AI is in the loop.
- [Agency Principle — "Assistants, Not Researchers" (grounding digest)](https://honest-scholar.science/references/agency-principle.md): It is not an anti-AI stance. Every norm below permits AI assistance (editing, retrieval, bookkeeping, discussion) while forbidding AI authorship and AI…
- [Generative Citation Scouting — methodology digest](https://honest-scholar.science/references/citation-scouting.md): Using the citation graph to generate research ideas, spot gaps, and find collaborators, anchored on an author's paper + rival anchors. Identifiers verified at…
- [Reproducible Dataset Management — standards digest](https://honest-scholar.science/references/dataset-management-standards.md): Grounding for a domain-neutral dataset registry + tiered retrieval + private mirror.
- [Dataset Tooling & Mirror Architecture — digest](https://honest-scholar.science/references/dataset-tooling-mirror.md): Single dep-free Go binary; Google Drive + S3/B2/R2/MinIO/SFTP/WebDAV/~65 more; remote:path; verifies integrity on transfer; rclone check/hashsum on demand.
- [Mentor / Reviewer Personas — grounding digest](https://honest-scholar.science/references/mentor-personas.md): LLM personality inference is contested on validity and ethically fraught (consent, bias, manipulation): arXiv:2503.02082, arXiv:2405.13052. A system that…
- [Positioning / Related-Works Synthesis — methodology digest](https://honest-scholar.science/references/related-works-synthesis.md): For a committed paper: systematically establish novelty, select baselines, situate the contribution. Every named method has a verified identifier below.
- [Thesis-by-Publication & Multi-Level Progress Tracking — digest](https://honest-scholar.science/references/thesis-and-progress-tracking.md): Suggested "done": hypothesis = resolved (verdict backed by recorded evidence; pending = no verdict); paper = done (constituent hypotheses resolved AND claim…
- [The Understanding Principle & the defend skill — grounding digest](https://honest-scholar.science/references/understanding-and-defense.md): Companion to the agency principle. Where agency says the human decides and is accountable, the Understanding principle says the human must understand their own…
- [dataset](https://honest-scholar.science/skills/dataset.md): Manage research datasets with a thin, git-tracked registry, tiered storage, a private rclone mirror, and SHA-256 fixity. Use when a run declares the data it needs, when adding/registering a dataset…
- [defend](https://honest-scholar.science/skills/defend.md): Use when a material research decision is about to be recorded (a findings verdict, a publish decision, a thesis defensibility judgment) or a method's rationale is undemonstrated, and whenever an…
- [hypothesis-exploration](https://honest-scholar.science/skills/hypothesis-exploration.md): Use when generating, capturing, ranking, or triaging candidate hypotheses for a paper — a raw idea to stash, citation-seeded leads to mine, a data pattern worth chasing, or a backlog to prioritize and…
- [hypothesis-testing](https://honest-scholar.science/skills/hypothesis-testing.md): Use when driving one promoted hypothesis from a claim to a signed verdict — the resolve skill at the hypothesis level. Runs the staged pipeline hypothesis → strategy → design/plan → findings, does the…
- [literature](https://honest-scholar.science/skills/literature.md): Mines and situates a research literature over one citation-graph substrate (OpenAlex + Semantic Scholar). Use when scouting the forward-citation graph for research leads (scout mode) or defending a…
- [paper-exploration](https://honest-scholar.science/skills/paper-exploration.md): Use when deciding what paper to write next — mining finished or in-flight work for candidate application and follow-up papers, filling or grooming the portfolio backlog, or wiring a new paper into the…
- [paper-synthesis](https://honest-scholar.science/skills/paper-synthesis.md): Use when developing a committed paper from its constituent hypotheses toward a publish/no-go decision and a submitted manuscript — situating it against prior work, structuring it, and assembling its…
- [progress](https://honest-scholar.science/skills/progress.md): Use when you want to see the state of a research program — where a hypothesis, paper, or thesis stands, what is blocking it, what is stale — or to regenerate the dashboard. Reads status from each…
- [research-init](https://honest-scholar.science/skills/research-init.md): Use when onboarding a repository onto the honest-scholar research workflow — either scaffolding a fresh repo (init) or backfilling an existing one that already has papers, datasets, benchmarks, and…
- [thesis](https://honest-scholar.science/skills/thesis.md): Use when a research program is (optionally) bound into a doctoral thesis — to frame the aims and choose which portfolio papers compose it, or to assemble the kappa framing chapter and clear the…