@percepta/create 3.1.2 → 3.1.3

package/templates/webapp/README.md

@@ -9,7 +9,8 @@ A production-ready Next.js application with authentication, database, logging, b
 - **Database** with PostgreSQL, Drizzle ORM, and migrations
 - **Logging** with Pino and structured safe/unsafe data separation
 - **Background Jobs** with Inngest
-- **Observability** with OpenTelemetry and Langfuse integration
+- **LLM Calls** with a provider-backed `LLMService`
+- **Observability** with OpenTelemetry, LGTM-compatible traces/metrics/logs, and Langfuse integration
 - **Infrastructure** with Terraform modules for AWS (RDS, S3, IAM)
 - **Type Safety** with TypeScript and Zod schemas
 
@@ -31,7 +32,15 @@ pnpm db:setup-and-migrate
 
 Copy `.env.example` to `.env.local` and configure your environment variables.
 
-### 4. Start Development Server
+### 4. Start Inngest When Using Background Jobs
+
+```bash
+pnpm inngest:dev
+```
+
+Run this in a separate terminal when the app has Inngest functions or you want the local Inngest dashboard.
+
+### 5. Start Development Server
 
 ```bash
 pnpm dev
@@ -39,6 +48,16 @@ pnpm dev
 
 Open [http://localhost:3000](http://localhost:3000) to see your app.
 
+OpenTelemetry, Faro, and Langfuse are optional in local development. Leave their env vars empty unless you are actively debugging telemetry; production deploys wire server traces, metrics, logs, and shared Langfuse demo credentials into the target Ryvn environment. General HTTP and database spans go to the OTEL/LGTM pipeline; Langfuse receives only AI SDK spans by default.
+
+If you need local LLM calls, set provider keys once in your shell profile or in `~/.config/percepta/create.env`:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+`pnpm dev` loads that shared file before starting Next.js, so you do not need to copy the same provider key into every generated app.
+
 ## Project Structure
 
 ```
@@ -53,6 +72,7 @@ src/
 ├── services/               # Business logic services
 │   ├── inngest/            # Background job definitions
 │   ├── langfuse/           # LLM observability
+│   ├── llm/                # LLM provider selection and call helpers
 │   └── logger/             # Structured logging
 └── utils/                  # Utility functions
 ```
@@ -67,6 +87,7 @@ src/
 | `pnpm lint` | Run ESLint |
 | `pnpm docker:up` | Start PostgreSQL container |
 | `pnpm docker:down` | Stop PostgreSQL container |
+| `pnpm inngest:dev` | Start the local Inngest dev server for this app |
 | `pnpm db:generate` | Generate Drizzle migrations |
 | `pnpm db:migrate` | Run database migrations |
 | `pnpm db:setup` | Create database and user |
@@ -164,6 +185,47 @@ node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
 | `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
 | `LANGFUSE_SECRET_KEY` | Langfuse secret key |
 
+`deploy:percepta-test` sets the shared Langfuse URL and inherits the demo project keys from the `demos-commons` Ryvn variable group.
+
+### LLM Providers
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Anthropic API key. Inherited from `demos-commons` for `percepta-test` deploys |
+| `OPENAI_API_KEY` | OpenAI API key for local or non-demo deployments |
+| `LLM_PROVIDER` | Optional provider override: `anthropic` or `openai` |
+| `LLM_MODEL` | Optional model override |
+
+Use `LLMService` for backend model calls:
+
+```typescript
+import { LLMService } from "@/services/llm/LLMService";
+
+const result = await LLMService.create().generateText({
+  telemetryFunctionId: "summarize-note",
+  system: "You summarize notes for internal users.",
+  prompt: "Summarize this note...",
+});
+```
+
+For local development, `pnpm dev` also loads `~/.config/percepta/create.env` when that file exists. Production deploys do not use that local file; they inherit provider keys from the target Ryvn environment.
+
+### OpenTelemetry / LGTM
+
+| Variable | Description |
+|----------|-------------|
+| `OTEL_SERVICE_NAME` | Service name attached to traces and metrics |
+| `OTEL_RESOURCE_ATTRIBUTES` | Extra resource labels such as deployment environment |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP protocol, usually `http/protobuf` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base OTLP HTTP collector endpoint |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Optional trace-specific OTLP endpoint |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Optional metric-specific OTLP endpoint |
+| `OTEL_TRACES_EXPORTER` | Set to `otlp` to export server traces |
+| `OTEL_METRICS_EXPORTER` | Set to `otlp` to export server metrics |
+| `OTEL_METRIC_EXPORT_INTERVAL` | Metrics export interval in milliseconds |
+
+`deploy:percepta-test` configures these for the existing percepta-test OTEL collector and LGTM stack. Application logs are written to stdout and collected by the platform collector.
+
 ## Local AWS Development
 
 This application uses the default AWS SDK credential provider chain:

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

