yvgude--lean-ctx/docs/guides/publishing-packages.md

Publishing Context Packages

How to publish a .ctxpkg context package to the hosted registry at ctxpkg.com and install packages from it. Contract: ctxpkg-registry-v1.

One-time setup

1. Claim your namespace — log in at leanctx.com, then Account → Registry → Claim namespace. Lowercase [a-z0-9-], 2–32 chars. Namespaces are permanent in v1, so pick deliberately.
2. Mint a publish token — same page. Tokens look like ctxp_…, are shown exactly once, and can be revoked anytime (max 10 active).

export CTXPKG_TOKEN=ctxp_…   # or pass --token per publish

Publish

# 1. Create your package locally (scoped name = @namespace/name)
lean-ctx pack create --name auth-context --scope @acme --description "Auth service context"

# 2. Export SIGNED — the registry rejects unsigned bundles
lean-ctx pack export @acme/auth-context --sign

# 3. Publish
lean-ctx pack publish acme-auth-context-1.0.0.ctxpkg

--sign uses an ed25519 key at ~/.lean-ctx/keys/ctxpkg-ed25519.key (auto-generated on first use, mode 0600). This key is your publisher identity across releases — back it up. Losing it means future releases show a different signer key.

Rules the registry enforces at publish time:

• manifest.name must equal @{namespace}/{name} from the publish target and the namespace must be yours (token-bound);
• the ed25519 signature must verify server-side — not just be present;
• versions are SemVer and immutable: re-publishing an existing version returns 409. Ship a new version instead;
• size cap 8 MiB per artifact.

Every accepted release gets a persisted trust_report stating exactly what was checked (schema, signature, name binding, size) and what was not (wasm_capability_audit, malware_heuristics).

Install

lean-ctx pack install acme/auth-context          # newest non-yanked version
lean-ctx pack install acme/auth-context@1.0.0    # exact pin

The client independently verifies what the registry claims:

1. artifact SHA-256 against the package index,
2. the engine's content-integrity chain (content hash, composite hash, byte size),
3. the ed25519 manifest signature, locally.

Each install is pinned in .lean-ctx/ctxpkg.lock (commit it):

[[package]]
name = "@acme/auth-context"
version = "1.0.0"
artifact_sha256 = "…"
registry = "https://ctxpkg.com/api"

Yank

curl -X DELETE -H "Authorization: Bearer $CTXPKG_TOKEN" \
  https://ctxpkg.com/api/v1/packages/acme/auth-context/1.0.0

Yanking excludes a version from latest resolution but keeps it downloadable for reproducibility (installing a pinned yanked version warns loudly). Nothing is ever deleted.

Self-hosting / other registries

Both ends honor overrides — useful for air-gapped mirrors or a private registry speaking the same v1 surface:

lean-ctx pack publish pkg.ctxpkg --registry https://registry.internal/api
CTXPKG_REGISTRY=https://registry.internal/api lean-ctx pack install acme/auth-context