@jaimevalasek/aioson 1.30.0 → 1.30.2

package/template/.aioson/docs/integrations/dashboard-app-form-publish-mapping.md

@@ -0,0 +1,183 @@
+---
+description: "Mapping between the aioson.com dashboard app edit form and aioson system:publish --build listing fields."
+scope: "global"
+agents: [dev, architect, product, qa]
+triggers: [system publish, marketplace app, dashboard app form, integrations, app listing]
+---
+
+# Integração — Formulário "Editar app" (dashboard) × `aioson system:publish --build`
+
+> Objetivo: mapear **cada campo do formulário de edição de app** no dashboard do
+> aioson.com aos dados que o `aioson system:publish --build` já captura (ou
+> poderia capturar) do app em desenvolvimento, para que a publicação preencha o
+> cadastro da loja de forma mais completa e o dev não tenha que digitar à mão.
+
+Doc-irmã: [`apps-publish-marketplace.md`](../../../docs/integrations/apps-publish-marketplace.md)
+(fluxo geral do publish). Aqui o foco é o **mapeamento campo-a-campo** do form.
+
+---
+
+## Onde fica cada peça
+
+| Peça | Caminho (repo) |
+|------|----------------|
+| Rota do form | `aioson-com/app/dashboard/ws/apps/[id]/edit/page.tsx` (ex.: `…/apps/cmqe2pnvw0005koa7ak5mbkge/edit`) |
+| Componente do form | `aioson-com/app/admin/services/service-app-form.tsx` (`ServiceAppForm`) |
+| Server action | `aioson-com/app/dashboard/ws/apps/actions.ts` → `updateWorkspaceAppAction` |
+| Modelo de dados do form | `ServiceApp` em `aioson-com/prisma/schema.prisma` |
+| Comando de publish (CLI) | `aioson/src/commands/store-system.js` → `runSystemPublish` |
+| Validação do manifest (CLI) | `store-system.js` → `validateListingFields` |
+| Recepção no servidor | `aioson-com/lib/store.ts` → `storePublishSystem` |
+| Extração de listing → `System` | `lib/store.ts` → `extractListingFields` |
+| Sync `System` → `ServiceApp` | `lib/store.ts` → `ensureServiceAppForSystemRecord` |
+
+---
+
+## Arquitetura: dois modelos, duas superfícies
+
+O publish e o formulário **não escrevem no mesmo registro**:
+
+- `aioson system:publish` envia o `system.json` inteiro como `manifest` e grava em
+  **`System` / `SystemVersion`**. Os campos de listing da loja
+  (`summary`, `category`, `tags`, `screenshots`, `purpose`, `iconUrl`,
+  `homepageUrl`, `supportEmail`, `supportUrl`, `privacyUrl`, `permissionsNote`)
+  são extraídos do manifest por `extractListingFields` e gravados em **`System`**.
+- O **formulário de "Editar app"** edita **`ServiceApp`** — outro modelo, com
+  outro conjunto de campos (descrição longa, features, emoji, SEO, vídeo, etc.).
+- Na publicação de app **não-privado**, `ensureServiceAppForSystemRecord` cria/atualiza
+  um `ServiceApp` espelhando o `System`, **mas só copia 5–7 campos**
+  (`name`, `description`, `price`, `visibility`, `ownerId`, `ownerProjectId`,
+  `trialDays`, `requiresLicense`). Todo o resto do form fica **manual**.
+
+> Resultado prático: hoje o dev publica via CLI e depois ainda precisa abrir o
+> form e preencher descrição longa, features, ícone, SEO e links na mão. É essa
+> lacuna que o "preenchimento via harness" fecha.
+
+---
+
+## Mapeamento campo-a-campo do formulário
+
+Legenda da coluna **Auto hoje?**: ✅ já preenchido na publicação · ⚠️ parcial · ❌ manual.
+
+| Campo do form | `name=` | Coluna `ServiceApp` | Limite | Obrig. | Auto hoje? | Origem de captura sugerida (harness / manifest) |
+|---|---|---|---|---|---|---|
+| Nome | `name` | `name` | 120 | sim | ✅ | `manifest.name` (já obrigatório) |
+| Slug | `slug` | `slug` | 140 (`[a-z0-9-]+`) | sim | ✅ | `manifest.slug` (já obrigatório) |
+| Descrição curta | `description` | `description` | 280 | sim | ✅ | `manifest.description` (ou `manifest.summary`) |
+| Descrição longa | `longDescription` | `longDescription` (Text) | — | não | ❌ | corpo do `README.md` (sem o 1º heading) · `manifest.long_description` · bootstrap `what-it-does.md` |
+| Features | `features` | `features` (Text) | — | não | ❌ | `manifest.features[]` (lista) · seção `## Features`/`## Funcionalidades` do README |
+| Preço | `price` | `price` (Decimal) | ≥ 0 | sim | ✅ | `System.priceInCents/100` ← `manifest.priceInCents`/`price` |
+| Ordem | `sortOrder` | `sortOrder` (Int) | — | não (0) | ❌ | manual (sem sinal confiável no app) — manter default 0 |
+| Ícone (emoji) | `icon` | `icon` VarChar(**8**) | 8 | não | ❌ | `manifest.icon_emoji` — **emoji**, NÃO a URL de ícone (essa é `System.iconUrl` ← `manifest.icon`) |
+| Status | `status` | `status` (enum) | active/coming_soon/inactive | não | ⚠️ | derivado da `visibility`; geralmente manual — default `active` |
+| Caminho do dashboard | `dashboardPath` | `dashboardPath` VarChar(255) | 255 | não | ❌ | `manifest.dashboard_path` · detectar rota admin do app (presença de `dashboard/`) |
+| Vídeo demo | `urlVideoDemo` | `urlVideoDemo` VarChar(512) | 512 | não | ❌ | `manifest.url_video_demo` (manual — não dá pra inferir do código) |
+| Storefront | `storefrontUrl` | `storefrontUrl` VarChar(**512**) | form aceita 1024 ⚠️ | não | ❌ | `manifest.storefront_url` (manual) |
+| SEO título | `seoTitle` | `seoTitle` VarChar(70) | 70 | não | ❌ | `manifest.seo_title` · derivar `${name} — ${summary}` truncado em 70 |
+| SEO descrição | `seoDescription` | `seoDescription` VarChar(160) | 160 | não | ❌ | `manifest.seo_description` · `manifest.summary` truncado em 160 |
+
+**Lacunas reais (❌) a fechar:** `longDescription`, `features`, `icon` (emoji),
+`dashboardPath`, `urlVideoDemo`, `storefrontUrl`, `seoTitle`, `seoDescription`.
+(`sortOrder` e `status` ficam manuais por design.)
+
+**Já capturado, mas em `System` (não neste form):** `summary`, `category`, `tags`,
+`screenshots`, `purpose`, `iconUrl`, `homepageUrl`, `supportEmail`, `supportUrl`,
+`privacyUrl`, `permissionsNote` — via `extractListingFields`. Reaproveitáveis:
+`summary`→`seoDescription`, `iconUrl` já existe (o form usa emoji separado).
+
+⚠️ **Inconsistência a anotar:** o input `storefrontUrl` no form aceita
+`maxLength=1024`, mas a coluna é `VarChar(512)`. Truncar/alinhar ao gravar.
+
+---
+
+## Chaves de `system.json` propostas (fonte única)
+
+O publish já envia o `manifest` inteiro, então **basta o harness escrever estas
+chaves no `system.json`** e o servidor mapeá-las no `ServiceApp`. Todas opcionais
+(apps antigos seguem publicando):
+
+```jsonc
+{
+  "slug": "meu-app",
+  "name": "Meu App",
+  "version": "1.0.0",
+  // — listing já suportado (vai pra System) —
+  "summary": "Resumo até 160 chars",
+  "category": "atendimento",
+  "tags": ["whatsapp", "crm"],
+  "icon": "https://.../icon.png",          // URL → System.iconUrl
+  "screenshots": ["https://.../1.png"],
+  // — novas chaves p/ preencher o form ServiceApp —
+  "long_description": "Texto longo (markdown ok).",
+  "features": ["Recurso A", "Recurso B"],   // → join em ServiceApp.features
+  "icon_emoji": "💬",                        // → ServiceApp.icon (≤8)
+  "dashboard_path": "/dashboard/atendimento",
+  "url_video_demo": "https://youtube.com/watch?v=...",
+  "storefront_url": "https://minha-loja.com",
+  "seo_title": "Meu App — atendimento no WhatsApp",
+  "seo_description": "Descrição SEO até 160 chars"
+}
+```
+
+---
+
+## O que faltaria implementar (3 pontos) — NÃO feito ainda
+
+Isto é o plano de fechamento da lacuna; **este doc só mapeia, não altera código**.
+
+1. **CLI — `validateListingFields`** (`store-system.js`): aceitar/validar as novas
+   chaves opcionais (`long_description`, `features[]`, `icon_emoji` ≤8,
+   `dashboard_path`, `url_video_demo`, `storefront_url`, `seo_title` ≤70,
+   `seo_description` ≤160). O envio em si já acontece (manifest viaja inteiro).
+2. **Servidor — `ensureServiceAppForSystemRecord`** (`lib/store.ts`): estender o
+   objeto `data` para mapear essas chaves do manifest nas colunas do `ServiceApp`
+   (respeitando "não sobrescrever edição manual" se desejado — ex.: só preencher
+   quando o campo no `ServiceApp` estiver vazio).
+3. **Harness — montagem do `system.json` antes do publish**: popular as chaves a
+   partir das fontes da tabela (README, rotas, living-memory). Candidato natural:
+   um passo de "enriquecer manifest" dentro de `runSystemPublish` (modo `--build`)
+   ou um agente/skill que rode antes do publish.
+
+### Estratégia de captura pelo harness (resumo)
+
+- `long_description` ← corpo do `README.md` (remover 1º heading) ou bootstrap `what-it-does.md`.
+- `features` ← bullets da seção `## Features`/`## Funcionalidades` do README.
+- `dashboard_path` ← detecção de rota admin (presença de `dashboard/`, `app/admin`, etc.).
+- `seo_title`/`seo_description` ← derivar de `name` + `summary` com truncamento.
+- `icon_emoji`, `url_video_demo`, `storefront_url` ← declarados pelo dev (manual no manifest).
+
+### ⚠️ Pré-condições e pegadinhas (descobertas na investigação)
+
+Antes de implementar, dois fatos do código atual que mudam o "quando" e o "onde":
+
+1. **`ServiceApp` só nasce em `status=PUBLISHED` + `FREE/PAID`.**
+   `ensureServiceAppForSystemRecord` retorna `null` se `status !== "PUBLISHED"` ou
+   `visibility === "PRIVATE"` (e também ignora `DEV/PRO/BUSINESS` — só FREE/PAID).
+   Para **publisher novo**, a 1ª publicação é quarentenada (`createStatus = "DRAFT"`),
+   então o `ServiceApp` **não é criado na primeira vez** — só quando o app sai da
+   quarentena e vira `PUBLISHED`. ⇒ O preenchimento precisa acontecer **no momento
+   da criação do `ServiceApp`** (que pode ser uma publicação posterior), não
+   necessariamente na 1ª chamada de `system:publish`.
+
+2. **`ownerProjectId` está `null` hardcoded no publish (linha ~1037 de `store.ts`).**
+   O CLI manda `workspaceSlug` (lido de `.aioson/workspace.json`), mas
+   `storePublishSystem` **não** o usa para vincular o app a um workspace: tanto o
+   `System` quanto o `ServiceApp` são criados com `ownerProjectId: null`.
+   ⇒ App publicado via CLI **não aparece** no form WS-scoped
+   (`/dashboard/ws/apps/[id]/edit` filtra por `app.ownerProjectId === ws.id`).
+   Apps que aparecem lá foram criados pelo form "novo app" (`createWorkspaceAppAction`),
+   que seta `ownerProjectId = ws.id`. **Não existe "workspace default" no publish hoje.**
+
+   Para o publish alimentar esse form, falta um **4º ponto de implementação**:
+   resolver `workspaceSlug → project.id` no servidor e setar `ownerProjectId`
+   (no `System` e no `ServiceApp`) em vez de `null`.
+
+---
+
+## Como verificar (quando implementado)
+
+1. `aioson system:publish ./app --dry-run` deve listar o manifest com as novas chaves.
+2. Após publish de app **não-privado**, abrir `…/apps/<id>/edit` e conferir que
+   `longDescription`, `features`, `icon`, SEO e links vieram preenchidos.
+3. App **privado** não gera `ServiceApp` (`ensureServiceAppForSystemRecord` só roda
+   para `visibility !== PRIVATE`) — não esperar preenchimento nesse caso.

