cg-cloud

cg-cloud — understand the cloud layer

This skill orients the user to how Cartograph's cloud layer works and handles the bounded account and registry operations that go with it: login/logout/whoami, registry add/remove/list, adopt, sync, publish/unpublish.

It does not own the stable setup preferences (cg-config handles defaults) or walking the proposals queue (cg-proposals). Hand off cleanly if the conversation drifts into either.

Tool boundary

Prefer Cartograph MCP tools when they cover the action. Use cartograph_config for defaults, checkin_widget with publish=true for explicit checkin-and-publish flows, and registry_widget for search/install/inspect operations.

Use the cartograph CLI for auth, registry listing, proposals, adopt/sync/unpublish/settings, or other cloud commands that are not currently exposed as MCP tools.

Opening reads

In parallel, call:

• cartograph_config — for publish-registry, visibility, governance, auto-publish
• cartograph whoami — for auth state on the current registry
• cartograph registry — for the list of configured registries

Start with where the user stands

Before explaining anything, ground the conversation in the user's current situation. One sentence, concrete:

• "You're authenticated as <user>, publishing to cg (public community registry), governance default is open."
• "You're not authenticated on cg. Reads work fine, but publishing or managing widgets needs cartograph login first."
• "You're set up to publish to acme (self-hosted), visibility default is private, governance default is protected."

This single sentence decides which parts of the explanation matter most to the user. Don't skip it.

What this means in practice

Before jumping into abstract concepts, spell out how the user's current settings actually behave. One short paragraph synthesizing auto-publish + publish-registry + governance + auth state into an operational narrative.

Common shapes:

• auto-publish on, registry=cg, governance=open, logged in: every successful checkin pushes a new public version to cg. Community members can propose updates; minor edits flow through automatically, significant changes (widget.json or substantial code) queue up for your review.
• auto-publish off, registry=cg, logged in: checkin stays local. When you explicitly run cloud publish, the widget goes public. Governance applies only to widgets you've actually published.
• auto-publish on, registry=, visibility=private, logged in: every checkin pushes privately to the org registry. Only invited collaborators see it. Governance determines whether those collaborators can edit without your approval.
• not logged in: reads still work — you can search and install — but any publish or governance action fails until cartograph login. If auto-publish=true, checkin will succeed locally and the publish step will fail loudly.

Write this as a single paragraph, not a bulleted list. Match the user's actual config.

The layer, in one paragraph

Cloud registries host widgets so other people — or other machines — can install them. cg is the public community registry that ships with Cartograph. Self-hosted registries exist for orgs that want their own namespace (identified by a custom prefix). Auth is per-registry; being logged into one doesn't log you into another.

The two choices that actually matter

Frame the user's decisions as two axes:

1. Where should widgets live?

• cg — public community registry. Free, shared, discoverable. All widgets on cg are public; visibility is a no-op here.
• Self-hosted (acme, myorg, etc.) — org's own namespace. Private visibility is load-bearing. Useful for proprietary widgets.

2. How much control do you want over your widgets?

• open — the community can push updates. Proposals fire back to you only for significant changes (widget.json edits, or substantive code changes). Minor edits flow through without approval. Best when you want the wheel to turn and don't mind others polishing your work.
• protected — every proposed update requires your manual accept/reject. Best when you spent a lot of time on a widget and don't want anyone breaking it.

Governance is set per-widget, but defaults to the config's governance value at publish time.

The operations, each in a sentence or two

publish — shares the widget with the configured registry so others can install it. Either manual (cartograph cloud publish) or automatic on every checkin (auto-publish=true).

unpublish — removes the widget from the registry. Users who already installed still have the code on their machine, but future searches won't find it. Republishable later with the same widget_id.

adopt — links a local widget to its cloud counterpart by writing a .cartograph_source sidecar. Use this when you have a local widget that's really the cloud version but Cartograph doesn't know that — so checkin --publish fails because the link is missing. cartograph cloud adopt <local-id> <@owner/prefix-widget-id> fixes it.

sync — pulls lesser versions up to speed. Compares local library against cloud; higher version wins in either direction. Useful after long offline stretches or a fresh clone.

settings — per-widget tweaks you own (its specific visibility, governance). Overrides the config defaults for that one widget.

proposals — incoming queue of changes others submitted to your widgets. Mention it in passing; the cg-proposals skill walks the actual review workflow.

Help the user decide

Close with a short, direct recommendation shaped by what you read:

• "If you mostly want to consume widgets, cg with no login is fine."
• "If you want to contribute back, login to cg and pick governance=open if you're comfortable with community edits, or protected if you want to gatekeep."
• "If you're at an org, add your org's registry with cartograph registry add <url>, set publish-registry=<org>, and visibility=private if that's the org's norm."

Hand-off line if they want to change defaults: "If you want to change any of this, cg-config can walk the setup."

Common gotchas (when publishing fails)

If the user's publish isn't working, check in this order:

1. Not logged in. cartograph whoami returns unauthenticated on the target registry. Fix: cartograph login.
2. Wrong publish-registry. Config points to a registry the user doesn't have configured, or the widget_id prefix doesn't match.
3. Sidecar missing on a cloud widget. Local widget exists but has no .cartograph_source — checkin refuses to push. Fix: cartograph cloud adopt.
4. Visibility misconfigured for target. On a self-hosted registry, visibility=public may be rejected by the registry's policy.
5. Unstamped widget. Validation stamp missing or stale — widget gets filtered from search post-publish. Fix: re-validate before checkin.

State the observed cause, don't guess. If multiple could apply, ask.

Scope

This skill explains the cloud layer. It does not change config (cg-config does), does not review proposals (cg-proposals does), and does not plan widget work (cg-plan does). If the conversation drifts into those, hand off cleanly.

What not to do

• Don't launch into mechanics before grounding the user in their current auth + registry state.
• Don't explain every CLI flag. The MCP surface handles mechanics; this skill is about the mental model.
• Don't recommend flipping a widget to public without the user saying they want that — publishing is meaningful.
• Don't walk the proposals queue here. Mention it, then stop.
• Don't editorialize governance choices. open and protected are both legitimate; the right one depends on the widget.