aiox-core 5.0.7 → 5.0.8

package/docs/guides/pro/access-grant-ops-playbook.md

@@ -0,0 +1,370 @@
+# Playbook: AIOX Pro Access Grant Ops
+
+**Status:** Validated on 2026-04-20
+**Primary operator:** `@devops`
+**Source story:** `PRO-11.1`
+
+---
+
+## Objective
+
+Grant or restore AIOX Pro access for a user without rediscovering the backend flow each time.
+
+This playbook is based on the live contract validated against:
+
+- License server: `https://aiox-license-server.vercel.app`
+- Vercel project: `aiox-license-server`
+- Vercel project id: `prj_URy89BjALJ8vMKcYQHJa1N2GLXle`
+- Vercel team id: `team_KZMs9FZJuVgsxQFZZp8I1p9t`
+- Supabase project ref: `evvvnarpwcdybxdvcwjh`
+
+---
+
+## System Of Record
+
+### Backend tables and auth surfaces
+
+- `public.buyers`
+  - Entitlement oracle for buyer status.
+  - Required by `validate_buyer` and by `POST /api/v1/auth/check-email`.
+- `public.buyer_validations`
+  - Local 24h cache and support fallback.
+  - Can be used as a positive local override when the upstream buyer RPC is unavailable.
+- `auth.users`
+  - Account existence oracle.
+- `licenses`
+  - Active Pro license storage.
+  - `POST /api/v1/auth/activate-pro` creates a license when missing and is idempotent when one already exists.
+
+### Live auth endpoints
+
+- `POST /api/v1/auth/check-email`
+  - Request: `{ "email": "user@example.com" }`
+  - Response: `{ isBuyer, hasAccount, email }`
+- `POST /api/v1/auth/login`
+  - Request: `{ "email": "...", "password": "..." }`
+  - Response includes `accessToken`
+- `POST /api/v1/auth/verify-status`
+  - Request: `{ "accessToken": "..." }`
+  - Response: `{ email, emailVerified }`
+- `POST /api/v1/auth/activate-pro`
+  - Request: `{ "accessToken": "...", "machineId": "...", "version": "...", "aioxCoreVersion": "..." }`
+  - Response on first activation: `201` with `licenseKey`
+  - Response on reinstall: `200` with existing `licenseKey`
+
+---
+
+## Decision Tree
+
+### Case A: `isBuyer=false` and `hasAccount=false`
+
+You must grant entitlement first, then create the account.
+
+1. Upsert a positive row in `public.buyers`.
+2. Create or confirm the auth user with the requested password.
+3. Confirm the email.
+4. Optionally seed `public.buyer_validations` if you want a local support override immediately available.
+5. Validate with `check-email`, `login`, `verify-status`, and `activate-pro`.
+
+### Case B: `isBuyer=true` and `hasAccount=false`
+
+The entitlement already exists. Only create the auth user, confirm email, and validate.
+
+### Case C: `isBuyer=true` and `hasAccount=true`
+
+The user already exists. Only reset password if requested, confirm email status if needed, then validate `login` and `activate-pro`.
+
+### Case D: `check-email` fails with buyer service unavailable
+
+Treat this as an upstream buyer validation issue.
+
+1. Confirm `public.buyers` contains an active row for the email.
+2. Seed `public.buyer_validations` with `is_valid=true` for the target user.
+3. Retry `check-email` and `activate-pro`.
+
+---
+
+## Step-By-Step Operator Runbook
+
+## Dedicated DevOps Aliases
+
+For repeat operations, prefer these `@devops` commands:
+
+- `@devops *pro-access-grant EMAIL SENHA`
+- `@devops *pro-check-access EMAIL`
+- `@devops *pro-request-reset EMAIL`
+- `@devops *pro-resend-verification EMAIL`
+- `@devops *pro-reset-password EMAIL NOVA_SENHA`
+- `@devops *pro-validate-login EMAIL SENHA`
+- `@devops *pro-verify-status ACCESS_TOKEN`
+- `@devops *pro-activate ACCESS_TOKEN [MACHINE_ID] [VERSION]`
+
+### 1. Preflight
+
+Run:
+
+```bash
+curl -sS https://aiox-license-server.vercel.app/api/v1/auth/check-email \
+  -H 'content-type: application/json' \
+  -d '{"email":"TARGET_EMAIL"}'
+```
+
+Expected outputs:
+
+- `isBuyer=true` means entitlement exists.
+- `hasAccount=true` means `auth.users` already contains the email.
+
+### 2. Grant buyer entitlement in Supabase
+
+Use the Supabase SQL editor for project `evvvnarpwcdybxdvcwjh` and run:
+
+```sql
+insert into public.buyers (email, source, is_active, metadata)
+values (
+  lower(trim('TARGET_EMAIL')),
+  'manual_support',
+  true,
+  jsonb_build_object(
+    'granted_by', 'devops',
+    'reason', 'manual_aiox_pro_access_grant',
+    'granted_at', now()
+  )
+)
+on conflict (email)
+do update set
+  source = excluded.source,
+  is_active = true,
+  metadata = coalesce(public.buyers.metadata, '{}'::jsonb) || excluded.metadata;
+```
+
+Rules:
+
+- Always normalize to lowercase email.
+- Always set `is_active = true`.
+- Use `source='manual_support'` for manual support grants.
+
+### 3. Create or update the auth user
+
+Preferred path: Supabase Auth dashboard for the same project.
+
+Required values:
+
+- Email: requested customer email
+- Password: requested or support-default password
+- Email confirmed: `true`
+
+If the user already exists:
+
+- update the password if support explicitly asked for a reset
+- ensure the email is confirmed
+
+If you need an API path instead of the dashboard, use the same admin capability the server uses (`supabaseAdmin.auth.admin.createUser`).
+
+### 4. Seed the local buyer validation fallback
+
+Do this when:
+
+- buyer RPC is unstable
+- you want support override resilience
+- `check-email` still returns buyer false right after the grant
+
+First fetch the auth user id for the email, then run:
+
+```sql
+insert into public.buyer_validations (user_id, email, is_valid, validated_at, expires_at)
+values (
+  'TARGET_USER_ID',
+  lower(trim('TARGET_EMAIL')),
+  true,
+  now(),
+  now() + interval '24 hours'
+)
+on conflict (user_id)
+do update set
+  email = excluded.email,
+  is_valid = true,
+  validated_at = now(),
+  expires_at = now() + interval '24 hours';
+```
+
+### 5. Validate the API flow directly
+
+Run in order.
+
+#### 5.1 `check-email`
+
+```bash
+curl -sS https://aiox-license-server.vercel.app/api/v1/auth/check-email \
+  -H 'content-type: application/json' \
+  -d '{"email":"TARGET_EMAIL"}'
+```
+
+Expected:
+
+- `isBuyer=true`
+- `hasAccount=true`
+
+#### 5.2 `login`
+
+```bash
+curl -sS https://aiox-license-server.vercel.app/api/v1/auth/login \
+  -H 'content-type: application/json' \
+  -d '{"email":"TARGET_EMAIL","password":"TARGET_PASSWORD"}'
+```
+
+Expected:
+
+- `200`
+- response contains `accessToken`
+
+#### 5.3 `verify-status`
+
+```bash
+curl -sS https://aiox-license-server.vercel.app/api/v1/auth/verify-status \
+  -H 'content-type: application/json' \
+  -d '{"accessToken":"ACCESS_TOKEN"}'
+```
+
+Expected:
+
+- `emailVerified=true`
+
+#### 5.4 `activate-pro`
+
+```bash
+curl -sS https://aiox-license-server.vercel.app/api/v1/auth/activate-pro \
+  -H 'content-type: application/json' \
+  -d '{
+    "accessToken":"ACCESS_TOKEN",
+    "machineId":"ops-validation-machine",
+    "version":"5.0.3",
+    "aioxCoreVersion":"5.0.3"
+  }'
+```
+
+Expected:
+
+- first activation: `201` with `licenseKey`
+- reinstall or already-provisioned user: `200` with message similar to `License restored`
+
+### 6. Validate the guided installer as the user
+
+This story validated both paths below with:
+
+- email: `costa.wanderl@gmail.com`
+- password: `AioxPro2026!`
+- result: success in source install and packaged install
+
+#### 6.1 Source checkout path
+
+```bash
+node bin/aiox.js install
+```
+
+Wizard choices used in validation:
+
+1. `Portugues`
+2. `Modo Avancado`
+3. `Greenfield`
+4. IDEs: `Claude Code` and `Codex CLI`
+5. tech preset: `nextjs-react`
+6. edition: `Pro`
+7. activation method: `Login ou criar conta`
+8. user email and password
+
+Expected success signals:
+
+- `Conteudo Pro instalado`
+- final verification report shows `Overall Status: All checks passed`
+- generated project contains:
+  - `.claude/skills`
+  - `.claude/commands`
+  - `.codex/skills`
+
+#### 6.2 Packaged tarball path
+
+Pack first:
+
+```bash
+npm pack
+```
+
+Then validate from a clean target directory:
+
+```bash
+npm exec --yes --package=/absolute/path/to/aiox-core-<version>.tgz aiox-core -- install
+```
+
+Use the same wizard answers and expect the same success signals.
+
+---
+
+## Validated Results From 2026-04-20
+
+### Direct API smoke test
+
+Validated against production for `costa.wanderl@gmail.com`:
+
+- `check-email`: `isBuyer=true`, `hasAccount=true`
+- `login`: `200`, `accessToken` present, `emailVerified=true`
+- `verify-status`: `200`, `emailVerified=true`
+- `activate-pro`: `200`, `activated=true`, existing license restored
+
+### Guided installation validation
+
+Validated successfully:
+
+- source checkout install
+- packaged tarball install
+
+The final installer verification passed in both cases and the generated projects contained the expected Claude and Codex assets.
+
+---
+
+## Troubleshooting
+
+### `activate-pro` returns `400 Invalid input: expected string, received undefined`
+
+Cause:
+
+- outdated client contract
+
+Fix:
+
+- caller must send `{ accessToken }` in the JSON body
+- newer installer build already does this
+
+### `check-email` returns `isBuyer=false` right after granting the user
+
+Check:
+
+- `public.buyers` row exists and `is_active=true`
+- email normalized to lowercase
+- if buyer RPC is degraded, seed `public.buyer_validations`
+
+### `login` works but `verify-status` says not verified
+
+Fix:
+
+- confirm the user email in Supabase Auth
+
+### Installer completes but `.codex/skills` or `.claude/skills` are missing
+
+This story fixed the packaging and generation path. Rebuild with the updated installer package and rerun.
+
+### Installer emits false dependency warnings in a normal user project
+
+This story fixed the dependency validator to avoid flagging installer-internal packages in user projects. Rebuild with the updated package and rerun.
+
+---
+
+## Evidence To Attach In Support Closure
+
+- `check-email` response
+- `login` response status only
+- `verify-status` response
+- `activate-pro` response status only
+- source guided install result
+- tarball guided install result
+
+Do not paste the full `accessToken` or the full `licenseKey` into tickets or chat.

