@percepta/create 3.1.0 → 3.1.3

package/templates/webapp/.github/workflows/__APP_NAME__-terraform-ryvn-release.yaml

@@ -0,0 +1,98 @@
+name: Build & Release __APP_NAME__-terraform
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "packages/__APP_NAME__/terraform/schema/**"
+      - ".github/workflows/__APP_NAME__-terraform-ryvn-release.yaml"
+  pull_request:
+    branches:
+      - "main"
+    paths:
+      - "packages/__APP_NAME__/terraform/schema/**"
+      - ".github/workflows/__APP_NAME__-terraform-ryvn-release.yaml"
+  workflow_dispatch:
+
+env:
+  SERVICE_NAME: __APP_NAME__-terraform
+
+jobs:
+  build-and-release:
+    name: Build and Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Ryvn CLI
+        uses: ryvn-technologies/install-ryvn-cli@v1.0.0
+
+      - name: Generate Release Tag
+        id: generate-tag
+        env:
+          RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
+          RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
+        run: |
+          tag_info=$(ryvn generate-release-tag "$SERVICE_NAME" --prefix="${SERVICE_NAME}@" -o json --default-bump-minor)
+
+          version=$(echo "$tag_info" | jq -r '.version')
+          new_tag=$(echo "$tag_info" | jq -r '.tag')
+          channel=$(echo "$tag_info" | jq -r '.channel')
+          isPreview=$(echo "$tag_info" | jq -r '.isPreview')
+
+          echo "version=$version" >> $GITHUB_OUTPUT
+          echo "new_tag=$new_tag" >> $GITHUB_OUTPUT
+          echo "channel=$channel" >> $GITHUB_OUTPUT
+          echo "isPreview=$isPreview" >> $GITHUB_OUTPUT
+
+      - name: Create Ryvn Release
+        if: |
+          !contains(github.event.head_commit.message, '[skip-release]') &&
+          !contains(github.event.pull_request.title, '[skip-release]') &&
+          (steps.generate-tag.outputs.isPreview == 'true' || github.ref == format('refs/heads/{0}', github.event.repository.default_branch))
+        env:
+          RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
+          RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
+        run: |
+          version="${{ steps.generate-tag.outputs.new_tag }}"
+          version="${version#"${SERVICE_NAME}@"}"
+          version="${version#@}"
+          channel="${{ steps.generate-tag.outputs.channel }}"
+
+          if [ -n "$channel" ] && [ "$channel" != "null" ]; then
+            ryvn create release "$SERVICE_NAME" "$version" --channel "$channel"
+          else
+            ryvn create release "$SERVICE_NAME" "$version"
+          fi
+
+      - name: Create GitHub Tag
+        if: |
+          github.ref == format('refs/heads/{0}', github.event.repository.default_branch) &&
+          !contains(github.event.head_commit.message, '[skip-release]') &&
+          !contains(github.event.pull_request.title, '[skip-release]')
+        run: |
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+          git tag "${{ steps.generate-tag.outputs.new_tag }}"
+          git push origin "${{ steps.generate-tag.outputs.new_tag }}"
+
+      - name: Create GitHub Release
+        if: |
+          github.ref == format('refs/heads/{0}', github.event.repository.default_branch) &&
+          !contains(github.event.head_commit.message, '[skip-release]') &&
+          !contains(github.event.pull_request.title, '[skip-release]')
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ steps.generate-tag.outputs.new_tag }}
+          name: ${{ steps.generate-tag.outputs.new_tag }}
+          generate_release_notes: true
+          draft: false
+          prerelease: false

package/templates/webapp/AGENTS.md

@@ -9,6 +9,7 @@ Next.js 15 full-stack application scaffolded from the Mosaic webapp template via
 - `pnpm lint` — run ESLint
 - `pnpm test` — run Vitest tests
 - `pnpm docker:up` / `pnpm docker:down` — start/stop PostgreSQL
+- `pnpm inngest:dev` — start local Inngest dev server when working on background jobs
 - `pnpm db:generate` — generate Drizzle migrations
 - `pnpm db:migrate` — apply migrations
 - `pnpm db:setup-and-migrate` — create DB + migrate
@@ -17,6 +18,8 @@ Next.js 15 full-stack application scaffolded from the Mosaic webapp template via
 
 **Package manager**: Always use `pnpm`, never `npm` or `yarn`.
 
