New users get no guidance to install or log in to raptor

[anshulsao]

The problem

A new user installs praxis, runs praxis login, sees a clean success message,
and thinks setup is done.

It isn't. Half the toolchain is missing, and nothing says so.

   brew install --cask Facets-cloud/tap/praxis
          │
          ▼
   praxis login          ── browser flow, user clicks "Create Key"
          │
          ├──▶ API key -> ~/.praxis/credentials
          ├──▶ installs the praxis-* skills
          └──▶ writes ~/.praxis/mcp-tools.json
          │
          ▼
      "✓ Logged in"   ← looks finished


   raptor?
          │
          ▼
   not installed. not mentioned. not logged in.

Why it matters

raptor is where the Facets control plane lives — projects, resources,
environments, releases, cloud accounts. Of the shell commands in our seeded
skills, 450 are raptor.

So a user who installs praxis and stops there cannot do most of the real work.
The skills we just installed for them will tell them to run raptor ..., and
the command won't exist.

Two tools, two logins, two credential files

	praxis	raptor
install	brew install --cask Facets-cloud/tap/praxis	nothing tells you
login	praxis login	raptor login
creds	~/.praxis/credentials	~/.facets/credentials
who does it	praxis, for you	you, by hand

raptor also has no Homebrew formula or cask (checked Facets-cloud/homebrew-tap
— only Casks/praxis.rb exists). Installing it is a manual download:

curl -LO https://github.com/Facets-cloud/raptor-releases/releases/latest/download/raptor-darwin-arm64
chmod +x raptor-darwin-arm64
sudo mv raptor-darwin-arm64 /usr/local/bin/raptor

So praxis is one command and raptor is four, one of which needs sudo.

What praxis does today

It does track whether raptor is on PATH and whether it is out of date.
praxis status --json reports it. If raptor is stale, praxis nudges the user to
run raptor upgrade — and never runs it for them. That part is good.

It does not say anything when raptor is missing entirely.

In cmd/update_check.go:112-118, if raptor is not installed then checkable is
false, so the check short-circuits and returns quietly. The installed: false
flag lands in the JSON and is never printed for a human.

cur, installed, checkable := spec.current()
f := Freshness{Tool: spec.Name, Installed: installed, Current: cur}
if os.Getenv("PRAXIS_NO_UPDATE_CHECK") != "" || !checkable {
    return f          // <- raptor absent exits here, silently
}

The only place this is mentioned

Two skills mention it, and both punt:

• internal/skillinstall/embedded/praxis-onboarding/SKILL.md:36
  "Installed? command -v raptor — if missing, ask the user to install it"
• the praxis meta-skill preflight says the same thing

The AI is told to ask the user to install raptor. The user is never told how.
There is no brew install raptor, no download URL, and no install docs anywhere
in this repo.

   AI:   "please install raptor"
   User: "ok, how?"
   AI:   nothing in any skill or command answers this

The gap

1. praxis login reports success while the toolchain is half-installed.
2. Nothing tells the user how to install raptor.
3. Nothing prompts for raptor login, so the second auth step is invisible too.

Suggested fix

At the end of praxis login and praxis refresh-skills, check for raptor. If it
is missing or not logged in, print the next steps. This can sit right where the
freshness notice already runs (cmd/login_setup.go:261), which already knows
whether raptor is installed.

Rough shape:

✓ Logged in to profile "acme".

⚠ raptor is not installed. Facets projects, resources and releases need it.

  Install:
    curl -LO https://github.com/Facets-cloud/raptor-releases/releases/latest/download/raptor-darwin-arm64
    chmod +x raptor-darwin-arm64 && sudo mv raptor-darwin-arm64 /usr/local/bin/raptor

  Then:
    raptor login

And when raptor is installed but raptor whoami fails, print just the
raptor login line.

Open questions for whoever picks this up:

• Should praxis offer to install raptor, or only tell the user how? Current
  guidance in the skills is deliberately "never install it yourself", so telling
  is probably right.
• Should raptor get a Homebrew cask like praxis has? That would make the message
  one line instead of three, and is arguably the better fix.
• Should praxis status show raptor as "not installed" instead of staying quiet?

🤖 Filed with Claude Code

[anshulsao]

Picking this up — working on it now.

Plan is the small version first: at the end of praxis login and praxis refresh-skills, check for raptor and print the next steps when it is missing or not logged in. That slots in where the freshness notice already runs (cmd/login_setup.go:261), which already knows whether raptor is installed.

Still open, and I'd like input before building:

• Tell the user how to install raptor, or offer to install it for them? The skills currently say "never install it yourself", so telling is probably right.
• Should raptor get a Homebrew cask like praxis? Would turn a three-line message into one line, and is arguably the better fix.
• Should praxis status list raptor as "not installed" instead of staying quiet?

[anshulsao]

Correcting this issue — part of it is already fixed.

I filed it against main at 50972a7. Since then #68 ("raptor profile cross-check", merged 4 Aug) landed internal/raptorstate and added a raptor: line to praxis status. So the claim "praxis says nothing when raptor is missing" is no longer true. My apologies — that part of the issue body is stale.

Current behaviour on main, with raptor absent from PATH:

profile:    snabbit (source: config)
url:        https://6711429322.facetsapp.cloud
raptor:     not installed
logged in:  yes (anshul@facets.cloud)

#68 also already handles the not-logged-in cases with run \raptor login`` hints. Good.

What is still missing, and what I am picking up:

1. not installed does not say why it matters or how to fix it. Two words, no next step.
2. logged in: yes sits directly below, so the output still reads as healthy. There is no "setup is incomplete" signal.
3. There is still no install URL anywhere in the repo.

Scope for part 1 is now just praxis status:

• make the not-installed line actionable (why it matters + how to install)
• add a closing summary line when raptor is missing or not logged in, so the user can tell setup is unfinished

Part 2 (whether praxis login should offer to install raptor, and whether raptor should get a Homebrew cask) stays open for discussion — the cask is probably the better root fix, since it turns three lines of curl+chmod+sudo into one.

[anshulsao]

Part 1 is up as a draft PR: #73

Scope is praxis status only:

• raptor: not installed now points at the releases page
• a closing ⚠ setup incomplete notice, so the output stops scanning as healthy when it isn't
• setup_complete in the JSON, so the skills' raptor preflight can say "run praxis status and follow it" instead of dead-ending

Part 2 (should praxis login offer to install raptor, and should raptor get a Homebrew cask) is still open here.