package/docs/guides/pro/install-gate-setup.md

@@ -19,14 +19,14 @@ Comprar Licenca → Instalar → Ativar → Usar Features Pro
 | Pacote | Tipo | Proposito |
 |--------|------|-----------|
 | `aiox-pro` | CLI (1.8 KB) | Comandos de instalacao e gerenciamento |
-| `@aiox-fullstack/pro` | Core (10 MB) | Features premium (squads, memory, metrics, integrations) |
+| `@aiox-fullstack/pro` | Core (10 MB) | Nome canônico do pacote premium (com fallback legado durante a transição) |
 
 ---
 
 ## Instalacao Rapida
 
 ```bash
-# Instalar AIOX Pro (instala @aiox-fullstack/pro automaticamente)
+# Instalar AIOX Pro (instala o pacote Pro compatível automaticamente)
 npx aiox-pro install
 
 # Ativar sua licenca
@@ -51,12 +51,18 @@ npx aiox-pro status
 npx aiox-pro install
 ```
 
-Isso executa `npm install @aiox-fullstack/pro` no seu projeto.
+Isso instala o pacote Pro compatível no seu projeto, priorizando o nome canônico e caindo para o legado quando necessário.
 
-**Alternativa** (instalacao manual):
+**Alternativa** (instalação manual):
 
 ```bash
-npm install @aiox-fullstack/pro
+npm install @aiox-fullstack/pro@latest
+```
+
+Depois da instalação manual, rode o bootstrap do conteúdo Pro no projeto:
+
+```bash
+npx aiox-pro install
 ```
 
 ### Passo 2: Ativar Licenca