@@ -1,107 +1,90 @@
 # 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.
+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 should run the direct deploy helper below.
 
-## What's already scaffolded
+This is the existing-environment deploy motion: `percepta-test` already owns the shared platform services, and this app is wired into them. Fresh-environment platform bootstrap is separate and should use a Ryvn blueprint or environment-specific platform rollout before app deploys run.
 
-When this app was created with `@percepta/create`, the IaC files were generated at `deploy/ryvn/` with all values pre-filled:
+## What's Already Scaffolded
 
-- `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 schema) are substituted at create-time. The Better Auth and encryption secrets are written to `deploy/ryvn/percepta-test.secrets.env`, which is ignored by git and intended for Ryvn UI import. Shared platform values (Inngest and OTel endpoints) are baked in as literals because they're stable across percepta-test apps.
+- `deploy/ryvn/__APP_NAME__.service.yaml` — Ryvn server service for the web app.
+- `deploy/ryvn/__APP_NAME__-terraform.service.yaml` — Ryvn Terraform service that creates the app's Postgres schema.
+- `deploy/ryvn/environments/percepta-test/installations/__APP_NAME__.env.percepta-test.serviceinstallation.yaml` — web installation.
+- `deploy/ryvn/environments/percepta-test/installations/__APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml` — schema installation.
+- `.github/workflows/__APP_NAME__-ryvn-release.yaml` — builds the Docker image and creates the web Ryvn release.
+- `.github/workflows/__APP_NAME__-terraform-ryvn-release.yaml` — creates the schema Terraform Ryvn release.
+- `deploy/ryvn/percepta-test.secrets.env` — generated locally and ignored by git; patched into Ryvn by the deploy helper.
 
 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.
-- `git` and `gh` are installed and authenticated.
-- The infra repo (`Percepta-Core/infra`) is checked out locally or can be cloned by the deploy script.
+- `git`, `gh`, and `ryvn` are installed and authenticated.
+- The worktree is clean and committed. The helper pushes the current branch to `main` because GitHub Actions builds from GitHub.
+- The Percepta-Core org has `RYVN_CLIENT_ID`, `RYVN_CLIENT_SECRET`, and `NPM_TOKEN` available as org-level GitHub secrets.
+- These shared platform installations are already deployed and healthy in `percepta-test`: `percepta-internal-terraform`, `inngest-test`, `otel-collector`, `lgtm-stack-helm`, and `langfuse`.
+- The `demos-commons` Ryvn variable group exists in `percepta-test` and provides `LANGFUSE_PUBLIC_KEY` plus sensitive `ANTHROPIC_API_KEY` and `LANGFUSE_SECRET_KEY` for shared demo LLM calls and Langfuse tracing.
 
 ## Deploy
 
-### Step 1: Open the service/schema infra PR
-
-Run the generated deploy helper from this package directory:
+From this package directory:
 
 ```bash