+Local development only requires Postgres by default. Run Inngest locally when a workflow needs it. Do not run a local LGTM/Langfuse stack unless you are specifically debugging telemetry; those are wired by the Ryvn environment for deploys. If local LLM calls are needed, `pnpm dev` loads shared provider keys from `~/.config/percepta/create.env` when it exists.
+
 ## Code Style
 
 - Double quotes for strings
@@ -44,14 +47,18 @@ src/                        # Application source
 ├── services/
 │   ├── inngest/            # Background job definitions
 │   ├── langfuse/           # LLM observability
+│   ├── llm/                # LLM provider selection and call helpers
 │   ├── logger/             # App logger setup (wraps @percepta/logger)
 │   └── observability/      # OpenTelemetry setup
 └── utils/                  # Helpers (cn, pathEncryption, etc.)
 
 deploy/                     # Infrastructure-as-code for Ryvn deployments
 └── ryvn/
-    ├── __APP_NAME__.service.yaml                                       # Ryvn Service definition
-    └── environments/<env>/installations/__APP_NAME__.env.<env>.serviceinstallation.yaml
+    ├── __APP_NAME__.service.yaml                                       # Ryvn web service
+    ├── __APP_NAME__-terraform.service.yaml                             # Ryvn schema service
+    └── environments/<env>/installations/
+        ├── __APP_NAME__.env.<env>.serviceinstallation.yaml
+        └── __APP_NAME__-terraform.env.<env>.serviceinstallation.yaml
 ```
 
 ## @percepta Packages
@@ -184,6 +191,7 @@ Detailed how-to guides for each major stack component. Read the relevant guide w
 | Guide | File | When to read |
 |-------|------|-------------|
 | Background Jobs (Inngest) | [agent-skills/inngest.md](agent-skills/inngest.md) | Adding async tasks, scheduled jobs, or agent workflows |
+| LLM Calls | [agent-skills/llm.md](agent-skills/llm.md) | Adding backend model calls, streaming, or structured generation |
 | LLM Observability (Langfuse) | [agent-skills/langfuse.md](agent-skills/langfuse.md) | App uses LLMs and needs trace/eval monitoring |
 | Database (Drizzle) | [agent-skills/database.md](agent-skills/database.md) | Adding tables, writing migrations, querying data |
 | Deployment (Ryvn) | [agent-skills/ryvn.md](agent-skills/ryvn.md) | Ryvn overview and Percepta environment context |
@@ -220,19 +228,23 @@ Better Auth configured in `src/lib/auth/`. Email/password credentials enabled by
 
 Inngest for async task processing. Define functions in `src/services/inngest/`. Configure via `INNGEST_*` env vars.
 
+### LLM Calls
+
+Use `LLMService` from `src/services/llm/LLMService.ts` for backend model calls. It chooses the configured provider, enables AI SDK telemetry, and attaches provider/model metadata for Langfuse.
+
 ### Database
 
 PostgreSQL with Drizzle ORM. Schema in `src/drizzle/schema/`, migrations in `src/drizzle/migrations/`. Connection managed by `src/services/DatabaseService.ts`.
 
 ### Observability
 
-OpenTelemetry initialized in `src/instrumentation.ts`. Langfuse for LLM tracking in `src/services/langfuse/`. Faro for frontend monitoring via `@percepta/next-utils/faro`.
+OpenTelemetry initialized in `src/instrumentation.ts`. Server traces and metrics export to the configured OTEL collector; platform logs are collected from stdout. Langfuse for LLM tracking in `src/services/langfuse/` activates when `LANGFUSE_*` env vars are configured, but only AI SDK spans are forwarded to Langfuse by default. Faro for frontend monitoring via `@percepta/next-utils/faro`.
 
 ## Deployment
 
-To deploy this app to percepta-test, follow [agent-skills/deploy.md](agent-skills/deploy.md). The Ryvn service definition and percepta-test installation YAML are already scaffolded at `deploy/ryvn/` with all values filled in — deploy is mostly "copy these two files into the infra repo, open a PR, set three secrets in the Ryvn UI."
+To deploy this app to percepta-test, follow [agent-skills/deploy.md](agent-skills/deploy.md). The direct deploy helper treats percepta-test as an existing platform environment: it preflights the shared Postgres, Inngest, OTEL collector, and LGTM installations, then creates/updates this app's Ryvn services and installations.
 
-The release CI/CD workflow is already included at `.github/workflows/ryvn-release.yaml`.
+The release CI/CD workflows are already included under `.github/workflows/`.
 
 For Ryvn CLI operations, use the `/use-ryvn` skill.
 

package/templates/webapp/Dockerfile

@@ -6,6 +6,8 @@ RUN npm install -g pnpm
 
 # Build stage:
 FROM base AS builder
+WORKDIR /repo
+ENV CI=true
 
 COPY . .
 
@@ -20,7 +22,7 @@ ENV BASE_PATH=${BASE_PATH}
 
 RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
 
-RUN NODE_ENV=production NODE_OPTIONS="--max-old-space-size=4096" pnpm build
+RUN NODE_ENV=production NODE_OPTIONS="--max-old-space-size=4096" pnpm --filter ./packages/__APP_NAME__ build
 
 # Remove .npmrc for security (contains auth token):
 RUN rm -f .npmrc
@@ -43,21 +45,28 @@ ENV NEXT_TELEMETRY_DISABLED=1
 ENV BASE_PATH=${BASE_PATH}
 
 # Copy built app from builder stage
-COPY --from=builder /app/.next/standalone ./
-COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /repo/packages/__APP_NAME__/.next/standalone ./
+COPY --from=builder /repo/packages/__APP_NAME__/.next/static ./packages/__APP_NAME__/.next/static
 
 # Copy scripts and source files needed for start.sh and runtime
-COPY --from=builder /app/scripts ./scripts
-COPY --from=builder /app/src ./src
-COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /repo/package.json ./package.json
+COPY --from=builder /repo/pnpm-lock.yaml ./pnpm-lock.yaml
+COPY --from=builder /repo/pnpm-workspace.yaml ./pnpm-workspace.yaml
+COPY --from=builder /repo/node_modules ./node_modules
+COPY --from=builder /repo/packages/__APP_NAME__/package.json ./packages/__APP_NAME__/package.json
+COPY --from=builder /repo/packages/__APP_NAME__/tsconfig.json ./packages/__APP_NAME__/tsconfig.json
+COPY --from=builder /repo/packages/__APP_NAME__/node_modules ./packages/__APP_NAME__/node_modules
+COPY --from=builder /repo/packages/__APP_NAME__/scripts ./packages/__APP_NAME__/scripts
+COPY --from=builder /repo/packages/__APP_NAME__/src ./packages/__APP_NAME__/src
 
 
 # Expose the port:
 EXPOSE 3000
 
 # Set correct permissions and user:
-RUN chown -R 1000:1000 /app && chmod +x /app/scripts/start.sh
+RUN chown -R 1000:1000 /app && chmod +x /app/packages/__APP_NAME__/scripts/start.sh
 USER 1000
+WORKDIR /app/packages/__APP_NAME__
 
 # Start the application:
 CMD ["./scripts/start.sh"]

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,91 +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 declared as Ryvn-managed secrets so their values are set after the infra PR merges, not committed to git. 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 infra PR
-
-Run the generated deploy helper from this package directory:
+From this package directory:
 
 ```bash
 pnpm deploy:percepta-test -- --yes
 ```
 
-This script:
+The helper:
 
-- 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 and installation YAML into infra
-- appends a `postgresql_schema "__APP_NAME_SNAKE__"` resource to `terraform/percepta-internal/databases.tf`
-- opens one PR against `Percepta-Core/infra`
+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.
 
-Get the PR reviewed and merged.
-
-### Step 2: Set Ryvn secrets
+The app will be available at **https://__APP_NAME__.percepta-test.aitco.dev**.
 
-After the infra PR merges, set the base Ryvn secrets for this installation:
+## Useful Variants
 
 ```bash
-BETTER_AUTH_SECRET=$(openssl rand -base64 32)
-ENCRYPTION_SECRET_KEY=$(openssl rand -hex 16)
+pnpm deploy:percepta-test -- --skip-workflows --yes
+pnpm deploy:percepta-test -- --skip-push --yes
+pnpm deploy:percepta-test -- --timeout-minutes 30 --yes
 ```
 
-Also set any app-specific secrets the implementation added, such as `OPENAI_API_KEY`.
+Use `--skip-workflows` when the required Ryvn releases already exist. Use `--skip-push` only when the target ref is already pushed.
 
-### Step 3: Trigger the first deploy
+The legacy infra-PR path is still available:
 
-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.
+```bash
+pnpm deploy:percepta-test:pr -- --phase service --yes
+pnpm deploy:percepta-test:pr -- --phase installation --yes
+```
 
-### Step 4: 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
 
-- **Pod crash-looping** → check `ryvn logs`; missing Ryvn secrets from Step 2 are the most common cause after a fresh deploy.
-- **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.
+- **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 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