@percepta/create 3.0.0

package/templates/webapp/agent-skills/deploy.md

@@ -0,0 +1,94 @@
+# Deploying to Percepta Test
+
+This guide deploys __APP_TITLE__ to `https://__APP_NAME__.percepta-test.aitco.dev` using Ryvn. Tell Claude "deploy this app to percepta-test" and it will follow the steps below.
+
+## What's already scaffolded
+
+When this app was created with `@percepta/create`, the IaC files were generated at `deploy/ryvn/` with all values pre-filled:
+
+- `deploy/ryvn/__APP_NAME__.service.yaml` — Ryvn Service definition
+- `deploy/ryvn/environments/percepta-test/installations/__APP_NAME__.env.percepta-test.serviceinstallation.yaml` — percepta-test installation
+- `.github/workflows/__APP_NAME__-ryvn-release.yaml` (at the repo root) — release workflow that builds the Docker image and creates a Ryvn release on push to `main`. Path filter scoped to `packages/__APP_NAME__/` so unrelated changes don't trigger builds.
+
+Per-app values (URLs, k8s service names, database name) are substituted at create-time. Shared platform values (Inngest, Langfuse, OTel endpoints) are baked in as literals — they're stable across percepta-test apps. Three secrets stay in the Ryvn UI.
+
+See [`deploy/README.md`](../deploy/README.md) for the file-by-file breakdown.
+
+## Prerequisites
+
+- The app repo is under the `Percepta-Core` GitHub org. If not yet, run `gh repo create Percepta-Core/__APP_NAME__ --private --source=. --push` from the monorepo root.
+- The Percepta-Core org has `RYVN_CLIENT_ID`, `RYVN_CLIENT_SECRET`, and `NPM_TOKEN` as org-level GitHub secrets (already in place).
+- The `percepta-internal-terraform` installation provides the shared PostgreSQL — already deployed on percepta-test.
+- The infra repo (`Percepta-Core/infra`) is checked out locally, typically at `../../infra` relative to this package.
+
+## Deploy
+
+### Step 1: Open the infra PR
+
+Copy the two scaffolded files into the infra repo and open a PR:
+
+```bash
+INFRA=../../infra   # adjust to your local path
+NAME=__APP_NAME__
+
+cp deploy/ryvn/$NAME.service.yaml \
+   $INFRA/ryvn/$NAME.service.yaml
+
+cp deploy/ryvn/environments/percepta-test/installations/$NAME.env.percepta-test.serviceinstallation.yaml \
+   $INFRA/ryvn/environments/percepta-test/installations/$NAME.env.percepta-test.serviceinstallation.yaml
+
+cd $INFRA
+git checkout -b deploy/$NAME-percepta-test
+git add ryvn/$NAME.service.yaml ryvn/environments/percepta-test/installations/$NAME.env.percepta-test.serviceinstallation.yaml
+git commit -m "Add $NAME service + percepta-test installation"
+git push -u origin deploy/$NAME-percepta-test
+gh pr create --fill
+```
+
+Get the PR reviewed and merged.
+
+### Step 2: Set the three secrets in the Ryvn UI
+
+After the infra PR merges, Ryvn creates the installation. Open the Ryvn UI for the `__APP_NAME__` installation in `percepta-test` and set:
+
+| Secret | Value |
+|--------|-------|
+| `BETTER_AUTH_SECRET` | `openssl rand -base64 32` |
+| `ENCRYPTION_SECRET_KEY` | `openssl rand -hex 16` |
+| `LANGFUSE_SECRET_KEY` | from 1Password: "Percepta Test Secrets" |
+
+### Step 3: Trigger the first deploy
+
+Push to `main` in the app repo (or `gh workflow run "Build & Release __APP_NAME__"`). The release workflow builds the Docker image and creates a Ryvn release; Ryvn deploys it to percepta-test.
+
+The workflow lives at `.github/workflows/__APP_NAME__-ryvn-release.yaml` (at the repo root, where GitHub Actions picks it up). It only fires on changes under `packages/__APP_NAME__/`, so unrelated edits to other packages in the monorepo won't trigger it.
+
+### Step 4: Verify
+
+```bash
+ryvn get installation __APP_NAME__ -e percepta-test
+ryvn logs __APP_NAME__ -e percepta-test
+curl -s https://__APP_NAME__.percepta-test.aitco.dev/api/healthz
+curl -s https://__APP_NAME__.percepta-test.aitco.dev/api/readyz
+```
+
+The app will be available at **https://__APP_NAME__.percepta-test.aitco.dev**.
+
+## Troubleshooting
+
+- **Pod crash-looping** → secrets probably aren't set yet (Step 2). Check `ryvn logs`.
+- **Database connection refused** → verify `DATABASE_USE_SSL=true` and that `percepta-internal-terraform` is deployed.
+- **Inngest can't reach the app** → `INNGEST_APP_URL` must use the k8s service name `__APP_NAME__-web-server`. The scaffolded YAML gets this right; if you renamed anything, double-check.
+- **Image build fails** → check `NPM_TOKEN` in the service definition is current. Build context is `packages/__APP_NAME__`.
+
+For Ryvn CLI operations, use the `/use-ryvn` skill.
+
+## Updating shared platform values
+
+The Inngest/Langfuse/OTel URLs are baked as literals in every webapp's installation YAML. If percepta-test infra ever changes those endpoints, update them with a single grep across the infra repo:
+
+```bash
+grep -rl "inngest.percepta-test.svc.cluster.local:8288" ryvn/environments/percepta-test/installations/
+```
+
+A future improvement would be a shared ConfigMap or Ryvn output reference; for now the scaffolded literals are the convention.