-pnpm deploy:percepta-test -- --phase service --yes
+pnpm deploy:percepta-test -- --yes
 ```
 
-This script:
-
-- uses `INFRA_REPO` or `--infra <path>` when provided
-- otherwise uses a sibling `../infra` checkout, cloning `Percepta-Core/infra` there if needed
-- copies the Ryvn service YAML into infra
-- appends a `postgresql_schema "__APP_NAME_SNAKE__"` resource to `terraform/percepta-internal/databases.tf`
-- opens the first PR against `Percepta-Core/infra`
-
-Get the PR reviewed and merged.
-
-### Step 2: Wait for service/schema import
+The helper:
 
-After the service/schema PR merges, wait for Ryvn GitOps to import the service. If Ryvn creates a `percepta-internal-terraform` task for the database schema, approve/apply it in Ryvn.
+1. Checks the existing platform installations and shared demo variable group in `percepta-test`.
+2. Creates `Percepta-Core/__REPO_NAME__` if needed.
+3. Pushes the current branch to `main`.
+4. Creates or replaces the Ryvn web and schema services.
+5. Runs the schema Terraform release workflow.
+6. Creates or replaces the schema installation and approves the Terraform plan.
+7. Runs the web release workflow.
+8. Creates or replaces the web installation.
+9. Patches `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` from `deploy/ryvn/percepta-test.secrets.env`.
+10. Waits for Ryvn health and checks `/api/healthz`, `/api/readyz`, and the protected app route.
 
-### Step 3: Create the first release
-
-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. Do this before creating the ServiceInstallation, otherwise GitOps can fail with `ReleaseNotFound`.
-
-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: Open the installation infra PR
+The app will be available at **https://__APP_NAME__.percepta-test.aitco.dev**.
 
-After the first release exists, open the installation PR:
+## Useful Variants
 
 ```bash
-pnpm deploy:percepta-test -- --phase installation --yes
+pnpm deploy:percepta-test -- --skip-workflows --yes
+pnpm deploy:percepta-test -- --skip-push --yes
+pnpm deploy:percepta-test -- --timeout-minutes 30 --yes
 ```
 
-The `--` is the pnpm argument delimiter; it passes `--phase` and `--yes` through to the deploy helper script.
-
-Get the PR reviewed and merged. Ryvn GitOps will import the ServiceInstallation and the Staging channel should deploy the latest release.
+Use `--skip-workflows` when the required Ryvn releases already exist. Use `--skip-push` only when the target ref is already pushed.
 
-### Step 5: Import Ryvn secrets
-
-After GitOps imports the installation, import this generated file in the Ryvn UI for the installation secrets:
+The legacy infra-PR path is still available:
 
 ```bash
-deploy/ryvn/percepta-test.secrets.env
+pnpm deploy:percepta-test:pr -- --phase service --yes
+pnpm deploy:percepta-test:pr -- --phase installation --yes
 ```
 
-Also set any app-specific secrets the implementation added, such as `OPENAI_API_KEY`.
-
-### Step 6: Verify
+## 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
+curl -I https://__APP_NAME__.percepta-test.aitco.dev/
 ```
 
-The app will be available at **https://__APP_NAME__.percepta-test.aitco.dev**.
-
 ## Troubleshooting
 
-- **Auth/sign-in routes fail after install** → import `deploy/ryvn/percepta-test.secrets.env` in the Ryvn UI, then let Ryvn update/restart the installation.
+- **Image build fails fetching @percepta packages** → check the Percepta-Core org-level `NPM_TOKEN` secret. Do not add a repo-level token unless the org secret is unavailable.
+- **Ryvn release already exists** → commit a new change or re-run with `--skip-workflows` if the current releases are already present.
+- **Terraform plan needs approval** → the helper approves it when run with `--yes`; without `--yes`, approve the prompt.
+- **Auth/sign-in routes fail after install** → verify the deploy helper patched `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY`.
 - **Pod crash-looping** → check `ryvn logs`; migration or database connectivity failures are the most common fresh-deploy causes.
-- **Database connection refused** → verify `DATABASE_USE_SSL=true` and that `percepta-internal-terraform` is deployed.
-- **Database schema missing** → verify the infra PR added `postgresql_schema "__APP_NAME_SNAKE__"` and Ryvn applied `percepta-internal-terraform`.
-- **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 fetching @percepta packages** → check the `NPM_TOKEN` GitHub org secret. The workflow passes it as a build arg.
+- **Database schema missing** → check `ryvn get installation __APP_NAME__-terraform -e percepta-test`.
+- **Inngest can't reach the app** → `INNGEST_APP_URL` must use the k8s service name `__APP_NAME__-web-server`.
+- **Platform preflight fails** → deploy or repair the missing shared installation first. This helper only wires apps into an existing environment.
+- **No Langfuse traces** → verify the target environment has Langfuse deployed and that the `demos-commons` variable group has `LANGFUSE_PUBLIC_KEY` and sensitive `LANGFUSE_SECRET_KEY`.
+- **LLM calls fail after deploy** → verify `demos-commons` has sensitive `ANTHROPIC_API_KEY` and the installation has `LLM_PROVIDER=anthropic`.
 
 For Ryvn CLI operations, use the `/use-ryvn` skill.
