fix: repair pro installer activation commands [Story PRO-13.5]

Fix Pro installer recovery/setup command hints, publish-surface package versions, legacy activation compatibility docs/tests, and Pro Integration private submodule auth.\n\nValidated with focused local checks plus green GitHub CI, including Pro Integration.

Author: rafaelscosta

.github/workflows/pro-integration.yml

@@ -79,8 +79,20 @@ jobs:
         if: steps.token-check.outputs.skip != 'true'
         uses: actions/checkout@v6
         with:
-          token: ${{ secrets.PRO_SUBMODULE_TOKEN }}
-          submodules: 'recursive'
+          token: ${{ secrets.GITHUB_TOKEN }}
+          submodules: false
+
+      - name: Initialize Pro submodule
+        if: steps.token-check.outputs.skip != 'true'
+        env:
+          PRO_SUBMODULE_TOKEN: ${{ secrets.PRO_SUBMODULE_TOKEN }}
+        run: |
+          echo "::add-mask::$PRO_SUBMODULE_TOKEN"
+          export GIT_CONFIG_COUNT=1
+          export GIT_CONFIG_KEY_0="url.https://x-access-token:${PRO_SUBMODULE_TOKEN}@github.com/SynkraAI/.insteadOf"
+          export GIT_CONFIG_VALUE_0="https://github.com/SynkraAI/"
+          git submodule sync --recursive
+          git submodule update --init --recursive
 
       - name: Setup Node.js
         if: steps.token-check.outputs.skip != 'true'

README.md

@@ -618,8 +618,7 @@ Para saber como acessar, ativar, recuperar conta e validar as squads Pro, consul
 ### Instalação
 
 ```bash
-npx aiox-pro install
-npx aiox-pro setup
+npx -y -p @aiox-squads/core@latest aiox pro setup
 ```
 
 ### Identificação Estável de Máquina (>= 5.0.8)

docs/guides/aiox-pro-access.md

@@ -15,8 +15,7 @@ Se o instalador responder que não encontrou acesso para o email, o problema é
 No projeto onde você quer usar o Pro:
 
 ```bash
-npx aiox-pro install
-npx aiox-pro setup
+npx -y -p @aiox-squads/core@latest aiox pro setup
 ```
 
 O setup guiado oferece dois caminhos:
@@ -29,24 +28,24 @@ Em automação/CI, use variáveis de ambiente:
 ```bash
 export AIOX_PRO_EMAIL="seu-email@exemplo.com"
 export AIOX_PRO_PASSWORD="sua-senha"
-npx aiox-pro setup
+npx -y -p @aiox-squads/core@latest aiox pro setup
 ```
 
 Ou, para chave legada:
 
 ```bash
 export AIOX_PRO_KEY="PRO-XXXX-XXXX-XXXX-XXXX"
-npx aiox-pro setup
+npx -y -p @aiox-squads/core@latest aiox pro setup
 ```
 
 ## Verificar o acesso
 
 Depois de instalar:
 
 ```bash
-npx aiox-pro status
-npx aiox-pro features
-npx aiox-pro validate
+npx -y -p @aiox-squads/core@latest aiox pro status
+npx -y -p @aiox-squads/core@latest aiox pro features
+npx -y -p @aiox-squads/core@latest aiox pro validate
 ```
 
 Esses comandos verificam a licença, listam recursos Pro disponíveis e forçam uma revalidação online quando necessário.
@@ -58,7 +57,7 @@ As squads Pro são entregues pelo pacote Pro privado e sincronizadas pelo instal
 Se as squads não aparecerem depois de uma instalação bem-sucedida, rode:
 
 ```bash
-npx aiox-pro update
+npx -y -p @aiox-squads/core@latest aiox pro update
 npm run sync:ide
 ```
 
@@ -67,7 +66,7 @@ npm run sync:ide
 Para recuperar senha ou licença:
 
 ```bash
-npx aiox-pro recover
+npx -y @aiox-squads/aiox-pro-cli@latest recover
 ```
 
 Se o email comprado não for reconhecido, ou se a conta existir mas a ativação falhar, o fluxo operacional correto é acionar `@devops` com um destes comandos:
