@percepta/create 3.1.0 → 3.1.3

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,41 +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 `pnpm deploy:percepta-test -- --yes` helper opens the required `Percepta-Core/infra` PR.
+These files deploy to `https://__APP_NAME__.percepta-test.aitco.dev`.
+
+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.
+
+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.
 
 ## 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.
+Tell Claude "deploy this app to percepta-test" or run:
+
+```bash
+pnpm deploy:percepta-test -- --yes
+```
+
+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.
 
 ## 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 release workflow passes `NPM_TOKEN` as a build arg from GitHub org secrets.
+**`__APP_NAME__.service.yaml`** — Ryvn server service for the web app. It points at `Percepta-Core/__REPO_NAME__` and builds from `packages/__APP_NAME__/`.
+
+**`__APP_NAME__-terraform.service.yaml`** — Ryvn Terraform service that owns the per-app Postgres schema in the shared `demos` database.
+
+**`__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.
+
+**`__APP_NAME__-terraform.env.percepta-test.serviceinstallation.yaml`** — schema installation for `percepta-test`.
+
+**`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.
+
+## Platform Wiring
 
-**`__APP_NAME__.env.percepta-test.serviceinstallation.yaml`** — configures the deployment on `percepta-test`. Three categories of values are baked in:
+`pnpm deploy:percepta-test` checks these existing `percepta-test` installations before it mutates GitHub or Ryvn app resources:
 
