# TN Site Agent Instructions

## Scope

- This repository is the replacement public website for TN Silver.
- `prototype/` is the authoritative design artifact during the prototype phase.
- Until the user explicitly starts production implementation, make site work only with static HTML, CSS, JavaScript, and local assets under `prototype/`.
- Do not add a frontend framework, package manager, build step, API implementation, authentication implementation, or production application scaffold during the prototype phase unless the user explicitly requests it.
- Keep the current production repositories `../tn-home` and `../tn-portal` unchanged unless the user explicitly expands the task scope.

## Public Page Integration

- The public prototype consists of seven page roles: landing, company introduction, production cases, production knowledge, production process, helpful resources, and contact.
- The current canonical mapping is:
  - landing: `prototype/index.html`
  - company introduction: `prototype/about.html`
  - production cases: `prototype/cases.html`
  - production knowledge: `prototype/knowledge.html`
  - production process: `prototype/particle-horizontal.html`
  - helpful resources: `prototype/resources.html`
  - contact: `prototype/contact.html`
- Determine whether a file is public from the user-designated page role and current integration mapping, not from a filename such as `*-lab`.
- The canonical landing entry route is `prototype/index.html?checkpoint=20&macro=24`. The query parameters are part of the approved landing state; preserve them in the shared brand/home link and in integration preview links instead of reducing the route to bare `index.html`.
- `prototype/process.html` is the former production-process baseline and remains a research reference while the mapping above points to `prototype/particle-horizontal.html`. Do not link it as the current production-process page.
- Files for particle, motion, rendering, Noble Shield, studies, and other experiments remain research inputs unless the user explicitly promotes their content into one of the seven public page roles. Do not expose a research page as an additional public route merely because it has a complete-looking UI.
- The seven public page originals are the integrated site. Do not create an eighth HTML file that copies their full contents as a separate combined version.
- A session is the integration session only when the user explicitly assigns site-wide integration or cross-page coordination in that session. Other sessions are page sessions even when they inspect shared files.

### Canonical and Work-in-Progress Routes

- The seven files in the canonical mapping above are stable public addresses. Each canonical file, together with every CSS, JavaScript, image, and other asset it references, is that page role's current integration-ready checkpoint (the project's meaning of `latest`).
- Do not create `latest.html`, `*-latest.html`, a `latest/` directory, or a dated copy as a second source of truth. Do not rename a canonical public file to reflect a design iteration.
- The integration session consumes only the seven canonical mappings when it needs the latest page versions. It must not guess which experimental filename is newest or integrate an unpromoted work-in-progress route.
- A page session may develop an unfinished variant at a non-public route under `prototype/experiments/<page-role>/`. Disposable preview wrappers, screenshots, traces, and generated QA artifacts belong under `.runtime/` instead. Experimental and runtime routes must never be added to the public header, primary navigation, footer, canonical cross-page links, or public route mapping.
- Keep a work-in-progress variant isolated from the canonical checkpoint. Do not modify CSS, JavaScript, images, or other assets already referenced by the canonical page while claiming that only an experimental HTML route is changing. Give the variant its own page-specific files, then merge the accepted changes during promotion.
- Promote a page variant to its canonical address only when it is ready to become the version seen by integration:
  1. Verify the variant's page-owned content, responsive layout, and interactions at desktop and mobile.
  2. Re-read the current canonical HTML and every affected canonical dependency immediately before editing so concurrent work is preserved.
  3. Merge only page-owned changes into the canonical HTML and page-dedicated assets. Preserve the shared header mount and all other integration-owned concerns.
  4. Remove references from the canonical dependency chain to temporary or experiment-only files.
  5. Verify the canonical public route itself at desktop and mobile, including browser errors and broken local assets or links.
- Until promotion and canonical-route verification finish, the previous canonical checkpoint remains `latest`. A page session must describe unfinished work as unpromoted rather than telling integration that the canonical page is current.
- A non-public integration review surface may link to or embed the seven canonical routes so they can be judged together. Keep that surface under `.runtime/`; it must not copy the seven page bodies, become an eighth public page, or read experimental routes by default.

### Ownership