package/template/.aioson/docs/play/README.md

@@ -0,0 +1,74 @@
+---
+description: "Entry point for AIOSON agents implementing apps compatible with AIOSON Play runtime, integrations, data bindings, LLM connections, auth, services, ports, and local testing."
+scope: "global"
+agents: [dev, deyvin, architect, analyst, qa, tester, product, sheldon]
+task_types: [aioson-play-app, app-compatibility, integration]
+triggers: [AIOSON Play, Play runtime, app compatible with Play, Play integrations, data bindings, ProductBridge]
+---
+
+# AIOSON Play App Compatibility
+
+Use this folder when the user says the app will run inside AIOSON Play, will be installed by AIOSON Play, is being built in a Play draft, or must consume Play integrations.
+
+These docs are an AIOSON-side operational layer. They do not replace the canonical Play contracts in:
+
+```text
+C:\dev\aioson-play\.aioson\docs\integrations\
+```
+
+If that source repo exists and the task touches a precise Play contract, read the canonical doc listed in `source-map.md`. If it is not available, this folder is the stable fallback for agents.
+
+## Installed Play docs are not a harness contract
+
+Do not assume a harness working in a random app project can access docs embedded in a user's installed AIOSON Play. A desktop install may package resources differently, may not expose `.aioson/docs/integrations/` as a normal source path, and the harness may be running in another cwd.
+
+For AIOSON agents, the stable contract is:
+
+1. Load this folder when the task is Play-targeted.
+2. Use `source-map.md` to know which canonical Play document owns each topic.
+3. Only read `C:\dev\aioson-play\.aioson\docs\integrations\...` when the repo is locally available and exact contract detail matters.
+
+## Loading order
+
+For implementation:
+
+1. `agent-usage-guide.md`
+2. `app-compatibility-guide.md`
+3. `manifest-and-runtime.md`
+4. `llm-data-and-bindings.md` if the app touches LLM, app DB, external data, Global Connectors, MCPI, REST connectors, MCP tools, or `app-config.yaml`
+5. `auth-services-and-testing.md` if the app touches auth, billing/trial, Play Services, dev-link, local installation, or smoke testing
+6. `source-map.md` when a canonical source must be checked
+
+For QA/review:
+
+1. `app-compatibility-guide.md`
+2. `manifest-and-runtime.md`
+3. Topic-specific docs for touched surfaces
+
+## Core rule
+
+AIOSON can build any kind of app. Apply this Play compatibility layer only when the user explicitly or clearly targets AIOSON Play.
+
+## Covered surfaces
+
+- App identity and `manifest.json`
+- Runtime selection, scripts, `pnpm`, Next.js, Vite, Node, split-stack processes
+- Dynamic ports and ProductBridge at `http://localhost:5180`
+- `GET /api/aioson-play` capability declaration
+- LLM connections and fallback chain expectations
+- App operational database via `DATABASE_URL`
+- Data Bindings and Global Connectors via `app-config.yaml`
+- MCPI/API/MCP connector execution through the Play registry
+- Local operator auth via `aioson-auth` and `@aioson/auth-sdk`
+- App-owned RBAC catalog via `manifest.json` `auth.permissions[]`
+- Cloud owner/trial auth via `AIOSON_COM_TOKEN`
+- Play Services via `service.json` and `requires_services`
+- Dev-link and local smoke testing
+
+## Non-goals
+
+- Do not copy the whole Play integration directory into app projects.
+- Do not make apps depend on source-repo-only files from `aioson-play`.
+- Do not invent Play env vars, port ranges, manifest fields, or connector APIs.
+- Do not infer app permissions by scanning source code; Play apps declare the catalog in `manifest.json` `auth.permissions[]`.
+- Do not treat `llm-chain.json` or `aioson-models.json` in the app cwd as the primary credential contract for installed apps.

