Harvest capability out of a repository
harvest_repoRead-onlyIdempotent
The harvest shortcut: point it at a repository you hold a licence to reuse — one you do not own and will never open a pull request against — and it goes straight to the capabilities. It reads what that repository can already do, fuses those affordances with the owned SHPBL capability library, ranks and names the results as proposals a person can read, stops for your decision on each one, and then emits the seed modules for exactly the ones you approved into your own .shpbl/ library. That is the gauntlet's steps 8, 9 and 10 without the audit, the repair plan or the pull request. It never writes to the target repository. Pass approve with approved_by and host_license to collect the approved grants; pass mode: "walk" for the older batched ledger walk of the whole tree (estimate, part, ledger_digest, budget belong to that mode). Free calls report what the repository can do and what is offerable against it, then stop at the composition boundary; grants need a Practitioner key (7-day free trial).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Your SHPBL Practitioner subscription key (shpbl_mcp_…). Optional if your client sends it as the `Authorization: Bearer …` request header. | |
| mode | No | `harvest` (the default when nothing else in the call implies a walk) is the shortcut: proposals, your decision, then the seed modules for what you approved. `walk` is the older batched ledger walk of the whole tree, which reads and classifies but composes nothing. Send it explicitly whenever you also send `part`, `ledger_digest`, `budget` or `brief`. | |
| part | No | Walk mode only: which batch to return, 1 to 2000. Batch 1 carries the protocol and the manifest; walk them all in order. | |
| repo | Yes | A GitHub repository: `owner/repo` or a URL. | |
| brief | No | Walk mode only: skip the harvest protocol preamble on batch 1 and spend the payload on source. Use it once you already hold the method — `method_protocol` (free) returns it verbatim. | |
| pages | No | Harvest mode: how many source pages to read for evidence, 1 to 12 (about 90,000 characters each). Proposals are cut only from what was actually read. | |
| budget | No | Characters per batch — a whole number from 10,000 to 120,000. Defaults to 90000; lower it for a smaller context window, raise it only if the client can carry it. Out-of-range values are refused in plain words, not silently clamped. | |
| grants | No | Harvest mode: how many capability proposals to rank, 1 to 200. There is no fixed shallow ceiling any more — a sophisticated repository can support far more than a couple of dozen higher-order compositions, and the safeguard against a weak proposal is the approval and the Capability Contract, not a small number here. | |
| approve | No | Harvest mode: the grant ids the person approved. Only these are emitted. Omit it on the first call — the proposals have to be put to them first. An id nobody proposed refuses the whole set rather than emitting the rest. | |
| decline | No | Harvest mode: the grant ids the person explicitly said no to. Only these are recorded as declined; anything they were not asked about stays open and is re-offered, never written down as a refusal. | |
| include | No | Optional path filter — only paths containing this text are harvested. | |
| estimate | No | Return the size of the walk only — batch count, total characters, largest batch, split files — with no source. | |
| approved_by | No | The name of the person who approved them. Required with `approve`. An agent, a model, a vendor, a policy or a default is refused, not recorded. | |
| cml_license | No | Your perpetual copy's licence key, if you hold one. It changes retention, never depth. | |
| github_token | No | Optional GitHub token (Contents: read) for a private repository. Not needed if the SHPBL GitHub App is connected to this key. | |
| governor_key | No | Operator passphrase for SHPBL's own copy. Resolved by the server; it changes only where the harvest is staged, never what is proposed. | |
| host_license | No | What the target repository's licence permits for this reuse, and any obligation it attaches — for example `MIT, attribution required`. Required with `approve`; SHPBL records your declaration and does not verify it. | |
| ledger_digest | No | The ledger folded so far, handed back by a previous session so this batch continues the same run instead of starting over. | |
| quality_floor | No | Harvest mode: drop proposals scoring below this, 0 to 1. The score is a discovery aid for ordering what to read first — it is never evidence that a capability deserves to exist. | |
| per_affordance | No | Harvest mode: how many proposals one host affordance may produce, 1 to 200. | |
| reuse_permitted | No | Required with `approve`: the person's explicit statement that reuse of this upstream project is permitted for this composition. Absence is never a yes, and SHPBL does not infer permission from a detected licence file. Recording your declaration is not legal verification and nothing here is legal advice. | |
| upstream_project | No | The upstream project the reuse is declared against. Defaults to the repository being harvested. | |
| novelty_threshold | No | Harvest mode: how different a proposal must be from the higher-ranked ones already chosen, 0 to 1, measured on bound capabilities and title vocabulary. 0 suppresses only exact duplicates; 0.4 is firm de-duplication of near-identical variants. | |
| reuse_obligations | No | The obligations the licence attaches that must be preserved in the artifact — attribution, notice retention, share-alike, and so on. Recorded against every emitted artifact and carried into its manifest. | |
| carry_notice_files | No | Licence or notice files from the host that must be copied into the artifact. Detected candidates are reported to you if you omit this. | |
| suppress_duplicates | No | Harvest mode: drop proposals whose proposed composition is identical to a higher-ranked one. Default true. |