spaps-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  SpapsHttpClient,
+  SpapsHttpError,
+  buildResourceDefinitions,
+  buildToolDefinitions,
+  createSpapsMcpServer,
+  docsPath,
+  docsPathWithCapturedLeadingSlash,
+  getWizardStep,
+  listWizardSteps,
+  resolveConfig,
+  resolveWizardDir
+} from "./chunk-GPBTYWDD.js";
+export {
+  SpapsHttpClient,
+  SpapsHttpError,
+  buildResourceDefinitions,
+  buildToolDefinitions,
+  createSpapsMcpServer,
+  docsPath,
+  docsPathWithCapturedLeadingSlash,
+  getWizardStep,
+  listWizardSteps,
+  resolveConfig,
+  resolveWizardDir
+};

package/dist/resources/SPAPS_SURFACE_CONTRACT.md

@@ -0,0 +1,125 @@
+# SPAPS Surface Contract
+
+This document defines the public surfaces around SPAPS, what each one owns, and how they are allowed to interact.
+
+The goal is simple: one operator shell, clean integration packages, and no drift where agent skills quietly become a second product interface.
+
+## Core Rule
+
+`spaps` is the self-serve administrator shell.
+
+Everything else either powers that shell, consumes what it provisions, or orchestrates around it.
+
+## Surfaces
+
+| Surface | Driven by | Owns | Must not own | Interface type | Canonical neighbor |
+| --- | --- | --- | --- | --- | --- |
+| `spaps` CLI (`packages/spaps`) | operator, agent, CI | account connect, app select/create, repo bootstrap/attach, local runtime orchestration, verification, machine-readable status | app business logic, framework SDK concerns, skillbox fleet ops, repo archaeology | product-facing shell | talks to `sweetpotato.dev`, local SPAPS runtimes, and repo-local config |
+| `sweetpotato.dev` hosted service | platform | account identity, free tier, app registry, hosted provisioning APIs, billing for hosted surfaces | repo patching, local runtime orchestration, custom implementation workflow | product-facing backend | backs the `spaps` CLI |
+| `spaps-sdk` (`packages/sdk`) | application code | frontend and Node integration against SPAPS auth, entitlements, issue reporting, and related APIs | account signup, app provisioning, repo bootstrap, operator workflows | product-facing library | consumes credentials and config created by `spaps` |
+| Python `spaps` client (`packages/python-client`) | application code, services, scripts | Python access to SPAPS APIs | operator shell behavior, local runtime control, repo mutation | product-facing library | consumes credentials and config created by `spaps` |
+| `spaps-server-quickstart` (`packages/python-server-quickstart`) | backend developers | FastAPI/Celery service scaffolding, auth middleware, endpoint contracts, local-mode behavior, backend templates | hosted account lifecycle, product onboarding shell, portfolio orchestration | product-facing backend scaffold | serves the runtime that `spaps` manages locally |
+| skills (`skills/`, global skills, skillbox overlays) | agent | multi-repo reasoning, wiki/context synthesis, audits, migrations, managed ops, portfolio decisions, workflow composition | stable product contract, end-user onboarding surface, backend API truth | agent-only orchestration | call the CLI, read docs, and coordinate sibling repos |
+
+## Interaction Rules
+
+### 1. Skills decide and compose; CLIs execute and report
+
+Skills may inspect repo state, overlays, plans, the wiki, and sibling repos. They can recommend or sequence work. They should call `spaps` when the task is a real operator action.
+
+`spaps` should perform the action, emit stable human-readable output, and support JSON where agents need a machine contract.
+
+### 2. Provisioning starts in the shell, not in the SDKs
+
+Application packages should assume credentials, app identity, and policy defaults already exist. They consume provisioned state; they do not create it.
+
+### 3. The backend scaffold is not the admin shell
+
+`spaps-server-quickstart` defines runtime capability and local-mode semantics. It should not become the place where account connect, app selection, or repo bootstrap logic lives.
+
+### 4. `sweetpotato.dev` is the hosted backing service, not the primary operator interface
+
+The website and hosted APIs hold account and app state. The shell is still `spaps`.
+
+### 5. Managed operations stay outside the shell
+
+`skillbox` and its overlays own managed boxes, runtime distribution, and higher-trust fleet operations. `buildooor` owns custom implementation work. The `spaps` CLI can hand users toward those layers, but it must not absorb their responsibilities.
+
+## OpenAPI Auth Metadata
+
+Every operation in `docs/api-reference.yaml` must carry standard OpenAPI
+`security` requirements and an `x-spaps-auth` object generated from the
+FastAPI route dependencies.
+
+Allowed `x-spaps-auth.auth_type` values:
+
+| Value | Meaning |
+| --- | --- |
+| `public` | No SPAPS credential required. |
+| `application` | Requires an application API key, with publishable or secret acceptance recorded in `api_key.accepted`. |
+| `application_optional_user` | Requires an application API key and accepts, but does not require, a bearer user token. |
+| `user` | Requires an application API key plus a bearer user token. |
+| `admin` | Requires a secret application key plus a bearer token with the `admin` role. |
+| `super_admin` | Requires a secret application key plus a bearer token with the `super_admin` role. |
+| `stripe_webhook_signature` | Requires a Stripe provider signature instead of a SPAPS application key. |
+| `mailgun_webhook_signature` | Requires a Mailgun provider signature instead of a SPAPS application key. |
+
+The `x-spaps-auth` object is fail-closed: unknown `auth_type`, API key type,
+security scheme, JWT shape, role, or provider-signature scheme values fail
+`npm run docs:validate-openapi`. The canonical generator and validator live in
+`spaps_server_quickstart.openapi_auth` and
+`scripts/validate_openapi_auth_metadata.py`; new route dependencies must update
+those files and the contract tests together.
+
+## Manifest Route Metadata
+
+`docs/manifest.json` version `1.4` is the machine-readable route contract for
+agents, SDK docs, and CLI tooling. Every endpoint entry must carry:
+
+| Field | Type | Source of truth |
+| --- | --- | --- |
+| `auth` | object | `spaps_server_quickstart.openapi_auth.route_auth_metadata()` |
+| `rate_tier` | string | `spaps_server_quickstart.middleware.rate_limiting.get_tier_for_endpoint()` |
+| `publishable_scope` | string array or `null` | `spaps_server_quickstart.middleware.key_scope.publishable_scopes_for_endpoint()` filtered to routes whose auth accepts publishable keys |
+| `entitlement_key` | string or `null` | fixed route-level entitlement gates only |
+
+`auth` uses the same shape and vocabulary as OpenAPI `x-spaps-auth`.
+`publishable_scope` is `null` when a route is public, secret-only, provider
+signed, or otherwise not callable with a publishable SPAPS key. It is an array
+because more than one built-in application blueprint scope may admit the same
+route over time. `entitlement_key` is intentionally `null` for dynamic
+entitlement checks, x402 resource rules, usage policies, and request-provided
+capability controls.
+
+Regenerate the manifest with `npm run docs:generate-manifest`; CI checks the
+checked-in file with `npm run docs:validate-manifest` and fails when route
+coverage or projected metadata drifts from FastAPI and middleware code.
+
+`npm run docs:validate-sdk-parity` also enforces inverse client coverage. For
+each domain in `docs/client-domain-parity.md`, a `yes` cell means that surface
+must claim at least one implemented route in the domain. A backend route may
+temporarily ship before its client helper only with a row in the policy file's
+`Pending Client Coverage Waivers` table, and that row must reference an open
+Bead. Waivers are route-level and expire when the Bead closes.
+
+## Administrator Journey
+
+The intended administrator loop is:
+
+1. `spaps connect`
+2. `spaps bootstrap`
+3. `spaps verify`
+
+Those verbs define the shell:
+
+- `connect`: establish operator identity, free-tier signup/login, and default app context
+- `bootstrap`: attach SPAPS to the current repo or scaffold a new app against the right blueprint
+- `verify`: prove the golden path end to end, including auth, entitlements, and local runtime hints
+
+Other commands should support that loop, not compete with it.
+
+## Present Naming Risk
+
+Today the JavaScript CLI package and the Python client both publish as `spaps`. That is already enough to confuse internal audit tooling and weakens the surface boundary described here.
+
+This document records the contract first. Package renaming, aliasing, or audit-tool disambiguation is a separate follow-on decision.

