Spec: M3 Authenticated Distribution

Initial Situation

Harness Intelligence is on the 2.0.0 line. The CLI already owns repo detection, scaffold writes, bundled baseline fallback, update/diff ergonomics, and release/baseline scripts. packages/contract already defines a typed Effect HttpApi baseline boundary, and apps/api implements placeholder authenticated baseline endpoints. Current control-plane metadata is additive: when the backend path is absent or unavailable, the CLI must keep GitHub stable and bundled fallback behavior.

The CLI has grown enough that M3 should not add auth, required-tool checks, and backend distribution into the existing shallow runtime modules without a small architecture refactor first.

Issue

M3 needs authenticated internal baseline access without making the npm package private, and it needs the backend to become the trusted metadata/control boundary without making the backend mutate local repos. It also needs the external harness toolchain to be explicit, testable, and visible to generated scaffold consumers.

If the CLI adds this directly into command files or scaffold/update runners, auth, baseline resolution, required tools, and prompt generation will become difficult to test and hard for future agents to navigate.

Solution

First deepen apps/cli around shared command/runtime boundaries:

shared baseline option resolution for command adapters
required-tool installation/checking as an injectable boundary
later auth/config/control-plane code as separate providers, not embedded in scaffold/update

Then deliver the M3 issue tree:

IP-101: CLI auth commands and authenticated typed backend calls
IP-103: required toolchain checks and dp-cli skill provisioning
IP-102: backend-mediated baseline registry/artifact access after IP-101 is usable

Non-Goals

Public web/backoffice work.
Removing GitHub stable or bundled baseline fallback without an accepted M3 requirement.
Backend-driven repo mutation.
Consumer-repo business logic inside the CLI.
Final production token-storage hardening beyond the explicit M3 acceptance surface.

Acceptance Criteria

CLI refactor gate is implemented with focused tests and preserves current command behavior.
Every issue and child in ISSUE-MATRIX.md is accounted for with evidence.
dp auth login, dp auth status, and dp auth logout exist and use a Better Auth-compatible browser approval flow or a proven local-development substitute when credentials are unavailable.
CLI stores and clears runtime credentials through a testable local config/provider boundary.
CLI authenticated control-plane calls attach bearer credentials through the typed @punks/contract client.
Backend accepts valid authenticated baseline requests and rejects unauthorized baseline access with typed errors.
Required tools include skills, opensrc, agent-browser, and portless; portless remains required.
Setup/update and generated metadata make required tools and dp-cli skill provisioning visible.
Backend can return recommended baseline metadata for an authenticated operator.
Backend can issue artifact access metadata for baseline downloads, with Vercel Blob evaluated or explicitly deferred with evidence.
CLI can cache/apply backend-resolved baseline artifacts locally.
Existing GitHub stable and bundled fallback behavior remains intact.
Docs/runbooks/wiki/spec artifacts are updated for changed operator workflow, auth, baseline, toolchain, and control-plane behavior.
Review, effect-review, validation, PR update, and Linear closeout are complete or blocked with concrete evidence.

Constraints

apps/cli remains the local scanner/cache/prompt-skill-hook placer/filesystem writer.
Backend/control plane owns registry, provenance, auth, telemetry, artifact access, and authoritative metadata.
packages/contract owns shared Effect HttpApi contracts, schemas, typed errors, security declarations, and typed client.
packages/scaffold owns shared scaffold models only, no behavior.
Use portless-style local URLs in docs/env/config examples rather than raw localhost:<port> defaults.
Effect code should use services/layers, typed schemas, tagged errors, and test layers rather than module mocks.

Decision Log

Decision	Rationale
Refactor CLI runtime boundaries before M3	Auth/control-plane/tooling work needs testable modules, not command sprawl.
Keep command registration explicit	Sentry CLI source reinforces boring explicit command trees.
Model auth/config as providers	Auth must be reusable by baseline resolution without living inside update.
Preserve fallback as a hard invariant	M3 is authenticated distribution, not removal of current public fallback.
Treat IP-102 as blocked by IP-101/IP-123	Backend distribution needs a usable credential and typed auth path first.

Open Questions

Which Better Auth device-login endpoint shape should the CLI call once backend auth routes are implemented?
Are production artifact URLs signed directly from Vercel Blob in M3, or is a proxied/local metadata path acceptable for first delivery?

Spec: M3 Authenticated Distribution

On this page