hns-oss-docs-structure-map

# docs-site Structure Map

Hugo **geekdoc** site at `docs-site/`, deployed to **adk.mo.ai.kr** via
Vercel (auto-deploy on push). All paths below are relative to `docs-site/`.

## Path map

| Surface | Path | Notes |
|---------|------|-------|
| Site config | `hugo.toml` | NOT hugo.yaml. `defaultContentLanguage = "ko"`; version SSOT `params.version` / `params.releaseDate` |
| Content | `content/{ko,en,ja,zh}/` | ko canonical; 4 locale trees mirror each other |
| Section order | `content/<locale>/_meta.yaml` | per-locale; a section change lands in ALL FOUR files |
| Sidebar menu | `data/menu/main.yaml` | 4-locale name maps + `icon:` per entry |
| Menu icons | `layouts/partials/menu.html` | SVG `switch`/case per `icon:` value — coupling below |
| Shortcodes | `layouts/shortcodes/` | `icon.html` (variants ok/warn/danger/primary/muted), etc. |
| CSS | `static/moai-brand.css` (**FROZEN** — never edit), `static/moai-design.css` | Claude Warm Editorial, light-only theme |
| Redirects | `vercel.json` | `redirects` array — the only Vercel surface this harness touches |

## main.yaml entry schema

Each sidebar entry carries a 4-locale name map and an icon:

```yaml
- name:
    ko: 시작하기
    en: Getting Started
    ja: はじめに
    zh: 快速开始
  ref: /getting-started
  icon: rocket
```

## icon ↔ menu.html SVG-case coupling [HARD]

Every `icon:` value in `main.yaml` MUST have a matching case in the SVG
switch inside `layouts/partials/menu.html`. An unmatched value renders an
empty `<svg>` — a silent visual defect (no build warning). After any icon
edit:

```bash
grep -n '"<icon-value>"' docs-site/layouts/partials/menu.html
```

If absent, add the SVG path case in the same change.

## vercel.json redirect pattern

Moved/renamed pages require BOTH entries:

```json
{
  "redirects": [
    { "source": "/:locale(ko|en|ja|zh)/old-path", "destination": "/:locale/new-path" },
    { "source": "/old-path", "destination": "/ko/new-path" }
  ]
}
```

The Vercel project binding itself is immutable — this harness edits only the
`redirects` array.

## Known divergence to reconcile

`content/<locale>/_meta.yaml` carries a **`design`** section while
`data/menu/main.yaml` carries **`guides`**. When touching either file,
reconcile toward the SSOT design report's 12→11 section restructure
(`.moai/reports/readme-docs-redesign-20260713.md`) and record the resolution
direction in your report.

## Tooling reality

- `gen_menu.py` (referenced by the legacy i18n rules doc) DOES NOT exist —
  menu edits are manual; use the coupling grep above.
- Build check: `cd docs-site && hugo --minify --gc` must complete
  warning-free (a malformed `_meta.yaml` or menu entry surfaces here).
  Full recipe: Skill("hns-oss-docs-verify").