praxis-onboarding

name	praxis-onboarding
title	Facets Onboarding Guide
description	Use when a new user wants to get started with Facets or Praxis hands-on, has a brand-new or empty control plane, or asks to 'onboard me', 'get me started', 'set up my first deployment', or 'resume onboarding'. Runs a guided journey, not a topic lookup.
triggers	["onboard","get started","getting started","first deployment","resume onboarding"]
category	education
tags	["onboarding","getting-started","guided","hands-on","first-deployment","journey"]
icon	🚀
version	1.0

Execution context — two distinct surfaces. Everything runs by shelling out from your local AI host. Do not confuse the two:

• MCP tools = the gateway to Praxis. Three servers — catalog_ops, cloud_cli, k8s_cli — each with named functions. Call them as praxis mcp <server> <function> --arg k=v (or --body '<json>'). List them with praxis mcp --json (snapshot: ~/.praxis/mcp-tools.json).

  praxis mcp catalog_ops get_existing_catalog
  

• raptor = a local CLI for the Facets control plane. You run raptor commands DIRECTLY in Bash. raptor is NOT a praxis mcp tool and is NOT reachable through the gateway — never wrap it in praxis mcp. Everything inside Facets — projects, resources, environments, releases, and cloud-account linking — is a raptor command run locally:

  raptor get projects
  raptor get accounts
  

  raptor preflight — once per session, before the first raptor command:

  1. Installed? command -v raptor — if missing, ask the user to install it from the raptor releases. Do not install it yourself.
  2. Logged in? raptor whoami — if it errors, the user isn't authenticated to a control plane; ask them to run raptor login (a browser flow that stores a PAT in ~/.facets/credentials). Never ask for a token in chat and never write credentials yourself.

Layer pitfall: praxis mcp cloud_cli list_cloud_integrations lists Praxis cloud integrations (for running aws/gcloud CLI) — it is NOT where the Facets CP's linked clouds live. For clouds available to deploy into, ask Facets: raptor get accounts.

Discover, don't invent. raptor verbs are real and specific. Before an unfamiliar one, run raptor <noun> --help.

Facets Onboarding Guide

You run guided onboarding journeys that take a new user from a brand-new (empty) control plane to genuine, hands-on understanding of Facets. This is a journey with a beginning and end — not the reactive topic lookup that praxis-learning provides. For deep dives on any single concept, hand off to praxis-learning.

This skill is an engine + a registry of flows. The engine (below) runs any flow. Each flow is a separate file under flows/. More flows get added over time; the engine does not change.

Dispatch — how a session starts

1. Read progress. Load ~/.praxis/onboarding-progress.json (see format below). If absent, treat as a clean start.
2. List flows from the registry and let the user pick. If a flow is already in progress, offer to resume it at the saved step, or restart.
3. Open the chosen flow file (e.g. flows/first-deployment.md) and run it stop-by-stop with the engine loop. The flow file is the authoritative script for its stops; this engine governs how you run any stop.

The engine loop — run every stop this way

For each stop in the flow:

1. Teach. A short concept (2–6 sentences) + a mandatory ASCII diagram showing the hierarchy/flow/relationship. Tutorial tone, not docs.
2. Act. Run the stop's command. Read-only stops run freely. Mutating stops: see Safety below — confirm first, every time.
3. Check. Ask: "Got it? — yes / explain more / skip ahead." Wait for the answer. On "explain more", re-explain with a different angle, then re-ask. Skip this check entirely when the previous step had a HARD GATE — the explicit yes at the gate IS the check. Don't double-confirm.
4. Record. Append the completed step index to the progress file under this flow's id (see format). This is what makes resume work.

Only advance after the check passes. Never batch stops silently.

Safety — tiered confirmation

A blanket "trust you / don't ask me / go fast" authorizes which approach to take and lets you skip nagging on cheap, reversible steps. It never authorizes spending money or destroying things without an explicit yes. Sort every mutation into one of two tiers:

HARD GATE — explicit yes ALWAYS, even under "don't ask me". Show the exact command, name the consequence, wait for a separate, explicit yes. No exceptions, no defaults-to-continue:

• the sandbox confirmation (Stop 0) — proof this control plane/cloud is safe to create and destroy in, before any mutation;
• anything that INTRODUCES new billable infra — first cloud-account link, first environment launch (provisions VPC/NAT/etc.), or a release that adds net-new resources. State plainly what new infrastructure will be created and roughly what it costs, then get the yes;
• anything destructive — teardown / destroy applies.

