monorepo: make first use of a valid child path actionable instead of reporting a broken push chain

[genedna]

Summary

A new user cannot create a repository directly at a valid Monorepo child path such as /project/workbuddy/demo with the normal Git or Libra flow. A root commit pushed to that path is rejected because the path has no server-known parent history, but the reported error is push chain is broken.

That text describes the internal history invariant, not the action the user must take. The supported workaround is an undocumented product write to POST /api/v1/create-entry, followed by clone and push. As a result, the first successful repository creation requires hand-written HTTP rather than a discoverable product workflow.

Versions and environment

• Mega2 image: genedna/mega2:latest
• Deployment: local macOS OrbStack evaluation stack
• Transport: HTTP with push_auth = none
• Client: Libra 0.23.46
• Target path: /project/workbuddy/demo

Reproduction

1. Start a storage-only Mega2 stack with /project as a valid Monorepo root.
2. Create a new local Libra repository and make one root commit.
3. Add http://127.0.0.1:9000/project/workbuddy/demo as origin.
4. Push main.

The push is rejected with a first-parent-chain error. Creating the directory first through POST /api/v1/create-entry, then cloning that path and pushing, succeeds.

Actual behavior

• A valid but uninitialized child path cannot be provisioned through a supported Git or Libra command.
• The rejection is indistinguishable from a genuine non-fast-forward or malformed-history failure.
• A user must discover and call an HTTP endpoint manually before the normal clone and push workflow can start.

Expected behavior

• Mega2 exposes a supported, discoverable path-provisioning workflow for a valid child path.
• The service keeps the existing safety invariant: a raw root commit must not silently become an arbitrary Monorepo subtree.
• An uninitialized valid path receives a distinct, actionable error that states the prerequisite and points to the supported provisioning action.

Scope boundaries

In scope:

• An idempotent path scaffold or create operation for valid Monorepo child paths.
• A documented CLI-facing or API-facing user journey that does not require users to write raw curl.
• A distinct error contract for an uninitialized path.

Out of scope:

• Accepting arbitrary parentless Git histories at any path.
• Auto-creating every misspelled path on the first push.
• Changing the single-trunk or client-tag policy.

Acceptance criteria

1. A supported provisioning operation creates a valid child path exactly once; a retry is safe and reports that the compatible path already exists.
2. A user can provision, clone, commit, and make at least two incremental pushes without raw HTTP scripting.
3. A parentless push to an uninitialized valid child path returns a stable, actionable error code and remediation, not only push chain is broken.
4. A genuine non-fast-forward or incomplete-history rejection retains its existing diagnostic and is not classified as path provisioning.
5. The operation respects configured root-directory and write-authorization policy.
6. Regression coverage exercises the real Git or Libra path together with the provisioning operation.
7. The quick-start documents the supported first-repository workflow.

Related evidence

• User trial report dated 2026-09-23, section P0-2.
• Current public product write surface: POST /api/v1/create-entry.