Solutions Consultant Field Kit

Source verification invokes the sibling executable at packages/spaps/bin/spaps.js. It does not prove that registry-resolved npx spaps currently resolves the same artifact.

This path was executed on 2026-09-03 against the current sibling source with:


node scripts/verify-upstream-first-run.mjs --include-writes --upstream ../sweet-potato \
  --receipt docs/evidence/2026-09-03-first-run.json

That proof completed the CLI version check, quickstart, verify, tools, React scaffold, fixture initialization, and fixture application: 7/7 checks passed. It used a disposable directory and the local-mode service; it is not production or billing proof. The machine-readable receipt binds the result to the tested Sweet Potato SHA.

Use this page when you need to show how an app can move from a local demo toward a governed implementation path. The executed workshop proves CLI/runtime/scaffold/fixture readiness. Billing, webhook, and entitlement rows below explain the target control plane; they are not executed revenue proof. SPAPS leaves enterprise IAM, AI governance, and full backend-platform concerns to the customer’s existing stack.

Wedge question: can you prove the governed local integration path in under one hour, then identify the separate billing, entitlement, webhook, and production evidence still required?

What This Proves Or Locates

Proof point	Customer question it answers	Where to go deeper
Local runtime	Can the team inspect the control plane before committing infrastructure?	Local runtime
Application identity	Which app is calling, and which origins are allowed?	API keys and origins
User identity	Who is acting, and how does local mode differ from production auth?	Auth and local mode
Revenue workflow map	Where would payment state become feature access?	Billing and entitlements
Webhook trust	How are provider and outbound events signed, scoped, and reconciled?	Webhooks and event delivery
Production guardrails	What fails closed before unsafe config receives traffic?	Security invariants
Agent-readable tooling	Can an agent or operator inspect available commands and contracts?	SPAPS CLI quickstart

Skills And Agent Handoff

The field kit should leave an agentic engineer with an executable next step. Use these Sweet Potato-related skills as the operator layer around the workshop. They are strongest when they are framed as adoption accelerators, support loops, and drift checks rather than as product claims.

Skill	Use it when	What it proves
`issue-reporting-setup`	A frontend already has SPAPS auth and needs user-facing issue capture	The customer can add page-level or component-level feedback without inventing a separate reporting stack.
`spaps-feedback`	Reported issues need triage after the app is live or in pilot	Support can pull SPAPS issue reports, match them to the right owning skill, and route the next fix deliberately.
`sweet-potato-usage-audit`	A team has one or more repos consuming SPAPS packages, SDKs, or APIs	Agentic engineers can scan for auth misuse, package drift, stale examples, local-dev drift, and duplicated integration code.
`bookme`	The demo needs a concrete revenue workflow instead of an abstract entitlement example	Bookme/dayrate shows a real SPAPS-backed booking, pricing, checkout, and backend integration path.
`documentation-website-for-software-project`	The customer wants a durable leave-behind or internal enablement site	The implementation can produce a navigable Nextra doc site from the source repo instead of leaving the team with only meeting notes.

Keep general repo-maintenance skills out of the sales path unless they directly advance the customer’s implementation. For this page, skills should answer: can we integrate, audit, support, or explain the SPAPS-backed app after the workshop?

60-Minute Workshop

Frame the implementation risk

Ask what must be true before an AI or agentic app can authenticate a user, charge the right account, grant access to a paid feature, and prove what happened later. Keep the answer app-level: SPAPS supplies the product control plane and leaves enterprise-wide identity or governance to the customer’s existing systems.

Start the runtime


npx spaps local
npx spaps status
npx spaps quickstart --json

The quickstart output shows mode-aware hints so the room can see whether the demo is using local mode or a provisioned application.

Create a demo app contract


npx spaps create governed-demo --template react --dir governed-demo

Use the provisioning result to talk through the application record, publishable keys, allowed origins, and the generated environment file.

Apply fixtures for repeatable proof


npx spaps fixtures init --dir governed-demo --base-url http://localhost:5173
npx spaps fixtures apply --dir governed-demo --base-url http://localhost:5173