package/dist/resources/glossary.md

@@ -0,0 +1,36 @@
+# SPAPS Glossary
+
+Canonical terminology for the Sweet Potato Authentication & Payment Service.
+Use these terms in code, API responses, docs, and SDK surface.
+
+## Keys
+
+| Term | Definition |
+|------|-----------|
+| **secret key** | Server-side application credential (`spaps_sec_` prefix). Authenticates backend API calls. Never expose to browsers. Formerly called "API key" — that term is deprecated. |
+| **publishable key** | Client-side application credential (`spaps_pub_` prefix). Safe to embed in browser/mobile code. Scoped to a subset of endpoints configured by the application blueprint. |
+
+## Identity
+
+| Term | Definition |
+|------|-----------|
+| **user** | An authenticated identity within an application. Has an email, optional username, and optional wallet addresses. |
+| **profile** | The public-facing projection of a user: id, email, username, wallets, tier, roles, permissions, and metadata. Returned by `/auth/user`. |
+| **wallet** | A blockchain address linked to a user. Each wallet has a `wallet_address` and `chain_type`. |
+| **wallet_address** | The on-chain address string (e.g. a Solana or Ethereum address). Always lowercase-normalized for EVM chains. |
+
+## Access
+
+| Term | Definition |
+|------|-----------|
+| **tier** | The subscription level of a user. Canonical values: `basic` (default), `premium`, `enterprise`. Drives policy evaluation and rate limiting. |
+| **subscription** | A Stripe-managed billing relationship that determines a user's tier. |
+| **application** | A registered SPAPS client. Owns a secret key, publishable key, settings, and a set of users via memberships. |
+| **entitlement** | A granted capability or resource access. Projected per-user via policy evaluation. Types: `access`, `feature`, `quota`. |
+
+## Deprecated Terms
+
+| Deprecated | Replacement |
+|-----------|------------|
+| `api_key` (in API responses) | `secret_key` |
+| `API key` (in docs/copy) | "secret key" or "publishable key" (be specific) |

