# Documentation

Canonical instructions for **tgmc-portfolio** live in this folder. The [root README](../README.md) is a GitHub landing page (badges, quick start, links).

**GitHub Pages** publishes this tree (Jekyll Cayman). Source: `/docs`. Workflow: [`.github/workflows/pages.yml`](../.github/workflows/pages.yml).

**AI agents:** [agents/README.md](./agents/README.md) · [agents/map.md](./agents/map.md) · generated checklist [`AGENTS.md`](../AGENTS.md)

**Humans:** [web/guides/quickstart.md](./web/guides/quickstart.md) · [cicd.md](./cicd.md)

## Catalog (by directory)

Instructions are grouped the same way as the repo. Prefer these pages over duplicating setup in package READMEs.

[Media Library current architecture and UML](./architecture/media-library/current.md) — source-verified current components, model, sequences, lifecycle and deployment; [October 14 snapshot](./architecture/media-library/README.md).

[Admin process current architecture and UML](./architecture/admin-process/current.md) — source-verified current session, CRUD, CDN, media and deployment diagrams; [October 14 snapshot](./architecture/admin-process/README.md).

[Admin target architecture](./architecture/admin-process/target-architecture.md) — October 17 proposal with October 21 implementation-status update.

### `docs/` (this tree)

| File                                                       | Topic                                               |
| ---------------------------------------------------------- | --------------------------------------------------- |
| [index.md](./index.md)                                     | GitHub Pages home                                   |
| [README.md](./README.md)                                   | This catalog (GitHub tree view)                     |
| [cicd.md](./cicd.md)                                       | Four-env CI/CD, workflows, OIDC, versioning, CDN/S3 |
| [templates/nuxt-ssr-cicd/](./templates/nuxt-ssr-cicd/)     | Portable Nuxt SSR CI/CD template for other agents   |
| [templates/commit-pr-rules/](./templates/commit-pr-rules/) | Portable commit, PR, merge, and ruleset template    |
| [docker.md](./docker.md)                                   | Compose local/dev/test, host `.output`, ports       |
| [infra.md](./infra.md)                                     | SAM Lambda + DynamoDB + CloudFront                  |
| [contributing.md](./contributing.md)                       | How to change docs and code                         |
| [portfolio-august-launch.md](./portfolio-august-launch.md) | Public IA, restyle layouts, QA, release gates       |

### `docs/agents/`

| File                                                    | Topic                                                     |
| ------------------------------------------------------- | --------------------------------------------------------- |
| [README.md](./agents/README.md)                         | AI agent onboarding (commands, conventions, pitfalls)     |
| [map.md](./agents/map.md)                               | Repo map: directory → purpose → source of truth           |
| [shared-cdn-handoff.md](./agents/shared-cdn-handoff.md) | Archived brief: shared test CDN with Example Organization |

Root [`AGENTS.md`](../AGENTS.md) is a **generated checklist**. Edit `scripts/update-agents.mjs` or pages here; do not hand-edit `AGENTS.md`.

### `docs/web/` — Nuxt app (`@tgmc/web`)

