docs(hosted): guide private remote runs

[mkceichelbeck]

Summary

• add concise candidate-only target, setup, and remote-run CLI help
• include a private guide and complete hosted examples for built-in and custom coordinators
• use provider, harness, and model consistently at the user-facing runtime boundary
• package and validate the guide and examples without changing the public npm artifact
• make uncertain-submission retry requirements explicit and payload-safe

Verification

• npm run test:hosted (59 private-candidate tests, 44 hosted-target tests)
• packed tarball global install, installed guide/example copy, and CLI launch
• npm run check (typecheck and lint; no errors)
• staged Opcore policy gate
• independent newcomer, information-boundary, and technical reviews

The candidate remains unpublished and private. Normal Zeroshot npm packing excludes the private candidate, guide, examples, and tests.

[greptile-apps]

Greptile Summary

The PR documents and packages the unpublished hosted CLI candidate while renaming its user-facing runtime selector from executable to harness.

• Adds a private remote-run guide, concise CLI help, and complete graph, input, cluster, and provider examples.
• Packages the guidance files into the candidate tarball without adding them to the public npm artifact.
• Preserves the capsule-facing executable payload while exposing harness in local runtime configuration.
• Clarifies idempotent retry requirements for submissions with uncertain outcomes.

Confidence Score: 5/5

The PR appears safe to merge with no actionable correctness, packaging, or security defects identified.

The candidate package preserves its downstream runtime contract, installs guidance at the documented location, keeps private assets out of the public artifact, and aligns the new examples and help text with current validation behavior.

Important Files Changed

Filename	Overview
private/hosted-cli-candidate/runtime-config.js	Renames the local runtime selector to harness while preserving the capsule-facing executable field during bundle resolution.
private/hosted-cli-candidate/build-candidate.js	Adds the guide, examples, and help module to the private candidate package and creates parent directories for nested files.
private/hosted-cli-candidate/register.js	Adds contextual help for target setup and hosted runs without changing the established validation boundary.
private/hosted-cli-candidate/README.md	Provides an end-to-end guide for candidate installation, target setup, remote execution, custom clusters, and retry recovery.
private/hosted-cli-candidate/default-run-intent-services.js	Expands uncertain-submission errors to state the exact payload-stability requirements for safe idempotent retries.
tests/private-hosted-cli/package-isolation.test.js	Verifies that private guidance is included in the candidate package while remaining excluded from the public artifact.
tests/private-hosted-cli/guidance.test.js	Validates the packaged guidance and examples against the candidate’s runtime and command contracts.

Sequence Diagram

sequenceDiagram
  participant User
  participant CLI as Private candidate CLI
  participant Config as Local runtime config
  participant Target as Hosted target
  participant Capsule as Hosted capsule
  User->>CLI: target setup --runtime-config
  CLI->>CLI: Store absolute config path
  User->>CLI: run --target --graph --input --ship
  CLI->>Config: Re-read provider, harness, model, and references
  Config-->>CLI: Resolved runtime bundle
  CLI->>CLI: Map harness to executable
  CLI->>Target: Submit RunIntent with idempotency key
  Target->>Capsule: Start bounded delivery job
  Capsule-->>Target: Status and result
  Target-->>CLI: RunIntent observations
  CLI-->>User: Result or resume command

Loading

_{Reviews (1): Last reviewed commit: "docs(hosted): guide private remote runs" | Re-trigger Greptile}

[github-actions]

🎉 This PR is included in version 6.40.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