@jaimevalasek/aioson 1.30.0 → 1.30.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.30.1] - 2026-06-23
+
+### Added
+- **AIOSON Play app compatibility docs.** Added curated `.aioson/docs/play/` guidance for agents building apps that target AIOSON Play, shipped through the install/update template. It covers manifest/runtime behavior, ports, ProductBridge, `/api/aioson-play`, LLM env injection, app-owned databases, Data Bindings, auth, services, and local testing.
+- **Framework integration docs surface.** Added `.aioson/docs/integrations/dashboard-app-form-publish-mapping.md` as a framework-managed integration reference and shipped it through the install/update template.
+
+### Fixed
+- **Preservative integration docs update.** `update` now has regression coverage proving official framework integration docs are refreshed while project-owned files in `.aioson/docs/integrations/` remain untouched.
+
 ## [1.30.0] - 2026-06-22
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.30.0",
+  "version": "1.30.1",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/constants.js

@@ -53,9 +53,17 @@ const MANAGED_FILES = [
   '.aioson/docs/deyvin/continuity-recovery.md',
   '.aioson/docs/deyvin/pair-execution.md',
   '.aioson/docs/deyvin/runtime-handoffs.md',
-  '.aioson/docs/deyvin/debugging-escalation.md',
-  '.aioson/docs/handoff-persistence.md',
-  '.aioson/docs/sheldon/research-loop.md',
+  '.aioson/docs/deyvin/debugging-escalation.md',
+  '.aioson/docs/handoff-persistence.md',
+  '.aioson/docs/integrations/dashboard-app-form-publish-mapping.md',
+  '.aioson/docs/play/README.md',
+  '.aioson/docs/play/agent-usage-guide.md',
+  '.aioson/docs/play/app-compatibility-guide.md',
+  '.aioson/docs/play/auth-services-and-testing.md',
+  '.aioson/docs/play/llm-data-and-bindings.md',
+  '.aioson/docs/play/manifest-and-runtime.md',
+  '.aioson/docs/play/source-map.md',
+  '.aioson/docs/sheldon/research-loop.md',
   '.aioson/docs/sheldon/web-intelligence.md',
   '.aioson/docs/sheldon/quality-lens.md',
   '.aioson/docs/sheldon/enrichment-paths.md',

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,72 @@
+---
+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`
+- 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 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,106 @@
+---
+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`
+- `/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 and `@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 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
+- 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
+- `manifest.compatibility` exists for publishable apps

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

@@ -0,0 +1,112 @@
+---
+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.
+- 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`.
+
+## 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.
+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.
+- [ ] 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.

package/template/.aioson/docs/play/auth-services-and-testing.md

@@ -0,0 +1,220 @@
+---
+description: "AIOSON Play auth, cloud owner token, local operator auth, Play Services, requires_services, dev-link, symlink installs, and smoke testing."
+scope: "global"
+agents: [dev, deyvin, architect, qa, tester, pentester]
+task_types: [aioson-play-app, auth, service-integration, testing]
+triggers: [aioson-auth, AIOSON_COM_TOKEN, requires_services, service.json, dev-link, Play Services, smoke test]
+---
+
+# Auth, Services, And Testing
+
+## Auth systems
+
+AIOSON Play has two different auth surfaces:
+
+| Surface | Purpose | App receives |
+|---|---|---|
+| `aioson.com` cloud auth | Owner identity, trial, billing, license/status | `AIOSON_COM_TOKEN` |
+| `aioson-auth` Play Service | Local operators, login, RBAC, permissions | service URL and binding id |
+
+Do not mix them.
+
+Use `aioson.com` when the app needs subscription/trial/license state.
+Use `aioson-auth` when the app needs operators, roles, permissions, 2FA, or local RBAC.
+
+## Cloud owner/trial auth
+
+When the owner is logged into AIOSON Play, Play can inject:
+
+```text
+AIOSON_COM_TOKEN=<bearer token>
+```
+
+The app should read it on backend startup and persist it in local settings if needed. If absent, the app should fall back to manual login or a disconnected state.
+
+Do not call `https://aioson.com` directly from browser code with this token. Use backend proxy routes.
+
+Recommended backend proxy routes:
+
+| App route | Purpose |
+|---|---|
+| `GET /api/aioson/connection` | Check local token state |
+| `GET /api/aioson/status?projectId={id}` | Proxy app subscription/trial status |
+| `POST /api/aioson/login` | Manual cloud login fallback |
+| `DELETE /api/aioson/logout` | Clear local token |
+
+Cloud endpoints the backend may call:
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /api/app-auth/token` | Manual token acquisition |
+| `POST /api/apps/{slug}/install` | Idempotent install/trial registration |
+| `GET /api/apps/{slug}/status?projectId={id}` | Subscription/trial status |
+
+## Local operator auth and RBAC
+
+For operator login and RBAC, depend on `aioson-auth`:
+
+```json
+{
+  "requires_services": ["aioson-auth"]
+}
+```
+
+Use `@aioson/auth-sdk` as the client layer when available. Avoid handwritten calls to auth endpoints unless the SDK cannot cover the specific case.
+
+Env vars Play injects for auth (only these exist):
+
+```text
+VITE_AIOSON_AUTH_URL=http://localhost:3001
+VITE_AIOSON_AUTH_BINDING_ID=<binding-id>
+```
+
+Play injects only the `VITE_`-prefixed auth vars. There is no `AIOSON_AUTH_URL` or `AIOSON_AUTH_BINDING_ID` without the prefix — do not read those, they will be `undefined`. Backend Node code reads the same injected vars through `process.env.VITE_AIOSON_AUTH_URL` and `process.env.VITE_AIOSON_AUTH_BINDING_ID`; the `VITE_` prefix does not stop Node from reading them at runtime. The app slug is the only auth-relevant value injected in both forms: `AIOSON_APP_SLUG` and `VITE_AIOSON_APP_SLUG`.
+
+Bearer header is preferred for auth calls:
+
+```http
+Authorization: Bearer <jwt>
+```
+
+Legacy `?token=` may still work in older paths, but new app code should prefer Bearer.
+
+Current implemented auth expectations from the Play docs:
+
+- JWT can include `binding_id` and `permissions`.
+- `/me/permissions` exists in `aioson-auth`.
+- `@aioson/auth-sdk` MVP exists.
+- Operator SSO token injection from Play keyring is planned in docs, not safe to rely on unless the local code confirms it.
+
+## Owner bypass
+
+Some flows allow owner-implicit behavior through the owner cloud identity. Do not use that as a replacement for operator RBAC when the app has real multi-user operator roles.
+
+## Play Services
+
+A Play Service is infrastructure, not an app webview.
+
+Service shape:
+
+```text
+service/
+  service.json
+  package.json
+  dist/
+```
+
+`service.json`:
+
+```json
+{
+  "slug": "aioson-auth",
+  "name": "AIOSON Auth",
+  "version": "1.0.0",
+  "description": "Servico de autenticacao para apps do AIOSON Play.",
+  "port": 3001,
+  "autostart": true,
+  "dev_command": "node dist/server.js",
+  "health_check": "/health"
+}
+```
+
+Rules:
+
+- Use ports in `3001-3099`.
+- Read `process.env.PORT` in the service.
+- Implement `GET /health`.
+- Configure CORS for localhost app origins.
+- Do not depend on Tauri APIs inside a Play Service.
+- Build to `dist/` before publishing or local symlink service testing.
+
+## Dev-link install
+
+Use dev-link for active app development:
+
+```text
+AIOSON Play -> Instalar App -> Linkar pasta (dev) -> select app folder with manifest.json
+```
+
+Dev-link creates a symlink from Play's app data directory to the source folder. It allows fast iteration, but it is not a production publish validation.
+
+Windows note: symlink creation normally needs Developer Mode enabled or elevated privileges.
+
+When `manifest.json` changes during dev-link, stop and reopen the app in Play to force manifest reload.
+
+## Local symlink layout
+
+Common Play data locations:
+
+```text
+Windows: %LOCALAPPDATA%\com.aioson.play\
+Linux:   ~/.local/share/com.aioson.play/
+```
+
+Inside:
+
+```text
+apps/{slug}/
+services/{slug}/
+```
+
+For manual local testing, symlink app or service folders there. Prefer the Play UI dev-link flow when available.
+
+## Testing an app
+
+Standalone smoke:
+
+```bash
+PORT=3399 pnpm dev
+curl http://localhost:3399/api/health
+curl http://localhost:3399/api/aioson-play
+```
+
+Play smoke:
+
+```text
+1. Start AIOSON Play.
+2. Dev-link the app folder.
+3. Open the app from the Play shell.
+4. Confirm badge/running state.
+5. Confirm webview renders.
+6. Confirm ProductBridge calls to :5180 work.
+7. Confirm missing auth/bindings show clear degraded states.
+```
+
+Data binding smoke:
+
+```bash
+curl http://localhost:5180/api/registry
+curl http://localhost:5180/api/connectors
+curl http://localhost:5180/api/bindings/meu-app
+```
+
+Service smoke:
+
+```bash
+curl http://localhost:3001/health
+```
+
+## QA checklist
+
+- [ ] `requires_services` matches actual service use.
+- [ ] Missing service does not produce a confusing crash.
+- [ ] `AIOSON_COM_TOKEN` is never exposed to frontend code.
+- [ ] Operator auth uses SDK or Bearer-compatible client.
+- [ ] `VITE_AIOSON_AUTH_BINDING_ID` absence is handled.
+- [ ] Service uses `process.env.PORT`.
+- [ ] Service has `/health`.
+- [ ] App dev-link reload was tested after manifest changes.
+- [ ] ProductBridge `:5180` endpoints are called only when Play is running or with a fallback/degraded path.
+
+## Source docs
+
+Canonical sources:
+
+- `app-cloud-auth.md`
+- `auth-integration-gaps.md`
+- `play-service-protocol.md`
+- `dev-link-install.md`
+- `local-dev-testing.md`
+- `platform-architecture.md`

package/template/.aioson/docs/play/llm-data-and-bindings.md

@@ -0,0 +1,238 @@
+---
+description: "How AIOSON Play apps should consume LLM connections, app-owned databases, Data Bindings, Global Connectors, MCPI, REST connectors, MCP tools, and ProductBridge."
+scope: "global"
+agents: [dev, deyvin, architect, analyst, qa, tester]
+task_types: [aioson-play-app, data-integration, llm-integration]
+triggers: [LLM connections, DATABASE_URL, data_bindings, Global Connectors, MCPI, MCP tools, ProductBridge]
+---
+
+# LLM, Data, And Bindings
+
+## Three separate surfaces
+
+Do not mix these:
+
+| Surface | Owner | App does |
+|---|---|---|
+| LLM connections | AIOSON Play Settings | Reads injected env vars or metadata and lazy-inits clients |
+| Operational app DB | The app | Reads `DATABASE_URL`, runs migrations, owns data |
+| External/domain data | Play Global Connectors | Declares `data_bindings`, binds aliases, calls ProductBridge |
+
+## LLM connections
+
+Play manages global LLM connections in Settings:
+
+- one API key per provider
+- models validated by operation
+- fallback order by operation
+- capabilities such as vision/audio inferred from validated models
+
+Apps should not store Play LLM secrets in repository files or frontend code.
+
+Expected app behavior:
+
+- Prefer app-local explicit config only when the app intentionally lets the user override provider settings.
+- Otherwise read provider API keys injected by Play during spawn, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENROUTER_API_KEY`.
+- Lazy-initialize LLM clients. Do not instantiate SDK clients at module load, because missing keys can crash the backend before the app can render a degraded state.
+- Treat `llm-chain.json` as metadata/order only when present. It must not contain API keys.
+- Treat `aioson-models.json` or `llm-chain.json` in the app cwd as optional/legacy for installed apps, not the primary credential contract.
+
+Recommended lazy pattern:
+
+```ts
+let client: OpenAI | null = null;
+
+function getOpenAiClient() {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) return null;
+  client ??= new OpenAI({ apiKey });
+  return client;
+}
+```
+
+Supported operation names in current Play docs include:
+
+- `text_generation`
+- `code_generation`
+- `image_understanding`
+- `image_generation`
+- `video_understanding`
+- `video_generation`
+- `speech_to_text`
+- `text_to_speech`
+- `audio_understanding`
+- `realtime_voice`
+
+## Operational database of the app
+
+The app owns its own operational database. Play does not provide a shared app database.
+
+Default recommendation:
+
+- SQLite with WAL mode for most local-first apps.
+- Read `DATABASE_URL` from env with fallback to `app-config.yaml`.
+- Declare supported drivers from day 1 even if only SQLite is used.
+
+`app-config.yaml` pattern:
+
+```yaml
+database:
+  default_url: "sqlite://./data/app.db?mode=rwc"
+  supported_drivers: ["sqlite", "postgres"]
+  sqlite_pragmas:
+    journal_mode: "WAL"
+    synchronous: "NORMAL"
+    busy_timeout: 5000
+```
+
+App code pattern:
+
+```ts
+const url = process.env.DATABASE_URL ?? config.database.default_url;
+const driver = url.startsWith("postgres://") ? "postgres" : "sqlite";
+const db = await connect(url, driver);
+
+if (driver === "sqlite") {
+  await db.exec("PRAGMA journal_mode=WAL");
+  await db.exec("PRAGMA synchronous=NORMAL");
+  await db.exec("PRAGMA busy_timeout=5000");
+}
+```
+
+Only move beyond SQLite when there is an objective need, such as:
+
+- persistent `SQLITE_BUSY` after WAL and `busy_timeout`
+- `pgvector`
+- serious JSONB indexing
+- full-text ranking beyond SQLite FTS5
+- multiple app processes writing to the same database
+- pre-existing customer Postgres infrastructure
+- multi-device sync or online-first architecture
+
+## External data through Data Bindings
+
+External domain data belongs to Play Global Connectors, not to app-specific connection UIs.
+
+The app declares slots in `app-config.yaml`:
+
+```yaml
+data_bindings:
+  - id: "busca-produtos"
+    description: "Busca produtos no catalogo por nome ou principio ativo"
+    accepted_types: ["mcpi", "api", "mcp"]
+    required_params:
+      - "search"
+
+  - id: "webhook-pedido"
+    description: "Notifica sistema externo quando um pedido e confirmado"
+    accepted_types: ["api"]
+    required_params:
+      - "pedido_json"
+```
+
+Fields:
+
+| Field | Meaning |
+|---|---|
+| `id` | Slot slug. Also the binding alias. Prefer kebab-case. |
+| `description` | Human-readable text for the app/admin UI. |
+| `accepted_types` | Canonical array: `mcpi`, `api`, `mcp`. |
+| `required_params` | Placeholder names expected by the connector. |
+
+`expected_type` is legacy. Prefer `accepted_types` in new apps.
+
+## What Play owns
+
+Play Settings owns:
+
+- Database Connections
+- Data Connectors
+- credential/keyring storage for connector auth
+- connector validation status
+- global admin view of App Data Sources
+
+For MCPI connectors, only validated Database Connections should be selectable when the driver supports validation.
+
+## What the app owns
+
+The app should expose a "Fontes de Dados" or equivalent in-app view when it has `data_bindings`.
+
+The app consumes ProductBridge:
+
+```ts
+const PLAY_BASE = import.meta.env.VITE_AIOSON_PLAY_URL || "http://localhost:5180";
+const APP_SLUG = import.meta.env.VITE_AIOSON_APP_SLUG || "meu-app";
+
+const connectors = await fetch(`${PLAY_BASE}/api/connectors?type=mcpi`).then(r => r.json());
+const bindings = await fetch(`${PLAY_BASE}/api/bindings/${APP_SLUG}`).then(r => r.json());
+
+await fetch(`${PLAY_BASE}/api/bindings/${APP_SLUG}`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    connector_id: "<uuid-do-connector>",
+    alias: "busca-produtos"
+  })
+});
+```
+
+## Executing connectors
+
+After binding, execute through ProductBridge by alias:
+
+```http
+POST http://localhost:5180/api/mcp/execute
+Content-Type: application/json
+
+{
+  "alias": "busca-produtos",
+  "params": {
+    "search": "dipirona"
+  }
+}
+```
+
+The alias must match both:
+
+- `data_bindings[].id`
+- the active binding alias
+
+## Degraded state
+
+If a declared binding is absent:
+
+- Do not crash.
+- Show a clear degraded state.
+- Link the user to the app's data-source binding UI when possible.
+- For non-optional connectors, block only the affected workflow, not the whole app unless the app cannot function.
+
+Boot check:
+
+```ts
+async function getMissingBindings(appSlug: string) {
+  const playBase = import.meta.env.VITE_AIOSON_PLAY_URL || "http://localhost:5180";
+  const bindings = await fetch(`${playBase}/api/bindings/${appSlug}`).then(r => r.json());
+  const activeAliases = new Set(bindings.map((b: { alias: string }) => b.alias));
+  return declaredBindings.filter(binding => !activeAliases.has(binding.id));
+}
+```
+
+## LLM tool injection
+
+Global Connectors are only useful to the LLM after they are bound to the app. Play can generate tool metadata from bindings, and the sidecar/orchestrator can use it in LLM payloads.
+
+Agent rule:
+
+- Keep connector names and descriptions accurate.
+- Do not advertise tools/endpoints that are not implemented.
+- Use prepared statements or connector-side parameterization for MCPI. The LLM must not assemble raw SQL.
+
+## Source docs
+
+Canonical sources:
+
+- `app-data-bindings.md`
+- `app-database-choice.md`
+- `integration-manual.md`
+- `ai-app-integration.md`
+- `platform-architecture.md`

package/template/.aioson/docs/play/manifest-and-runtime.md

@@ -0,0 +1,244 @@
+---
+description: "AIOSON Play app manifest, runtime, package manager, scripts, ports, endpoint declaration, split-stack, and compatibility contract."
+scope: "global"
+agents: [dev, deyvin, architect, qa, tester]
+task_types: [aioson-play-app, runtime, manifest]
+triggers: [manifest.json, Play runtime, PORT, pnpm, ProductBridge, /api/aioson-play, requires_services]
+---
+
+# Manifest And Runtime
+
+## Manifest basics
+
+`manifest.json` is the app identity and runtime contract for Play.
+
+Minimum shape:
+
+```json
+{
+  "slug": "meu-app",
+  "name": "Meu App",
+  "version": "0.1.0",
+  "runtime": "vite",
+  "has_api": true
+}
+```
+
+Use stable lowercase slugs. The same slug is reused by Play registry, `VITE_AIOSON_APP_SLUG`, auth binding, cloud app status, package/update metadata, and data bindings.
+
+## Runtime detection
+
+Play can detect common Node stacks from `package.json`, but explicit manifest fields are allowed when autodetect is not enough.
+
+Supported Node runtime families in current docs:
+
+| Stack | Signal |
+|---|---|
+| Next.js | `next` dependency |
+| Vite | `vite` dependency or devDependency |
+| Generic Node | `scripts.dev` |
+
+For Play drafts and AIOSON-authored app work, use `pnpm`:
+
+- `pnpm install`
+- `pnpm add <pkg>`
+- `pnpm add -D <pkg>`
+- canonical lockfile: `pnpm-lock.yaml`
+
+Do not create or preserve `package-lock.json` or `yarn.lock` in Play draft work unless an existing non-Play app explicitly requires it.
+
+## Scripts
+
+`package.json` should provide a single Play entrypoint:
+
+```json
+{
+  "scripts": {
+    "dev": "node src/server.js",
+    "start": "node dist/server.js"
+  }
+}
+```
+
+Rules:
+
+- `dev` must work when Play injects `PORT`.
+- `start` should work for published/build output when source is absent.
+- Do not put fixed app ports in scripts.
+- Do not run production build as the dev command.
+- In Play drafts, do not fight the Play-injected cache env vars for Next/Vite/SWC.
+
+## Ports
+
+Reserved ranges:
+
+| Range | Purpose |
+|---|---|
+| `3001-3099` | Play Services, fixed in `service.json` |
+| `3100-3299` | Internal Play systems, do not use |
+| `3300-3499` | Marketplace-installed apps |
+| `3500-3999` | Draft/dev-link apps |
+| `4000-4099` | External curated apps, compatibility range |
+| `5173` | Vite dev default, not a Play app contract |
+| `5180` | ProductBridge HTTP server |
+
+Rule: the app reads its own port from env; it discovers other ports through ProductBridge or service env vars.
+
+Generic Node server:
+
+```js
+const port = Number(process.env.PORT) || 3000;
+app.listen(port, "0.0.0.0");
+```
+
+Split-stack backend:
+
+```js
+const port = Number(process.env.BACKEND_PORT) || 3301;
+server.listen(port, "0.0.0.0");
+```
+
+## Split-stack apps
+
+Use split-stack when the app has separate frontend and backend processes.
+
+Manifest pattern:
+
+```json
+{
+  "slug": "meu-app",
+  "name": "Meu App",
+  "version": "0.1.0",
+  "stack": "split",
+  "processes": {
+    "frontend": { "port_env": "PORT", "framework": "vite" },
+    "backend": { "port_env": "BACKEND_PORT", "framework": "node" }
+  },
+  "webview_target": "frontend"
+}
+```
+
+Rules:
+
+- `webview_target` must match a key under `processes`.
+- The frontend port is for the Play webview.
+- Browser code should call `/api` same-origin and let Vite/Next proxy to the backend.
+- The backend should use `BACKEND_PORT`.
+- Do not hardcode `BACKEND_PORT` in scripts.
+
+## Next.js and Vite notes
+
+For Next.js in Play drafts, include `allowedDevOrigins` with explicit loopback hosts. Next 16+ does not accept a wildcard for this case.
+
+```ts
+const nextConfig = {
+  allowedDevOrigins: ["127.0.0.1", "localhost", "::1", "0.0.0.0"]
+};
+
+export default nextConfig;
+```
+
+For Vite in Play drafts, prefer the current AIOSON Play draft convention: let Play pass the port through its spawn command and avoid declaring a fixed `server.port` unless the existing app contract explicitly uses env-driven split-stack config.
+
+## ProductBridge
+
+ProductBridge is fixed at:
+
+```text
+http://localhost:5180
+```
+
+In browser/frontend code:
+
+```ts
+const PLAY_URL = import.meta.env.VITE_AIOSON_PLAY_URL || "http://localhost:5180";
+```
+
+Useful endpoints:
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/registry` | Discover running apps and Play Services |
+| `GET /api/connectors` | List Global Connectors |
+| `GET /api/bindings/:app_slug` | List app bindings |
+| `POST /api/bindings/:app_slug` | Bind connector to app slot |
+| `POST /api/mcp/execute` | Execute connector by alias |
+
+## Capability endpoint
+
+If `has_api: true`, expose:
+
+```text
+GET /api/aioson-play
+```
+
+It declares identity, API base URL, endpoints, auth metadata, and events for Play, Bridge Apps, and LLM orchestration.
+
+Minimum response shape:
+
+```json
+{
+  "name": "Meu App",
+  "slug": "meu-app",
+  "version": "0.1.0",
+  "api_base_url": "http://localhost:3399",
+  "endpoints": [
+    {
+      "path": "/api/items",
+      "method": "GET",
+      "description": "Lista itens visiveis ao usuario",
+      "params": [],
+      "auth": false
+    }
+  ],
+  "events": []
+}
+```
+
+Only list endpoints that exist. The orchestrator may try to call what this endpoint advertises.
+
+## Services dependency
+
+When an app requires a Play Service:
+
+```json
+{
+  "requires_services": ["aioson-auth"]
+}
+```
+
+Play uses this to show onboarding requirements, check service install/runtime state, and block or degrade app launch when the required service is missing.
+
+## Publish compatibility
+
+Publishable apps should declare compatibility:
+
+```json
+{
+  "compatibility": {
+    "min_play_version": "0.2.0",
+    "min_runtime_version": "1.0.0",
+    "max_runtime_version": "1.x",
+    "sidecar_contract": "ndjson-v1",
+    "schema_version": 1,
+    "requires_migration": false
+  }
+}
+```
+
+If local data schema changes:
+
+- Increment `schema_version`.
+- Provide idempotent migrations where possible.
+- Never delete user data as the default migration strategy.
+- Use backup before destructive or risky migration.
+
+## Source docs
+
+Canonical sources:
+
+- `ai-app-integration.md`
+- `aioson-endpoint-protocol.md`
+- `port-management.md`
+- `software-update-compatibility.md`
+- `.aioson/rules/aioson-play-conventions.md` in this repo

package/template/.aioson/docs/play/source-map.md

@@ -0,0 +1,104 @@
+---
+description: "Map from AIOSON Play app compatibility topics to canonical source docs in the aioson-play repository."
+scope: "global"
+agents: [dev, deyvin, architect, analyst, qa, tester, product, sheldon, pentester]
+task_types: [aioson-play-app, source-map, integration]
+triggers: [AIOSON Play source docs, canonical Play docs, integration docs, ProductBridge, data bindings]
+---
+
+# Source Map
+
+Canonical source directory:
+
+```text
+C:\dev\aioson-play\.aioson\docs\integrations\
+```
+
+This AIOSON folder is a curated operational layer. When exact Play runtime behavior matters and the source repo is present, read the canonical file below.
+
+## Entry points
+
+| Need | Canonical doc |
+|---|---|
+| Build or modify a Play-compatible app | `ai-app-integration.md` |
+| Cross-cutting Play/platform fix | `platform-architecture.md` |
+| Auth roadmap/gaps and delivered slices | `auth-integration-gaps.md` |
+
+## Topic map
+
+| Topic | Canonical doc |
+|---|---|
+| App developer overview | `aioson-app-developer-guide.md` |
+| `/api/aioson-play` capability endpoint | `aioson-endpoint-protocol.md` |
+| ProductBridge and port registry | `port-management.md` |
+| Play Services and `service.json` | `play-service-protocol.md` |
+| Cloud owner/trial auth | `app-cloud-auth.md` |
+| Data Bindings and Global Connectors | `app-data-bindings.md` |
+| App operational database choice | `app-database-choice.md` |
+| External systems, MCPI/API/MCP connector manual | `integration-manual.md` |
+| Dev-link install | `dev-link-install.md` |
+| Local symlink testing | `local-dev-testing.md` |
+| App update and compatibility fields | `software-update-compatibility.md` |
+| Atendimento reference integration | `atendimento-squad-integration.md` |
+| Farmacia implementation review | `farmacia-implementation-review.md` |
+
+## Current source docs observed
+
+As of 2026-06-23, the Play integration source directory contains:
+
+```text
+ai-app-integration.md
+aioson-app-developer-guide.md
+aioson-endpoint-protocol.md
+app-cloud-auth.md
+app-data-bindings.md
+app-database-choice.md
+atendimento-squad-integration.md
+auth-integration-gaps.md
+dev-link-install.md
+farmacia-implementation-review.md
+integration-manual.md
+local-dev-testing.md
+platform-architecture.md
+play-service-protocol.md
+port-management.md
+README.md
+software-update-compatibility.md
+```
+
+## Embedded contract stamped into apps
+
+Play stamps a canonical contract directly into each app, between
+`AIOSON-PLAY-CONTRACT:START` / `AIOSON-PLAY-CONTRACT:END` markers. Source:
+
+```text
+C:\dev\aioson-play\src-tauri\src\resources\play_app_contract.md
+```
+
+This is the most authoritative single-file contract for an installed app. It carries:
+
+- The closed whitelist of env vars Play injects at spawn, including `AIOSON_APP_DIR` (absolute app dir) and the auth vars in `VITE_`-only form.
+- `.aioson/preview.json` — written by Play at runtime with `{ running, url, port }`; read it on demand to learn the live preview URL/port instead of guessing.
+- The "ready-for-Play" gate the app must pass before being declared done.
+
+When an app project already contains this stamped block, treat it as primary and do not contradict it. The docs in this folder are the AIOSON-side fallback when the stamped contract or the `aioson-play` repo is not available.
+
+## Known priority notes
+
+- `.aioson/rules/aioson-play-conventions.md` in this AIOSON repo overrides older examples when working inside Play drafts, especially package manager and draft runtime behavior.
+- Older Play docs may show `npm` examples. In AIOSON-authored Play draft work, use `pnpm`.
+- Some canonical docs describe planned behavior. Check wording before implementing: "planejado", "futuro", "pendente", or "nao implementado" means do not rely on it as shipped runtime behavior.
+- If a canonical doc and local Play source code disagree, inspect code and update the canonical Play doc before relying on the changed behavior.
+
+## Suggested human-facing Play Guide page
+
+If AIOSON Play exposes a "Guia" tab for human users, it should not dump these agent docs. It should present a short human path:
+
+1. Create an app folder with `manifest.json`.
+2. Use `pnpm`.
+3. Make the app read `PORT`.
+4. Add `app-config.yaml` only when using database config or data sources.
+5. Link the folder through "Instalar App -> Linkar pasta (dev)".
+6. Test inside the Play webview.
+
+The detailed implementation contract should remain here for AIOSON agents and in the canonical `aioson-play` integration docs.