# Repository map (agents)

Use this table to find the **source of truth** for a topic. Do not invent parallel docs in package READMEs.

## Top-level directories

| Directory                | Purpose                                               | Read first                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docs/`                  | Canonical human + agent documentation                 | [docs catalog](../) · [architecture diagrams](../web/reference/architecture.md) · [contributing sync](../contributing.md#whenever-documentation-is-altered) |
| `docs/templates/`        | Portable templates for other agents/repos             | [nuxt-ssr-cicd](../templates/nuxt-ssr-cicd/) · [commit-pr-rules](../templates/commit-pr-rules/)                                                             |
| `core/web/`              | Nuxt 4 app `@tgmc/web`                                | [web/README.md](../web/) (public chrome IA), [august launch](../portfolio-august-launch.md), `nuxt.config.ts`                                               |
| `core/admin/`            | Docker-only admin `@tgmc/admin`                       | [admin.md](../web/features/admin.md), [core/admin/README.md](../../core/admin/README.md)                                                                    |
| `core/web-e2e/`          | Cypress E2E                                           | `cypress.config.ts`                                                                                                                                         |
| `packages/utilities/`    | Shared Node + `/browser` + `/universal`               | [packages/utilities.md](../packages/utilities.md)                                                                                                           |
| `packages/media-player/` | Media player lib                                      | `packages/media-player/README.md` · [packages hub](../packages/)                                                                                            |
| `packages/likwidlibs/`   | Shared libs / generators                              | `packages/likwidlibs/README.md` · [packages hub](../packages/)                                                                                              |
| `theme/core/`            | `@tgmc/theme` tokens + page-fit / ratios (via `dist`) | [packages/theme.md](../packages/theme.md)                                                                                                                   |
| `archive/v2/`            | Pre-ember coral/ivory launch snapshot (not imported)  | `archive/v2/README.md`                                                                                                                                      |
| `theme/foundation/`      | Upstream Foundation (vendor docs in-tree)             | `theme/foundation/README.md`                                                                                                                                |
| `theme/primevue/`        | PrimeVue theme bits                                   | `theme/primevue/README.md`                                                                                                                                  |
| `docker/`                | Compose + Dockerfiles                                 | [docker.md](../docker.md)                                                                                                                                   |
| `infra/sam/`             | SAM template, samconfig, staged `.aws-sam/`           | [infra.md](../infra.md), **[shared CDN handoff](./shared-cdn-handoff.md)**                                                                                  |
| `scripts/`               | migrate, SAM, GH env, lint-staged, update-agents      | this map + script headers                                                                                                                                   |
| `.github/workflows/`     | CI/CD YAML                                            | [cicd.md](../cicd.md)                                                                                                                                       |
| `.husky/`                | Git hooks                                             | [dev/git-hooks.md](../dev/git-hooks.md)                                                                                                                     |
| `data/`                  | Local SQLite (gitignored)                             | [web/setup/environment.md](../web/setup/environment.md)                                                                                                     |

## Important files

| File                                                    | Role                                                      |
| ------------------------------------------------------- | --------------------------------------------------------- |
| `package.json`                                          | Workspaces, scripts, keywords, `engines.node >= 24`       |
| `docs/dev/github-access.md`                             | Intended GitHub About, topics, homepage, `gh repo edit`   |
| `nx.json`                                               | Nx plugins and target defaults                            |
| `tsconfig.json`                                         | Project references                                        |
| `vitest.workspace.ts`                                   | Vitest globs                                              |
| `.nvmrc`                                                | Node 24                                                   |
| `core/web/nuxt.config.ts`                               | Aliases, Nitro preset, runtimeConfig, CDN                 |
| `core/web/content.config.ts`                            | `@nuxt/content` + SQLite connector                        |
| `../../core/web/app/components/AppPrimaryNav/index.vue` | Primary rail: Work / About / Gallery / Writing / Code     |
| `core/web/app/components/AppWorkSubNav.vue`             | Work Related: Docs / AI Lab / Process                     |
| `docs/portfolio-august-launch.md`                       | Public IA, restyle layouts, teal spots, launch QA         |
| `infra/sam/template.yaml`                               | Lambda, HTTP API, DynamoDB, S3, CloudFront                |
| `docker/docker-compose.local.yml`                       | SQLite `./data` + web `:4200` (exclusive with docker:dev) |
| `docker/docker-compose.dev.yml`                         | Postgres + api `:4100` + web `:4200`                      |
| `docker/docker-compose.test.yml`                        | DynamoDB Local + Lambda RIE + proxy `:4300`               |
| `docker/docker-compose.admin.yml`                       | Standalone admin: all DBs + MinIO + `@tgmc/admin` `:4400` |
| `lint-staged.config.mjs`                                | Pre-commit Prettier + Nx ESLint                           |

## Doc vs code README

| Location                                  | Length        | Role                                                                                               |
| ----------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------- |
| `README.md` (root)                        | Short         | GitHub + Pages entry: badges, quick start, links                                                   |
| `docs/**`                                 | Full          | Runbooks, matrices, agent instructions                                                             |
| `docker/README.md`, `infra/sam/README.md` | Operational   | Commands that must sit next to Compose/SAM files; mirrored from `docs/docker.md` / `docs/infra.md` |
| Package `README.md`                       | Package-local | Install/API for that package only                                                                  |