Skip to the content.

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 Example Organization/portfolio CDN (shared-cdn-test). See infra.md and shared-cdn-handoff.md (archived brief).

GitHub.io portfolio synchronization

.github/workflows/sync-tamaramack-github-io.yml exports the tracked source commit and opens or updates automation/portfolio-sync into destination development. Only destination apps/portfolio/ is replaceable; destination apps/profile/ owns the Pages root and must never be touched, while destination workflows retain validation, promotion, and deployment ownership. The source repository uses fine-grained token secret TAMARAMACK_GITHUB_IO_SYNC_TOKEN; only TAMARAMACK_GITHUB_IO_SYNC_ENABLED=1 enables automatic source main runs, while manual dispatch remains allowed. See cicd.md for setup, rollout, and recovery.

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.
  7. Theme tokens + Sass theme-* helpers: packages/theme.md. Personalize brand roles / FOUC / backgrounds: web/features/personalization.md. App SCSS inject: web/features/app-scss.md.
  8. Contrast roles & interaction rules — text, links, focus and control borders use --theme-link-color, --theme-focus-ring-color, --theme-border-strong-color, --theme-primary-fill-color/--theme-on-primary-color, --theme-primary-ink-color / --theme-secondary-ink-color (brand-coloured text), --theme-success-ink-color/--theme-error-ink-color (brand --theme-primary-color etc. reach only 3:1 and are for fills, never color: — see rule 17 and the colour rules). One link per card, one primary action per view, confirm-in-place + Undo for destructive actions. Browse pages bind AppBrowseToolbar through useBrowseQuery(). Overview: web/features/interaction-redesign.md.
  9. Pug + <script setup>: never reference an import only from a Pug template — eslint --fix (pre-commit) deletes it. Bind it to a local const first. See solutions/build-errors/pug-template-only-imports-stripped.md.
  10. Open TODO / follow-ups live in web/features/interaction-redesign.md#todo (admin media for all types — audio, video, image, 3D / XR, documents — plus redesign follow-ups). Check it before starting related work; tick or remove items you complete, and add new follow-ups there rather than scattering TODO comments.
  11. Public GitHub links — every public link to code or docs (site content, /code, docs, package homepage) points to the configured public repository on main, never the private source repo. Build them with publicSourceUrl() / publicTreeUrl() from core/web/shared/public-repo.ts. Only operational links (Actions runs, CI badges, issues, PRs) stay on the source repo. Enforced by core/web/tests/public-repo-links.spec.ts.
  12. UI/UX: responsive, accessible, touch — always. Every UI/UX proposal, mockup and change covers all three, explicitly: responsive (phone 375 → tablet → desktop; nothing pushes the page sideways — grid tracks minmax(0, 1fr), flex children min-width: 0), accessible (WCAG 2.2 AA: real controls with names, keyboard + visible --theme-focus-ring-color, screen-reader announcements, contrast roles, 400% zoom / reflow), and touchscreen (≥44px targets, no swipe-only or hover-only affordances, native pickers where they beat custom ones). When offering options, compare them on all three. Use the theme floors — --touch-target / --type-min, the touch-target / font-size-floor mixins, .touch-target / .back-link — instead of per-page sizes (packages/theme.md); core/web/tests/ui-floors.spec.ts guards them.
  13. Archive, don’t delete, replaced styling — move it to theme/core/scss/_archive/<date>-<slug>/ (repo path mirrored, .vue → its old <style> block) with a README; never import from _archive/.
  14. Style layers and units — theme (universal) → app global → layout → page (scoped) → component (scoped); relative units (rem / em / % / dvh / container units), em breakpoints with range syntax, px only for hairlines, focus rings, shadows, blur and the max() floors. Policy: packages/theme.md § Style layers and units. Guards: scripts/scss-units-report.mjs, scripts/scss-units-report.test.mjs (strict: 0 convertible px), core/web/tests/{pages,components}-scss.spec.ts (scoping, no reach-ins, no raw width queries), core/web-e2e/src/e2e/ui-audit.cy.ts. Breakpoint pitfall: solutions/ui-bugs/breakpoint-overlap-at-768px.md.
  15. docs/solutions/ — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type). Relevant when implementing or debugging in documented areas.
  16. Never revert the owner’s changes on your own. If the user (or one of their agents) made a change or commit, do not assume it was a mistake and revert or rewrite it — ask first. When something looks wrong, or you see a better process, present the concern or recommendation to the user and let them decide. Only fix user-authored work without asking when it is a confirmed bug you were asked to fix.
  17. Colour system (spec, packages/theme.md § Colour system). Restyle from the solid colours only: main primary / secondary / accent, grounds ink / paper, flags warning / error (alert) / info / success / focus. Every other colour is a variation of them — --theme-<c>-{light,dark}{,-background}-color (active: --theme-<c>-color / -background-color), a neutral step --theme-neutral-<N>-color, an alpha --theme-<c>-a<N>-color, or a role (--theme-text-color, --theme-surface-color, --theme-border-strong-color …) — never an independent colour (guarded by theme/core/tests/rule3-guard.spec.ts; the derived roles are listed in packages/theme.md § Derived families). Names: every colour variable ends in -color — theme --theme-*-color / $theme-*, core/web globals --portfolio-*-color, core/admin globals --web-*-color. Pages and components have no colour literals (hex, rgb(), named colours, Sass $ colours) and declare no colour variables; web apps use CSS variables, never Sass colour values. Exceptions (names kept): the owner’s palettes — the ten basic --<hue>-color names and the data palettes (--navy-color, --tertiary-color, --primary-default …); third-party interfaces — Foundation’s --foundation-* and PrimeVue’s --p-* (their values read --theme-*-color). The old names (--primary-color, --text-color, --paper, --portfolio-rose …) are gone — no aliases; the maps (theme/core/src/color-rename-map.json, core/web/shared/portfolio-color-names.ts) remain for scripts/rename-color-vars.mjs (--check core theme packages must stay 0) and for the theme API, which accepts an old key on input and writes its new name. Guards: theme/core/tests/color-naming.spec.ts, core/web/tests/colors-scss.spec.ts, core/admin/tests/colors-scss.spec.ts.
  18. CONCEPTS.md — shared domain vocabulary (entities, named processes, status concepts). Relevant when orienting to the codebase or discussing domain concepts.
  19. Review / verify / test means the full user path. Open the exact URL the user uses first and read the screen; if you can’t reproduce the user’s report, stop and ask (URL, page, exact message) instead of guessing, and never call it fixed — or commit it as fixed — until it is reproduced, fixed and re-checked there; every 4xx/5xx or framework error page is a defect — never call one “expected” yourself. Report every defect as soon as you see it — do not hold findings until they “explain” the reported symptom (e.g. deployed siteUrl=localhost). Local e2e:regression is not AWS test/prod topology (execute-api + CDN + Lambda SITE_URL). Then sign in through the UI, click through every page and feature (phone + desktop, keyboard, touch), and only then check APIs and failure paths. Rule: .cursor/rules/full-review-verify-test.mdc; incident: aws-test-site-url-localhost.

