# Moving the local Area Guide content to production (site bundle, 2026-11-03)

**Written for:** whoever runs the production deploy. You do not need to know how the content was
made. You need shell access to a production app server, and the production `.env` that writes
the shared catalogue (`master_projects`) and the production bucket (`petav3-prod`).

The content was built on a developer machine. It went into that machine's own Area Guide
database and the **dev** bucket (`petav3-dev`). Nothing on production has been touched. This
runbook moves it across, adding only what production lacks.

---

## What travels, and what does not

The bundle is `site-20261105.zip`. It is **not in the repository**: with the narration it is too
large for git, so the developer hands it over and step 2 copies it to the server. Unzipped, it is
a folder holding `manifest.json`, `files/` and `catalogue-reference/`. Its contents were counted against a
read-only snapshot of production taken on 2026-11-03.

| Content | In the bundle | What the import does on production |
| --- | --- | --- |
| Countries / regions | 4 / 7 | Adds **Singapore** and its **singapore-central** region. The other 3 countries and 6 regions already exist and are kept. |
| Areas | 39 | Adds the **15** that production lacks: 13 new KL & Selangor areas (Kampung Baru, Chan Sow Lin, Cheras, Sri Hartamas, Dutamas, Damansara Heights, Kwasa Damansara, Damansara Perdana, Ara Damansara, Bukit Jalil, Jalan Puchong, PJ South, Bandar Sunway) plus Marina Bay and Orchard. The **24** that exist keep their story and pictures. The only exception: an existing area with **no picture at all** gets the bundle's cover photo (see below). |
| Pictures (area covers, building-tab photos) | 89 | Uploaded once each, and only when something being added uses them. A picture of the same country and name that already exists is reused. |
| Custom buildings + their tabs | 21 | Added. A building of the same country and name that already exists is kept as it is. |
| **3D building models + files** | **75** (≈ 47 MB, Meshopt-compressed) | Added with their map placements (position, heading, height, scale) and published state. A model of the same country and title that already exists is kept, **position included**: the 2026-11-05 placement pass reaches production only for models the import adds. The plan's `keep` lines name the ones it does not; move those in the map editor if wanted. |
| Panoramas | — | **Not carried.** The 4 local panoramas were drafts of ones production already has. |
| 44 custom buildings that no model uses | — | Not carried. They stay on the developer machine. |
| Catalogue edits for 15 projects | `catalogue-reference/` only | **Never imported.** See step 7. |

Every link inside the bundle is by natural key (an area's `key`, a building's name, a model's
title), never by the developer machine's ids. Pictures travel as `{{avatar:…}}` tokens, which
the import replaces with production's own ids. So a building-tab photo points at the copy
uploaded to production, with production's `?v=` version.

**Covers on existing areas:** the import only fills an area that has no picture at all.
Bangsar South and any area someone gave a picture on production are left alone. Expect up to
23 `cover` lines in the plan.

---

## 0 · Before you start

- [ ] **Back up the Area Guide tables** of `master_projects`. The import only adds rows, but this
      backup is the rollback:
      ```bash
      mysqldump <connection options> master_projects $(mysql <connection options> -N -e "SHOW TABLES FROM master_projects LIKE 'area\_guide\_%'" | tr '\n' ' ') > area_guide_before_bundle.sql
      ```
- [ ] Pick a quiet time. The apply takes a few minutes, mostly uploading ≈ 60 MB to the bucket.

## 1 · Deploy the code first

The import needs the code from branch **`dev-zihan-2`**. It brings the import command itself,
Meshopt/Draco support in the upload rule and in the map's loader, and two migrations.

```bash
sudo bash scripts/deploy-update.sh      # the usual deploy, with the commit that has area-guide:import-bundle
# deploy-update.sh runs the SITE migrations only. The Area Guide tables live in the shared
# catalogue (master_projects), whose migrations are a separate directory:
php artisan migrate --path=database/migrations/catalogue --database=catalogue
```

That second command adds `area_guide_link_logs` and `area_guide_buildings.panorama_asset_id`.
It is safe to repeat.

⚠️ **The order matters.** On older code the import refuses every model, and the map would also
refuse to draw a Meshopt model. The dry run below says so in its `refuse` lines.

Leave `AREA_GUIDE_SIGNED_MEDIA` unset (`false`). Signed delivery is a separate change that waits
on the bucket's CORS.

## 2 · Unzip the bundle

Copy the zip to the server (`scp`, or a private bucket), then unzip it outside the app directory:

```bash
unzip -q site-20261105.zip -d /tmp      # → /tmp/site-20261105/manifest.json
```

The import checks every file's SHA-256 against the manifest and refuses a damaged copy.

## 3 · Dry run (writes nothing)

```bash
php artisan area-guide:import-bundle /tmp/site-20261105
```

Read the plan. Each line starts with one of these words:

| Word | Meaning |
| --- | --- |
| `add` | will be created |
| `cover` | an existing area with no picture gets the bundle's cover |
| `keep` | production already has it; untouched |
| `skip` | cannot be added yet (e.g. its catalogue project is missing); re-run later |
| `refuse` | this site's upload rule rejects the model file; the code is too old (step 1) |

