> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acondawayuno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Customize and Publish

> Run The Living Index locally, customize content and scene layout, save generated project artifacts, validate, and publish through GitHub Actions.

## Prerequisites / 准备

* Node.js `>=22.13.0`
* npm
* Git
* A cloned fork or copy of `ACondaway/HOME-3D`
* Cloudflare secrets already configured in GitHub for automatic deployment

## 1. Install and run / 安装与启动

```bash theme={null}
git clone https://github.com/ACondaway/HOME-3D.git
cd HOME-3D
npm install
npm run dev
```

使用终端打印的 URL。端口 3000 被占用时，开发服务器可能自动改用 3001。

Use the URL printed in the terminal. If port 3000 is occupied, the server may select 3001.

```text theme={null}
http://localhost:3000/?studio=1
```

保存和上传接口只存在于本地 Vite 开发服务器，并接受 loopback host/origin，例如 `localhost`、`127.x.x.x` 和 `::1`。

Save and upload endpoints exist only in the local Vite server and accept loopback hosts/origins such as `localhost`, `127.x.x.x`, and `::1`.

## 2. Customize profile and content / 编辑资料与内容

In **Profile**:

* replace display name and intro copy;
* set the city;
* set the author's IANA timezone or `GMT`/`UTC` fixed offset.

In **Digital assets**:

* edit Chinese and English separately;
* configure mirror bio, portrait, alt text, and social buttons;
* upload every camera-page photo and choose one Spotlight;
* add text, media, or links cards.

All photos remain visible. Clicking any photo opens its instant-photo dialog. Spotlight adds ordering and a dedicated editorial column; it does not hide the other photos.

所有照片都会展示。Spotlight 只增加排序与专属文字栏，不会隐藏其他照片。

## 3. Compose the scene / 编辑场景

In **Scene layout** you can:

* move, rotate, and scale built-ins;
* disable a built-in and reactivate it later;
* replace only a built-in's visual with a GLB;
* add custom decorative or interactive GLBs;
* edit interactive custom content with the same card system.

Drag placement has three modes:

| Mode    | Effect                              |
| ------- | ----------------------------------- |
| Plane   | X and Z                             |
| Height  | Y                                   |
| Heading | Y-axis rotation; Shift snaps to 15° |

Scale remains a numeric control.

<Warning>
  拖动结果只是 placement preview。点击 **Confirm placement** 后才进入 Studio 草稿；完成或取消当前摆放后，才能保存、导入、导出或复制 JSON。

  A drag is only a placement preview. It enters the Studio draft after **Confirm placement**. Finish or cancel the placement before saving, importing, exporting, or copying JSON.
</Warning>

## 4. Understand uploads / 理解上传

Images write immediately to:

```text theme={null}
public/uploads/profile
public/uploads/photography
public/uploads/cards
```

GLBs first stage in:

```text theme={null}
.content-studio-cache/models
```

They preview through their future `/uploads/models/<uuid>.glb` URL. Only models still referenced when you click **Save to project** move into `public/uploads/models`.

GLB 会先以未来 URL 进行预览；只有保存时仍被引用的模型才进入 `public/uploads/models`。

## 5. Save to the repository / 保存到代码仓库

**Save to project** performs one local transaction:

```text theme={null}
public/content/site-content.json
app/generated/scene-config.ts
public/uploads/models/<final-referenced-models>
```

It also clears uncommitted staged models and removes only previously saved GLBs that the new saved scene no longer references.

它还会清空未提交暂存，并只删除“上一份保存场景引用、下一份不再引用”的已发布 GLB。

<Note>
  The browser draft `living-index.content-draft.v1` exists only for `?studio=1`. Normal published routes ignore it. **Reset draft** returns Studio to the published state.

  浏览器草稿只服务 `?studio=1`。普通发布路由忽略它；**Reset draft** 会让 Studio 回到已发布状态。
</Note>

## 6. Validate / 验证

```bash theme={null}
npm run typecheck
npm run lint
npm test
git diff --check
```

Manually check:

* Chinese and English content;
* portrait and social icons;
* every photo and Spotlight;
* plane, height, and heading placement;
* decorative assets cannot open content;
* interactive assets work through both 3D and the semantic index;
* imported PBR GLBs respond to day/night lighting;
* a normal route without `?studio=1` matches committed content.

## 7. Commit and publish / 提交与发布

```bash theme={null}
git status --short
git add public/content/site-content.json app/generated/scene-config.ts
git add public/uploads/<specific-files-used-by-this-change>
git diff --cached --check
git commit -m "Customize content and scene"
git push origin main
```

GitHub Actions runs validation and deploys the Cloudflare Worker. Do not use a direct local deployment for routine updates.

GitHub Actions 会完成验证与 Cloudflare Worker 部署。日常更新不要直接从本机部署。

## Import and export / 导入与导出

JSON import/export does not include image or GLB binaries and does not regenerate scene source by itself. To migrate content:

1. copy the referenced uploads;
2. import JSON in a local `?studio=1`;
3. click **Save to project**;
4. validate and commit all resulting files together.

JSON 导入/导出不是完整备份。它不包含二进制资源，也不会单独生成场景源码。