# Publish to <specs-repo> & the in-repo resource snapshot

> Bundled detail for [../SKILL.md](../SKILL.md). How the generated artifact lands in `<specs-repo>`, and
> how the redesign resources get snapshotted there so the whole flow is **single-repo** (like `design-export`).

## Single-repo model  -  why snapshot into <specs-repo>

The skill reads four sources. Three already live in `<specs-repo>` (`design-export/`, legacy iOS/Android,
the live label service over the network). The fourth  -  the redesign **component registry** and **Suggested
translations**  -  lives in `<resources-repo>`. Snapshotting those two into `<specs-repo>`
(exactly as `design-export/` is a manual/CI snapshot of Figma) removes the cross-repo round-trip: every
read is one repo.

**Layout** (top-level, mirroring `design-export`'s convention):
```
<specs-repo>/
├── design-export/                      # existing (Figma snapshot)
├── resources/                         # NEW snapshot  -  all data the mapper needs, in-repo
│   ├── Figma/Components/<node>.json   # component registry (localizationKeys, componentName)
│   ├── Localization/Suggested/<Key>.json   # NEW translation values (8 langs)
│   └── Localization/Legacy/<lang>.json     # LEGACY values  -  label snapshot (flat key→value, one file per language)
└── localizations/                     # NEW  -  the maps this skill publishes
    └── <screen-slug>/
        ├── <screen-slug>.md           # the reuse map
        ├── <screen-slug>.confluence.xml
        ├── <screen-slug>.overlay.png  # key↔UI overlay (when produced)
        ├── <screen-slug>.keyshots.manifest.json  # per-key screenpiece index (when produced)
        ├── keyshots/                  # per-key red-box screenpieces (render-key-shots.py)
        │   └── keyshot__<NN>__<key>.png
        └── screenshot.png
```

**Refresh**  -  two steps, both "like a `design-export` update" (run by CI or manually):
```bash
# 1. registry + new (Suggested) values  -  local copy from <resources-repo> (no network)
scripts/snapshot-resources.sh <resources-repo-root> <specs-repo-root>
# 2. legacy values  -  the ONLY network step: fetch the legacy labels for all 8 languages
scripts/fetch-legacy-labels.py --out <specs-repo>/resources/Localization/Legacy --langs all
```
With the snapshot in place every read is in-repo  -  **no live label round-trip per run**:
- new values: `resolve-new-values.py --resources-root <specs-repo>/resources` (Suggested lives there)
- legacy values: `resolve-legacy-values.py --snapshot-root <specs-repo>/resources/Localization/Legacy`
  (offline; `--live` only to verify/refresh, `--plist-root` as last resort).

## Publishing a screen's map (the skill's last step)

Two destinations; **ask the user which** (and the target space/parent/formats)  -  they are not mutually
exclusive:

### A) Confluence  -  live & idempotent (`scripts/publish-confluence.py`)

```bash
python3 scripts/publish-confluence.py --xml "$OUT/$SLUG.confluence.xml" --screen "<name>" \
    --screenshot "$OUT/screenshot.png" --overlay "$OUT/$SLUG.overlay.png" \
    --keyshots "$OUT/$SLUG.keyshots.manifest.json" \
    --attach "$OUT/$SLUG.localization.xlsx"
#   defaults: --base $CONFLUENCE_BASE_URL  --space <SPACE>  --parent <PARENT-ID>  --title "<prefix>  -  <name>"
```
- **Target configuration.** Nothing about your wiki is baked in: pass `--base-url` / `--space` / `--parent`,
  or set `CONFLUENCE_BASE_URL` / `CONFLUENCE_SPACE` / `CONFLUENCE_PARENT` once in the environment. Without a
  target the script refuses rather than guessing. `--title-prefix` (env `LOCALIZATION_PAGE_PREFIX`) sets the
  wording of the default page title.
- **Server/DC Bearer auth** (NOT Atlassian Cloud `user:token`): the PAT is read from the macOS keychain item
  **`CONFLUENCE_API_TOKEN`** and passed to `curl` via a `chmod 600` `-K` config (never on the argv). HTTP goes
  through `curl` so a corporate TLS proxy's trust store is honored (Python `urllib` fails cert verification
  there).
- **Idempotent by title.** It looks the page up via the DB-backed `GET /rest/api/content?spaceKey=...&title=...`
  (NOT CQL `/content/search`, whose async index lags a fresh page and would create a duplicate). Found →
  **PUT `version+1`, updating the same page in place**; absent → **POST create** under `--parent`. Re-running
  the mapper on a screen refreshes its page; it never duplicates.
- **Attachments.** `screenshot.png` + the overlay PNG are attached (create, or update-by-filename if present);
  the storage `<ac:image><ri:attachment ri:filename="...">` tags resolve to them. Filenames must match what
  `build-artifact.py` embedded (its basenames). **`--keyshots <manifest>`** attaches every per-key screenpiece
  PNG listed in `$SLUG.keyshots.manifest.json` (render-key-shots.py)  -  without it the Summary table's
  "Screenshot" cells reference attachments that don't exist and render as broken images.
  **`--attach <file>` (repeatable)** attaches any extra document
- pass `$SLUG.localization.xlsx` (the CMS import sheet, build-spreadsheet.py); office/spreadsheet files also
  get a `view-file` macro appended to the body so they **render inline** under a "CMS transfer file" heading.
- The skill asks the user for the space / parent / title when the environment doesn't already pin them.
- `build-artifact.py ... --print-upload` prints the exact command (plus the raw Bearer `curl`) for copy-paste.

### B) <specs-repo> PR (in-repo record  -  optional)

Place the canonical set under `localizations/<slug>/` and open an additive PR:
```bash
SLUG=sign-up-account-details
DST="$SPECS/localizations/$SLUG"; mkdir -p "$DST"
cp "$OUT/$SLUG".{md,confluence.xml} "$OUT/$SLUG.overlay.png" "$OUT/screenshot.png" \
   "$OUT/$SLUG.keyshots.manifest.json" "$DST"/ 2>/dev/null
[ -d "$OUT/keyshots" ] && cp -R "$OUT/keyshots" "$DST"/   # per-key screenpieces (md embeds them relatively)
cd "$SPECS" && git switch -c "loc-map/$SLUG" \
  && git add "localizations/$SLUG" \
  && git commit -m "localizations: $SLUG reuse map" \
  && git push -u origin "loc-map/$SLUG" \
  && gh pr create --title "Localization reuse map  -  $SLUG" \
       --body "Generated by the localization-reuse-map skill; screenshot + overlay included." --fill
```
- The `.md` is the human-readable map (images embedded by filename  -  keep the PNGs beside it so they render
  on GitHub). The `.confluence.xml` is the storage-format payload Confluence consumes.
- **Merge policy:** additive (new files under `localizations/`) → auto-/admin-merge cleanly.
- Need a file for the content team? Re-run `build-artifact.py` with `--docx` / `--pdf` / `--all` (CMS columns
  + overlay embedded). Keep these heavy binaries **out** of the PR  -  share them directly.

## Guardrails
- **Additive only.** This flow creates files under `localizations/` and `resources/`; it never edits
  legacy source, `design-export/`, or `specs/`.
- The `resources/` snapshot is **generated, not authored**  -  never hand-edit it; refresh it from
  `<resources-repo>` (its source of truth), same as `design-export/` is refreshed from Figma.