-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.
+- `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.
 
-`BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` are declared as Ryvn-managed secrets. Set their values in Ryvn after the infra PR merges; the scaffold does not commit deployment secret values to git.
+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__

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

@@ -10,8 +10,23 @@ spec:
     service:
       port: 3000
 
+    startupEnabled: true
+    startupProbe:
+      httpGet:
+        path: /api/healthz
+        port: 3000
+      failureThreshold: 30
+      periodSeconds: 10
     livenessEnabled: true
+    livenessProbe:
+      httpGet:
+        path: /api/healthz
+        port: 3000
     readinessEnabled: true
+    readinessProbe:
+      httpGet:
+        path: /api/readyz
+        port: 3000
 
     resources:
       requests:
@@ -39,8 +54,9 @@ spec:
 
     env:
       # Database — shared `demos` DB on the percepta-internal Postgres instance.
-      # Tables live under a per-app schema created by the infra PR. DATABASE_SCHEMA
-      # pins the connection search_path so Drizzle migrations + queries land there.
+      # Tables live under a per-app schema created by the __APP_NAME__-terraform
+      # Ryvn service. DATABASE_SCHEMA pins the connection search_path so Drizzle
+      # migrations + queries land there.
       - name: DATABASE_HOST
         valueFrom:
           secretKeyRef:
@@ -78,13 +94,11 @@ spec:
       value: https://__APP_NAME__.percepta-test.aitco.dev
     - key: BETTER_AUTH_URL
       value: https://__APP_NAME__.percepta-test.aitco.dev
-    # Set these in Ryvn after the infra PR merges.
-    - key: BETTER_AUTH_SECRET
-      isSecret: true
-    - key: ENCRYPTION_SECRET_KEY
-      isSecret: true
+    # deploy:percepta-test patches BETTER_AUTH_SECRET and ENCRYPTION_SECRET_KEY
+    # from deploy/ryvn/percepta-test.secrets.env after the installation exists.
+    # Secret values are intentionally not declared in GitOps IaC.
 
-    # Inngest (shared percepta-test instance)
+    # Inngest (shared percepta-test platform service)
     - key: INNGEST_BASE_URL
       value: http://inngest.percepta-test.svc.cluster.local:8288
     - key: INNGEST_EVENT_KEY
@@ -96,10 +110,45 @@ spec:
     - key: INNGEST_SERVE_HOST
       value: http://__APP_NAME__-web-server.percepta-test.svc.cluster.local:3000/api/inngest
 
-    # OpenTelemetry
-    - key: OTEL_METRICS_EXPORTER_OTLP_ENDPOINT
+    # Observability (shared percepta-test OTEL collector + LGTM stack)
+    # Application logs are emitted to stdout and collected by the shared OTEL
+    # collector. Traces and metrics are exported over OTLP HTTP.
+    - key: OTEL_SERVICE_NAME
+      value: __APP_NAME__
+    - key: OTEL_RESOURCE_ATTRIBUTES
+      value: service.namespace=__REPO_NAME__,deployment.environment=percepta-test
+    - key: OTEL_TRACES_EXPORTER
+      value: otlp
+    - key: OTEL_METRICS_EXPORTER
+      value: otlp
+    - key: OTEL_LOGS_EXPORTER
+      value: none
+    - key: OTEL_EXPORTER_OTLP_PROTOCOL
+      value: http/protobuf
+    - key: OTEL_EXPORTER_OTLP_ENDPOINT
+      value: http://otel-collector-opentelemetry-collector.percepta-test.svc.cluster.local:4318
+    - key: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+      value: http://otel-collector-opentelemetry-collector.percepta-test.svc.cluster.local:4318/v1/traces
+    - key: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
       value: http://otel-collector-opentelemetry-collector.percepta-test.svc.cluster.local:4318/v1/metrics
-    - key: OTEL_EXPORT_INTERVAL_MS
+    - key: OTEL_METRIC_EXPORT_INTERVAL
       value: "60000"
+    - key: NEXT_PUBLIC_FARO_APP_NAME
+      value: __APP_NAME__
+    - key: NEXT_PUBLIC_FARO_APP_VERSION
+      value: "0.1.0"
+    - key: NEXT_PUBLIC_FARO_APP_ENVIRONMENT
+      value: percepta-test
     - key: LOG_LEVEL
       value: debug
+
+    # Langfuse (shared percepta-test platform service). Project keys come from
+    # the demos-commons Ryvn variable group below.
+    - key: LANGFUSE_BASE_URL
+      value: https://langfuse.percepta-test.aitco.dev
+
+    # LLM provider (shared demo Anthropic key comes from demos-commons).
+    - key: LLM_PROVIDER
+      value: anthropic
+  variableGroups:
+    - name: demos-commons

package/templates/webapp/env.example.template

@@ -19,9 +19,9 @@ BETTER_AUTH_URL=http://localhost:3000
 ENCRYPTION_SECRET_KEY=generate-with-node-e-console-log-require-crypto-randomBytes-16-toString-hex
 
 # Inngest (Background Jobs)
-# INNGEST_BASE_URL=
+INNGEST_BASE_URL=http://localhost:8288
 # INNGEST_SIGNING_KEY=
-# INNGEST_EVENT_KEY=
+INNGEST_EVENT_KEY=local
 
 # Grafana Faro (client-side observability)
 # Leave NEXT_PUBLIC_FARO_COLLECTOR_URL empty to disable in local development.
@@ -36,6 +36,24 @@ NEXT_PUBLIC_FARO_APP_ENVIRONMENT=development
 # LANGFUSE_PUBLIC_KEY=
 # LANGFUSE_SECRET_KEY=
 
+# LLM providers
+# Deployed percepta-test apps inherit ANTHROPIC_API_KEY from the demos-commons
+# Ryvn variable group. For local LLM testing, set ANTHROPIC_API_KEY once in your
+# shell profile or ~/.config/percepta/create.env.
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# LLM_PROVIDER=anthropic
+# LLM_MODEL=claude-sonnet-4-5-20250929
+
+# OpenTelemetry (server-side traces and metrics)
+# OTEL_SERVICE_NAME=__APP_NAME__
+# OTEL_TRACES_EXPORTER=otlp
+# OTEL_METRICS_EXPORTER=otlp
+# OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+# OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics
+
 # AWS (uses default credential chain in development)
 # AWS_REGION=us-east-1
 # AWS_ACCESS_KEY_ID=

package/templates/webapp/eslint.config.mjs

@@ -11,6 +11,7 @@ export default [
   {
     ignores: [
       "pnpm-lock.yaml",
+      "package.json",
       ".next/**",
       "next-env.d.ts",
       "public/**",
@@ -56,4 +57,10 @@ export default [
       "n/no-process-env": "off",
     },
   },
+  {
+    files: ["scripts/with-local-env.ts"],
+    rules: {
+      "n/no-process-env": "off",
+    },
+  },
 ];

package/templates/webapp/gitignore.template

@@ -33,6 +33,7 @@ yarn-error.log*
 # env files (can opt-in for committing if needed)
 .env*
 !.env.example
+deploy/ryvn/*.secrets.env
 
 # vercel
 .vercel

package/templates/webapp/next.config.ts

@@ -1,8 +1,17 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { NextConfig } from "next";
 
+const appDir = path.dirname(fileURLToPath(import.meta.url));
+const monorepoRoot = path.resolve(appDir, "../..");
+
 const nextConfig: NextConfig = {
   // Enable standalone output for Docker:
   output: "standalone",
+  outputFileTracingRoot: monorepoRoot,
+  turbopack: {
+    root: monorepoRoot,
+  },
 };
 
 export default nextConfig;

package/templates/webapp/package.json.template

@@ -6,13 +6,14 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "dev": "next dev --turbopack",
+    "dev": "tsx ./scripts/with-local-env.ts next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "eslint .",
     "setup": "pnpm docker:up && pnpm db:setup-and-migrate && pnpm db:seed",
     "docker:up": "docker compose up -d",
     "docker:down": "docker compose down",
+    "inngest:dev": "pnpm dlx inngest-cli@latest dev -u http://localhost:3000/api/inngest",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "tsx ./scripts/migrate.ts",
     "db:setup": "tsx ./scripts/setup-database.ts",
@@ -21,11 +22,13 @@
     "db:studio": "drizzle-kit studio",
     "db:create-user": "tsx ./scripts/create-user.ts",
     "db:seed": "tsx ./scripts/seed.ts",
-    "deploy:percepta-test": "tsx ./scripts/open-ryvn-deploy-pr.ts",
+    "deploy:percepta-test": "tsx ./scripts/deploy-percepta-test.ts",
+    "deploy:percepta-test:pr": "tsx ./scripts/open-ryvn-deploy-pr.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^2.0.23",
     "@ai-sdk/openai": "^2.0.23",
     "@aws-sdk/client-s3": "^3.888.0",
     "@aws-sdk/client-secrets-manager": "^3.914.0",
@@ -47,6 +50,7 @@
     "@next/env": "^15.3.5",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.62.1",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.203.0",
     "@opentelemetry/sdk-node": "^0.203.0",
     "@percepta/design": "0.3.2",
     "@percepta/logger": "0.0.6",