Agent guide

This is the canonical onboarding for AI coding agents. Root AGENTS.md is generated (scripts/update-agents.mjs) and must stay a short checklist — put durable instructions here.

Catalog: docs/README.md · Repo map: map.md

Shared CDN (test)

Test hashed assets use the shared HyperActivity/portfolio CDN (shared-cdn-test). See infra.md and shared-cdn-handoff.md (archived brief).

Before you edit

1. Read map.md for directory ownership.
2. Use Nx for build/test/lint (npx nx … or npm exec nx …). See root package.json / nx.json.
3. Prefer @tgmc/utilities (Node/Nitro/Lambda) vs @tgmc/utilities/browser (DOM/storage) vs @tgmc/utilities/universal (SSR-safe shared). Never import /browser from server or Lambda. Details: packages/utilities.md.
4. Line endings are LF only. On Windows: git config core.autocrlf false.
5. Git hooks: Prettier + Nx-scoped ESLint on commit; npm test on push — dev/git-hooks.md. Skip locally with HUSKY=0.
6. Public chrome IA (primary nav + Work sub-nav + restyle surfaces): portfolio-august-launch.md and web/README.md.

Environment matrix (SYS_ENV)

Env	Runtime	Data	Commands
local	Nitro node-server	SQLite data/local.sqlite	npm run db:migrate:local, npm run dev / docker:local
development	Docker web+api+Postgres	PostgreSQL	npm run docker:build:dev, npm run docker:dev
test	SAM aws_lambda	DynamoDB	npm run sam:build, sam:deploy:test; CD on main
production	SAM aws_lambda	DynamoDB	Release published or cd-aws-prod.yml (confirm=deploy)

Full topology: cicd.md. Env vars: web/setup/environment.md.

Portable skills for other repos:

• Nuxt SSR CI/CD: nuxt-ssr-cicd-template (docs)
• Commit / PR / rulesets: commit-pr-rules-template (docs)

Commands agents should run

Task	Command
Dev	npm run dev
Build web	npm run build
Build libs	npm run build:libs
Test	npm test
Lint + format	npm run lint
Local migrate	npm run db:migrate:local
HTTPS (Windows)	npm run ssl:gen:windows then npm run start:ssl:4200
Docker local	npm run docker:local / docker:local:down (SQLite ./data; not with docker:dev on :4200)
Docker dev	npm run docker:dev / docker:dev:down
Lambda test stack	npm run docker:test (proxy :4300; ensureNitroOutput first)
SAM deploy	npm run sam:deploy:test / sam:deploy:prod
CDN S3 dry-run	npm run sam:sync:dryrun
GitHub Environments	PROD_REVIEWERS=user npm run gh:setup-environments
Regenerate AGENTS.md	node scripts/update-agents.mjs

E2E: npx nx run web:e2e (web at http://localhost:4200).

Conventions

• TypeScript project references live in root tsconfig.json — not one tsconfig for all packages.
• Nuxt maps @tgmc/theme to theme/core/dist. Rebuild theme after source changes (npm run postinstall or nx prepare).
• Aliases in core/web/nuxt.config.ts: #shared, #types, theme, PrimeVue shim.
• SYS_ENV selects Nitro preset (node-server vs aws_lambda), MessageStore adapter, and output dir.
• Imports stay at the top of the file (no inline imports). Switches over unions use a never default.
• After changing packages/utilities, npm run build --workspace=@tgmc/utilities (or build:libs).

Pitfalls

• Nitro rollupConfig.onwarn silences known cache-driver / circular-dep warnings — do not “fix” without reproducing.
• HTTPS=1 needs certs in core/web/bin/ssl/.
• Docker test does not emulate S3/CDN; public assets are staged at infra/sam/.aws-sam/build-src/public for CD sync.
• Prettier does not run on GitHub (GITHUB_ACTIONS=true turns prettier/prettier off). Format locally.
• Region for SAM/CD: see cicd.md / infra/sam/samconfig.toml (currently us-west-2).

After each implementation

• Document non-obvious behavior (JSDoc or a page under docs/).
• Update the catalog in docs/README.md / docs/_catalog.md if you add a doc file.
• Whenever documentation is altered: review related docs + inline comments/JSDoc for the same topic; keep catalogs and hubs in sync. Repo docs/*.md is the in-app /docs content (no copy into core/web/content/). Full checklist: contributing.md.
• Commit only files from this conversation (git add path, never git add -A unless asked).
• Leave unrelated working-tree edits untouched.

Tests that prove docs/scripts

Area	Location
MessageStore / API	core/web/server/db/*.spec.ts, server/api/messages/
SAM/CDN helpers	scripts/sam-aws-helpers.test.mjs, core/web/tests/scripts/
Run focused	cd core/web && node ./bin/run-vitest.mjs server/db server/api/messages tests/scripts (launcher uppercases the Windows drive so Vitest does not load two runtimes)