# AI Maintenance Guide — Signal Noir Light

## Product identity

This repository is the public commercial **Signal Noir Light** fixed-theme edition, version 3.3.0. It is not the private I/US Music website and it is not a multi-theme bundle.

## Non-negotiable rules

1. Keep the edition fixed to `data-palette="signal-noir"` and `data-appearance="light"`.
2. Do not add palette or appearance switching controls.
3. Do not import token definitions from other I/US theme editions.
4. Keep the English/Japanese control right-aligned in `.preference-controls`.
5. Preserve the visible linked credit: `Designed by I/US brand.` → `https://iusmusic.com`.
6. Do not introduce orange, amber, gold or warm-brown interface colours.
7. Preserve semantic HTML, keyboard access, focus restoration, print layouts and reduced-motion behaviour.
8. Edit source files, not generated `dist/` or `standalone.html` files.

## Source of truth

- `content/site-config.json` — brand, company, social links, form/comment adapters and fixed theme metadata.
- `content/projects.json` — project records.
- `content/posts.json` — post records and routes.
- `content/translations.json` — English/Japanese strings.
- `index.html` — homepage structure and dialogs.
- `assets/css/tokens.css` — geometry, typography, timing and shared design tokens.
- `assets/css/palettes.css` — the single Signal Noir Light colour-token mapping.
- `assets/css/base.css`, `layout.css`, `components.css`, `motion.css`, `print.css` — shared presentation.
- `assets/js/` — interaction modules.
- `scripts/generate-post-pages.mjs` — canonical article generation.

## Generated files

Never edit these directly:

- `assets/js/data/*.js`
- `dist/`
- `standalone.html`
- generated canonical post pages
- generated feeds and sitemap

Regenerate with:

```bash
npm run build
npm run standalone
```

## Runtime architecture

`state.js` creates `window.IUS_TEMPLATE`. `theme.js` enforces the fixed palette and appearance; it must never read or persist a user-selected theme. `i18n.js` manages English/Japanese. Other modules initialise UI demos, projects, lightbox, comments, posts, forms, company details, social links and motion. `app.js` starts modules after the DOM is ready.

## Safe update workflow

1. Read `edition.json` and `AI_CONTEXT.json`.
2. Change the smallest source-of-truth file.
3. Run `npm run validate`.
4. Run `npm run build`.
5. Run `npm run standalone`.
6. Run `npm run qa` with Chromium available.
7. Search the output for `data-palette-toggle` and `data-appearance-toggle`; both counts must be zero.
8. Confirm the root still uses `signal-noir` and `light` on the homepage and every canonical post page.

## Definition of done

- fixed theme is unchanged;
- no other palette name or token set is shipped;
- language switching works;
- all dialogs, forms, posts, comments, sharing and printing work;
- no horizontal overflow at 320px;
- no console errors;
- attribution remains visible and linked;
- `preview/QA.md` passes.
