Site Operations

Site operations

The repo's README.md is the operating guide for setup, tests, indexing and releases. AGENTS.md holds the production and secrets rules. This page keeps supplementary observations from the retired Blender AI tutor plan, recorded by 2026-10-13. Treat version-dependent troubleshooting notes as observations, not guaranteed current behaviour.

Production boundaries

• Production is https://project-buddy-rust.vercel.app; the Vercel project is project-buddy. Team aliases were behind Vercel SSO.
• Production, Preview and Development share one Neon database. Agents must never connect to it or run real Claude. Tests use the separate test database and mock tutor.
• Never print a .env* file or copy secrets into docs, logs, issues or commits. Follow the repo's secrets rules.
• PRs target integration, whose pushes deploy previews. Production releases are manual. See release-workflow and integration-branch for release order, failure recovery and migration compatibility.

Token spend boundaries

The repo's other development tooling spends no tokens. The CI workflows (.github/workflows/integration.yml and release.yml) smoke-test with signed-out requests only, and no script calls a model. The web app's tests refuse to run unless TUTOR_MODEL is mock (apps/web/scripts/test-db/test-database.ts, apps/web/playwright.config.ts).

At runtime, the web app spends tokens on users' buddy chats, metered per user under claude-spend-quota. That spend isn't commit-driven, so this page doesn't cover it.

Vercel observations

• vercel link writes projectId and the owning team's orgId to the ignored .vercel/project.json. Tools use VERCEL_PROJECT_ID and VERCEL_ORG_ID.

• vercel env pull returned sensitive variables as empty strings. A pulled file alone did not establish that those variables were configured locally.

• vercel logs --follow missed lines written in after(), such as [tutor-steps]. The recorded alternative was a bounded log query:

  vercel logs --deployment DEPLOYMENT_ID --since START --until END --json

  DEPLOYMENT_ID identifies the deployment; START and END bound the query's time range. Use timestamps with an explicit time zone.

• A push to main once produced no Vercel deployment (3f6e57f), and GitHub exposed no commit status. Vercel's API was needed to associate a deployment with its commit. This predates the current manual release workflow; a push alone is not evidence of a release.

Local troubleshooting observations

• Turbopack builds failed when node_modules was a symlink. Replacing it with a real directory from npm ci resolved that case.
• Docker Desktop's credential helper could hang while pulling test-database images. A credential-free DOCKER_CONFIG was the recorded workaround.
• npm run manual:reindex peaked at about 450–510 MB and wrote about 8,974 sections. These are historical measurements, not resource limits or an expected section count. The configured manual branch is in apps/web/src/manual/manual-source.ts.

Validation

The release workflow checks signed-out requests, not real tutor behaviour. The remaining evidence gap and the maintainer-only checks are described under Production validation gap.