-
-## Updating shared platform values
-
-The Inngest and 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

@@ -102,13 +102,13 @@ await inngest.client.send({
 
 ## Running Inngest Locally
 
-### 1. Install the Inngest Dev Server
+### 1. Start the Inngest Dev Server
 
 ```bash
-pnpm dlx inngest-cli@latest dev
+pnpm inngest:dev
 ```
 
-This starts the Inngest Dev Server at `http://localhost:8288` with a dashboard UI.
+This starts the Inngest Dev Server for `http://localhost:3000/api/inngest` with a dashboard UI.
 
 ### 2. Set environment variables
 
@@ -126,7 +126,7 @@ INNGEST_EVENT_KEY=local           # any value works locally
 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.
+The Inngest Dev Server auto-discovers functions by calling the serve endpoint at `/api/inngest`. Open the dashboard URL printed by `pnpm inngest:dev` to see registered functions, trigger events manually, and inspect runs.
 
 ## Environment Variables
 

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

@@ -2,7 +2,7 @@
 
 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.
+**Our opinionated setup:** We integrate Langfuse via OpenTelemetry (OTEL), not the Langfuse SDK directly. OTEL auto-instruments the app (HTTP, DB, etc.), exports general traces to the environment's OTEL collector, and adds Langfuse as a span processor when `LANGFUSE_*` values are configured. This gives us unified tracing while still letting the app run when Langfuse is not available in an environment.
 
 ## When to Use Langfuse
 
@@ -18,24 +18,28 @@ Langfuse is an open-source LLM observability platform. It captures traces, spans
 
 ### OpenTelemetry + Langfuse Span Processor
 
-The template uses Next.js's instrumentation hook (called on server startup) to bootstrap OTEL with Langfuse:
+The template uses Next.js's instrumentation hook (called on server startup) to bootstrap OTEL with both the environment collector and optional Langfuse:
 
 ```typescript
 import { LangfuseSpanProcessor } from "@langfuse/otel";
-import { NodeSDK } from "@opentelemetry/sdk-node";
+import { NodeSDK, tracing } from "@opentelemetry/sdk-node";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 
 const sdk = new NodeSDK({
-  spanProcessors: [new LangfuseSpanProcessor({ baseUrl, publicKey, secretKey })],
+  spanProcessors: [
+    new tracing.BatchSpanProcessor(otlpTraceExporter),
+    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.
+- The OTLP span processor forwards general server traces to the environment collector.
+- `LangfuseSpanProcessor` forwards only AI SDK spans to Langfuse when all `LANGFUSE_*` variables are set. General HTTP, DB, and server spans stay in the OTEL/LGTM pipeline and are not sent to Langfuse by default.
 
-**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.
+**You do not need to manually instrument LLM calls.** Use `LLMService` from `src/services/llm/LLMService.ts`; it calls the Vercel AI SDK with telemetry enabled and provider/model metadata attached.
 
 ### LangfuseService (Direct API)
 
@@ -58,12 +62,9 @@ This is a singleton — `create()` returns the same instance every time. It grac
 
 ### Percepta's Internal Instance
 
-Percepta runs a shared Langfuse instance. To get keys:
+Percepta runs a shared Langfuse instance. For `percepta-test` deploys, the generated Ryvn installation uses the shared demo project by inheriting `LANGFUSE_PUBLIC_KEY` and sensitive `LANGFUSE_SECRET_KEY` from the `demos-commons` variable group.
 
-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**
+For non-demo environments, verify the target Ryvn environment has a Langfuse installation or shared Langfuse project, then store the project keys in an environment-scoped variable group or installation secrets.
 
 ### Self-Hosted / Langfuse Cloud
 
@@ -75,10 +76,10 @@ For external projects, you can:
 
 ### Option 1: Use Percepta's Langfuse (recommended)
 
-Set the keys in `.env.local` pointing to the shared instance:
+Set the keys in `.env.local` if you want local traces to go to the shared instance:
 
 ```bash
-LANGFUSE_BASE_URL=https://langfuse.internal.percepta.ai  # ask team for actual URL
+LANGFUSE_BASE_URL=https://langfuse.percepta-test.aitco.dev
 LANGFUSE_PUBLIC_KEY=pk-lf-...
 LANGFUSE_SECRET_KEY=sk-lf-...
 ```
@@ -104,7 +105,7 @@ 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.
+Simply don't set the `LANGFUSE_*` env vars. This is the default local development path unless you are specifically debugging LLM telemetry. The instrumentation gracefully skips the Langfuse span processor, and `LangfuseService.isConfigured()` returns `false`. OTEL still instruments the app for general tracing when an OTLP collector endpoint is configured.
 
 ## Environment Variables
 

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

@@ -0,0 +1,59 @@
+# LLM Calls
+
+Use this guide when the app needs backend model calls, streaming responses, or structured generation.
+
+## Default Pattern
+
+Use `LLMService` from `src/services/llm/LLMService.ts`. Do not instantiate provider clients directly in routes, tRPC routers, or Inngest functions.
+
+```typescript
+import { LLMService } from "@/services/llm/LLMService";
+
+const result = await LLMService.create().generateText({
+  telemetryFunctionId: "summarize-document",
+  system: "You summarize documents for internal operators.",
+  prompt: `Summarize this document:\n\n${documentText}`,
+});
+
+return result.text;
+```
+
+For streaming:
+
+```typescript
+const stream = LLMService.create().streamText({
+  telemetryFunctionId: "chat-response",
+  system: "You are a concise assistant.",
+  messages,
+});
+```
+
+## Providers
+
+`LlmProviderService` chooses a provider at call time:
+
+1. `LLM_PROVIDER`, when explicitly set.
+2. Anthropic when `ANTHROPIC_API_KEY` is available.
+3. OpenAI when `OPENAI_API_KEY` is available.
+
+`LLM_MODEL` can override the default model. A per-call `modelId` or `provider` passed to `LLMService` overrides env defaults.
+
+## Deployment
+
+For `percepta-test`, `deploy:percepta-test` attaches the `demos-commons` Ryvn variable group. That group provides the shared `ANTHROPIC_API_KEY` and Langfuse project keys, so generated demo apps do not need per-app LLM secrets.
+
+## Local Development
+
+Local LLM calls are optional. If needed, set a provider key once in your shell profile or `~/.config/percepta/create.env`:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+`pnpm dev` loads `~/.config/percepta/create.env` automatically. Do not put shared demo keys in committed files. Do not require local Langfuse or a local LGTM stack unless the task is specifically about telemetry.
+
+## Observability
+
+`LLMService` enables AI SDK telemetry by default and attaches provider/model metadata to each call. When `LANGFUSE_*` values are configured, the template's OpenTelemetry bootstrap sends LLM spans to Langfuse. In `percepta-test`, those values are inherited from the environment.
+
+Use a stable `telemetryFunctionId` for every meaningful LLM operation, such as `extract-invoice-fields` or `draft-member-message`.

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

@@ -78,12 +78,16 @@ Cover:
 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)
+5. **LLM integration** — use `LLMService` from `src/services/llm/LLMService.ts` when model calls are needed
 
 ### 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: LLM Calls
+
+Read [agent-skills/llm.md](llm.md) when the app calls a model. Use `LLMService` for backend model calls and set a stable `telemetryFunctionId` for each LLM operation. Do not create provider clients directly in app code.
+
 ### 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.
@@ -125,6 +129,7 @@ If it fails, fix the errors before moving to the next chunk. Do not accumulate b
 - **Use robust loading states.** `@percepta/components` is optional; add it first if you want `AsyncContent`.
 - **Use `getEnvConfig()` for env vars.** Never use `process.env` directly.
 - **Use `getLogger()` for logging.** Never use `console.log`. Use safe/unsafe field separation.
+- **Use `LLMService` for model calls.** It handles provider selection and Langfuse/OTEL telemetry metadata.
 - **Follow the singleton pattern** for new services. Follow the existing `DatabaseService` singleton pattern in the codebase.
 - **Use `protectedProcedure`** for authenticated tRPC routes.
 
@@ -141,6 +146,14 @@ pnpm docker:up
 pnpm db:setup-and-migrate
 ```
 
+If the app uses Inngest functions, start the local Inngest dev server in a separate terminal:
+
+```bash
+pnpm inngest:dev
+```
+
+Do not start local LGTM, OTEL collector, Faro, or Langfuse services unless the task is specifically about telemetry. Those integrations are optional locally and are wired by the Ryvn environment for deploys.
+
 ### Step 2: Start the dev server
 
 ```bash

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

@@ -8,7 +8,7 @@ Ryvn is the deployment platform used by Percepta to manage cloud infrastructure.
 |-------------|---------|---------------|
 | `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.
+New apps are deployed to **percepta-test** using the existing-environment deploy motion. This environment must already have shared PostgreSQL, Inngest, OTEL collector, LGTM stack, and Langfuse installations before app deploys run. The service installation points at the shared Langfuse URL and attaches the `demos-commons` variable group for shared demo Langfuse project keys.
 
 ## Deploying This App
 

package/templates/webapp/deploy/README.md

@@ -1,65 +1,66 @@
 # Deploy
 
-This directory holds infrastructure-as-code for deploying __APP_TITLE__ to Percepta environments.
+This directory holds Ryvn infrastructure-as-code for deploying __APP_TITLE__ to Percepta environments.
 
 ```
 deploy/
 └── ryvn/
-    ├── __APP_NAME__.service.yaml                                           # Ryvn Service definition
+    ├── __APP_NAME__.service.yaml
+    ├── __APP_NAME__-terraform.service.yaml
     └── environments/
         └── percepta-test/
             └── installations/
-                └── __APP_NAME__.env.percepta-test.serviceinstallation.yaml # percepta-test installation
+                ├── __APP_NAME__.env.percepta-test.serviceinstallation.yaml
+                └── __APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml
 ```
 
-These files are pre-filled with all base values needed to deploy to `https://__APP_NAME__.percepta-test.aitco.dev`. The generated deploy helper opens the required `Percepta-Core/infra` PRs in two phases.
+These files deploy to `https://__APP_NAME__.percepta-test.aitco.dev`.
 
-## Deploying
-
-Tell Claude "deploy this app to percepta-test" — it'll follow [`agent-skills/deploy.md`](../agent-skills/deploy.md), which runs the generated PR helper and then verifies Ryvn.
+The default deploy helper performs the existing-environment deploy motion: it assumes the target Ryvn environment already has the shared platform services installed, then wires this app into them. For `percepta-test`, that means shared Postgres, Inngest, the OTEL collector, the LGTM stack, and Langfuse must already exist before app deploy starts. Fresh-environment platform bootstrap is a separate motion and should be handled by a Ryvn blueprint or environment-specific platform rollout.
 
-## What's in these files
+The helper talks directly to Ryvn: it preflights the existing platform services, creates/updates the services, runs the GitHub Actions release workflows, creates the schema installation, approves the schema Terraform plan, creates the web installation, patches generated secrets, waits for health, and verifies the health and app routes.
 
-**`__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 release workflow passes `NPM_TOKEN` as a build arg from GitHub org secrets.
+## Deploying
 
-**`__APP_NAME__.env.percepta-test.serviceinstallation.yaml`** — configures the deployment on `percepta-test`. Three categories of values are baked in:
+Tell Claude "deploy this app to percepta-test" or run:
 
-1. **Per-app values** that vary by app name (URLs, k8s service names, database schema) — substituted at create-time.
-2. **Shared platform values** (Inngest and OTel endpoints) — copied as literals from existing percepta-test installations. These are stable across percepta-test apps.
-3. **Database wiring** — points at the shared `demos` database and a per-app schema created by the infra PR.
+```bash
+pnpm deploy:percepta-test -- --yes
+```
 
-**`percepta-test.secrets.env`** — generated locally and ignored by git. Import it in the Ryvn UI for `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY`; deployment secret values are intentionally not committed to GitOps IaC.
+The helper expects a clean, committed git worktree because GitHub Actions builds from the pushed repo. It can create `Percepta-Core/__REPO_NAME__` if it does not exist yet, and it pushes the current branch to `main` before triggering releases.
 
-## Deployment order
+## What's in these files
 
-Use two infra PRs. The Service must exist before the first release can be created, and the first release must exist before the ServiceInstallation can be imported.
+**`__APP_NAME__.service.yaml`** — Ryvn server service for the web app. It points at `Percepta-Core/__REPO_NAME__` and builds from `packages/__APP_NAME__/`.
 
-1. Open and merge the service/schema PR:
+**`__APP_NAME__-terraform.service.yaml`** — Ryvn Terraform service that owns the per-app Postgres schema in the shared `demos` database.
 
-   ```bash
-   pnpm deploy:percepta-test -- --phase service --yes
-   ```
+**`__APP_NAME__.env.percepta-test.serviceinstallation.yaml`** — web app installation for `percepta-test`. It wires the shared platform services, ingress, health probes, database connection, Inngest, OTEL/LGTM telemetry, the Langfuse base URL, and the shared demo variable group.
 
-2. Wait for GitOps to import the service. If the schema change creates a `percepta-internal-terraform` task in Ryvn, approve/apply it.
+**`__APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml`** — schema installation for `percepta-test`.
 
-3. Push the app to `main` or run the release workflow so Ryvn has a first release for `__APP_NAME__`.
+**`percepta-test.secrets.env`** — generated locally and ignored by git. The deploy helper patches app-specific auth/encryption secrets into the Ryvn installation; shared Langfuse and LLM demo keys are inherited from a Ryvn variable group.
 
-4. Open and merge the installation PR:
+## Platform Wiring
 
-   ```bash
-   pnpm deploy:percepta-test -- --phase installation --yes
-   ```
+`pnpm deploy:percepta-test` checks these existing `percepta-test` installations before it mutates GitHub or Ryvn app resources:
 
-5. After GitOps imports the installation, import `deploy/ryvn/percepta-test.secrets.env` into the Ryvn UI for the `__APP_NAME__` installation secrets.
+- `percepta-internal-terraform` for the shared Postgres instance.
+- `inngest-test` for background jobs and function callbacks.
+- `otel-collector` for trace, metric, and log collection.
+- `lgtm-stack-helm` for Loki, Grafana, Tempo, and Mimir.
+- `langfuse` for LLM tracing and eval observability.
+- `demos-commons` variable group for shared demo configuration, including the Anthropic API key and Langfuse demo project keys.
 
-The `--` is the pnpm argument delimiter; it passes the flags after it through to `scripts/open-ryvn-deploy-pr.ts`.
+The service installation sets `LANGFUSE_BASE_URL` to the shared `percepta-test` Langfuse URL, sets `LLM_PROVIDER=anthropic`, and attaches `demos-commons` for `ANTHROPIC_API_KEY`, `LANGFUSE_PUBLIC_KEY`, and sensitive `LANGFUSE_SECRET_KEY`. Individual demo apps do not need LLM or Langfuse keys in `percepta-test.secrets.env`.
 
-## Repo layout note
+## Notes
 
-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 workflows live at the repo root under `.github/workflows/`. The web workflow uses the org-level `NPM_TOKEN` secret for private `@percepta/*` packages; do not add a repo-level token unless the org secret is unavailable.
 
-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.
+For the old GitOps PR path, use `pnpm deploy:percepta-test:pr -- --phase service --yes` and then `pnpm deploy:percepta-test:pr -- --phase installation --yes`.
 
-## Adding more environments
+## 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.
+Copy the two `percepta-test` installation manifests to `environments/<env>/installations/`, then change the `environment:`, host, and environment-specific config.

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

@@ -0,0 +1,10 @@
+kind: Service
+metadata:
+  name: __APP_NAME__-terraform
+spec:
+  type: terraform
+  repo: Percepta-Core/__REPO_NAME__
+  autoApprove: false
+  build:
+    path: packages/__APP_NAME__/terraform/schema
+    tagPrefix: __APP_NAME__-terraform@

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

@@ -3,7 +3,7 @@ metadata:
   name: __APP_NAME__
 spec:
   type: server
-  repo: Percepta-Core/__APP_NAME__
+  repo: Percepta-Core/__REPO_NAME__
   build:
-    context: packages/__APP_NAME__
+    context: .
     dockerfile: packages/__APP_NAME__/Dockerfile

package/templates/webapp/deploy/ryvn/environments/percepta-test/installations/__APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml

@@ -0,0 +1,11 @@
+kind: ServiceInstallation
+metadata:
+  name: __APP_NAME__-terraform
+spec:
+  service: __APP_NAME__-terraform
+  environment: percepta-test
+  config: |
+    aws_region: {{ .ryvn.env.state.cluster_region }}
+    database_secret_name: {{ .ryvn.installations.percepta_internal_terraform.outputs.percepta_internal_secrets_manager_secret_name }}
+    database_name: demos
+    schema_name: __APP_NAME_SNAKE__