- The integration session owns cross-page concerns: public routes, header, footer, primary navigation, shared design tokens and base styles, shared scripts and interactions, common responsive behavior, and cross-page accessibility behavior.
- A page session owns only its page-specific content, section layout, dedicated motion, dedicated interactions, and assets.
- Shared-shell source files are protected integration-owned files: `prototype/styles/site-shell.css` and `prototype/scripts/site-shell.js`. Existing cross-page legacy assets such as `prototype/styles/site.css` and `prototype/scripts/particle-title.js` are also integration-owned while more than one public page loads them. Page sessions may read integration-owned files but must not edit them.
- Before editing a stylesheet, script, or existing asset, a page session must check whether another public page references it. Any file referenced by more than one public page is integration-owned even when it is not named above. Add new page work to a page-dedicated file instead of extending a cross-page file.
- Each public page may contain only the shared-shell mount element supplied by the integration session. Page sessions must not add, remove, replace, wrap, or restyle the shared header, primary navigation, customer-portal entry, future shared footer, or their mount elements.
- Page-specific CSS and JavaScript must not target shared-shell selectors such as `.site-header`, `.brand`, `.primary-navigation`, `.nav-link`, `.menu-toggle`, `.portal-link`, or future shared-footer selectors. If a page-specific layout appears to require such a rule, stop that part of the change and report the requested integration exception.
- In `prototype/index.html` and `prototype/process.html`, hidden legacy sections for other page roles are preserved integration areas, not page-session work areas. Landing and production-process sessions must edit only their currently public visible page content and must not revive or modify those hidden copies.
- Page sessions must not fork a cross-page concern into page-local markup, CSS, or JavaScript. When a page appears to need a different shared element, preserve the page-specific work and report the proposed shared change for integration instead of silently creating a local variant.
- Page-specific exceptions to a shared concern require an explicit integration decision. Record and implement the exception narrowly; do not treat accidental divergence as an exception.

### Approved Footer Baselines

- The public prototype has exactly two user-approved footer baselines. Treat both as frozen integration references until the user explicitly approves a footer redesign.
- `landing-wordmark` is the landing-only baseline on `prototype/index.html?checkpoint=20&macro=24`: a black full-bleed footer led by the oversized edge-to-edge `TN SILVER` wordmark.
- `internal-colophon` is the shared baseline for the other six public page roles: a quieter compact black colophon with the `TN SILVER` name, company registration details, studio address, business hours, phone number, email address, and copyright.
- `prototype/scripts/site-shell.js` must set the selected baseline on the shared footer mount as `data-footer-variant`, and `prototype/styles/site-shell.css` remains the sole styling source for both baselines. Do not copy either footer into page-local markup or styles.
- Future integration previews must render the shared footer through `[data-site-footer]` and use the canonical public routes above as the visual references. Do not reconstruct a baseline from screenshots, merge the two baselines, or introduce a third footer variant without an explicit user decision.
- These frozen baselines approve the footer direction for future integration; they do not by themselves approve production implementation or unrelated page changes.

### Integration Procedure

When a task changes a cross-page concern or the user assigns integration work:

1. Inspect the current versions of all seven public page originals and the shared CSS and JavaScript they load. Re-read affected regions immediately before editing so another session's newer work is not replaced with a stale copy.
2. Identify the canonical shared behavior and distinguish intentional page-specific differences from drift.
3. Implement shared header and navigation markup, styling, and behavior only through `site-shell.css` and `site-shell.js`; public HTML files retain mount elements rather than copied shared markup. Add a shared footer through the same integration-owned mount pattern when its design is approved.
4. Preserve each page's body content, dedicated interaction, and research-derived visual work unless the integration decision explicitly changes it.
5. Update public navigation targets and per-page active state together. Do not leave temporary hash routes, research routes, or stale filenames in only some public headers.
6. If another session changes an affected region during integration, re-read and merge it. Do not overwrite the newer work or declare integration complete with unresolved divergence.
7. Verify every affected public route at desktop and mobile, including header layout, menu interaction, active navigation state, route transitions, browser errors, and broken local assets or links.

An integration task is complete only when the shared decision is present in every affected page original, the public routes work as one site, and no unresolved page-specific divergence remains. If propagation or verification is incomplete, report the integration as incomplete rather than presenting the combined site as current.

## Prototype Completion

- Treat the prototype as implementation-ready only after its required pages, responsive layouts, interactions, assets, and important UI states are represented and the user explicitly approves the transition.
- When production implementation begins, keep the approved prototype available as the visual and behavioral reference instead of silently replacing it.

## Visual Verification

- Use the global `$verify-frontend` workflow for every rendered prototype change or visual review.
- Verify the actual prototype route at desktop and mobile, exercise the changed interaction, inspect screenshot pixels, and check browser/runtime errors before claiming completion.
- Keep tests and evidence in the shared Git-ignored frontend QA runtime during the prototype phase; do not add a package manager or test dependency to this repository.

## Remote Preview Servers

- When a task needs an HTML, development, preview, or static-file server, bind it to `0.0.0.0` (or the framework's equivalent), not only to `127.0.0.1` or `localhost`.
- Before starting another server, inspect existing listeners and reuse the preview server for the current task when it is healthy. Restart it only when it is stopped, bound only to loopback, serving the wrong root, or otherwise unusable.
- Determine the machine's current Tailscale IPv4 address at runtime with `tailscale ip -4`. Report and link the preview as `http://<tailscale-ip>:<port>/...`; do not present a localhost URL as the only usable link.
- Before reporting that a preview is ready, verify that the listener is reachable beyond loopback and that an HTTP request to the Tailscale URL returns the expected page. If verification fails, report the failure instead of claiming the preview is available.
- Keep preview processes and generated logs, screenshots, traces, or other runtime artifacts under a Git-ignored `.runtime/` path when practical. Do not commit runtime artifacts.

## Reports

보고서 작성 시 `~/workspace/tools/report`의 컨벤션을 먼저 읽고 적용한다.