| Path                                                                                           | Topic                                                                                                                |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [web/README.md](./web/README.md)                                                               | App docs hub                                                                                                         |
| [web/guides/quickstart.md](./web/guides/quickstart.md)                                         | Local 5-minute setup                                                                                                 |
| [web/guides/examples.md](./web/guides/examples.md)                                             | CDN and feature examples                                                                                             |
| [web/setup/environment.md](./web/setup/environment.md)                                         | `SYS_ENV`, secrets, runtimeConfig                                                                                    |
| [web/setup/ssl-setup.md](./web/setup/ssl-setup.md)                                             | Local HTTPS certs                                                                                                    |
| [web/features/cdn-guide.md](./web/features/cdn-guide.md)                                       | CDN / `NUXT_APP_CDN_URL`                                                                                             |
| [web/features/cdn-quickstart.md](./web/features/cdn-quickstart.md)                             | CDN cheat sheet                                                                                                      |
| [web/features/site-media.md](./web/features/site-media.md)                                     | Site media manifest, metadata-only rendering, guard, `media:site-import`                                             |
| [web/features/messages-api.md](./web/features/messages-api.md)                                 | Contact messages API                                                                                                 |
| [web/features/admin.md](./web/features/admin.md)                                               | Docker-only admin (`@tgmc/admin`)                                                                                    |
| [web/features/page-data-loading.md](./web/features/page-data-loading.md)                       | `useContentAsyncData` + content-driven Vitest conventions                                                            |
| [web/features/gallery-and-docs.md](./web/features/gallery-and-docs.md)                         | `/gallery` full-screen grid + feed, `/docs` (Work sub-nav)                                                           |
| [web/features/app-scss.md](./web/features/app-scss.md)                                         | App SCSS variables and globals                                                                                       |
| [web/features/personalization.md](./web/features/personalization.md)                           | Style Studio, setups, FOUC, thin Personalize                                                                         |
| [web/features/seo-and-ai-visibility.md](./web/features/seo-and-ai-visibility.md)               | SEO meta, JSON-LD, robots, llms.txt, theme-color                                                                     |
| [web/features/theme-studio-preset-research.md](./web/features/theme-studio-preset-research.md) | Primary-source notes: Theme/Color/palettes → Style Studio brand packs                                                |
| [web/features/footer-and-social-links.md](./web/features/footer-and-social-links.md)           | Slim footer (sticks to the bottom) + `AppSocialLinks`                                                                |
| [web/features/icons.md](./web/features/icons.md)                                               | Lucide icons via `@nuxt/icon` (`UiIcon`), inline SVG                                                                 |
| [web/features/brand-marks.md](./web/features/brand-marks.md)                                   | Placeholder TM monogram, wordmark, favicons, manifest and social card                                                |
| [web/features/site-header.md](./web/features/site-header.md)                                   | Measured header, nav order, phone Menu disclosure                                                                    |
| [web/features/ui-components.md](./web/features/ui-components.md)                               | Component standard + `UiButton`, `UiDialog` and forms reference (`useForm`, leave dialog): tiers, naming, API, tests |
| [web/features/interaction-redesign.md](./web/features/interaction-redesign.md)                 | Interaction redesign + **open TODO list** (admin media types, follow-ups)                                            |
| [web/data-stores.md](./web/data-stores.md)                                                     | SQLite / Postgres / Dynamo adapters                                                                                  |
| [web/reference/project-structure.md](./web/reference/project-structure.md)                     | App layout                                                                                                           |
| [web/reference/architecture.md](./web/reference/architecture.md)                               | Architecture diagram hub                                                                                             |
| [web/reference/system-c4.md](./web/reference/system-c4.md)                                     | C4 context, containers, deployment                                                                                   |
| [web/reference/api-uml.md](./web/reference/api-uml.md)                                         | API inventory and store UML                                                                                          |
| [web/reference/site-wireframes.md](./web/reference/site-wireframes.md)                         | Site map and page wireframes                                                                                         |
| [web/reference/cognitive-a11y-audit.md](./web/reference/cognitive-a11y-audit.md)               | Cognitive accessibility audit (2026-10-22), friction profiles and fixes                                              |
| [web/reference/process-sequences.md](./web/reference/process-sequences.md)                     | UML sequences for key processes                                                                                      |
| [web/reference/types.md](./web/reference/types.md)                                             | TypeScript types                                                                                                     |
| [web/reference/typescript-config.md](./web/reference/typescript-config.md)                     | Paths and compiler                                                                                                   |
| [web/reference/site-person.md](./web/reference/site-person.md)                                 | Centralized `profile.json` site identity                                                                             |

### `docs/packages/`