Environment matrix (SYS_ENV)

Env Runtime Data Commands
local Nitro node-server SQLite data/local.sqlite (host); docker:local uses DynamoDB Local npm run db:migrate:local, npm run dev / docker:local
development Docker web+api+DynamoDB Local+MinIO DynamoDB Local (Postgres opt-in) 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:

Client adapters and mirrors:

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

Pitfalls

After each implementation

Tests that prove docs/scripts

Area Location
MessageStore / API core/web/tests/server/db/*.spec.ts, server/api/messages/
Personalization core/web/tests/personalization.spec.ts, theme/core/tests/color-facade.spec.ts, theme/core/tests/scss-color-fns.spec.ts
Module format core/web/tests/module-format.spec.ts
SAM/CDN helpers scripts/sam-aws-helpers.test.mjs, scripts/sam-template.test.js, core/web/tests/scripts/
Run focused cd core/web && node ./bin/run-vitest.mjs tests/server/db … (and cd core/admin && node ./bin/run-vitest.mjs / nx run @tgmc/admin:test) — launchers uppercase the Windows drive so Vitest does not load two runtimes (vitest#10692)
Content-driven Vitest Prefer loaders / SITE_PROFILE / theme library over copy literals — page-data-loading.md

Sanitized documentation and examples

Documentation, rules and skill mirrors use generic sensitive resource values. The owner’s name and name variants, email variants, and identifying tag or tagline may remain as attribution. This exception does not permit credentials, private resource IDs, third-party personal information or other sensitive data. Use Example Owner, Example Organization, user@example.com, https://example.com, 000000000000 for an account number, and EXAMPLE_DISTRIBUTION_ID for a distribution. These are placeholders, not deployment defaults. Resolve example repository owners, workflow names, secret names, tenant identifiers and endpoints from authorized local configuration before using commands. Keep real credentials in the approved secret store; never copy tokens, private keys, third-party personal contact details, employer information or workstation paths into documentation or agent prompts.

Prefer relative links for repository documents. Existing source filenames, package/API names and valid local-link paths remain operational references; they are not renamed by sanitization. Keep mirrored skill references consistent and edit scripts/update-agents.mjs before regenerating AGENTS.md. Historical Git revisions and binary attachments are not sanitized by a text-documentation update; review those separately before redistribution.

Exclude Git-ignored files before reading or editing. Preserve business-document filenames and titles; sanitize sensitive body content. Leave binaries unchanged and list eligible attachments for separate review.