Land finished work in a repository as a pull request: pass the files you wrote (full new contents, not diffs) and this opens a branch and a PR for the human to review and merge. Nothing is ever pushed to the default branch. Requires a SHPBL Practitioner key and the SHPBL GitHub App installed on that repository (or a one-off `github_token`). The caller chooses the repository — ask which one, or call `list_repos` first; never assume. Where things go:
Harvest output belongs under `.shpbl/` in **the caller's own repository** — the person who asked for the run — and never in the repository that was harvested. Those are frequently not the same repository: a run may read a public open-source project, or a repository the caller merely has access to, and writing a harvest back into a source repository would be putting our output into somebody else's software. Sources a run may read: public repositories that carry a proper open-source license, the caller's own repositories, or private repositories the caller has access to. The server never reads a repository the caller has no right to read, and it never absorbs customer harvests back into the public library.
- `.shpbl/README.md` — the index of their capability library (this tool scaffolds it when it is absent).
- `.shpbl/<run-seal>/LEDGER.md` — the folded ledger for one run.
- `.shpbl/<run-seal>/REPORT.html` — the branded report, if one was produced.
- `.shpbl/<capability-name>/` — a capability kept as source, one folder each.
- `.shpbl/COMPOSITES.md` — your own composites: capabilities this run invented for your repository by fusing parts that did nothing alone. Record each as `- <name> — <what it fuses> — <why neither part sufficed>`. These are yours and stay private; SHPBL's global composites ledger is fed only by Governor-keyed published runs, so never send yours anywhere and never expect them to appear there.
If the harvested repository is not the caller's own, the harvest still lands in the caller's `.shpbl/` and the source is named in provenance. Ask the person which of their repositories is the home for their library if it is not obvious, and stop for that answer rather than guessing.
Give each kept capability a one-line contract in `.shpbl/README.md`, in the form `- <name> — <path> — <contract>`. That index is what makes the library reusable: on the next run, read it and pass those entries as `own_library` to `evaluate_repo`, `fix_repo` or `run_gauntlet`, and the run will tell you which concerns you already solved before citing anything new. Those entries stay yours — they are held for the call and never stored by SHPBL.
Repairs are the exception: write the repaired file at its own path, never under `.shpbl/`.