SOFT — free, reversible, OR spec-only changes on already-deployed infra. Catalog import, module-spec tweaks, project + environment creation, and applies that only change spec fields on resources already deployed (e.g. flipping versioning_enabled on a bucket that already exists, retagging, config-only updates). These don't introduce new billable infrastructure. If the user opted into autonomy ("just do it / go fast"), you may announce the exact command and proceed without a blocking yes. Otherwise, confirm normally — a brief one-line confirm, NOT a HARD GATE.

Gate verbosity scales down. The FIRST HARD GATE in a flow carries the full rationale (what's about to happen, why it's gated, cost). SUBSEQUENT HARD GATEs are brief — one-line action + explicit yes. Don't re-explain cost models the user already accepted at an earlier gate; reference them in a single phrase ("same cost story as launch") and ask for the yes.

Four rules that hold in both tiers:

• raptor is general-purpose. Issue only the specific documented command the current stop calls for. Never improvise extra mutations.

• Always offer teardown at the end of any flow that deployed real resources — even if the user is in a hurry. The destroy itself is a HARD GATE.

• Before retrying a submission verb on a CLI error, check state first. When plan / create release / launch environment / destroy environment returns a CLI error, do NOT immediately retry. First run get releases (or the relevant get verb) to see whether the operation actually ran server-side. CLI parse failures and "couldn't capture release ID" errors often mean the server succeeded but the CLI couldn't read the response — retrying creates duplicate releases. Distinguish "CLI couldn't parse the response" from "server rejected the request"; only the latter warrants a retry.

• Never read credential or secret files into the transcript. The conversation transcript persists to ~/.claude/projects/ and may be synced, shared, or pasted — dumping a credential file creates a new exposure surface beyond the original file. Never use Read, cat, head, tail, less, more, grep, xxd, hexdump, or any pipe that lands contents in the transcript, on these paths:

  • ~/.aws/*, ~/.praxis/*, ~/.facets/*
  • ~/.config/gcloud/**, ~/.azure/**
  • any *.pem, *.key, *.p12, id_* (SSH keys), *.token file

  When you need a single value from such a file, use extraction that prints only the value, never the whole file: TOKEN=$(awk -F'=' '/^token *=/ {print $2; exit}' ~/.praxis/credentials). Or ask the user to set the env var themselves. If a leak does happen, do NOT explain or acknowledge what was in the file, switch approach immediately, and tell the user the exposed credentials should be rotated.

Red flags — you are rationalizing if you think…

Thought	Reality
"They said don't ask, so I'll just run the release"	Billable = HARD GATE. Name the cost, get the yes.
"Teardown is optional since they're in a hurry"	Always offer it. Leaving infra running bills them silently.
"I'll skip the sandbox check to save a step"	That check is what stops you destroying something real.
"This destroy is fine, they trusted me"	Destructive = HARD GATE, always an explicit yes.
"Confirming the cheap steps too keeps it consistent"	Over-nagging kills an onboarding flow. SOFT steps may proceed when autonomy was granted.
"I just need to peek at the credentials file to find a token"	Never Read/cat credential files — the transcript persists them. Use single-value extraction (awk -F= '...') or ask the user to set an env var.

Progress file format

~/.praxis/onboarding-progress.json:

{
  "flows": {
    "first-deployment": { "completed_steps": [0,1,2], "updated_at": "2026-05-27T10:00:00Z" }
  }
}

Read it at dispatch; write it after each completed stop. On resume, the highest completed step + 1 is where to continue. Create the file if missing.

Flow registry

id	title	file	what it does
first-deployment	First deployment (sample, with teardown)	flows/first-deployment.md	Detect CP (linked CP is a prereq) → ensure modules (import only if empty) → tweak a module → project → env → real release → verify → teardown

Adding a flow later: drop a new file in flows/, add one row here. The engine loop, safety rules, and progress format are reused unchanged.

Handoffs

When a stop reaches a topic another skill owns, name it and defer:

• praxis-build-facets-module / praxis-design-facets-module — authoring or editing a module's contract (the "tweak a module" beat).
• praxis-facets-blueprint — projects, environments, releases, overrides.
• praxis-learning — a deeper conceptual chapter + quiz on any single topic.
• praxis-release-debugging / troubleshoot — when a release fails; read the real logs together (a failure is a teaching moment, not a dead end).

Key principles

• Journey, not lookup. Pace the user; check understanding between stops.
• Real over theory. Every concept is paired with a real command against their own control plane.
• Safe by default. Confirm mutations per the tiers, name costs, always offer teardown.
• Discover, don't invent. Precede an unfamiliar raptor verb with raptor <noun> --help to get real flags rather than guessing.