@@ -80,7 +79,7 @@ Se o email comprado não for reconhecido, ou se a conta existir mas a ativação
 ## Erros comuns
 
 - `No AIOX Pro access found for this email.`: o email ainda não tem entitlement Pro ou foi digitado diferente do cadastro.
-- `AIOX Pro is not installed.`: rode `npx aiox-pro install` antes de status/validate.
+- `AIOX Pro is not installed.`: rode `npx -y -p @aiox-squads/core@latest aiox pro setup` antes de status/validate.
 - `Invalid key format`: a chave legada precisa seguir o formato `PRO-XXXX-XXXX-XXXX-XXXX`.
 - Falha em CI sem prompt interativo: defina `AIOX_PRO_EMAIL` + `AIOX_PRO_PASSWORD` ou `AIOX_PRO_KEY`.
 

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

@@ -18,7 +18,7 @@ Comprar Licença -> Validar -> Baixar artefato assinado -> Usar Features Pro
 
 | Pacote | Tipo | Propósito |
 |--------|------|-----------|
-| `aiox-pro` | CLI (1.8 KB) | Comandos de instalação e gerenciamento |
+| `@aiox-squads/aiox-pro-cli` | CLI | Comandos de recuperação e compatibilidade |
 | `@aiox-squads/pro` | Artefato premium | Pacote Pro canônico, entregue ao cliente pelo artifact broker autenticado |
 
 ---
@@ -27,13 +27,13 @@ Comprar Licença -> Validar -> Baixar artefato assinado -> Usar Features Pro
 
 ```bash
 # Instalar AIOX Pro (instala o pacote Pro compatível automaticamente)
-npx aiox-pro install
+npx -y -p @aiox-squads/core@latest aiox pro setup
 
-# Ativar sua licenca
-npx aiox-pro activate --key PRO-XXXX-XXXX-XXXX-XXXX
+# Ativar sua licença por chave legada
+npx -y -p @aiox-squads/core@latest aiox pro activate --key PRO-XXXX-XXXX-XXXX-XXXX
 
-# Verificar ativacao
-npx aiox-pro status
+# Verificar ativação
+npx -y -p @aiox-squads/core@latest aiox pro status
 ```
 
 ---
@@ -48,23 +48,23 @@ npx aiox-pro status
 ### Passo 1: Instalar AIOX Pro
 
 ```bash
-npx aiox-pro install
+npx -y -p @aiox-squads/core@latest aiox pro setup
 ```
 
 Isso valida sua licença e instala o artefato canônico `@aiox-squads/pro` no projeto. O cliente não precisa de acesso direto ao pacote privado/restrito no npm.
 
 **Se você já tem o artefato Pro instalado por outro fluxo autorizado**, rode novamente o bootstrap para revalidar e re-scaffoldar o conteúdo Pro:
 
 ```bash
-npx aiox-pro install
+npx -y -p @aiox-squads/core@latest aiox pro setup
 ```
 
 ### Passo 2: Ativar Licenca
 
 Apos a compra, voce recebera uma chave no formato `PRO-XXXX-XXXX-XXXX-XXXX`.
 
 ```bash
-npx aiox-pro activate --key PRO-XXXX-XXXX-XXXX-XXXX
+npx -y -p @aiox-squads/core@latest aiox pro activate --key PRO-XXXX-XXXX-XXXX-XXXX
 ```
 
 Esse comando:
@@ -76,10 +76,10 @@ Esse comando:
 
 ```bash
 # Status da licenca
-npx aiox-pro status
+npx -y -p @aiox-squads/core@latest aiox pro status
 
 # Listar features disponiveis
-npx aiox-pro features
+npx -y -p @aiox-squads/core@latest aiox pro features
 ```
 
 ---
@@ -88,13 +88,13 @@ npx aiox-pro features
 
 | Comando | Descricao |
 |---------|-----------|
