@soloworks/smking-wizard

AI-powered install wizard for Page Zero SDKs. One command installs the SDK, configures your .env, and verifies the installation.

npx @soloworks/smking-wizard@latest

Supported frameworks: Laravel (smking/laravel) and Next.js (@soloworks/smking-next).

What the wizard does

1. Opens your browser to log in to Page Zero (OAuth)
2. Detects your framework (Laravel or Next.js App Router)
3. Runs the install command sequence (composer require / pnpm add)
4. Writes SMKING_API_KEY + SMKING_BASE_URL to your .env
5. Lets you choose AEO + SEO, Blog only, or both
6. Wires only the selected surfaces; Blog-only leaves AEO + SEO disabled
7. Runs the framework doctor and, for Next.js, a real production build
8. If a check fails, an AI agent attempts a targeted repair
9. If the agent gives up, posts a structured failure ticket to Page Zero support

What the wizard will NEVER do

• Commit, push, stash, or otherwise mutate git state — you review the diff yourself
• Read or upload your .env values to any server
• Run destructive commands (rm, drop, migrate:fresh, etc.)
• Modify environment variables other than SMKING_*
• Install packages other than the Page Zero SDK for your framework

The agent is restricted to project files and cannot read .env directly. Package installation, environment writes, doctor checks, Laravel commands, Blog routes, and the Next.js build use typed handlers with narrow allowlists. Raw shell access is not available.

Requirements

• Node 20.10+
• A clean git working tree (the wizard wants its diff to be unambiguous — override with --allow-dirty)
• Not a production-like environment (override with --allow-prod)

Flags

--debug          Verbose debug output (also writes to /tmp/smking-wizard.log)
--allow-prod     Override production-environment refusal
--allow-dirty    Override the git-status-must-be-clean check
--resume <id>    Resume an interrupted run from the same project directory
--version        Print version
--help           Print usage

Environment variables

SMKING_SAAS_URL          Override the SaaS origin the wizard talks to.
                         Default: https://getpagezero.com.
                         Set to http://localhost:3001
                         for local dev against a `pnpm dev` SaaS.
SMKING_WIZARD_CLIENT_ID  Override the OAuth client_id (default: smking_wizard_v1).
                         Only useful when running against a custom SaaS
                         deploy that registered a different client.

How LLM cost works

Wizard LLM calls go through the Page Zero gateway. You do not need Claude credits or an Anthropic API key — Page Zero supplies the install session. The model may change server-side without requiring a wizard release.

Quota caps (enforced server-side):

• 200,000 tokens per wizard session
• 5 sessions per user per day

If you hit the daily limit during testing, wait until UTC midnight or contact Page Zero support.

The full session ID appears while the agent runs. If the process is interrupted, resume it from the same project directory with:

npx @soloworks/smking-wizard@latest --resume <session-id>

For SSH / remote dev environments

The wizard opens your browser via open. If you're SSH'd into a remote machine, that won't work — but the TUI also prints the OAuth URL as text. Copy that URL to a browser on your laptop, log in, and the wizard's localhost callback will catch the redirect (because the laptop's browser proxies the localhost callback to your SSH tunnel — assuming you've set up port forwarding for one of 8235-8240).

For headless CI: not yet supported. CI mode (--ci with a personal API key) is on the roadmap.

How to debug a failed install

If the doctor check fails and the agent can't fix it after 3 retries, the wizard automatically files a ticket to Page Zero support with:

• Which checks failed (structured list)
• Your environment (Node / PHP / framework versions)
• Raw doctor output

You'll see a ticket ID printed (dr_xxxxxxxxxxxx). Page Zero support can look it up directly — no need to send a separate email with logs.

License

MIT. See LICENSE.