Paper Scaffold diagnostics use stable codes so command output, reports, and docs can point to the same fix.
Documented diagnostic codes are intended to remain stable through v1.0 unless explicitly marked provisional. New codes may be added, but existing documented codes should not silently change severity or meaning.
Use:
paper-scaffold explain E003
paper-scaffold explain --list| Code | Title | Common cause | Typical fix |
|---|---|---|---|
| E001 | main.tex missing |
The manuscript repo does not contain the configured main TeX file. | Create main.tex or update project.main_tex in metadata/manuscript_config.yaml. |
| E002 | references.bib missing |
The bibliography file is absent. | Add references.bib or update the manuscript to use the correct file. |
| E003 | Missing figure path | \includegraphics{...} points to a file that is not in the manuscript repo. |
Copy the figure into the repo or fix the relative path. |
| E004 | Manifest artifact missing | metadata/artifact_manifest.yaml has invalid entries or points to missing manuscript files. |
Run copy-artifacts or update the manifest. |
| E005 | Forbidden raw output found | Raw data, model outputs, caches, or checkpoint-like files were copied into the manuscript repo. | Remove the file and keep only paper-ready artifacts. |
| E006 | Banned implementation label found | A term from metadata/terminology_map.yaml appears in manuscript text. |
Replace it with the publication-facing label. |
| E007 | Git remote origin missing | The repo is not connected to a GitHub remote named origin. |
Add the intended GitHub manuscript repository as origin. |
| E008 | Absolute local path found | A source file contains a machine-specific path. | Replace it with a relative path inside the manuscript repo. |
| E009 | Supplement configured but missing | Config says a supplement exists, but the supplement file is absent. | Create supplement/supplement.tex or set has_supplement: false. |
| E010 | Duplicate LaTeX label | The same \label{...} key appears more than once. |
Rename labels so each key is unique. |
| E011 | Missing LaTeX label target | A \ref, \cref, \autoref, or \eqref points to an undefined label. |
Add the missing label or fix the reference key. |
| E012 | Citation key missing from bibliography | A citation in TeX is not present in references.bib. |
Add the BibTeX entry or fix the citation key. |
| E013 | File larger than configured maximum | A file exceeds the manuscript repo size threshold. | Remove raw outputs or explicitly review whether the file belongs in the repo. |
| E014 | Forbidden directory found | A raw/cache/output directory was copied into the manuscript repo. | Move the directory back to the research repo or archive. |
| E015 | Artifact source missing | copy-artifacts cannot find a manifest source path. |
Regenerate the source artifact or correct source_repo and source_path. |
| E016 | Schema validation error | A config, manifest, terminology map, or validation JSON file has invalid structure. | Fix the reported field type, required field, or top-level structure. |
| E020 | Manifest artifact missing manuscript file | A provenance report found a manifest entry whose manuscript artifact file is missing. | Copy the artifact into the manuscript repo or update metadata/artifact_manifest.yaml. |
| E021 | Referenced artifact missing from disk | A TeX source references a figure or table file that is not present on disk. | Restore the referenced file or fix the TeX path. |
| E030 | Manuscript CI workflow could not be written | add-manuscript-ci could not create or replace the workflow. |
Check the manuscript repo path and pass --overwrite only when replacing intentionally. |
| E031 | Submission package output exists | package-submission found an existing output folder. |
Choose a new output folder or pass --overwrite after reviewing the old package. |
| E032 | Artifact lock missing | compare-lock cannot find the requested lock JSON. |
Create a lock with freeze-artifacts or pass the correct --lock path. |
| E033 | Locked artifact missing | A locked artifact is no longer present in the current manifest artifact set. | Restore the artifact or create a new lock only after reviewing the change. |
| E034 | Manuscript repository missing | A workflow command was given a non-existent manuscript repo path. | Create the manuscript repo or fix --manuscript-repo. |
| E035 | Reviewer binder output exists | reviewer-binder found an existing output folder. |
Choose a new output folder or pass --overwrite after reviewing the old binder. |
| Code | Title | Common cause | Typical fix |
|---|---|---|---|
| W001 | Pandoc missing | Word conversion tools are not installed. | Install Pandoc only if using import-word. |
| W002 | LaTeX compiler missing | latexmk or pdflatex is not installed locally. |
Install LaTeX only if local compilation is needed. |
| W003 | GitHub CLI missing | gh is not installed. |
Use the GitHub website or install GitHub CLI if desired. |
| W004 | Working tree has uncommitted changes | Git status is not clean or upstream is not configured. | Review git status --short and commit intentionally. |
| W005 | Figure present but not referenced | A figure file exists but is not used by \includegraphics. |
Remove stale figures or reference them intentionally. |
| W006 | Raster figure concern | A raster figure may be low resolution, have spaces in the name, or lack a vector alternative. | Prefer PDF for vector plots and high-resolution PNG/JPG for raster images. |
| W007 | Table may be too wide | A generated table may not fit manuscript layout. | Inspect the compiled manuscript and adjust table formatting. |
| W008 | Word conversion needs cleanup | Converted Word/Pandoc text has patterns that often need manual review. | Audit equations, citations, tables, figures, captions, and tracked changes. |
| W009 | Overleaf sync may fail with Git LFS or submodules | The repo uses Git LFS pointers or submodules. | Avoid LFS/submodules for simple manuscript repos or confirm Overleaf support. |
| W010 | No artifact manifest found | The manuscript repo lacks metadata/artifact_manifest.yaml. |
Add a manifest when figures/tables are copied from a research repo. |
| W011 | No terminology map found | The repo lacks metadata/terminology_map.yaml. |
Add one if implementation labels need cleanup. |
| W012 | No supplement found | No supplement file was detected. | Ignore if the manuscript has no supplement. |
| W013 | No LICENSE found | A public repository has no license. | Add a license before public release. |
| W014 | No README found | The repository lacks a README. | Add a README explaining the manuscript repo. |
| W015 | Uncited bibliography entry | A BibTeX entry is not cited by TeX source. | Remove stale references or cite them intentionally. |
| W016 | Figure or table may be missing a label | A figure/table environment lacks \label{...}. |
Add labels where cross-references are needed. |
| W017 | Possible private or secret text | The privacy scan found a local path, email, token-like text, or private marker. | Redact the value before publishing. |
| W018 | Unknown schema field | A metadata file contains a field Paper Scaffold does not use. | Remove it if accidental, or keep it if it is intentional project-local metadata. |
| W019 | Artifact source changed after copy | A manifest source file is newer than the manuscript copy and has different content. | Review and rerun copy-artifacts if the manuscript should use the updated output. |
| W020 | Unused manuscript artifact | A figure or table file exists but is not referenced by TeX source. | Remove stale files or reference them intentionally. |
| W021 | Artifact discovery skipped raw output path | Discovery saw files under raw/cache/output directories and skipped them. | Keep raw outputs in the research repo and copy only selected manuscript artifacts. |
| W022 | Suspicious final filename | A project audit found a filename such as final2 or final_FINAL. |
Inspect manually and choose one canonical source or artifact. |
| W023 | LaTeX build artifact found | A project audit found generated files such as .aux, .log, .bbl, or .synctex.gz. |
Do not copy build artifacts into the clean manuscript repo. |
| W024 | Raw or generated output found | A project audit found raw/generated output files such as .npz, .pt, .pkl, .nc, .parquet, .h5, .tif, or .zip. |
Keep these in the research repo or archive and copy only selected paper-ready artifacts. |
| W030 | Manifest artifact source missing | The manifest declares a source file that the provenance report cannot find. | Update the source path or document why only the manuscript copy remains. |
| W031 | Manuscript artifact stale relative to source | Source and manuscript artifact hashes differ. | Review and refresh the manuscript copy when the source update should be used. |
| W032 | Manuscript artifact present but not in manifest | A figure/table file exists in manuscript artifact folders but is not listed in the manifest. | Add a manifest entry or remove the stale file. |
| W033 | Artifact in manifest but not referenced | A manifest figure/table is present but not referenced from TeX. | Reference it intentionally or remove the stale artifact. |
| W040 | Artifact hash changed since lock | compare-lock found a different hash for a locked artifact. |
Review the artifact change before creating a new lock. |
| W041 | New artifact not present in lock | A current artifact is not in the lock file. | Review whether the artifact belongs in the current submission or revision package. |
| W042 | Untracked artifact excluded from package | A manuscript artifact is present but not listed in the manifest. | Add intentional files to the manifest before packaging or remove stale artifacts. |
| W043 | Unreferenced artifact excluded from package | package-submission skipped a manifest artifact that TeX does not reference. |
Reference it from TeX or pass --include-unreferenced after review. |
| W044 | Manuscript CI is advisory | The generated CI checks hygiene but does not compile or submit the paper. | Use it with release checks and journal-specific manual review. |
| W045 | Reviewer binder needs manual review | The generated binder is a checklist and evidence folder. | Fill in response content and verify confidential text handling manually. |
| Code | Title | Meaning |
|---|---|---|
| I001 | Running inside Paper Scaffold tool repo | The current repo is the tool repo, not a manuscript repo. |
| I002 | Optional tool missing but workflow can continue | A missing optional dependency does not block the current command. |
| I003 | Manuscript repo shape detected | Expected manuscript markers were found. |
| I004 | Git remote origin configured | A Git remote named origin exists. |
| I005 | Artifact manifest valid | The manifest parsed and referenced files exist. |
| I006 | No forbidden files found | No raw/model/cache output patterns were detected. |
| I020 | Likely manuscript file found | audit-project found a manuscript source candidate or Overleaf export folder. |
| I021 | Likely figure or table candidate found | audit-project found a figure or table candidate to review. |
| I030 | Provenance ledger generated | A generated provenance ledger or report was written. |
| I031 | Artifact lock written | freeze-artifacts wrote current manuscript artifact hashes. |
| I040 | Manuscript CI workflow written | add-manuscript-ci wrote the generated workflow. |
| I041 | Submission package written | package-submission wrote a clean output folder. |
| I042 | Artifact lock comparison passed | compare-lock found no changed or missing locked artifacts. |
| I043 | Reviewer binder written | reviewer-binder wrote a revision evidence folder. |
| I044 | Artifact lock comparison report written | compare-lock wrote a Markdown or JSON report. |