-| `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 |
-| `npx aiox-pro validate` | Forca revalidacao online da licenca |
-| `npx aiox-pro deactivate` | Desativa a licenca nesta maquina |
-| `npx aiox-pro help` | Mostra todos os comandos |
+| `npx -y -p @aiox-squads/core@latest aiox pro setup` | Instala o pacote AIOX Pro compatível no projeto |
+| `npx -y -p @aiox-squads/core@latest aiox pro activate --key KEY` | Ativa uma chave de licença |
+| `npx -y -p @aiox-squads/core@latest aiox pro status` | Mostra status da licença atual |
+| `npx -y -p @aiox-squads/core@latest aiox pro features` | Lista todas as features Pro e disponibilidade |
+| `npx -y -p @aiox-squads/core@latest aiox pro validate` | Força revalidação online da licença |
+| `npx -y -p @aiox-squads/core@latest aiox pro deactivate` | Desativa a licença nesta máquina |
+| `npx -y -p @aiox-squads/core@latest aiox pro help` | Mostra todos os comandos |
 
 ---
 
@@ -107,9 +107,9 @@ Apos a instalacao e ativacao, o AIOX Pro funciona offline:
 - Verificacao de features 100% local no dia a dia
 
 A internet so e necessaria para:
-1. Ativacao inicial (`npx aiox-pro activate`)
+1. Ativação inicial (`npx -y -p @aiox-squads/core@latest aiox pro activate`)
 2. Revalidacao periodica (automatica a cada 30 dias)
-3. Desativacao (`npx aiox-pro deactivate`)
+3. Desativação (`npx -y -p @aiox-squads/core@latest aiox pro deactivate`)
 
 ---
 
@@ -120,17 +120,17 @@ Para pipelines, instale e ative usando secrets de ambiente:
 **GitHub Actions:**
 ```yaml
 - name: Install AIOX Pro
-  run: npx aiox-pro install
+  run: npx -y -p @aiox-squads/core@latest aiox pro setup
 
 - name: Activate License
-  run: npx aiox-pro activate --key ${{ secrets.AIOX_PRO_LICENSE_KEY }}
+  run: npx -y -p @aiox-squads/core@latest aiox pro activate --key ${{ secrets.AIOX_PRO_LICENSE_KEY }}
 ```
 
 **GitLab CI:**
 ```yaml
 before_script:
-  - npx aiox-pro install
-  - npx aiox-pro activate --key ${AIOX_PRO_LICENSE_KEY}
+  - npx -y -p @aiox-squads/core@latest aiox pro setup
+  - npx -y -p @aiox-squads/core@latest aiox pro activate --key ${AIOX_PRO_LICENSE_KEY}
 ```
 
 ---
@@ -153,7 +153,7 @@ License activation failed: Invalid key format
 License activation failed: Maximum seats exceeded
 ```
 
-- Desative a licenca na outra maquina: `npx aiox-pro deactivate`
+- Desative a licença na outra máquina: `npx -y -p @aiox-squads/core@latest aiox pro deactivate`
 - Ou contate support para aumentar o limite de seats
 
 ### Erro de rede na ativacao
@@ -173,7 +173,7 @@ License activation failed: ECONNREFUSED
 ```
 ┌─────────────────┐     ┌─────────────────────────────────┐     ┌──────────┐
 │  Cliente (CLI)   │────>│  License Server (Vercel)        │────>│ Supabase │
-│  npx aiox-pro    │<────│  aiox-license-server.vercel.app │<────│ Database │
+│  aiox pro        │<────│  aiox-license-server.vercel.app │<────│ Database │
 └─────────────────┘     └─────────────────────────────────┘     └──────────┘
                                                                       │
                                                                       │

docs/guides/workflows/pro-developer-workflow.md

@@ -119,14 +119,14 @@ ls pro/package.json
 ### Customer Pro Setup
 
 ```bash