package/templates/webapp/agent-skills/inngest.md

@@ -0,0 +1,147 @@
+# Inngest — Background Jobs & Agent Workflows
+
+Inngest is a durable execution engine for background tasks. Instead of managing queues, workers, and retries yourself, you define functions that respond to events — Inngest handles scheduling, retries, concurrency, and observability. Think of it as "cron jobs + event-driven workflows + built-in retry logic" in one tool.
+
+In this template, Inngest powers all async work: background processing, scheduled jobs, multi-step agent pipelines, and anything that shouldn't block the HTTP request/response cycle.
+
+## Adding a New Event
+
+### 1. Define the payload schema
+
+Create a Zod schema for the event payload:
+
+```typescript
+import z from "zod";
+
+export type DocumentProcessedPayload = z.infer<typeof DocumentProcessedPayload.SCHEMA>;
+export namespace DocumentProcessedPayload {
+  export const SCHEMA = z.object({
+    documentId: z.string(),
+    userId: z.string(),
+    pageCount: z.number(),
+  });
+}
+```
+
+### 2. Register in AppEvents
+
+Add the event to the central `AppEvents` registry:
+
+```typescript
+import { DocumentProcessedPayload } from "./payloads/DocumentProcessedPayload";
+
+export const AppEvents = {
+  "app/document.processed": z.object({
+    data: DocumentProcessedPayload.SCHEMA,
+  }),
+};
+```
+
+Event names follow the convention `"app/<entity>.<action>"`.
+
+## Adding a New Function
+
+### 1. Create a function collection
+
+Group related functions into a collection class that implements `InngestFunctionCollection`:
+
+```typescript
+import { type InngestFunction } from "inngest";
+import { type InngestFunctionCollection } from "../InngestFunctionCollection";
+import { InngestService } from "../InngestService";
+
+export class DocumentFunctions implements InngestFunctionCollection {
+  private inngestService = InngestService.create();
+
+  public get functions(): InngestFunction.Like[] {
+    return [this.processDocument()];
+  }
+
+  private processDocument() {
+    return this.inngestService.createFunction(
+      { id: "process-document", retries: 3 },
+      { event: "app/document.processed" },
+      async ({ event, step }) => {
+        const { documentId, userId } = event.data;
+
+        // step.run wraps each unit of work for durability — if a step fails,
+        // Inngest retries from that step, not from the beginning
+        const extracted = await step.run("extract-text", async () => {
+          // ... extract text from document
+          return { text: "..." };
+        });
+
+        await step.run("store-results", async () => {
+          // ... save to database
+        });
+      },
+    );
+  }
+}
+```
+
+### 2. Register with the serve endpoint
+
+Add your collection to the `functionCollections` array in the Inngest serve endpoint:
+
+```typescript
+const functionCollections: InngestFunctionCollection[] = compact([
+  new DocumentFunctions(),
+]);
+```
+
+## Sending Events
+
+```typescript
+const inngest = InngestService.create();
+await inngest.client.send({
+  name: "app/document.processed",
+  data: { documentId: "abc", userId: "user-1", pageCount: 5 },
+});
+```
+
+## Running Inngest Locally
+
+### 1. Install the Inngest Dev Server
+
+```bash
+pnpm dlx inngest-cli@latest dev
+```
+
+This starts the Inngest Dev Server at `http://localhost:8288` with a dashboard UI.
+
+### 2. Set environment variables
+
+In `.env.local`:
+
+```bash
+INNGEST_BASE_URL=http://localhost:8288
+INNGEST_EVENT_KEY=local           # any value works locally
+# INNGEST_SIGNING_KEY is not needed for local dev
+```
+
+### 3. Start the app
+
+```bash
+pnpm dev
+```
+
+The Inngest Dev Server auto-discovers functions by calling the serve endpoint at `/api/inngest`. Open `http://localhost:8288` to see registered functions, trigger events manually, and inspect runs.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `INNGEST_BASE_URL` | Yes | Inngest server URL (`http://localhost:8288` locally) |
+| `INNGEST_EVENT_KEY` | Yes (prod) | Event authentication key |
+| `INNGEST_SIGNING_KEY` | Yes (prod) | Function registration signing key |
+| `INNGEST_APP_URL` | No | Override app URL for Inngest to call back |
+| `SKIP_INNGEST_SYNC` | No | Set `true` to skip Inngest app sync on startup |
+
+## Key Concepts
+
+- **Events** are the trigger. Define them with Zod schemas for runtime validation.
+- **Functions** respond to events. They contain one or more **steps**.
+- **Steps** (`step.run`, `step.sleep`, `step.waitForEvent`) are durable — if the function crashes mid-execution, Inngest resumes from the last completed step.
+- **Retries** are automatic. Default is 3 retries with exponential backoff.
+- The `InngestService` singleton wraps the Inngest client and enforces typed events via `AppEvents`.

