Getting started

This guide walks you from an empty directory to a linted, compiled proposal.

Installation¶

pip install grantkit          # core engine
pip install "grantkit[pdf]"   # optional: PDF output (WeasyPrint)
pip install "grantkit[docx]"  # optional: DOCX output (python-docx)

GrantKit requires Python 3.12 or later.

1. Scaffold a project¶

grantkit init --funder nuffield-rda

This writes a self-contained project:

my-grant/
├── grant.yaml            # funder, program, deadline, section table
├── responses/            # one Markdown file per section
│   ├── project_summary.md
│   └── ...
├── budget.yaml           # empty, arithmetically-consistent skeleton
└── references.bib        # empty BibTeX file

Sections, word limits, spelling locale, and portal behaviour all come from the funder rule pack. Run grantkit init without --funder for a generic two-section skeleton.

2. Write¶

Each response is a Markdown file with optional YAML frontmatter (frontmatter is ignored by the linter and the word count):

---
title: Project Summary
word_limit: 250
status: draft
---

PolicyEngine democratizes policy analysis with free, open-source tools...

Edit these with your editor or an AI agent:

claude "draft responses/b_case_for_importance.md from our repo README"

3. Check¶

grantkit check

The linter reports errors and warnings — required sections, word/char/page limits, placeholder text, citation resolution, budget arithmetic and funder caps, machine-checkable funder rules, and spelling locale. Other formatting rules remain sourced pack guidance for generated-artifact or manual review. It exits non-zero on errors (add --strict to fail on warnings too, or --urls to also verify links resolve).

4. Track status¶

grantkit status            # human table + deadline countdown
grantkit status --json     # writes status.json (machine-readable)

5. Build¶

grantkit build --format pdf --share

build assembles every response into one review document (md, html, pdf, or docx). For plain-text portals it emits labelled copy blocks to paste box by box. --share also writes a self-contained assembled.html review page, and every build refreshes status.json.

For NSF projects, the combined PDF is review-only and says so in the document and at the CLI. Upload or enter each required section separately in Research.gov; the combined PDF and its raw [@key] citation markers are not submission-ready.

Next steps¶

• CLI reference

• Funder rule packs — including how to contribute one

• Artifacts and the status.json contract