Operations

This section covers everything needed to build, deploy, configure, test, and troubleshoot the Foundation/Lens Forge application.

Documents

Document	Description
Deployment Guide	Build pipeline, environment management, deploy commands, and the full verification pipeline
App Configuration	Manifest structure, CaaS byte limits, package layout, hooks, MCP, and worktree conventions
Troubleshooting	Known Forge platform bugs, common failures, and their solutions
Security & Permissions	Forge sandboxing, lens-level ACL, Jira permission checks, CSP, and external fetch permissions
Testing Guide	Jest + React Testing Library setup, mock patterns, verification scripts, and manual testing

Quick Reference

Common Commands

# Run quick pre-push verification (manifest + TypeScript + frontend builds)
cd foundation && npm run verify:quick

# Run full CI-equivalent verification (adds backend + frontend Jest suites)
cd foundation && npm run verify:local

# Check manifest byte budget before adding actions
cd foundation && npm run check:manifest

# Deploy to the working development environment
cd foundation && npm run deploy:dev

# Deploy to production (requires --confirm)
cd foundation && npm run deploy:production

# Build frontend only (all three packages)
cd foundation/static/main && npm run build

# Run frontend tests
cd foundation/static/main && npm test

# Run backend tests
cd foundation && npm test

# Run schema/migration tests
cd foundation && npx jest --testPathPattern='schema|migration' --no-coverage

# Run i18n key parity test
cd foundation/static/main && npm test -- --testPathPattern=i18n-coverage

Environment Status (as of 2026-03-25)

Environment	Status	Notes
`dev-recovery`	Working	Default development environment
`development`	Corrupted	CaaS deploy fails with 500; do not use
`staging`	Corrupted	Deploy failures; do not use
`production`	Working	Live Marketplace app at humanr.atlassian.net

Key Constraints

CaaS manifest byte limit (ECO-1310): ~23,500 raw bytes / ~257KB after CaaS conversion. Currently at 35 actions, ~22,850 bytes.
Jira API rate limits: Tier 2 granted (100K-500K points/hour per tenant). Product event triggers are free.
Forge SQL: 150 DML operations/second, 1 GiB storage per installation.
Resolver timeout: 25 seconds (standard), 900 seconds (async events).
Frontend payload limit: 5 MB per response.
Never deploy from worktrees. Always merge to main first, then deploy from the main working tree.