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
- Read map.md for directory ownership.
- Use Nx for build/test/lint (
npx nx …ornpm exec nx …). See rootpackage.json/nx.json. - Prefer
@tgmc/utilities(Node/Nitro/Lambda) vs@tgmc/utilities/browser(DOM/storage) vs@tgmc/utilities/universal(SSR-safe shared). Never import/browserfrom server or Lambda. Details: packages/utilities.md. - Line endings are LF only. On Windows:
git config core.autocrlf false. - Git hooks: Prettier + Nx-scoped ESLint on commit;
npm teston push — dev/git-hooks.md. Skip locally withHUSKY=0. - Public chrome IA (primary nav + Work sub-nav + restyle surfaces): portfolio-august-launch.md and web/README.md.
- 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. - 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-coloretc. reach only 3:1 and are for fills, nevercolor:— 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 bindAppBrowseToolbarthroughuseBrowseQuery(). Overview: web/features/interaction-redesign.md. - Pug +
<script setup>: never reference an import only from a Pug template —eslint --fix(pre-commit) deletes it. Bind it to a localconstfirst. See solutions/build-errors/pug-template-only-imports-stripped.md. - 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.
- Public GitHub links — every public link to code or docs (site content,
/code, docs, packagehomepage) points to the configured public repository onmain, never the private source repo. Build them withpublicSourceUrl()/publicTreeUrl()fromcore/web/shared/public-repo.ts. Only operational links (Actions runs, CI badges, issues, PRs) stay on the source repo. Enforced bycore/web/tests/public-repo-links.spec.ts. - 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 childrenmin-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, thetouch-target/font-size-floormixins,.touch-target/.back-link— instead of per-page sizes (packages/theme.md);core/web/tests/ui-floors.spec.tsguards them. - 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/. - Style layers and units — theme (universal) → app global → layout → page (scoped) → component (scoped); relative units (
rem/em/%/dvh/ container units),embreakpoints with range syntax, px only for hairlines, focus rings, shadows, blur and themax()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. 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.- 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.
- Colour system (spec, packages/theme.md § Colour system). Restyle from the solid colours only: main
primary/secondary/accent, groundsink/paper, flagswarning/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 bytheme/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>-colornames 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 forscripts/rename-color-vars.mjs(--check core theme packagesmust 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. CONCEPTS.md— shared domain vocabulary (entities, named processes, status concepts). Relevant when orienting to the codebase or discussing domain concepts.- 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). Locale2e:regressionis not AWS test/prod topology (execute-api + CDN + LambdaSITE_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:
- Operate this repo’s AWS/SAM/Docker CD: portfolio-aws-cicd
- Nuxt SSR CI/CD template (other repos): nuxt-ssr-cicd-template (docs)
- Commit / PR / rulesets: commit-pr-rules-template (docs)
Client adapters and mirrors:
- Google Gemini / Antigravity: GEMINI.md and .gemini/skills
- Cursor: .cursor/rules/
- Codex: .codex/
- OpenCode: .opencode/
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/themetotheme/core/dist. Rebuild theme after source changes (npm run postinstallornx prepare). - Aliases in
core/web/nuxt.config.ts:#shared,#types,theme,theme/scss/#theme/scss. SYS_ENVselects Nitro preset (node-servervsaws_lambda), MessageStore adapter, and output dir.- Imports stay at the top of the file (no inline imports). Switches over unions use a
neverdefault. - JavaScript is ESM by default:
.jsin"type": "module"packages;.cjsonly when a tool requires CommonJS (with a one-line reason); never add.mjs(the root package is"type": "module"too). Existing.mjs/.cjsare frozen allowlists that only shrink. Rule:.cursor/rules/javascript-esm-modules.mdc; guard:core/web/tests/module-format.spec.ts. - After changing
packages/utilities,npm run build --workspace=@tgmc/utilities(orbuild:libs).
Pitfalls
- Nitro
rollupConfig.onwarnsilences known cache-driver / circular-dep warnings — do not “fix” without reproducing. HTTPS=1needs certs incore/web/bin/ssl/.- Docker test does not emulate S3/CDN; public assets are staged at
infra/sam/.aws-sam/build-src/publicfor CD sync. - The
/i/portfolio/tesseract/*.pngpaths in the spatial-experiences and innovation-prototyping case studies, and their mix with/i/tesseract/elsewhere, are intentional (owner, #279): don’t move the files, rewrite or align the paths, or report them as broken or inconsistent. See site-media.md. - Prettier does not run on GitHub (
GITHUB_ACTIONS=trueturnsprettier/prettieroff). Format locally. - Icons: Lucide via
@nuxt/icon(UiIcon, oricon="<lucide-name>"onUiButton/UiChip), inline SVG — no icon fonts. Names the shared components or both apps use go intoTGMC_BASE_ICONS(packages/nuxt-layer-base/src/config/icons.ts); each app lists only its own extra names in itsnuxt.config.tsicon.clientBundle.icons(dynamic names aren’t scanned;tests/icons.spec.tsguards it). See web/features/icons.md. - Region for SAM/CD: see cicd.md /
infra/sam/samconfig.toml(currentlyus-west-2).
After each implementation
- Document non-obvious behavior (JSDoc or a page under
docs/). - Update the catalog in
docs/README.md/docs/_catalog.mdif 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/*.mdis the in-app/docscontent (no copy intocore/web/content/). Full checklist: contributing.md. - Portfolio-only commit override: after implementation, commit that conversation’s work (implementation + docs together) unless the user forbids it. This intentionally differs from the global Cursor user rule “commit only when asked.” Do not flip this repo to ask-first.
- Commit only files from this conversation (
git add path, nevergit add -Aunless asked). - Leave unrelated working-tree edits untouched.
- Never discard changes without the user’s explicit approval — no
git restore/git checkout --/ hard reset / clean / silent overwrite to isolate a commit. If a file mixes WIP, ask before splitting.
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.