Onboarding flow: 2 real bugs + 1 doc gap blocking first-agent setup

[vks-archastro]

Walked through the documented onboarding instructions end-to-end (brew install, archagent setup, archagent auth login <email>, archagent install agentsample archastro-onboarding, embed). Agent did go live, but two real CLI bugs would trip up a first-time user and one doc gap needs to be filled.

1. archagent auth status reports Authenticated when the org session is expired (CLI bug)

Repro:

1. archagent auth status → prints Status: Authenticated
2. archagent list agents → Org session expired or missing. Run: archagent auth login <email>

The two commands disagree. A first-time user runs auth status, sees a green light, then every command fails with Org session expired and there's nothing in the status output to tell them how to recover.

Fix options:

• Have auth status actually probe the org session (or check token expiry) before reporting Authenticated.
• If session is expired, print Status: Session expired — run \archagent auth login `instead ofAuthenticated`.

2. /agents:embed doesn't work right after archagent setup — needs Claude Code restart (UX bug)

archagent setup installs the Claude Code plugin to ~/.claude/plugins/... and the setup output does say Restart Claude Code/Codex for plugin changes to take effect. But step 3 of the documented onboarding flow ("Claude Code → /agents:embed") doesn't repeat that warning, so users who follow the docs linearly will type /agents:embed in their current Claude Code session and the slash command won't exist.

Fix options:

• Add an explicit "Restart Claude Code, then run /agents:embed" line to step 3 of the docs.
• Better: have the Claude Code plugin support hot-reload, or have archagent setup detect a running Claude Code session and prompt the user to restart.

3. Doc gap: archagent install agentsample fails inside a directory bound to a different app

Not a fresh-user blocker, but a sharp edge for returning users. If you run archagent install agentsample archastro-onboarding inside a project that already has an archagent.json pointing to a different app than the one you've authenticated against, the install fails with Org session expired or missing — even though you just successfully logged in to the default app.

Fix options (any of):

• Doc note in step 2: "Run these from a fresh directory (e.g. mkdir my-agent && cd my-agent)."
• CLI: when the project's pinned app has no session, fall back to the authenticated default app and warn, rather than failing with a misleading "session expired" message.

Out of scope (not bugs)

• The login URL needs to be visible in the user's terminal (true of any browser-SSO CLI; only a problem if wrapped).
• Staging/prod environment differences (irrelevant for external users — prod is the default).

Context

• CLI version: 0.32.0
• Server: staging (https://staging.platform.archastro.ai)
• Sample tested: archastro-onboarding@v0.1.4 — installed successfully once moved to a fresh directory