Fixtures make the workshop repeatable. They also leave artifacts under .spaps/ that an implementation team can inspect after the call.

Show the revenue-to-access path

Walk the customer through the control-plane shape:

Use Billing and entitlements for the model, then show Security invariants for the fail-closed checks.

Close with machine-readable verification


npx spaps verify --json
npx spaps tools --json

The leave-behind is not a slide. It is the command output, fixture state, and links to the exact docs that explain each control.

Hand off the next skill

Pick the next operator skill while the implementation context is still fresh:


issue-reporting-setup        # add feedback capture to the app
sweet-potato-usage-audit     # scan existing repos for SPAPS drift
bookme                       # turn the demo into a revenue workflow
documentation-website-for-software-project  # generate the customer-facing docs site

That handoff makes the workshop useful to both the solutions consultant and the agentic engineer who inherits the work.

Expected Signals And Failure Interpretation

Validate the scenario from this docs repo before a workshop or after changing the field kit:


npm run first-run:dry-run
npm run first-run:live -- --json

Step	Expected signal	If it fails
`npx spaps local`	Runtime starts or reports the existing local runtime	Use Local runtime and Troubleshooting; record runtime-source or port blockers
`npx spaps quickstart --json`	JSON output names local-mode or provisioning hints	Treat missing mode hints as runtime metadata failure, not as proof that the app contract is wrong
`npx spaps create governed-demo --template react`	Provisioning returns `provisioned`, `local_mode`, or `scaffold_only`	`scaffold_only` is acceptable only if the leave-behind names the server or `SELF_SERVICE_PASSWORD` blocker
`npx spaps fixtures apply --base-url http://localhost:5173`	`.spaps/` fixture artifacts are written for repeatable app, users, roles, entitlements, and browser replay state	Check the frontend base URL and runtime mode before continuing the workshop
`npx spaps verify --json`	Runtime and auth checks produce machine-readable pass/fail details	Include failed checks in the leave-behind with the next implementation action
`npx spaps tools --json`	Runtime and domain command contracts are printable for an agent or operator	If unavailable, hand off to CLI/runtime diagnostics before promising agent-readable tooling

Objection Handling

Objection	Response
We already have Okta, Entra, or Auth0	Keep them. SPAPS is for app-level identity, API keys, billing projection, and entitlement decisions around the product surface.
We need full AI governance	SPAPS does not claim to be the AI governance layer. It gives the app a concrete identity and revenue control plane that can plug into the customer’s governance stack.
This looks early	Treat SPAPS as a proof surface and implementation substrate. Do not claim category maturity, compliance certification, or benchmark leadership without project-specific evidence.
We need custom workflows	Use the field-kit output as the brief: which app, which origins, which auth mode, which payment trigger, which entitlement, and which verification commands passed.

Leave-Behind Artifacts

spaps quickstart --json output for the selected mode.
spaps verify --json output for runtime and auth checks.
.spaps/ fixture files for app, users, roles, entitlements, and browser state.
The revenue-to-access diagram from this page.
The selected next skill and the reason it was selected.
Links to the specific docs used to answer security, billing, webhook, and production-readiness questions.

Follow-On Work

When the demo becomes implementation work, turn the workshop notes into a short brief:

Brief field	Example
Application	`governed-demo` or the customer’s real app slug
Auth mode	Local persona, email magic link, wallet, or JWT-backed session
Revenue trigger	Checkout, subscription, manual grant, or wallet payment
Entitlement	The feature key that paid users should receive
Next skill	`issue-reporting-setup`, `sweet-potato-usage-audit`, `bookme`, or a project-specific operator skill
Verification	The `spaps verify --json` result and any failed checks
Production boundary	Origins, secrets, webhook destinations, and startup invariants
Troubleshooting row	Link to the matching row in Troubleshooting when a command fails

For release-governed docs changes, use SPAPS docs release governance before the leave-behind is reused with a new upstream runtime or package version.

That brief is the handoff from field demo to implementation. It keeps the next step grounded in a working control-plane contract instead of a loose architecture conversation.