package/dist/resources/llms.txt

@@ -0,0 +1,15 @@
+# Sweet Potato llms.txt
+# Source file copied to docs.sweetpotato.dev by deploy/reverse-proxy/sync-docs.sh.
+
+/index.md | Sweet Potato documentation index and source-of-truth pointer.
+/docs/agents/AGENT_QUICKSTART.md | Agent quickstart for local mode, API keys, auth flows, verification, capability checks, and tool-spec generation.
+/docs/manifest.json | Endpoint manifest with path, category, docs, tests, and consumer-facing tags.
+/docs/api-reference.yaml | OpenAPI contract for SPAPS HTTP routes and schemas.
+/docs/guides/authentication-methods.md | Canonical authentication method matrix, security caveats, rate tiers, key requirements, and TypeScript/Python examples.
+/docs/guides/email-authentication.md | Password, OIDC, SMS, WebAuthn, magic-link, MFA, password reset, and email-delivery auth guide.
+/docs/guides/magic-link-authentication.md | Magic-link request and verification behavior, including MFA challenge handling.
+/packages/sdk/README.md | TypeScript SDK usage for auth, payments, sessions, entitlements, access, graph, and domain helpers.
+/packages/python-client/README.md | Python SDK usage for sync and async auth, MFA, OIDC, WebAuthn, payments, sessions, and domain helpers.
+/packages/spaps/AI_TOOLS.json | Generated OpenAI-style SPAPS tool spec for agent callers.
+/docs/manifest.json tags | admin-stripe, affiliate-referrals, agent, agent-approvals, app-links, apply-log, attribution, audit, auth, authorization, authz, billing-accounts, capability-graph, cfo, controlled-reveal, crypto-payments, dayrate, dev, device-flow, discovery, docs, elevenlabs, email, entitlements, experiments, features, fixtures, governance, handoff, health, history, hosted-assets, idempotency, insights, invitations, issue-reporting, ledger, local, marketing-events, memberships, notifications, operator-control-plane, other, outbox, paid-resources, paid-review, payments, policies, privacy, project-grants, publishable-key, realtime, receipts, reporter-thread, results, reviews, rollups, screenshots, secret-key, secure-messages, security, self-service, service-admin, sessions, short-links, skill-evals, status, stripe, stripe-webhooks, support-triage, triage, usage, user-messaging, users, voice, webhooks, whitelist, x402.
+/sweet-potato-logo.jpg | Sweet Potato brand image.

