@percepta/create 3.1.2 → 3.1.4

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
 ```
@@ -65,8 +85,9 @@ src/
 | `pnpm build` | Build for production |
 | `pnpm start` | Start production server |
 | `pnpm lint` | Run ESLint |
-| `pnpm docker:up` | Start PostgreSQL container |
+| `pnpm docker:up` | Start PostgreSQL container and wait until it is healthy |
 | `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/database.md

@@ -38,7 +38,11 @@ export * from "./documents";
 pnpm db:generate
 ```
 
-This creates a new SQL migration file. **Review the generated SQL** — Drizzle generates it automatically but you should verify it's correct.
+This creates a new SQL migration file and normalizes generated foreign key
+references so they stay schema-relative when `DATABASE_SCHEMA` is set in
+`percepta-test`. **Review the generated SQL** — Drizzle generates it
+automatically but you should verify it's correct, especially for new foreign
+keys and destructive changes.
 
 ### 4. Apply the migration
 

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

@@ -1,107 +1,92 @@
 # 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; injected into the app installation as Ryvn secrets 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. Creates or updates app-scoped Ryvn installation secrets for `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` from `deploy/ryvn/percepta-test.secrets.env`. On first install, the helper injects them into the create manifest so the first pod starts with auth configured.
+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**.
+For apps with tRPC routes, also verify at least one endpoint that initializes Better Auth or app services. `healthz` can be green even when app-specific secrets or workflow wiring are wrong.
 
 ## 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 or tRPC routes fail after install** → verify the `__APP_NAME__` installation has `BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET_KEY` secrets from `deploy/ryvn/percepta-test.secrets.env`, then redeploy `__APP_NAME__` so the pod reloads them.
 - **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

@@ -31,13 +31,13 @@ Add the event to the central `AppEvents` registry:
 import { DocumentProcessedPayload } from "./payloads/DocumentProcessedPayload";
 
 export const AppEvents = {
-  "app/document.processed": z.object({
-    data: DocumentProcessedPayload.SCHEMA,
-  }),
+  "app/document.processed": DocumentProcessedPayload.SCHEMA,
 };
 ```
 
-Event names follow the convention `"app/<entity>.<action>"`.
+Event names follow the convention `"app/<entity>.<action>"`. `AppEvents`
+schemas validate `event.data`, so do not wrap payload schemas in another
+`{ data: ... }` object.
 
 ## Adding a New Function
 
@@ -93,22 +93,27 @@ const functionCollections: InngestFunctionCollection[] = compact([
 ## Sending Events
 
 ```typescript
-const inngest = InngestService.create();
-await inngest.client.send({
-  name: "app/document.processed",
-  data: { documentId: "abc", userId: "user-1", pageCount: 5 },
+await AppWorkflowService.create().sendDocumentProcessed({
+  documentId: "abc",
+  userId: "user-1",
+  pageCount: 5,
 });
 ```
 
+Prefer adding typed methods to `AppWorkflowService` instead of calling
+`InngestService.create().client.send(...)` directly from routers or route
+handlers. Keep a unit test that asserts the method sends the same payload shape
+that `AppEvents` validates.
+
 ## 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 +131,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
@@ -180,7 +193,7 @@ git add -A
 git commit -m "Initial implementation of <app-name>"
 
 # Create the repo under the Percepta-Core org
-gh repo create Percepta-Core/<app-name> --private --source=. --push
+gh repo create Percepta-Core/<app-name> --internal --source=. --push
 ```
 
 If `gh` is not authenticated, tell the user to run `gh auth login` and then continue.

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