package/templates/webapp/agent-skills/langfuse.md

@@ -0,0 +1,117 @@
+# Langfuse — LLM Observability & Tracing
+
+Langfuse is an open-source LLM observability platform. It captures traces, spans, and generations from LLM calls so you can debug prompt behavior, monitor latency/cost, and run evaluations. Think of it as "Datadog for LLM apps."
+
+**Our opinionated setup:** We integrate Langfuse via OpenTelemetry (OTEL), not the Langfuse SDK directly. OTEL auto-instruments the app (HTTP, DB, etc.), and Langfuse acts as a span processor that receives LLM-specific traces. This gives us unified tracing — both traditional backend spans and LLM generations in the same trace.
+
+## When to Use Langfuse
+
+**Use Langfuse when the app calls LLMs** (OpenAI, Bedrock/Claude, etc.). It gives you:
+- Trace visualization of multi-step LLM chains
+- Token usage and cost tracking per request
+- Prompt versioning and A/B testing
+- Evaluation scores attached to traces
+
+**Skip Langfuse when the app has no LLM calls.** The OTEL instrumentation still works without Langfuse — you just won't have the LLM-specific dashboard. If Langfuse env vars are not set, the integration gracefully no-ops.
+
+## How It Works
+
+### OpenTelemetry + Langfuse Span Processor
+
+The template uses Next.js's instrumentation hook (called on server startup) to bootstrap OTEL with Langfuse:
+
+```typescript
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+
+const sdk = new NodeSDK({
+  spanProcessors: [new LangfuseSpanProcessor({ baseUrl, publicKey, secretKey })],
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+sdk.start();
+```
+
+- `getNodeAutoInstrumentations()` automatically instruments HTTP calls, database queries, and other standard Node.js operations.
+- `LangfuseSpanProcessor` forwards spans to Langfuse. LLM spans (from the Vercel AI SDK or OpenAI SDK) are recognized and displayed as generations in the Langfuse UI.
+
+**You do not need to manually instrument LLM calls.** If you use the Vercel AI SDK (`ai` package) or the OpenAI SDK, OTEL picks them up automatically.
+
+### LangfuseService (Direct API)
+
+For operations beyond automatic tracing — like attaching metadata or evaluation scores to a trace — the template includes a `LangfuseService` singleton:
+
+```typescript
+const langfuse = LangfuseService.create();
+
+if (langfuse.isConfigured()) {
+  await langfuse.updateTraceMetadata(traceId, {
+    userId: "user-123",
+    feedbackScore: 0.95,
+  });
+}
+```
+
+This is a singleton — `create()` returns the same instance every time. It gracefully no-ops when Langfuse is not configured.
+
+## Getting Langfuse Keys
+
+### Percepta's Internal Instance
+
+Percepta runs a shared Langfuse instance. To get keys:
+
+1. Ask your team lead for access to the Percepta Langfuse instance
+2. Log into the Langfuse dashboard
+3. Go to **Settings → API Keys** and create a new key pair
+4. You'll get a **public key** and **secret key**
+
+### Self-Hosted / Langfuse Cloud
+
+For external projects, you can:
+- Use [Langfuse Cloud](https://cloud.langfuse.com) (free tier available)
+- Self-host with `docker run langfuse/langfuse`
+
+## Running Locally
+
+### Option 1: Use Percepta's Langfuse (recommended)
+
+Set the keys in `.env.local` pointing to the shared instance:
+
+```bash
+LANGFUSE_BASE_URL=https://langfuse.internal.percepta.ai  # ask team for actual URL
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
+```
+
+Traces from local dev appear in the shared dashboard under your project.
+
+### Option 2: Run Langfuse locally
+
+```bash
+docker run -d --name langfuse \
+  -p 3001:3000 \
+  -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5434/langfuse \
+  langfuse/langfuse
+```
+
+Then set:
+
+```bash
+LANGFUSE_BASE_URL=http://localhost:3001
+LANGFUSE_PUBLIC_KEY=pk-lf-...   # create in local UI after first login
+LANGFUSE_SECRET_KEY=sk-lf-...
+```
+
+### Option 3: Skip Langfuse entirely
+
+Simply don't set the `LANGFUSE_*` env vars. The instrumentation gracefully skips the Langfuse span processor, and `LangfuseService.isConfigured()` returns `false`. OTEL still instruments the app for general tracing.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `LANGFUSE_BASE_URL` | No | Langfuse server URL. If unset, Langfuse integration is disabled. |
+| `LANGFUSE_PUBLIC_KEY` | No | Public key from Langfuse dashboard |
+| `LANGFUSE_SECRET_KEY` | No | Secret key from Langfuse dashboard |
+
+All three must be set for Langfuse to activate. If any is missing, the integration silently no-ops.

package/templates/webapp/agent-skills/oneshot.md

@@ -0,0 +1,216 @@
+# Oneshot — Build a Complete App from Requirements
+
+Build a full application end-to-end in one shot: gather requirements, design, implement, verify locally, create the GitHub repo, and optionally deploy — fully autonomous after requirements are locked.
+
+**When to use this:** The user has scaffolded a new project with `@percepta/create` and wants to build an app on top of it. They'll describe what they want at a high level. Your job is to turn that into a running application.
+
+<HARD-GATE>
+After requirements are confirmed, do NOT stop and give the turn back to the user until the app is fully built and running locally. Do NOT ask for approval between phases. Make reasonable assumptions and keep moving. The user can interrupt with course corrections at any time — treat those as input, not as a reason to pause.
+</HARD-GATE>
+
+## Process Flow
+
+```
+Gather requirements
+  → Confirm with user (ONLY pause point)
+  → Design architecture
+  → Implement in a loop (build → verify → fix → repeat)
+  → Get local app running
+  → Create GitHub repo
+  → [If requested] Deploy to Ryvn
+```
+
+---
+
+## Phase 1: Gather Requirements
+
+Ask the user structured questions AND open-ended questions. Do this in ONE message — do not drip-feed questions across multiple turns.
+
+### Structured Questions
+
+Ask all that are relevant:
+
+1. **What does this app do?** One-sentence description of the core purpose.
+2. **Who are the users?** Internal team, external customers, both?
+3. **What are the core entities?** (e.g., "Documents, Users, Teams" — the nouns in the data model)
+4. **What are the key workflows?** (e.g., "User uploads a document → system extracts text → user reviews results")
+5. **Does this app call LLMs?** If yes, which provider (OpenAI, Bedrock/Claude, both)? What for?
+6. **Does this app need background jobs?** Long-running tasks, scheduled jobs, multi-step pipelines?
+7. **Auth requirements?** Which provider — Google, Okta, Credentials, or just use the template default?
+8. **Any external integrations?** APIs, webhooks, third-party services?
+
+### Open-Ended
+
+After the structured questions, ask:
+
+> "Is there anything else I should know about this app — constraints, design preferences, prior art, or things you definitely don't want?"
+
+### Confirm Requirements
+
+Summarize what you understood back to the user in a structured format:
+
+```
+## Requirements Summary
+
+**App:** [one sentence]
+**Users:** [who]
+**Entities:** [list]
+**Workflows:** [numbered list]
+**LLM usage:** [yes/no, details]
+**Background jobs:** [yes/no, details]
+**Auth:** [provider]
+**Integrations:** [list or none]
+**Notes:** [anything else]
+```
+
+Ask: **"Does this look right? Any corrections before I start building?"**
+
+This is the ONLY point where you pause for user confirmation. After they confirm, go fully autonomous.
+
+---
+
+## Phase 2: Design Architecture
+
+Based on the confirmed requirements, design the architecture. Do NOT write a plan document — think through it and write it as a brief message to the user (so they can see your thinking), then start building.
+
+Cover:
+1. **Database schema** — which tables, columns, relationships
+2. **API routes** — which tRPC routers and procedures
+3. **Pages** — which routes/pages in the app
+4. **Background jobs** — which Inngest events and functions (if any)
+5. **LLM integration** — which service to use, how to wire it (if any)
+
+### Decision: Langfuse
+
+Read [agent-skills/langfuse.md](langfuse.md) to understand Langfuse. **Use Langfuse if the app calls LLMs.** Skip it otherwise. The template already has the integration wired — you just need to ensure env vars are set.
+
+### Decision: Inngest
+
+Read [agent-skills/inngest.md](inngest.md) to understand Inngest. **Use Inngest if the app has background jobs, scheduled tasks, or multi-step agent pipelines.** The template has the scaffold — you add events and functions.
+
+### Decision: Database
+
+Read [agent-skills/database.md](database.md) for the Drizzle patterns. You will almost always need new tables.
+
+---
+
+## Phase 3: Implement
+
+Build the app in logical chunks. For each chunk: implement, then verify it compiles and runs. Fix issues before moving on.
+
+### Implementation Order
+
+Follow this order — each layer builds on the previous:
+
+1. **Database schema** — Define tables, export from schema index, generate migration, apply it
+2. **Services** — Business logic services (follow the existing singleton + `AsyncLocalStorage` pattern)
+3. **tRPC routers** — API endpoints, compose in the root appRouter
+4. **Inngest functions** — Events and function collections (if needed)
+5. **Pages and components** — React pages and UI components
+6. **Polish** — Error states, loading states, edge cases
+
+### After Each Chunk
+
+Run:
+
+```bash
+pnpm build
+```
+
+If it fails, fix the errors before moving to the next chunk. Do not accumulate broken code.
+
+### Implementation Rules
+
+- **Use `@percepta/design` components.** Do not write custom UI for things that exist in the design system (Button, Dialog, Table, Card, Input, etc.). Read `node_modules/@percepta/design/dist/src/index.d.ts` to see what's available.
+- **Use `AsyncContent` for loading states.** Every data-fetching UI should use `AsyncContent` from `@percepta/components`.
+- **Use `getEnvConfig()` for env vars.** Never use `process.env` directly.
+- **Use `getLogger()` for logging.** Never use `console.log`. Use safe/unsafe field separation.
+- **Follow the singleton pattern** for new services. Follow the existing `DatabaseService` singleton pattern in the codebase.
+- **Use `protectedProcedure`** for authenticated tRPC routes.
+
+---
+
+## Phase 4: Local Verification
+
+Once all chunks are implemented, verify the app runs end-to-end locally.
+
+### Step 1: Start dependencies
+
+```bash
+pnpm docker:up
+pnpm db:setup-and-migrate
+```
+
+### Step 2: Start the dev server
+
+```bash
+pnpm dev
+```
+
+### Step 3: Verify the app works
+
+Open the app in a browser and walk through the core workflows from the requirements. Check:
+- Pages load without errors
+- Data can be created, read, updated, deleted
+- Auth works (if configured)
+- Background jobs trigger and complete (if applicable)
+- No console errors in the browser
+
+### Step 4: Build check
+
+```bash
+pnpm build
+pnpm lint
+```
+
+Both must pass clean.
+
+**Do not report the app as complete until it builds, lints, and the core workflows work in the browser.**
+
+---
+
+## Phase 5: Create GitHub Repository
+
+After the app is verified locally, create the GitHub repo:
+
+```bash
+# Initialize git if not already done
+git init
+git add -A
+git commit -m "Initial implementation of <app-name>"
+
+# Create the repo under percepta-ai org
+gh repo create percepta-ai/<app-name> --private --source=. --push
+```
+
+If `gh` is not authenticated, tell the user to run `gh auth login` and then continue.
+
+---
+
+## Phase 6: Deploy to Ryvn (When Requested)
+
+Only do this when the user explicitly asks to deploy.
+
+Follow the step-by-step guide in [agent-skills/deploy.md](deploy.md). It contains the service definition, installation YAML, environment variables, and secrets needed for percepta-test.
+
+For Ryvn CLI operations (checking status, logs, troubleshooting), use the `/use-ryvn` skill.
+
+Report the deployment URL to the user when done.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Stopping after design to ask permission | After requirements are confirmed, build autonomously. |
+| Not running `pnpm build` between chunks | Build after every chunk. Fix errors immediately. |
+| Writing custom UI instead of using `@percepta/design` | Check the design system first. |
+| Using `console.log` | Use `getLogger()` with safe/unsafe fields. |
+| Using `process.env` | Use `getEnvConfig()`. |
+| Forgetting to export new schema from the schema index | Every new table must be exported from the index. |
+| Forgetting to register Inngest functions in the serve endpoint | Function collections must be added to the serve endpoint. |
+| Forgetting to add new router to the root appRouter | Every new tRPC router must be composed in the root. |
+| Not verifying the app in the browser | Build + lint passing is necessary but not sufficient. Test the UI. |
+| Creating the GitHub repo before the app works locally | Verify locally first, then create the repo. |
+| Deploying without the user asking | Only deploy when explicitly requested. |

package/templates/webapp/agent-skills/ryvn.md

@@ -0,0 +1,25 @@
+# Ryvn — Deployment Platform
+
+Ryvn is the deployment platform used by Percepta to manage cloud infrastructure. It provisions environments, deploys services, and handles CI/CD — abstracting away Kubernetes, Terraform, and cloud provider details.
+
+## Percepta Environments
+
+| Environment | Purpose | Domain pattern |
+|-------------|---------|---------------|
+| `percepta-test` | Internal dev/test | `<app>.percepta-test.aitco.dev` |
+
+New apps are deployed to **percepta-test**. This environment has a shared PostgreSQL instance, Inngest server, Langfuse, and OTEL collector.
+
+## Deploying This App
+
+For the full step-by-step deployment guide to percepta-test, see [deploy.md](deploy.md).
+
+## Ryvn CLI
+
+For all Ryvn CLI operations (checking status, viewing logs, troubleshooting, managing installations), use the **`/use-ryvn`** skill. It has comprehensive CLI reference docs and handles authentication, deployment, configuration, and operations.
+
+```bash
+# Quick status check
+ryvn get installation __APP_NAME__ -e percepta-test
+ryvn logs __APP_NAME__ -e percepta-test
+```

package/templates/webapp/deploy/README.md

@@ -0,0 +1,39 @@
+# Deploy
+
+This directory holds infrastructure-as-code for deploying __APP_TITLE__ to Percepta environments.
+
+```
+deploy/
+└── ryvn/
+    ├── __APP_NAME__.service.yaml                                           # Ryvn Service definition
+    └── environments/
+        └── percepta-test/
+            └── installations/
+                └── __APP_NAME__.env.percepta-test.serviceinstallation.yaml # percepta-test installation
+```
+
+These files are pre-filled with all values needed to deploy to `https://__APP_NAME__.percepta-test.aitco.dev`. The only manual steps are: open a PR in `Percepta-Core/infra` to copy them in, and set three secrets in the Ryvn UI.
+
+## Deploying
+
+Tell Claude "deploy this app to percepta-test" — it'll follow [`agent-skills/deploy.md`](../agent-skills/deploy.md), which walks through copying these files into the infra repo, opening the PR, and the manual Ryvn UI step.
+
+## What's in these files
+
+**`__APP_NAME__.service.yaml`** — tells Ryvn how to build the Docker image. Points at `Percepta-Core/__APP_NAME__` (change the repo if you've named the GitHub repo differently). The `NPM_TOKEN` build arg is a read-only npm token shared across all Percepta apps for installing `@percepta/*` packages — it's not a secret.
+
+**`__APP_NAME__.env.percepta-test.serviceinstallation.yaml`** — configures the deployment on `percepta-test`. Three categories of values are baked in:
+
+1. **Per-app values** that vary by app name (URLs, k8s service names) — substituted at create-time.
+2. **Shared platform values** (Inngest, Langfuse, OTel endpoints) — copied as literals from the `tc-emo` reference installation. These are stable across percepta-test apps.
+3. **Secrets** (`BETTER_AUTH_SECRET`, `ENCRYPTION_SECRET_KEY`, `LANGFUSE_SECRET_KEY`) — declared in the YAML, value entered once in the Ryvn UI.
+
+## Repo layout note
+
+These files assume this repo is a **monorepo** with the app at `packages/__APP_NAME__/` (the layout produced by `@percepta/create`). The `service.yaml` sets `context: packages/__APP_NAME__` accordingly. If you've flattened this into a single-package repo, change `context:` and `dockerfile:` to `.` and `Dockerfile`.
+
+The release workflow lives at `.github/workflows/__APP_NAME__-ryvn-release.yaml` (at the repo root, where GitHub Actions picks it up). It's path-filtered to `packages/__APP_NAME__/`, so changes to other packages won't trigger this app's deploy. Multiple webapps in the same monorepo each get their own `<name>-ryvn-release.yaml` and don't collide.
+
+## Adding more environments
+
+Copy `environments/percepta-test/installations/__APP_NAME__.env.percepta-test.serviceinstallation.yaml` to a new `environments/<env>/installations/__APP_NAME__.env.<env>.serviceinstallation.yaml` and change the `environment:`, host, and any environment-specific values.

package/templates/webapp/deploy/ryvn/__APP_NAME__.service.yaml

@@ -0,0 +1,11 @@
+kind: Service
+metadata:
+  name: __APP_NAME__
+spec:
+  type: server
+  repo: Percepta-Core/__APP_NAME__
+  build:
+    args:
+      NPM_TOKEN: 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
+    context: packages/__APP_NAME__
+    dockerfile: packages/__APP_NAME__/Dockerfile