package/template/.aioson/docs/play/agent-usage-guide.md

@@ -0,0 +1,112 @@
+---
+description: "How AIOSON agents should decide when and how to apply AIOSON Play app compatibility docs during product, architecture, implementation, QA, and review work."
+scope: "global"
+agents: [dev, deyvin, architect, analyst, qa, tester, product, sheldon]
+task_types: [aioson-play-app, app-compatibility, integration]
+triggers: [AIOSON Play, Play app, Play-compatible app, Play integrations, ProductBridge, data_bindings]
+---
+
+# Agent Usage Guide
+
+## Trigger phrases
+
+Load this folder when the user mentions:
+
+- "AIOSON Play"
+- "play"
+- "draft"
+- "app compativel com o Play"
+- "runtime do Play"
+- "instalar no Play"
+- "marketplace do Play"
+- "Global Connector"
+- "Data Binding"
+- "MCPI"
+- "ProductBridge"
+- `manifest.json` for Play apps
+- `app-config.yaml`
+- `requires_services`
+- `auth.permissions`
+- `/api/aioson-play`
+
+Do not load it for generic web apps unless the user connects the app to Play.
+
+## First decision
+
+Before coding, classify the work:
+
+| User intent | Agent behavior |
+|---|---|
+| New app for Play | Use all docs in this folder. Start from `app-compatibility-guide.md`. |
+| Existing app should become Play-compatible | Audit `manifest.json`, scripts, port usage, `app-config.yaml`, auth and test path. |
+| App only needs Play data connectors | Load `llm-data-and-bindings.md`; do not redesign auth/runtime. |
+| App only needs Play auth | Load `auth-services-and-testing.md`; do not add data bindings unless needed. |
+| App only runs as standalone | Do not apply Play constraints unless user asks. |
+| Play runtime itself is being changed | Read canonical docs in `C:\dev\aioson-play\.aioson\docs\integrations\` if available. |
+
+## Four questions before implementation
+
+For a Play-targeted app, answer these before creating files:
+
+1. Does the app have a visual UI?
+   - Yes: it needs a webview-facing process, usually Vite/Next or split-stack.
+   - No: it may be a CLI/sidecar-style app.
+
+2. Does the app expose an HTTP API?
+   - Yes: `manifest.json` needs `has_api: true`, the app must read `PORT`, and it should expose `GET /api/aioson-play`.
+   - No: skip `/api/aioson-play` unless another Play feature requires endpoint discovery.
+
+3. Does the app need external domain data?
+   - Yes: declare `data_bindings` in `app-config.yaml` and consume Global Connectors through ProductBridge.
+   - No: do not create connector UI or fake bindings.
+
+4. Does the app need users/operators?
+   - Owner/trial/billing: use `AIOSON_COM_TOKEN` and backend proxy routes.
+   - Local operators/RBAC: use `aioson-auth` as Play Service, declare `manifest.json` `auth.permissions[]`, and use `@aioson/auth-sdk`.
+   - No auth: do not add login just because it is a Play app.
+
+## Source priority
+
+Use this priority order:
+
+1. Project rule `.aioson/rules/aioson-play-conventions.md` for AIOSON-authored Play drafts.
+2. These `.aioson/docs/play/` docs for AIOSON agents implementing apps.
+3. Canonical Play docs in `C:\dev\aioson-play\.aioson\docs\integrations\` for exact or current runtime contracts.
+4. Existing app code patterns, only when they do not violate the above.
+
+## What agents must not infer
+
+- Do not infer fixed app ports.
+- Do not invent env vars.
+- Do not expose Database Connection creation inside the app UI.
+- Do not put provider API keys in `llm-chain.json`, `tools.json`, manifest, app docs, or frontend code.
+- Do not make browser code call `https://aioson.com` directly with a token.
+- Do not treat `aioson-auth` and `aioson.com` auth as the same system.
+- Do not create app permissions only in the Auth dashboard. For Play apps, the app declares the permission catalog in `manifest.json` `auth.permissions[]`; the dashboard assigns those permissions to roles.
+- Do not ask Auth or Play to scan source code for policies/permissions.
+- Do not add `@tauri-apps/api` to Play Services. Services are standalone background processes.
+- Do not assume SSO operator token injection is implemented unless the canonical Play docs and code confirm it.
+
+## Expected agent output
+
+For implementation, produce or verify:
+
+- `manifest.json`
+- `package.json` scripts that work under Play spawn
+- `app-config.yaml` when the app has database config or data bindings
+- `/api/aioson-play` when `has_api: true`
+- Lazy LLM client initialization when the app uses LLM providers
+- Degraded state when required bindings are absent
+- `manifest.json` `auth.permissions[]` when the app uses `aioson-auth`
+- Frontend/backend permission gates implemented with `@aioson/auth-sdk`
+- Local smoke steps through dev-link or standalone `PORT=...` run
+
+For QA, verify:
+
+- No hardcoded Play-managed port
+- No invented `VITE_AIOSON_*` env var
+- No secret in frontend or package artifact
+- Data bindings use alias names that match `app-config.yaml`
+- Auth path uses the right system: `aioson-auth` for operators, `aioson.com` for owner/trial
+- Apps using `aioson-auth` declare permissions in `manifest.json`, and those declared permissions match implemented route/API gates.
+- `manifest.compatibility` exists for publishable apps

