Support registry-backed hyard clone handles

[zack-nova]

This was generated by AI during triage.

Implement the public hyard clone <handle> path for registry-backed Harness Packages and align the public docs and demos around package handles instead of explicit GitHub URL/ref examples.

The repository should remain English-only; generated Chinese translation drafts are intentionally excluded from this delivery.

[zack-nova]

This was generated by AI during triage.

Triage Notes

Confirmed facts:

• Runtime demos and public release docs should prefer Package Handle Coordinates over explicit GitHub URL/ref examples once registry entries exist.
• hyard install <handle> already resolves registry-backed package handles.
• hyard clone <handle> was missing as a public path for creating a new Harness Runtime from a published Harness Package.
• The official registry catalog uses namespace package indexes with package.type, package.name, and versions.<version>.locator metadata.
• The repository is English-only for committed documentation; Chinese translation drafts are excluded from this issue delivery.

Recommendation:

• Type: feature.
• Delivery mode: afk, because implementation and review can be validated through objective CLI, integration, docs, and release-surface gates.
• Advance with one slice: resolver support, clone command support, public docs/demo updates, and release-surface tests.

No missing information:

• Acceptance criteria and validation can be defined from the current public CLI contract and registry source contract.

[zack-nova]

This was generated by AI during triage.

Dev Brief

Type: feature

Delivery mode: afk

HITL rationale:

Not required; this slice can advance through objective local validation, GitHub PR review artifact creation, and squash merge.

Summary:

Add registry-backed hyard clone <handle> support and update public documentation so published Harness Package demos use package handles as the ordinary path.

Current behavior / context:

• Public docs describe Package Handle Coordinates as the ordinary install path, but Harness Runtime fast-start examples still leaned on explicit GitHub URL/ref setup.
• hyard install <handle> resolves registry-backed package handles.
• hyard clone accepted explicit harness template sources and git locator package coordinates, but not registry-backed package handles.
• The resolver needed to consume the current catalog index schema used by the official registry.

Desired behavior:

• hyard clone <curated-harness-handle> and hyard clone <namespace>/<harness-handle> create a new Harness Runtime from the registry-resolved Harness Package source.
• Clone rejects Orbit Package handles with a clear instruction to use hyard install <handle> inside an existing runtime.
• Clone JSON and install records preserve registry provenance.
• Public quickstart, release-surface, and demo docs teach handle-based clone/install paths first.
• Generated Chinese docs are not committed.

Key interfaces / constraints:

• Public binary remains hyard.
• Do not push directly to main or locally merge main.
• Preserve Git-native package provenance and commit-pinned registry resolution.
• Keep explicit Git locators as an advanced escape hatch.
• Keep release-surface tests aligned with public command/docs behavior.

Acceptance criteria:

• hyard clone product-lab-style handles resolve through the registry and create a runtime using the handle name as the default target directory.
• Namespaced Harness Package handles are supported for clone.
• Orbit handles are rejected by clone with an install-oriented message.
• Registry provenance is emitted in clone JSON and stored in the bundle record.
• Resolver supports the current catalog index schema with package-level identity and version-level locator metadata.
• Public docs and demos use handle paths as the default path and retain explicit Git locators as advanced escape hatches.
• Chinese .zh.md translation drafts are excluded from the committed repository state.

Validation plan:

• Unit/integration: targeted registry resolver and clone tests.
• Integration: real smoke of hyard clone product-lab --json against the official registry.
• Release surface: sh ./scripts/test_release_surface_hyard.sh.
• Full repository gates: mise run fix and mise run ci.
• Repository hygiene: git diff --check and no committed .zh.md docs.

Out of scope:

• Publishing Chinese translations.
• Changing registry curation policy beyond documenting the current schema consumed by the resolver.
• Removing explicit Git locator support.

[zack-nova]

This was generated by AI during triage.

Dev Workpad

repo: zack-nova/harnessyard
issue: #152
branch: issue/clone-handle-public-path
base: main
owner: codex

Plan

• Confirm current behavior
• Design implementation path
• Implement
• Validate
• Publish review artifact
• Review sweep
• Land

Acceptance Criteria

• Registry-backed Harness Package handles work with hyard clone.
• Orbit Package handles are rejected with an install-oriented message.
• Registry provenance is recorded in clone output and bundle records.
• Public docs and demos prefer handle paths.
• Chinese translation drafts are stashed and not included in repository changes.

Validation

• Command: mise run fix
• Result: passed
• Command: mise run ci
• Result: passed
• Command: sh ./scripts/test_release_surface_hyard.sh
• Result: passed
• Command: git diff --check
• Result: passed

Review Artifact

• Pending PR creation from issue/clone-handle-public-path into main.

Notes

• Branch push dry-run completed before the actual push.
• Chinese .zh.md docs are stored in stash@{0} with message stash Chinese docs translations.

Confusions

• None.

[zack-nova]

This was generated by AI during triage.

Review Sweep

This was generated by the Review Sweep Producer. It is not a rework or merge decision.

Review artifact: #153
Sweep time: 2026-05-18T07:55:42Z
Review Sweep Producer: Codex

Checks

• Status: passed
• Failing checks: none
• Passing checks: Lint, Go tests (hyard-cli), Go tests (harness-cli), Go tests (orbit-cli), Go tests (orbit-template), Go tests (orbit-harness), Go tests (orbit-libraries), govulncheck, Shell validation

Reviews

• Approved: none
• Changes requested: none
• Commented: none

Unresolved Review Artifact Comments

• None observed.

Inline Review Comments

• None observed.

AFK / HITL Assessment

• AFK eligible: yes
• Human review needed: no
• Reason: local validation and GitHub CI passed, PR is mergeable and clean, and no unresolved comments or human-dependent review items were observed.

Potentially Actionable Items

• None.

Non-actionable Notes

• hyard clone <bare-name> now treats handle-shaped bare names as registry handles; local relative paths should use ./name or ../name. This is documented as PR risk, not a blocker.

Human Decision Gate

No human decision is required for AFK advancement from in-review to to-merge because objective review evidence is sufficient and no human-dependent item remains.