package/dist/wizard/step-01-setup.md

@@ -0,0 +1,149 @@
+# SPAPS Integration Step 1/12: Project Setup & Dependencies
+
+## Your Current Task
+
+You are setting up a new Next.js application with SPAPS integration. This is the foundation - getting this right is critical.
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items (copy this list):
+
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Create Next.js app with TypeScript and App Router", status: "pending", activeForm: "Creating Next.js app with TypeScript and App Router" },
+    { content: "Initialize shadcn/ui with Default style and Slate base color", status: "pending", activeForm: "Initializing shadcn/ui with Default style and Slate base color" },
+    { content: "Install spaps-sdk from npm (version 1.0.1)", status: "pending", activeForm: "Installing spaps-sdk from npm" },
+    { content: "Install spaps CLI in devDependencies", status: "pending", activeForm: "Installing spaps CLI in devDependencies" },
+    { content: "Install concurrently in devDependencies", status: "pending", activeForm: "Installing concurrently in devDependencies" },
+    { content: "Update package.json dev script to run spaps local", status: "pending", activeForm: "Updating package.json dev script" },
+    { content: "Verify all dependencies are correctly installed", status: "pending", activeForm: "Verifying dependencies" },
+    { content: "Request step 2 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Step-by-Step Instructions
+
+### 1. Create Next.js Application
+```bash
+npx create-next-app@latest spaps-demo --typescript --tailwind --app --no-src-dir --import-alias "@/*"
+cd spaps-demo
+```
+
+### 2. Setup shadcn/ui
+```bash
+npx shadcn@latest init
+```
+When prompted, choose:
+- ✅ Style: **Default** (NOT New York)
+- ✅ Base color: **Slate**
+- ✅ CSS variables: **Yes**
+
+### 3. Install SPAPS SDK
+```bash
+npm install spaps-sdk
+```
+⚠️ **CRITICAL**: The package is `spaps-sdk` NOT:
+- ❌ @sweet-potato/sdk
+- ❌ @sweetpotato/sdk  
+- ❌ sweet-potato-sdk
+
+### 4. Install Development Dependencies
+```bash
+npm install -D spaps concurrently
+```
+
+### 5. Update package.json Scripts
+Edit package.json and update the dev script:
+```json
+{
+  "scripts": {
+    "dev": "concurrently \"npx spaps local\" \"next dev\"",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  }
+}
+```
+
+## Validation Checklist
+
+Before marking this step complete, verify:
+
+✅ **package.json** contains:
+```json
+{
+  "dependencies": {
+    "spaps-sdk": "^1.0.1",
+    "next": "^15.0.0",
+    // ... other deps
+  },
+  "devDependencies": {
+    "spaps": "^0.3.2",
+    "concurrently": "^8.0.0",
+    // ... other dev deps
+  }
+}
+```
+
+✅ **Dev script** includes both commands:
+```json
+"dev": "concurrently \"npx spaps local\" \"next dev\""
+```
+
+✅ **shadcn/ui** is configured with:
+- components.json exists
+- Uses Default style (not New York)
+- Uses Slate as base color
+
+✅ **Project structure** has:
+- app/ directory (App Router)
+- TypeScript configured
+- Tailwind CSS working
+
+## Common Mistakes to Avoid
+
+❌ **Wrong package name**: Using @sweet-potato/sdk instead of spaps-sdk
+❌ **Missing concurrently**: Not installing or using concurrently
+❌ **Wrong dev script**: Not including spaps local command
+❌ **Wrong shadcn style**: Choosing New York instead of Default
+❌ **Missing TypeScript**: Creating JavaScript project instead
+
+## Testing Your Setup
+
+Run this command to test:
+```bash
+npm run dev
+```
+
+You should see:
+- SPAPS starting on port **3301** (NOT 3000, 3300, or 3456)
+- Next.js starting on port 3000
+- No dependency errors
+
+## Next Step
+
+When ALL todos are ✅ complete and validation passes:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 2
+})
+```
+
+## Need Help?
+
+If you're stuck, create a detailed task describing the issue:
+```javascript
+mcp__product-manager__create_task({
+  project: "spaps-integration",
+  description: "Step 1 Blocker: [specific issue description]",
+  category: "bug",
+  priority: "high"
+})
+```
+
+Remember: **Get this foundation right!** All subsequent steps depend on correct setup.

package/dist/wizard/step-02-environment.md

@@ -0,0 +1,291 @@
+# SPAPS Integration Step 2/12: Environment Configuration
+
+## Prerequisites Check
+
+Before starting, confirm you have completed:
+- ✅ Step 1: Project setup with all dependencies installed
+- ✅ Next.js app created with TypeScript
+- ✅ shadcn/ui initialized
+- ✅ spaps-sdk and spaps CLI installed
+
+## Required TodoWrite List
+
+Create a TodoWrite with EXACTLY these items:
+
+```javascript
+	TodoWrite({
+	  todos: [
+	    { content: "Create .env.local file in project root", status: "pending", activeForm: "Creating .env.local file" },
+	    { content: "Set NEXT_PUBLIC_SPAPS_API_URL to http://localhost:3301", status: "pending", activeForm: "Setting API URL to port 3301" },
+	    { content: "Add SPAPS_API_KEY configuration", status: "pending", activeForm: "Adding API key configuration" },
+	    { content: "Add admin credentials for later use", status: "pending", activeForm: "Adding admin credentials" },
+	    { content: "Create .env.local.example for documentation", status: "pending", activeForm: "Creating example env file" },
+    { content: "Add .env.local to .gitignore", status: "pending", activeForm: "Adding to gitignore" },
+    { content: "Verify environment variables are loaded", status: "pending", activeForm: "Verifying environment setup" },
+    { content: "Request step 3 of SPAPS integration wizard", status: "pending", activeForm: "Requesting next step" }
+  ]
+})
+```
+
+## Environment Configuration
+
+### 1. Create .env.local File
+
+In your project root (same level as package.json), create `.env.local`:
+
+```bash
+touch .env.local
+```
+
+### 2. Add Environment Variables
+
+⚠️ **CRITICAL**: The port MUST be 3301, not 3000, 3300, or 3456!
+
+```env
+# .env.local
+
+# SPAPS Configuration - Port 3301 is REQUIRED
+NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3301
+SPAPS_API_KEY=test_key_local_dev_only
+
+# Admin Credentials (for whitelist/admin operations)
+NEXT_PUBLIC_ADMIN_EMAIL=admin@example.com
+NEXT_PUBLIC_ADMIN_PASSWORD=Admin123!
+
+# App Configuration
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Optional: For production (not available yet)
+# NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.dev
+# SPAPS_API_KEY=your_production_api_key_here
+```
+
+### 3. Create .env.local.example
+
+Create a template for other developers:
+
+```env
+# .env.local.example
+
+# SPAPS Configuration (Port 3301 is standardized)
+NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3301
+SPAPS_API_KEY=test_key_local_dev_only
+
+# Admin credentials for whitelist/admin operations
+NEXT_PUBLIC_ADMIN_EMAIL=admin@example.com
+NEXT_PUBLIC_ADMIN_PASSWORD=your_admin_password_here
+
+# Next.js Configuration
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Note: SPAPS runs on port 3301 in this repository
+# Production API not yet available
+```
+
+### 4. Update .gitignore
+
+Make sure `.env.local` is NOT committed:
+
+```gitignore
+# Environment variables
+.env*.local
+.env.local
+
+# Keep the example file
+!.env.local.example
+```
+
+### 5. Verify Configuration
+
+Create a test file to verify environment variables:
+
+```typescript
+// app/api/test-env/route.ts
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  return NextResponse.json({
+    apiUrl: process.env.NEXT_PUBLIC_SPAPS_API_URL,
+    hasApiKey: !!process.env.SPAPS_API_KEY,
+    hasAdminEmail: !!process.env.NEXT_PUBLIC_ADMIN_EMAIL,
+    nodeEnv: process.env.NODE_ENV
+  })
+}
+```
+
+Test it:
+```bash
+curl http://localhost:3000/api/test-env
+```
+
+Should return:
+```json
+{
+  "apiUrl": "http://localhost:3301",
+  "hasApiKey": true,
+  "hasAdminEmail": true,
+  "nodeEnv": "development"
+}
+```
+
+## Important Port Information
+
+### Why Port 3301?
+
+This repository's SPAPS server defaults to port 3301.
+- ✅ 3301 - Correct SPAPS port here
+- ❌ 3000 - This is your Next.js app
+- ❌ 3300 - Old port (legacy)
+- ❌ 3456 - Old port used in previous docs
+- ❌ 8080 - Wrong, not SPAPS
+
+### Running Both Servers
+
+Your `package.json` dev script (from Step 1) runs both:
+```json
+"dev": "concurrently \"npx spaps local\" \"next dev\""
+```
+
+This starts:
+- SPAPS on `http://localhost:3301`
+- Next.js on `http://localhost:3000`
+
+## Environment Variable Naming
+
+### Public vs Private Variables
+
+- `NEXT_PUBLIC_*` - Available in browser and server
+- Without prefix - Server-side only
+
+```typescript
+// Browser accessible
+process.env.NEXT_PUBLIC_SPAPS_API_URL ✅
+
+// Server-only
+process.env.SPAPS_API_KEY ✅ (backend only)
+```
+
+## Validation Checklist
+
+✅ **File Structure**:
+- `.env.local` exists in project root
+- `.env.local.example` created for documentation
+- `.gitignore` updated to exclude `.env.local`
+
+✅ **Configuration Values**:
+- `NEXT_PUBLIC_SPAPS_API_URL` = `http://localhost:3301`
+- Port is 3301 (NOT 3000, 3300, or 3456)
+- API key is set to `test_key_local_dev_only`
+- Admin credentials are configured
+
+✅ **Testing**:
+- Environment variables load correctly
+- Test endpoint returns expected values
+- No errors in console
+
+## Common Mistakes to Avoid
+
+❌ **Wrong port**:
+```env
+# WRONG
+NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3000  # This is Next.js
+NEXT_PUBLIC_SPAPS_API_URL=http://localhost:3300  # Old port
+```
+
+❌ **Missing NEXT_PUBLIC prefix**:
+```env
+# WRONG - Won't be available in browser
+SPAPS_API_URL=http://localhost:3301
+```
+
+❌ **Committing secrets**:
+```gitignore
+# WRONG - Forgot to add to .gitignore
+# .env.local will be committed!
+```
+
+❌ **Using production URL**:
+```env
+# WRONG - Production not available yet
+NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.dev
+```
+
+## Testing Your Setup
+
+Run this command to verify SPAPS is accessible:
+
+```bash
+# Start your dev server first
+npm run dev
+
+# In another terminal, test SPAPS
+curl http://localhost:3301/health
+```
+
+Should return:
+```json
+{
+  "status": "ok",
+  "mode": "local",
+  "version": "0.3.2"
+}
+```
+
+## Troubleshooting
+
+### Port Already in Use
+
+If port 3301 is already in use:
+```bash
+# Find what's using port 3301
+lsof -i :3301
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Environment Variables Not Loading
+
+1. Restart your dev server
+2. Check file is named exactly `.env.local`
+3. Verify you're in the project root
+4. Try clearing Next.js cache:
+```bash
+rm -rf .next
+npm run dev
+```
+
+### SPAPS Not Starting
+
+Check your package.json dev script:
+```json
+"dev": "concurrently \"npx spaps local\" \"next dev\""
+```
+
+## Security Notes
+
+⚠️ **Never commit real credentials**:
+- Use `.env.local` for local development
+- Use environment variables in production
+- Never hardcode API keys in code
+- Admin passwords should be strong
+
+## Next Step
+
+When ALL todos are ✅ complete and environment is configured:
+
+```javascript
+mcp__product-manager__get_agent_instructions({
+  category: "spaps-integration",
+  project: "spaps-demo",
+  step: 3
+})
+```
+
+## Summary
+
+Environment configuration is critical for SPAPS integration:
+- **Port 3301** is the standard in this repository
+- **NEXT_PUBLIC_** prefix for browser-accessible variables
+- **Never commit** `.env.local` file
+- **Always test** your configuration before proceeding