package/template/.aioson/docs/play/app-compatibility-guide.md

@@ -0,0 +1,117 @@
+---
+description: "Operational checklist and implementation path for making an app compatible with AIOSON Play."
+scope: "global"
+agents: [dev, deyvin, architect, analyst, qa, tester, product, sheldon]
+task_types: [aioson-play-app, app-compatibility, implementation]
+triggers: [AIOSON Play, compatible app, app manifest, /api/aioson-play, Play draft, Play install]
+---
+
+# App Compatibility Guide
+
+## Mental model
+
+An AIOSON Play app is a child process managed by Play. It can be a frontend, backend, split-stack app, CLI/sidecar app, or app with Play Services. Play owns process launch, ports, registry, installed app lifecycle, and shared integration surfaces.
+
+The app owns its domain behavior, UI, operational database, migrations, API routes, and degraded mode.
+
+## Minimum app contract
+
+Every Play-compatible app should have:
+
+```text
+app/
+  manifest.json
+  package.json
+  app-config.yaml       # when it has database config or data bindings
+```
+
+If `has_api: true`, also expose:
+
+```text
+GET /api/aioson-play
+GET /api/health         # strongly recommended for debug/loading states
+```
+
+If the app has a UI, the Play webview must be able to load the UI from the process selected by the manifest.
+
+## Required behavior
+
+- Read `process.env.PORT` for the main Play-managed process.
+- In split-stack, read the configured env names such as `PORT` and `BACKEND_PORT`.
+- Keep browser-facing calls same-origin where possible. For split Vite apps, proxy `/api` and websocket routes through the frontend dev server instead of calling the backend port directly from browser code.
+- Use `http://localhost:5180` or `VITE_AIOSON_PLAY_URL` for ProductBridge calls.
+- Use `GET /api/registry` when discovering other apps or services dynamically.
+- Use `requires_services` for Play Service dependencies.
+- If the app uses `aioson-auth`, declare the permission catalog in `manifest.json` `auth.permissions[]` and implement matching gates in the app with `@aioson/auth-sdk`.
+- Keep app-local operational DB separate from Play Global Connectors.
+- Fail clearly or degrade gracefully when optional Play integrations are absent.
+
+## Do not do
+
+- Do not hardcode app runtime ports.
+- Do not assume `localhost:3000`, `5173`, `3301`, or any other port is stable for this app.
+- Do not use `npm install` in Play drafts. Use `pnpm` per the AIOSON Play draft convention.
+- Do not create a UI inside the app for creating global Database Connections or Data Connectors. Those live in Play Settings.
+- Do not put LLM provider secrets in files shipped with the app.
+- Do not call cloud APIs from browser code with `AIOSON_COM_TOKEN`.
+- Do not rely on Auth/Play scanning source code to discover permissions.
+- Do not create app permissions only in the Auth dashboard for manifest-driven Play apps.
+
+## Implementation sequence
+
+1. Add or audit `manifest.json`.
+2. Add or audit `package.json` scripts.
+3. Make every server listen on Play-injected env ports.
+4. Add `GET /api/aioson-play` if the app exposes API capabilities.
+5. Add `app-config.yaml` for operational DB defaults and/or `data_bindings`.
+6. Add Play auth only if the app needs it; include `requires_services: ["aioson-auth"]`, `auth.permissions[]`, and SDK gates.
+7. Add local smoke tests and dev-link run instructions.
+
+## Ready-for-Play checklist
+
+- [ ] `manifest.json` has stable `slug`, `name`, `version`.
+- [ ] Runtime fields match actual stack.
+- [ ] `has_api` matches reality.
+- [ ] `package.json` has a Play-compatible `dev` script.
+- [ ] No app code hardcodes a Play-managed port.
+- [ ] `GET /api/aioson-play` returns existing endpoints only.
+- [ ] `app-config.yaml` declares `data_bindings` if the app needs external domain data.
+- [ ] `app-config.yaml` declares `database.default_url` and `supported_drivers` if the app owns an operational DB.
+- [ ] App handles missing bindings with degraded UI or a clear blocking state.
+- [ ] LLM clients are lazy-initialized and read credentials from app config or injected env vars.
+- [ ] Auth uses the correct path: `aioson-auth` for operators/RBAC, `aioson.com` for owner/trial/billing.
+- [ ] Apps using `aioson-auth` declare `manifest.json` `auth.permissions[]`.
+- [ ] Declared permissions match frontend/backend gates implemented by the app.
+- [ ] Publishable apps declare `manifest.compatibility`.
+- [ ] Dev-link smoke was run inside Play or the app was manually started with a test `PORT`.
+
+## Smoke commands
+
+For an API app, run a standalone smoke before dev-link:
+
+```bash
+PORT=3399 pnpm dev
+curl http://localhost:3399/api/aioson-play
+curl http://localhost:3399/api/health
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:PORT = "3399"
+pnpm dev
+```
+
+Then install through Play:
+
+```text
+AIOSON Play -> Instalar App -> Linkar pasta (dev) -> select app folder
+```
+
+Validate:
+
+- App appears with DEV badge.
+- Webview renders.
+- API endpoint responds.
+- ProductBridge calls to `http://localhost:5180` work when Play is running.
+- Missing connectors/auth produce clear degraded states.