@@ -88,7 +94,7 @@ npx aiox-pro features
 
 | Comando | Descricao |
 |---------|-----------|
-| `npx aiox-pro install` | Instala `@aiox-fullstack/pro` no projeto |
+| `npx aiox-pro install` | Instala o pacote AIOX Pro compatível no projeto |
 | `npx aiox-pro activate --key KEY` | Ativa uma chave de licenca |
 | `npx aiox-pro status` | Mostra status da licenca atual |
 | `npx aiox-pro features` | Lista todas as features pro e disponibilidade |

package/docs/guides/pro/squad-creator-handoff-pro-access-ops.md

@@ -0,0 +1,134 @@
+# Handoff: Squad Creator -> DevOps Pro Access Ops
+
+**Status:** Ready to operationalize
+**Validated on:** 2026-04-20
+**Target squad/task owner:** `@squad-creator` creating reusable surfaces for `@devops`
+
+---
+
+## Objective
+
+Convert the validated AIOX Pro access grant procedure into a reusable task/workflow pair so DevOps can execute it repeatedly without rediscovering:
+
+- which system is authoritative
+- which tables matter
+- which API contract is current
+- which validations are mandatory
+
+---
+
+## What Is Already Validated
+
+The following is not speculative. It was validated end-to-end on 2026-04-20:
+
+- live license server contract uses `accessToken` in `verify-status` and `activate-pro`
+- `activate-pro` returns `licenseKey`
+- buyer entitlement comes from `public.buyers`
+- local support fallback can be seeded through `public.buyer_validations`
+- `activate-pro` is idempotent and restores existing licenses
+- guided installer passed in:
+  - source checkout flow
+  - packaged tarball flow
+
+Validated customer used in this run:
+
+- email: `costa.wanderl@gmail.com`
+- password used for validation: `AioxPro2026!`
+
+---
+
+## Artifacts To Use As Inputs
+
+Squad creator should treat these files as the authoritative seed set:
+
+1. `docs/guides/pro/access-grant-ops-playbook.md`
+2. `docs/aiox-workflows/pro-access-grant-workflow.md`
+3. `.aiox-core/development/tasks/devops-pro-access-grant.md`
+4. `docs/stories/PRO-11.1-auth-contract-hardening-and-pro-access-ops.md`
+
+---
+
+## Required Deliverables
+
+Squad creator must create or register:
+
+1. A reusable DevOps task for Pro access grants.
+2. Dedicated point-action aliases for common support operations.
+3. A reusable workflow that chains:
+- preflight
+- entitlement grant
+- account setup
+- API validation
+- guided install validation
+4. Clear input schema:
+- `target_email`
+- `target_password`
+- `reset_password`
+- `run_guided_validation`
+5. A closeout/evidence template that never leaks full token or full license key.
+
+Minimum alias set now expected:
+
+- `*pro-access-grant`
+- `*pro-check-access`
+- `*pro-request-reset`
+- `*pro-resend-verification`
+- `*pro-reset-password`
+- `*pro-validate-login`
+- `*pro-verify-status`
+- `*pro-activate`
+
+---
+
+## Non-Negotiable Rules
+
+Do not let the generated task/workflow drift from these rules:
+
+- `public.buyers` is the buyer entitlement oracle.
+- `check-email` and `login` are the preflight validation pair.
+- `verify-status` and `activate-pro` must send `accessToken` in the JSON body.
+- `activate-pro` may return success for an already-activated user; that is correct behavior.
+- Guided validation must assert Claude and Codex assets exist in the installed project.
+- No rediscovery instructions. The output must assume fixed backend context and operator access.
+
+---
+
+## Suggested Registration Shape
+
+### Task name
+
+- `devops-pro-access-grant`
+
+### Workflow name
+
+- `pro-access-grant-workflow`
+
+### Primary agent
+
+- `@devops`
+
+### Secondary references
+
+- `@qa` only for validating future regressions in installer behavior
+- `@squad-creator` only for packaging and publishing the reusable assets
+
+---
+
+## Done Criteria
+
+The squad creator work is done only when:
+
+- the task exists in the canonical task surface
+- the workflow exists in the canonical workflow surface
+- both point back to the validated playbook
+- both preserve the exact decision tree and validation order
+- a DevOps operator can run the process without asking where buyer data, auth state, or activation checks live
+
+---
+
+## Implementation Notes For Squad Creator
+
+- Prefer copying the validated sequence directly instead of rewriting from scratch.
+- Keep the workflow operational, not pedagogical.
+- Keep the task biased toward action and evidence collection.
+- If you add examples, use masked values for tokens and license keys.