The Architecture of Plain-Text Research Vaults: Link Integrity and Evidence Traceability
In academic research, investigative reporting, doctoral scholarship, and scientific policy analysis, researchers confront an escalating volume of primary literature, quantitative datasets, and methodological decisions. When starting a major project, many investigators resort to fragmented organizational habits: PDF highlights stored in proprietary reference managers, meeting notes buried in cloud documents, and working manuscript drafts disconnected from underlying citations.
This organizational fragmentation produces severe epistemic vulnerabilities: citations drift from their original context, empirical claims in drafts lack direct quotation anchors, and researchers waste dozens of hours re-reading papers they already summarized. Our Master Plan (§TOOL-076) establishes a rigorous, sovereign paradigm: the plain-text research starter kit with 100% internal link resolution.
1. The Five Essential Research Artifacts in Plain-Text Systems
A complete, resilient research repository requires five distinct interconnected artifacts, each serving a unique stage in the cycle of scientific inquiry:
- 1. The Project Dashboard (
00-Project-Dashboard.md): The central Map of Content (MOC) and executive mission statement. It anchors the core research question, defines the theoretical scope, tracks active milestones, and links bidirectionally to all downstream folders. - 2. Primary Source Reading Notes (
01-Sources/): Atomic, structured notes summarizing inspected monographs and journal papers. Each note captures bibliographic metadata (BibTeX keys, DOIs, authors), summarizes methodological frameworks, and extracts verbatim empirical quotes. - 3. The Evidence-to-Claim Matrix (
02-Evidence/): The critical verification bridge. It maps factual claims intended for the manuscript directly to cited quotations and exact page numbers, preventing factual hallucinations before drafting begins. - 4. The Literature Synthesis & Contradiction Map (
03-Synthesis/): A comparative synthesis note that clusters competing scholarly camps, highlights methodological contradictions, and establishes the project's unique theoretical positioning. - 5. The Manuscript Working Draft (
04-Writing/): The structured academic manuscript (Abstract, Introduction, Background, Methodology, Results, Discussion). Every introductory claim and discussion argument links directly back to the Evidence Matrix.
2. The Mathematical Requirement of Internal Link Resolution
A foundational requirement mandated in our Master Plan (§TOOL-076) dictates that all internal sample links must resolve strictly within the generated package.
Many generic template packs provide boilerplate text containing hypothetical links (such as [[Smith-2024]] or [[Appendix-B]]) without actually providing the target notes. When a researcher imports these templates into Obsidian or Logseq, their vault graph immediately litters with broken links and dead ends.
Our generator algorithmically inspects every outgoing wikilink and relative file path across all generated templates. If an optional module (such as the Decision Journal) is toggled off, the engine automatically purges links pointing to that module across the dashboard and draft templates. When you import the generated package into your vault, every single link resolves to an existing file with 0 broken targets.
3. Methodological Pre-Registration and Decision Logging
In modern experimental science and psychology, the replication crisis highlighted the danger of p-hacking, retrospective hypothesis generation (HARKing), and subtle publication bias. When researchers encounter unexpected friction, they frequently alter parameter boundaries or sample exclusions without documenting the rationale.
The Methodological Decision Journal (05-Meta/Research-Decision-Log.md) provides an immutable audit trail within your knowledge vault. By logging critical methodological choices, parameter calibrations, and rejected alternative pathways in real time, you establish transparent provenance that withstands rigorous peer review.
4. Wikilinks vs CommonMark Hyperlinks: Choosing Your Vault Format
The starter kit builder supports two major link syntax standards:
- Obsidian [[WikiLinks]]: Formatted as
[[01-Sources/Source-Reading-Notes|Source Notes]]. Ideal for researchers working within Obsidian or Roam, providing seamless auto-complete, bi-directional backlink sidebars, and graph visualization. - CommonMark Hyperlinks: Formatted as
[Source Notes](./01-Sources/Source-Reading-Notes.md). Ideal for open-source research teams collaborating via GitHub, GitLab, or static documentation engines, where links must resolve natively in web browsers and IDEs without special plugins.
5. Formula Injection Defense and Air-Gapped Security
Scientific research projects often involve sensitive intellectual property, unreleased algorithmic code, confidential medical trial data, or proprietary patent disclosures. Cloud-based research assistants upload your research questions and notes to hosted language model servers.
The Research Project Starter Kit Builder runs entirely client-side in your web browser. All file generation, link graph validation, and CSV manifest serializers execute within local JavaScript memory. No research hypotheses or project titles are ever transmitted over the network.
6. Provenance Architecture: Connecting BibTeX Keys to Atomic Quotes and Manuscript Paragraphs
The core vulnerability in traditional academic composition is the "citation leap"—the unverified chasm between a broad reference entry in a bibliography and a specific factual assertion made in the body of an article.
In conventional writing workflows, an author types a sentence such as: "Sub-linear scaling persists across distributed transformer topologies." The author attaches a general citation key (\cite{smith2025}). Two years later, during rigorous peer review, a referee requests the precise experimental conditions, baseline hyperparameter tuning, or page location where that scaling exponent was established. The author is forced to conduct an agonizing manual search through a 40-page PDF to rediscover the evidence.
Our Research Starter Kit resolves this cognitive friction through an unbroken three-tier provenance trail:
- Tier 1: Atomic Source Notes: Foundational papers are summarized with verbatim extracts and exact page indicators (e.g.,
p. 114, paragraph 3) in01-Sources/Source-Reading-Notes.md. - Tier 2: The Empirical Evidence Matrix: Each factual assertion receives a deterministic identifier (e.g.,
Claim C-01) in02-Evidence/Evidence-to-Claim-Matrix.md, connecting the extracted quotation directly to the thesis assertion. - Tier 3: The Working Manuscript: In
04-Writing/Manuscript-Draft.md, draft paragraphs embed direct wikilinks or relative references to the Evidence Matrix rather than loose mental impressions.
7. Multi-Investigator Collaboration in Git-Versioned Markdown Repositories
When research teams collaborate using commercial office suites or cloud word processors, track changes quickly devolve into versioning conflicts: Manuscript_v2_final_FINAL_edits_revised.docx. Furthermore, proprietary binary formats make line-by-line attribution and automated linting impossible.
By grounding your investigation in plain-text Markdown files generated by this kit, your research repository gains immediate access to the entire modern software engineering ecosystem:
- Deterministic Git Branching: Co-authors can author parallel experimental sections on dedicated feature branches (e.g.,
feature/methodology-benchmark) and merge changes using standard pull requests with visual diffs. - Atomic Merge Conflict Resolution: Plain-text Markdown files allow granular line-by-line conflict resolution in standard text editors, eliminating corrupted binary document archives.
- Continuous Integration for Research Quality: Automated CI workflows can run link checkers, BibTeX syntax validators, and word count estimators on every commit, ensuring that your research repository maintains pristine structural integrity throughout the project lifecycle.
8. Peer Review Preparation: Exporting Evidence Bundles as Supplementary Material
In high-stakes academic publishing and regulatory policy filings, transparency is the ultimate differentiator. Reviewers and committee chairs increasingly demand open science transparency, requesting access to underlying literature audits and empirical calculation logs.
Because our starter kit compiles your complete investigation into a cohesive, linked package, preparing supplementary materials requires zero manual formatting. You can export the Evidence-to-Claim Matrix and Literature Synthesis directly into your replication package or Zenodo preprint repository. Reviewers can verify the exact quotation provenance for every claim in your manuscript with a single click, dramatically accelerating the path to peer acceptance.
9. Resilient Open Science: Escaping Proprietary Reference Manager Lock-In
Over the past two decades, academic researchers have repeatedly suffered when commercial publishers acquired and closed independent reference management software. Proprietary databases lock your marginalia, tags, and synthesis notes behind subscription paywalls or proprietary file formats.
Plain-text Markdown files and standard BibTeX keys are open international standards that will remain readable and parsable for centuries. By establishing your research project on a sovereign, local-first starter kit, you guarantee that your intellectual discoveries remain permanently accessible, independent of corporate acquisitions, platform pivots, or software licensing fees.