-npx aiox-pro setup
+npx -y -p @aiox-squads/core@latest aiox pro setup
 ```
 
 The setup flow uses email/password authentication. Normal customers do not need npm org access or `NPM_TOKEN`.
 
 Troubleshooting:
 
-- `Pro content source not found`: rerun `npx aiox-pro setup` and choose the email login/create-account flow.
+- `Pro content source not found`: rerun `npx -y -p @aiox-squads/core@latest aiox pro setup` and choose the email login/create-account flow.
 - `Pro artifact download failed`: retry after a few minutes; the signed URL is short-lived.
 - `Pro artifact sha256 mismatch`: stop and contact support. Do not scaffold from the downloaded artifact.
 - `No active Pro subscription`: confirm the email used for login matches the Pro purchase.

docs/stories/epic-pro-13/STORY-PRO-13.5-PRIVATE-PRO-DISTRIBUTION-HARDENING.md

@@ -357,12 +357,19 @@ Implementation should preserve the open-core boundary:
 Expected implementation touchpoints:
 
 - `package.json`
+- `package-lock.json`
 - `bin/utils/validate-publish.js`
 - `packages/installer/src/wizard/pro-setup.js`
 - `packages/installer/src/pro/pro-scaffolder.js`
 - `packages/aiox-pro-cli/bin/aiox-pro.js`
+- `packages/aiox-pro-cli/package.json`
+- `packages/installer/package.json`
 - `packages/installer/src/wizard/i18n.js`
+- `.github/workflows/pro-integration.yml`
 - `docs/PUBLISHING.md`
+- `README.md`
+- `docs/guides/aiox-pro-access.md`
+- `docs/guides/pro/install-gate-setup.md`
 - `docs/guides/workflows/pro-developer-workflow.md`
 - `tests/pro-wizard.test.js`
 - `tests/installer/pro-setup-auth.test.js`
@@ -456,13 +463,25 @@ Expected implementation touchpoints:
 - 2026-05-09: Published `@aiox-squads/core@5.1.17`; npm `latest` resolves to `5.1.17`; clean install smoke confirms `aiox --version` returns `5.1.17`, the installed public package has zero `pro/` paths, and the installer default points to Pro artifact `0.4.2`.
 - 2026-05-08: GitHub CI follow-up fixed: `tests/pro-wizard.test.js` interactive license-key retry test now stubs the license client instead of reaching the real inline HTTP fallback, removing the Node 18 timeout while preserving prompt/retry assertions.
 - 2026-05-08: Merged `origin/main` and addressed CodeRabbit actionable comments: legacy `npm notice` size-prefixed pack output is normalized before `pro/` checks, `aiox-pro install/setup/wizard -k` is accepted, artifact download has an abort timeout, and artifact-installed Pro package cleanup runs on scaffold failures.
+- 2026-05-12: Student install incident triage confirmed the unscoped `npx aiox-pro recover/install/setup` path is invalid for fresh machines; installer and docs now point recovery to `npx -y @aiox-squads/aiox-pro-cli@latest recover` and setup to `npx -y -p @aiox-squads/core@latest aiox pro setup`.
+- 2026-05-12: `@aiox-squads/installer` bumped to `3.3.2` and `@aiox-squads/aiox-pro-cli` bumped to `0.2.1` so @devops can publish the signed-artifact installer and scoped CLI command fix.
+- 2026-05-12: GitHub Pro Integration checkout fixed to use `GITHUB_TOKEN` for the `aiox-core` PR merge ref and reserve `PRO_SUBMODULE_TOKEN` for private Pro submodule initialization only.
+- 2026-05-12: CodeRabbit PR follow-up applied: Pro Integration now injects the credentialized submodule URL through process-scoped `GIT_CONFIG_*` environment variables, and Pro wizard tests use repository-absolute package imports.
 - Validation evidence:
   - `node -c packages/installer/src/wizard/pro-setup.js && node -c packages/aiox-pro-cli/bin/aiox-pro.js && node -c bin/utils/validate-publish.js`
   - `node -c packages/installer/src/pro/pro-scaffolder.js && node -c pro/license/license-api.js && node -c .aiox-core/cli/commands/pro/index.js`
   - `npm --prefix pro ci --ignore-scripts --no-audit --no-fund && npm --prefix pro run validate:publish-surface`
   - `npm run validate:publish`
   - `npm run typecheck`
   - `npm test -- --runInBand tests/pro-wizard.test.js tests/installer/pro-setup-auth.test.js tests/installer/pro-scaffolder.test.js tests/cli/validate-publish.test.js tests/pro/pro-updater.test.js tests/pro-recover.test.js`
+  - `node -c packages/installer/src/wizard/i18n.js && node -c packages/installer/src/wizard/pro-setup.js && node -c packages/installer/src/pro/pro-scaffolder.js && node -c packages/aiox-pro-cli/bin/aiox-pro.js`
+  - `npm test -- --runInBand tests/pro-wizard.test.js tests/installer/pro-setup-auth.test.js tests/pro-recover.test.js tests/installer/pro-scaffolder.test.js`
+  - `npm pack --workspace @aiox-squads/aiox-pro-cli --dry-run --json`
+  - `npm pack --workspace @aiox-squads/installer --dry-run --json`
+  - `npm run validate:publish`
+  - `npx yaml-lint .github/workflows/pro-integration.yml`
+  - `npm test -- --runInBand tests/pro-wizard.test.js`
+  - `npx eslint tests/pro-wizard.test.js`
   - `npx jest --runInBand tests/license/license-api.test.js --testPathIgnorePatterns='node_modules'`
   - full smoke matrix saved in `outputs/qa/2026-05-pro-13-5-smoke.json`
   - Pro artifact upload evidence saved in `outputs/qa/2026-05-pro-13-5-pro-artifact-0.4.1.json`

package-lock.json

@@ -4,7 +4,7 @@
  * aiox-pro CLI
  *
  * Thin CLI wrapper for AIOX Pro setup and delegated commands.
- * Provides a clean npx interface: npx aiox-pro install
+ * Provides a clean npx interface: npx @aiox-squads/aiox-pro-cli install
  *
  * Commands:
  *   install             Run authenticated Pro setup in the current project
@@ -121,7 +121,7 @@ function showHelp() {
 aiox-pro v${VERSION} — AIOX Pro CLI
 
 Usage:
-  npx aiox-pro <command> [options]
+  npx -y @aiox-squads/aiox-pro-cli@latest <command> [options]
 
 Commands:
   install              Run authenticated Pro setup in the current project
@@ -137,14 +137,14 @@ Commands:
   help                 Show this help message
 
 Examples:
-  npx aiox-pro install
-  npx aiox-pro update
-  npx aiox-pro setup
-  npx aiox-pro wizard --key PRO-XXXX-XXXX-XXXX-XXXX
-  npx aiox-pro install -k PRO-XXXX-XXXX-XXXX-XXXX
-  npx aiox-pro activate --key PRO-XXXX-XXXX-XXXX-XXXX
-  npx aiox-pro status
-  npx aiox-pro recover
+  npx -y @aiox-squads/aiox-pro-cli@latest install
+  npx -y @aiox-squads/aiox-pro-cli@latest update
+  npx -y @aiox-squads/aiox-pro-cli@latest setup
+  npx -y @aiox-squads/aiox-pro-cli@latest wizard --key PRO-XXXX-XXXX-XXXX-XXXX
+  npx -y @aiox-squads/aiox-pro-cli@latest install -k PRO-XXXX-XXXX-XXXX-XXXX
+  npx -y @aiox-squads/aiox-pro-cli@latest activate --key PRO-XXXX-XXXX-XXXX-XXXX
+  npx -y @aiox-squads/aiox-pro-cli@latest status
+  npx -y @aiox-squads/aiox-pro-cli@latest recover
 
 Documentation: https://synkra.ai/pro/docs
 `);

packages/aiox-pro-cli/bin/aiox-pro.js

@@ -1,6 +1,6 @@
 {
   "name": "@aiox-squads/aiox-pro-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "CLI for AIOX Pro — install, activate and manage your license",
   "bin": {
     "aiox-pro": "bin/aiox-pro.js"
@@ -10,7 +10,7 @@
     "src/"
   ],
   "dependencies": {
-    "@aiox-squads/installer": "^3.3.0",
+    "@aiox-squads/installer": "^3.3.2",
     "open": "^10.0.0"
   },
   "keywords": [

packages/aiox-pro-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiox-squads/installer",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "AIOX Installer - Automated setup wizard for AIOX projects (greenfield & brownfield)",
   "main": "src/index.js",
   "bin": {