# Agent guide

This is the **canonical** onboarding for AI coding agents. Root [`AGENTS.md`](../../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](./map.md)

## Shared CDN (test)

Test hashed assets use the shared Example Organization/portfolio CDN
(`shared-cdn-test`). See [infra.md](../infra.md#shared-test-cdn-example-organization--portfolio)
and [shared-cdn-handoff.md](./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](../cicd.md#portfolio-synchronization-to-tamaramackgithubio) for setup, rollout, and recovery.

## Before you edit

1. Read [map.md](./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](../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](../dev/git-hooks.md). Skip locally with `HUSKY=0`.
6. Public chrome IA (primary nav + Work sub-nav + restyle surfaces): [portfolio-august-launch.md](../portfolio-august-launch.md#public-information-architecture) and [web/README.md](../web/).
7. Theme tokens + Sass `theme-*` helpers: [packages/theme.md](../packages/theme.md). Personalize brand roles / FOUC / backgrounds: [web/features/personalization.md](../web/features/personalization.md). App SCSS inject: [web/features/app-scss.md](../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](../web/features/app-scss.md#colour-rules-for-pages-and-components)). 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](../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](../solutions/build-errors/pug-template-only-imports-stripped.md).
10. **Open TODO / follow-ups** live in [web/features/interaction-redesign.md#todo](../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](../packages/theme.md#touch-and-type-floors)); `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](../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](../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](../superpowers/specs/2026-09-24-color-system-design.md), [packages/theme.md § Colour system](../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](../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`](../../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](../solutions/ci-cd/aws-test-site-url-localhost.md).

## 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](../cicd.md). Env vars: [web/setup/environment.md](../web/setup/environment.md).

Portable skills for **other** repos:

- Operate this repo’s AWS/SAM/Docker CD: [portfolio-aws-cicd](../../.agents/skills/portfolio-aws-cicd/)
- Nuxt SSR CI/CD template (other repos): [nuxt-ssr-cicd-template](../../.agents/skills/nuxt-ssr-cicd-template/) ([docs](../templates/nuxt-ssr-cicd/))
- Commit / PR / rulesets: [commit-pr-rules-template](../../.agents/skills/commit-pr-rules-template/) ([docs](../templates/commit-pr-rules/))

Client adapters and mirrors:

- Google Gemini / Antigravity: [GEMINI.md](../../GEMINI.md) and [.gemini/skills](../../.gemini/skills/)
- Cursor: [.cursor/rules/](../../.cursor/rules/)
- Codex: [.codex/](../../.codex/)
- OpenCode: [.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/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`, `theme/scss` / `#theme/scss`.
- `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.
- JavaScript is **ESM by default**: `.js` in `"type": "module"` packages; `.cjs` only when a tool requires CommonJS (with a one-line reason); never add `.mjs` (the root package is `"type": "module"` too). Existing `.mjs` / `.cjs` are 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` (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.
- The `/i/portfolio/tesseract/*.png` paths 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](../web/features/site-media.md#intentional-case-study-paths-do-not-flag).
- Prettier does **not** run on GitHub (`GITHUB_ACTIONS=true` turns `prettier/prettier` off). Format locally.
- Icons: Lucide via `@nuxt/icon` (`UiIcon`, or `icon="<lucide-name>"` on `UiButton`/`UiChip`), inline SVG — no icon fonts. Names the shared components or both apps use go into `TGMC_BASE_ICONS` (`packages/nuxt-layer-base/src/config/icons.ts`); each app lists only its own extra names in its `nuxt.config.ts` `icon.clientBundle.icons` (dynamic names aren't scanned; `tests/icons.spec.ts` guards it). See [web/features/icons.md](../web/features/icons.md).
- Region for SAM/CD: see [cicd.md](../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](../contributing.md#whenever-documentation-is-altered).
- **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`, never `git add -A` unless 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](../web/features/page-data-loading.md#vitest-conventions-content-driven)                                                                     |

## 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.