⚠️ **`site-20261105` needs `--stories` on every import command in steps 3 to 5**, or the existing
areas keep their old words and their narration is skipped. See step 6b first.

The last line is the summary. With `--stories`, the 2026-11-05 rehearsal on a scratch database
read about **`story 12 · add 113 · picture add ≈ 161`**, with no `refuse` and no `skip`.
Different numbers mean production changed since then. That is fine as long as each line makes
sense.

## 4 · Apply

```bash
php artisan area-guide:import-bundle /tmp/site-20261105 --apply
```

The import continues past a single failure. It names the failure at the end and exits
non-zero, and any file that failure had already uploaded is removed again. Fix the cause,
then run the same command again. It is **re-runnable**: whatever was added the first time
shows as `keep`.

## 5 · Check

Run the dry run again. Every line should now be `keep` (or `skip`, see step 7).

```bash
php artisan area-guide:import-bundle /tmp/site-20261105
```

Then check the result in a browser:

- `/manage/area-guide/map`: KL & Selangor lists the new areas, each with a photo. KLCC shows its
  3D towers at street zoom.
- `/manage/area-guide/models`: 75 more models; green = project building, black = custom building.
- The member map (`/property/academy/area-guide/explore`): one click on a model shows its card.
  View details opens its page.

## 6 · Narration for the new areas (paid, optional)

New areas have their words but no rendered voice. Each area is a paid provider call per
chapter and language:

```bash
php artisan area-guide:narrate --area=kampung-baru     # repeat per new area you want voiced
```

## 6b · Stories and narration (bundles exported from 2026-11-05)

A bundle of format 2 also carries each area's rewritten story and the rendered narration. Add
`--stories` to the dry run and the apply in steps 3 to 5:

```bash
php artisan area-guide:import-bundle /tmp/site-<date> --stories          # dry run
php artisan area-guide:import-bundle /tmp/site-<date> --stories --apply
```

- **What it replaces:** each existing area's chapters (words and cameras). The plan shows these as
  `story` lines. Back up first (step 0): this is the one part of the import that overwrites.
- **What it keeps:** a chapter's pictures if it already has any, a traced boundary, a saved view,
  and the area's position.
- **Narration:** a file is stored only where the chapter's words match the words it was rendered
  from. A mismatch prints as `skip`; re-render that chapter with
  `php artisan area-guide:narrate --area=<key> --chapter=<n> --force`, a paid provider call.
- **Without `--stories`:** existing areas keep their words, so their narration prints as `skip`.

⚠️ **This bundle does not fit in git.** With narration it is several hundred MB, and GitHub refuses
files over 100 MB. Copy the zip to the server directly (`scp`, or a private bucket), then unzip it
as in step 2. The import checks every file's SHA-256 and refuses a damaged copy.

**Editing a story on production after this** leaves its voice reading the old words: nothing
detects that. Re-render the chapter you changed.

## 7 · The 15 catalogue projects (catalogue team)

15 of the models are **project buildings** whose catalogue projects are **unpublished on
production**. They import normally, but members only see them once those projects are
published. Their content was completed on the developer machine: a description, merged floor
plans, and photos with credits. It is in `catalogue-reference/projects.json`, with the photos
in `catalogue-reference/photos/`.

This is **reference material, not an import**. A catalogue project is published only through
its publish review (an initiator, two reviewers and an approver), so a catalogue editor enters
it in the catalogue admin and submits the review there. Once a project is approved, its model
appears on the member map by itself. Nothing needs re-running.

## Rollback

There is no undo command; the import only adds. To take it all back, restore the backup from
step 0. Uploaded objects then become orphans in the bucket. To remove a single model or
building instead, delete it in the map editor.

---

## How this was tested (2026-11-03, developer machine)

1. **Export:** `php artisan area-guide:export-bundle` on the developer machine: 39 areas,
   89 pictures, 21 buildings, 75 models.
2. **A production stand-in:** an empty database migrated with the Area Guide migrations and
   seeded with `area-guide:import-registry`, the same way production was seeded. That gives
   3 countries, 6 regions and 24 areas with production's keys but different uuids. Media were
   written to a local disk, not a bucket.
3. **Dry run, apply, dry run again:**
   - The apply added everything above with no failure.
   - All 75 models matched the source field by field: published state, project link, landmark
     flag, placement and file size.
   - All 50 building-tab photos resolved to the new pictures with matching `?v=`.
   - 38 of 39 areas had a picture; JVC has none in the source either.
   - The second dry run reported `keep 146`.
4. **Automated test:** `AreaGuideMapAssetsTest::test_a_site_bundle_carries_models_buildings_and_pictures_to_another_site_once`.

## Files

- `app/Console/Commands/ExportAreaGuideBundle.php`: builds the folder and zip (developer machine).
- `app/Console/Commands/ImportAreaGuideBundle.php`: the dry run and the apply (production).
- The single-area tools these follow: `area-guide:export-area` / `import-area`
  ([area-guide-bangsar-south-deploy.md](area-guide-bangsar-south-deploy.md)).
