> ## 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.

# Project Structure and Sources of Truth

> Understand where The Living Index stores default content, Studio overrides, generated scene source, uploads, runtime code, skills, tests, and deployment configuration.

The Living Index 将模板默认值、个人覆盖、发布场景源码和二进制资源分开保存。理解这些层级可以避免“本地预览正确，但提交或生产不一致”。

The Living Index separates template defaults, personal overrides, generated scene source, and binary resources. Understanding these layers prevents local previews from diverging from committed or production behavior.

## Repository map / 仓库结构

```text theme={null}
.
├── app/
│   ├── page.tsx
│   ├── layout.tsx
│   ├── RoomExperience.tsx
│   ├── ContentStudio.tsx
│   ├── SceneStudio.tsx
│   ├── ContentCardEditor.tsx
│   ├── AboutProfileModule.tsx
│   ├── PhotographyGallery.tsx
│   ├── ModelUploadField.tsx
│   ├── ImageUploadField.tsx
│   ├── content-config.ts
│   ├── content-draft.ts
│   ├── model-loading.ts
│   ├── scene-placement.ts
│   ├── solar-lighting.ts
│   ├── portfolio-data.ts
│   ├── portfolio-data-en.ts
│   └── generated/
│       └── scene-config.ts
├── build/
│   └── content-studio-vite-plugin.ts
├── public/
│   ├── content/
│   │   └── site-content.json
│   └── uploads/
│       ├── profile/
│       ├── photography/
│       ├── cards/
│       └── models/
├── .content-studio-cache/
│   └── models/
├── skills/
│   ├── living-index-content/
│   ├── living-index-scene/
│   ├── living-index-native-assets/
│   └── living-index-developer/
├── tests/
├── worker/
│   └── index.ts
├── .github/workflows/deploy.yml
├── AGENTS.md
├── ASSET_CREDITS.md
├── package.json
├── vite.config.ts
└── wrangler.jsonc
```

## Source-of-truth table / 事实源

| Concern                                       | Source of truth                                |
| --------------------------------------------- | ---------------------------------------------- |
| Schema, limits, normalization                 | `app/content-config.ts`                        |
| Default Chinese content                       | `app/portfolio-data.ts`                        |
| Default English content                       | `app/portfolio-data-en.ts`                     |
| Personal content and scene authoring document | `public/content/site-content.json`             |
| Published scene snapshot                      | `app/generated/scene-config.ts`                |
| Content and scene UI                          | `app/ContentStudio.tsx`, `app/SceneStudio.tsx` |
| Three.js runtime and semantic index           | `app/RoomExperience.tsx`                       |
| Author-timezone lighting                      | `app/solar-lighting.ts`                        |
| Drag-placement transaction                    | `app/scene-placement.ts`                       |
| Local save/upload/GLB validation              | `build/content-studio-vite-plugin.ts`          |
| Agent workflows                               | `AGENTS.md`, `skills/`                         |
| Executable contracts                          | `tests/`                                       |
| Release pipeline                              | `.github/workflows/deploy.yml`                 |

## How content loads / 内容加载顺序

```mermaid theme={null}
flowchart LR
  A["portfolio-data*.ts defaults"] --> D["Merged content"]
  B["site-content.json overrides"] --> D
  C["generated/scene-config.ts"] --> E["Published scene"]
  D --> F["RoomExperience"]
  E --> F
  G["?studio=1 browser draft"] --> F
```

The default TypeScript data provides a complete starting point. JSON overrides only the fields you author. For production scene state, the runtime overlays `PUBLISHED_SCENE_CONFIG` from the generated module.

默认 TypeScript 数据提供完整起点，JSON 只覆盖你编辑的字段。生产场景会使用生成模块中的 `PUBLISHED_SCENE_CONFIG`。

Only `?studio=1` may then overlay `living-index.content-draft.v1` for unsaved authoring. Normal routes ignore the browser draft.

只有 `?studio=1` 会再覆盖未保存的 `living-index.content-draft.v1`。普通路由忽略浏览器草稿。

## Save outputs / 保存产物

**Save to project** treats these as one change:

1. normalized `public/content/site-content.json`;
2. deterministically generated `app/generated/scene-config.ts`;
3. final referenced GLBs promoted to `public/uploads/models`;
4. reference-aware removal of superseded published GLBs;
5. cleanup of remaining staged GLBs.

Do not hand-edit the generated scene file. If you manually replace only the JSON, scene changes are not a complete release and the consistency test should fail.

不要手工修改生成场景文件。只手工替换 JSON 不是完整的场景发布，一致性测试应阻止它。

## Upload directories / 上传目录

| Directory                      | Ownership                                                   |
| ------------------------------ | ----------------------------------------------------------- |
| `public/uploads/profile`       | Profile images written immediately                          |
| `public/uploads/photography`   | Photography images written immediately                      |
| `public/uploads/cards`         | Content-card images written immediately                     |
| `.content-studio-cache/models` | Uncommitted local GLB previews                              |
| `public/uploads/models`        | GLBs confirmed by **Save to project**                       |
| `public/models`                | Optional manually coded assets; not the Studio-managed path |

Image unlinking does not remove the stored image. GLB cleanup is reference-aware and automatic at the Studio save boundary.

解除图片引用不会删除图片文件；GLB 则在 Studio 保存边界执行精确引用清理。

## Runtime modules / 运行时模块

* `RoomExperience.tsx` creates one renderer, room geometry, asset runtimes, hitboxes, markers, routes, and the semantic index.
* `model-loading.ts` retains a prepared upload buffer so the first preview can avoid an immediate second request.
* `scene-placement.ts` keeps plane, height, and heading previews separate from confirmed config.
* `solar-lighting.ts` resolves IANA/fixed-offset time and calculates the stylized light state.
* `AboutProfileModule.tsx` renders portrait, bio, and social buttons.
* `PhotographyGallery.tsx` renders every photo, the Spotlight editorial block, and instant-photo dialog.

## Agent-native extension / Agent 原生扩展

Read root `AGENTS.md` before code changes. It routes work to the repository skills for content, scene composition, native Three.js assets, or cross-layer framework changes.

代码改动前先阅读根目录 `AGENTS.md`。它会根据内容、场景、原生 Three.js 资产或跨层框架任务选择对应 skill。

See [Agent-native development](/development/agent-native).