| File                                                               | Topic                                                                                                                                                                                    |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [packages/README.md](./packages/README.md)                         | Workspace packages index                                                                                                                                                                 |
| [packages/utilities.md](./packages/utilities.md)                   | `@tgmc/utilities` Node vs `/browser` vs `/universal`                                                                                                                                     |
| [packages/theme.md](./packages/theme.md)                           | `@tgmc/theme` Color/Theme APIs, tokens, brand vs hue, focus rings, `data-fit`, ratios                                                                                                    |
| [packages/image.md](./packages/image.md)                           | `@tgmc/image` sharp ingest/transform, LQIP, delivery UX, sanitize                                                                                                                        |
| [packages/media.md](./packages/media.md)                           | `@tgmc/media` catalog, children, audit/jobs, local SQLite/FS SDK, transfer                                                                                                               |
| [packages/media-aws.md](./packages/media-aws.md)                   | `@tgmc/media-aws` DynamoDB/S3/SQS adapters + worker                                                                                                                                      |
| [packages/media-postgres.md](./packages/media-postgres.md)         | `@tgmc/media-postgres` PostgreSQL catalog/jobs/audit, transfer endpoint                                                                                                                  |
| [packages/media-client.md](./packages/media-client.md)             | `@tgmc/media-client` portable media HTTP client                                                                                                                                          |
| [packages/media-nuxt.md](./packages/media-nuxt.md)                 | `@tgmc/media-nuxt` Nuxt `/api/media/*` route kit                                                                                                                                         |
| [packages/nuxt-layer-base.md](./packages/nuxt-layer-base.md)       | `@tgmc/nuxt-layer-base` Base Nuxt layer: theme stylesheet + Sass auto-use, a11y shell components, `@nuxt/a11y`, Lucide icons, `tgmc:` feature flags and the theme-off fallback           |
| [packages/nuxt-layer-ui.md](./packages/nuxt-layer-ui.md)           | `@tgmc/nuxt-layer-ui` UI Nuxt layer: PrimeVue (styled, theme preset, optional) + the `Ui*` component kit, `useUiStack`, `useAppToast`, `useForm`, `useUnsavedChangesGuard`, build matrix |
| [packages/nuxt-layers.md](./packages/nuxt-layers.md)               | Nuxt template layers architecture blueprint (base + ui layers, optional features, interfaces)                                                                                            |
| [packages/nuxt-app-generator.md](./packages/nuxt-app-generator.md) | `@tgmc/likwidlibs:nuxt-app` Nuxt 4 workspace app generator                                                                                                                               |

### `docs/dev/`

| File                                                                                                                 | Topic                                                                 |
| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [dev/README.md](./dev/README.md)                                                                                     | Developer tooling index                                               |
| [dev/git-hooks.md](./dev/git-hooks.md)                                                                               | Husky 9 hooks, lint-staged, LF line endings                           |
| [dev/github-access.md](./dev/github-access.md)                                                                       | GitHub About, topics, Pages, `gh`                                     |
| [dev/npm-security-overrides.md](./dev/npm-security-overrides.md)                                                     | npm overrides                                                         |
| [solutions/security/npm-audit-vulnerabilities-2026-10.md](./solutions/security/npm-audit-vulnerabilities-2026-10.md) | npm audit triage, minimal overrides (2026-10)                         |
| [solutions/security/codeql-regex-backtracking-2026-10.md](./solutions/security/codeql-regex-backtracking-2026-10.md) | CodeQL regex alerts: 3 real ReDoS fixed, 9 bounded or false (2026-10) |
| [dev/encapsulation-remediation.md](./dev/encapsulation-remediation.md)                                               | Layer / import boundaries                                             |

### Design history (not runbooks)

| Directory                                                                                                | Topic                                  |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| [superpowers/specs/](./superpowers/specs/)                                                               | Locked design specs                    |
| [superpowers/plans/](./superpowers/plans/)                                                               | Implementation plans                   |
| [plans/](./plans/)                                                                                       | Feature plans (e.g. media-player MSE)  |
| [Portfolio architecture review (2026-10-22)](./plans/2026-10-22-portfolio-architecture-review/README.md) | Archived diagrams and improvement plan |

These are excluded from the GitHub Pages build (`docs/_config.yml`).

### Code trees (pointers only)

| Path                                          | Use                                                                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [`core/web/`](../core/web/)                   | Nuxt app source; config `nuxt.config.ts`                                                                     |
| [`docker/`](../docker/)                       | Dockerfiles + Compose; details in [docker.md](./docker.md)                                                   |
| [`infra/sam/`](../infra/sam/)                 | SAM template; details in [infra.md](./infra.md)                                                              |
| [`packages/`](../packages/)                   | `utilities`, `image`, `media-player`, `likwidlibs`, `web-layer-admin`                                        |
| [`theme/core/`](../theme/core/)               | Packaged theme (`@tgmc/theme`)                                                                               |
| [`archive/v3/`](../archive/v3/)               | Credential-plaza home snapshot (copy-back restore)                                                           |
| [`scripts/`](../scripts/)                     | migrate, SAM, GitHub env, `update-agents.mjs`; shared helpers in `scripts/lib/` (spawn, aws-config, is-main) |
| [`.github/workflows/`](../.github/workflows/) | CI/CD YAML; narrative in [cicd.md](./cicd.md)                                                                |

## Code documentation

- [Coverage and authoring contracts](./dev/code-documentation.md)
- [Runtime boundaries and flows](./web/reference/runtime-flows.md)
