[callumflack]

Summary

Builders can prepare and submit a new PDP-Connect connector or an improvement using Vana CLI. prepare-pr previews one signed-off connector commit and its review evidence. submit-pr checks the builder's GitHub identity, requires confirmation of that exact public preview, pushes to their existing public fork and opens a draft PR.

The public review pack carries the checked commit, environment, exact commands, exit statuses and output, plus a reviewed synthetic input and resulting record. Updates also show the previous output and describe effects on existing records, IDs and cursors. Older summaries remain previewable with explicit gaps. Submission requires the complete initial pack. The bundled Create Connector instructions include the schema and submission steps.

New connector submissions can include the required upstream registration and generated files. Validation checks that the added entries belong to the selected connector, the generated credential and consent entries match its manifest, and the manifest count increases by one. The rest of each shared file is preserved.

Recovery contract. GitHub can create a PR even when the CLI loses the response. Retry looks up the stable account/commit branch before any push or creation. Tests record every write attempt and require zero additional writes when recovering the same PR.

Evidence

Verified at ecdd089583c1d238c440385bf42c78353d17b3e1 on Node 24.22.1, macOS.

• ./node_modules/.bin/vitest run exited 0. All 1,165 tests in 80 files passed.
• The 22 focused submission tests include a new connector that actually reads synthetic input, emits an independently checked record, runs its own test, and supplies that captured output to the CLI. The CLI previews, submits through simulated GitHub to a local Git fork, and recovers the same PR without writes.
• Coverage includes missing evidence, inconsistent exit statuses, stale commits, conflicting connector keys, missing entry points, changed-evidence confirmation, failed/skipped checks, and safe rendering of evidence containing Markdown fences.
• TypeScript, ESLint, Prettier and build passed. The built CLI exposes the submission instructions and updated help.
• The registration changes passed all 35 focused CLI tests at 11df55e39e6f7cb7f5c4651ff2b93987e3a3ba76, plus TypeScript, ESLint, formatting and build.
• The built CLI opened Readwise draft #642 from reviewed commit 540d34e7b3ebaa8fcb62c7bc92a2ee360c0b9945 using the builder’s GitHub account. The identical confirmed retry returned #642 with reused: true. The transport allowed GitHub reads only and recorded zero push or write attempts.
• Readwise passed 135 targeted upstream tests and Linux verification. The full Linux suite reported one intermittent JSONL cursor failure, also observed on untouched upstream main. The draft’s evidence records the failure and unrun lanes.

Release gate

Tim accepted starting with this review format on 11 November and confirmed the flow should submit new connectors. The evidence format can evolve with use.

This PR remains draft. The live CLI submission and recovery are verified through Readwise #642. Before shipping, complete review, merge, signing and publication proof, and settle the operating owners and release handoff in BUI-952. App availability needs its own proof wherever reported.

BUI-942 · BUI-952