Skip to content

D134 — kb create requires a git remote

Status: implemented (2026-08-26); amends D85.

Context. A KB is a git repository, and its origin is what makes it durable and reconstructible: the kb-create skill opens with a data-loss warning for exactly that reason, and every sync path degrades silently without one (hasRemote in internal/kb/gitsync.go:27, the no_remote git status, and CARTOGRAPHER_GIT_SYNC documented as inert for a remote-less KB). The local onboarding path did not enforce it: cmdKBCreate called kb.Init and nothing else, and docs/agent-install.md presented the remote as optional, falling back to a plain kb create whenever the user had not supplied one. Observed in the field: a from-scratch installation completed successfully and left a local-only KB, never prompting for a repository and never surfacing that the KB was neither backed up nor syncable.

Decision. cartographer kb create <name> requires an explicit remote decision: --remote <url> or --no-remote, with neither (or both) a usage error (exit 2) that lists the three ways to get a KB — --remote for an empty repository, kb clone for a repository that already holds a KB, --no-remote for a local-only one. --remote attaches the URL as origin and pushes the initial commit with upstream tracking (gitx.PushSetUpstream, added next to Push, which must keep leaving tracking configuration alone for the sync paths). A failure to attach or push removes the scaffold entirely and exits 1, with hints separating an authentication failure from a non-empty remote — the same cleanup guarantee kb clone already gives, so auto-discovery never mounts a half-provisioned KB. --no-remote keeps the previous behavior and prints a stderr warning naming the cost and the recovery commands. The agent runbook (docs/agent-install.md) instructs the agent to ask for the repository before creating anything and to fall back to --no-remote only on the user's explicit acceptance.

Rationale. D85 correctly separated the local CLI path from the GitOps skill, but made the remote optional to keep the path short, which made a non-durable KB the outcome of the shortest sequence of commands a first-time user runs. The product has no other moment where that state becomes visible: nothing prompts later, and the sync machinery treats it as normal. Requiring the choice at the only point where it is cheap to fix costs one flag and removes the silent failure mode; keeping --no-remote preserves the throwaway/dev case without making it the default.

Compatibility. Breaking for scripted cartographer kb create <name> invocations: adding --no-remote restores the previous behavior exactly.