Paper Scaffold is a lightweight Python CLI and documentation set for creating clean manuscript repositories from selected research outputs.
Paper Scaffold helps you keep manuscript source, selected figures/tables, and provenance metadata in a separate repository from research code and generated outputs. It is designed for local-first workflows that may later connect to GitHub and Overleaf.
Core message: Keep research code and manuscript source separate. Copy only selected paper-ready artifacts into the manuscript repo, then validate the repo before syncing or sharing.
It does not write the paper, create remote repositories, compile LaTeX, upload to Overleaf, choose artifacts for you, or replace review.
- New user entry point: docs/start_here.md
- Common workflow map: docs/common_paths.md
- Command cheat sheet: docs/one_page_reference.md
- Full CLI reference: docs/cli_reference.md
- Terms used in the docs: docs/glossary.md
- Privacy and data safety: docs/privacy_and_data_safety.md
Try the tool from a checkout:
python scripts/paper-scaffold.py self-test
python scripts/paper-scaffold.py demo --output scratch/demo_manuscript --overwrite
python scripts/paper-scaffold.py validate --manuscript-repo scratch/demo_manuscript --write-json scratch/demo_manuscript/validation_report.json| Starting point | Read | Main commands |
|---|---|---|
| Try the tool | five-minute demo | self-test, demo, validate |
| Python figures or tables | Python outputs walkthrough | discover-artifacts, copy-artifacts, provenance-report |
| Existing LaTeX folder | LaTeX cleanup walkthrough | doctor, validate, check-figures, check-citations |
| Submission package | pre-submission walkthrough | release-check, freeze-artifacts, package-submission |
| Revision round | reviewer response walkthrough | provenance-report, reviewer-binder, compare-lock |
| Unsure | which workflow? | recipes list, recipes show <id> |
Recipe commands:
paper-scaffold recipes list
paper-scaffold recipes show pre-submission-flight-check
paper-scaffold release-check --manuscript-repo ./paperUse-case recipe docs: docs/use_cases.
No install is required from a checkout:
git clone https://github.com/rappjer1/lab-paper-git-workflow.git
cd lab-paper-git-workflow
python scripts/paper-scaffold.py --help
python scripts/paper-scaffold.py self-testEditable install:
python -m pip install -e ".[dev]"
paper-scaffold --helpInstalled fallback when the console script is not on PATH:
python -m paper_scaffold --help
python -m paper_scaffold self-testInstall details and platform notes: docs/install.md, docs/compatibility.md, docs/troubleshooting.md.
self-test: run a no-network smoke workflow.demo: create a synthetic manuscript repo.init: create a clean manuscript repo scaffold.discover-artifacts: find likely manuscript figures and tables.copy-artifacts: copy manifest-listed artifacts.validate: check manuscript structure, metadata, terminology, and Git state.release-check: run consolidated pre-submission checks.provenance-report: write a Markdown/JSON artifact bill of materials.stale-artifactsandunused-artifacts: find outdated or unreferenced manuscript artifacts.freeze-artifactsandcompare-lock: lock artifact hashes and detect drift.add-manuscript-ci: add a dependency-free manuscript hygiene workflow.package-submission: create a clean local submission folder.reviewer-binder: create a revision-round checklist and evidence folder.
Complete list: docs/cli_reference.md. Diagnostic codes: docs/error_codes.md.
Public safety and release hygiene:
- Privacy and data safety: docs/privacy_and_data_safety.md
- GitHub repository settings: docs/github_repo_settings.md
- Historical release reports: docs/release_reports.md
Keep manuscript repositories small and reviewable. Do not commit:
- Raw data dumps or external data exports.
- Model checkpoints, prediction caches, and generated run folders.
- Large binary arrays or archives such as
.npz,.pt,.pth,.pkl,.pickle,.nc,.zarr, or.zip. - Full output trees when only selected paper artifacts are needed.
- API credentials, machine-local paths, or personal notes.
- LaTeX build files such as
.aux,.log,.bbl,.out,.toc, and.synctex.gz.
- Walkthrough index: docs/walkthroughs/README.md
- Example index: examples/README.md
- Dogfood examples: examples/dogfood
- Example integrity guide: docs/example_integrity.md
Examples are synthetic and intentionally small.
Paper Scaffold records what was copied, where it came from, whether manuscript files reference it, and whether hashes changed after locking.
- Provenance guide: docs/provenance_ledger.md
- Artifact locks: docs/artifact_locks.md
- Submission packaging: docs/submission_packaging.md
- Schema reference: docs/schema_reference.md
- Exit codes: docs/exit_codes.md
- Privacy and data safety: docs/privacy_and_data_safety.md
The v0.9 series is the release-candidate hardening series for v1.0. Command names, documented flags, schemas, diagnostic codes, and exit-code conventions are being frozen.
v1.0.1 is a post-release metadata and repository-layout patch. It preserves the current CLI, schema, diagnostic, test, package-build, install-matrix, and public-safety checks without adding major user workflows.
- Public contract: docs/contract.md
- Versioning policy: docs/versioning_policy.md
- v1.0 readiness: docs/v1_0_readiness.md
- Release process: docs/release_process.md
- Public release checklist: PUBLIC_RELEASE_CHECKLIST.md
- Roadmap: ROADMAP.md
Contributions should keep examples generic, small, and public-safe. Add tests for CLI or docs-contract changes and run the maintainer checks in CONTRIBUTING.md.
If Paper Scaffold helps your project, cite or acknowledge it using CITATION.cff or link to this repository.
MIT. See LICENSE.