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

# Develop The Living Index with Coding Agents

> Use the repository's open skills to customize content, compose scenes, generate native Three.js assets, and extend the framework without losing accessibility or deployment guarantees.

The Living Index 是一个 agent-native 代码框架：仓库不仅提供可视化 Content Studio，也提供面向 coding agent 的开放技能、事实源映射、测试契约和交付规则。

The Living Index is an agent-native framework. Alongside the visual Content Studio, the repository includes open coding-agent skills, source-of-truth maps, executable contracts, and release rules.

## Start with `AGENTS.md`

仓库根目录的 `AGENTS.md` 会根据任务把 agent 路由到最小的相关 skill：

The root `AGENTS.md` routes an agent to the smallest relevant skill:

| Skill                         | 适用任务 / Use it for                                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `$living-index-content`       | 个人资料、镜子页照片与社交链接、摄影与 Spotlight、内容卡片 / Profile, mirror portrait and social links, photography, Spotlight, and content cards       |
| `$living-index-scene`         | 作者时区光照、物件移动、GLB、停用/替换、装饰与交互行为 / Author-timezone lighting, placement, GLBs, disable/replace, decorative and interactive behavior |
| `$living-index-native-assets` | 直接用 Three.js 生成简单家具、灯具、标牌和装饰 / Generate simple furniture, lamps, signs, and props directly with Three.js                        |
| `$living-index-developer`     | 新字段、模块、交互、路由、跨层能力和发布级改动 / New fields, modules, interactions, routes, cross-layer capabilities, and release-ready changes        |

这些 skill 位于 `skills/`，随 MIT 许可一起开源，可以阅读、复制和改进。

These skills live in `skills/` and are open source under the repository's MIT license. You can inspect, copy, and improve them.

## Choose Studio, GLB, native code, or framework work

```mermaid theme={null}
flowchart TD
  A["What are you changing?"] --> B{"Content or existing layout?"}
  B -->|Yes| C["Content Studio"]
  B -->|No| D{"Complex textured 3D form?"}
  D -->|Yes| E["GLB workflow"]
  D -->|No| F{"Simple visual prop?"}
  F -->|Yes| G["Native Three.js skill"]
  F -->|No| H["Developer skill / cross-layer change"]
```

* 使用 Content Studio 完成日常文案、图片、社交链接、卡片、已有物件位置和 GLB 配置。 / Use Content Studio for routine copy, images, social links, cards, existing placement, and GLB configuration.
* 使用 GLB 表达复杂拓扑、UV 纹理或来自 Blender 的资产。 / Use GLB for complex topology, UV textures, or Blender-authored assets.
* 使用原生 Three.js 表达简单、轻量且应立即加载的场景物件。 / Use native Three.js for simple, lightweight objects that should load immediately.
* 只有新能力跨越 schema、editor、runtime、semantic index、routes 和 tests 时，才进入框架开发。 / Enter framework development when a capability spans schema, editor, runtime, semantic index, routes, and tests.

## Prompt with product intent / 用产品意图描述任务

告诉 agent 物件的用途，而不只是文件操作：

Describe the product intent, not only the file operation:

```text theme={null}
Use $living-index-scene to add this GLB as a decorative object.
Place it beside the camera, keep it out of the semantic index, and verify
that Save to project generates the published scene source.
```

```text theme={null}
Use $living-index-content to add a bilingual photography series.
Keep every photo visible, make one Spotlight, and add accessible alt text.
```

```text theme={null}
Use $living-index-native-assets to generate a small ceramic floor lamp.
It should react to day/night lighting and must not open a content page.
```

## Cross-layer invariants / 跨层约束

任何 agent 改动都应保留：

Every agent change should preserve:

* 中英文内容的有意对齐。 / Intentional Chinese and English parity.
* 空间交互对应的语义索引与键盘路径。 / A semantic index and keyboard path for every spatial interaction.
* reduced motion、WebGL failure 和 `noscript` 降级。 / Reduced-motion, WebGL-failure, and `noscript` fallbacks.
* loopback-only 的保存与上传接口。 / Loopback-only save and upload endpoints.
* JSON、生成场景源码和最终上传资源的一致提交。 / One consistent change set for JSON, generated scene source, and final uploads.
* 第三方资产在 `ASSET_CREDITS.md` 中的来源与许可记录。 / Third-party provenance and licence records in `ASSET_CREDITS.md`.

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

| 关注点 / Concern       | Source                                              |
| ------------------- | --------------------------------------------------- |
| 内容 schema、限制与 merge | `app/content-config.ts`                             |
| 中英文默认章节             | `app/portfolio-data.ts`, `app/portfolio-data-en.ts` |
| 发布内容                | `public/content/site-content.json`                  |
| 发布场景快照              | `app/generated/scene-config.ts`                     |
| 编辑器                 | `app/ContentStudio.tsx`, `app/SceneStudio.tsx`      |
| Three.js 运行时        | `app/RoomExperience.tsx`                            |
| 光照与摆放事务             | `app/solar-lighting.ts`, `app/scene-placement.ts`   |
| 本地保存、上传与 GLB 校验     | `build/content-studio-vite-plugin.ts`               |
| 可执行契约               | `tests/`                                            |

<Warning>
  不要手工修改 `app/generated/scene-config.ts`。请在本地 `?studio=1` 中编辑并点击 **Save to project**，让 JSON、场景源码和 GLB 生命周期保持同步。

  Do not hand-edit `app/generated/scene-config.ts`. Edit through local `?studio=1` and use **Save to project** so JSON, generated scene source, and the GLB lifecycle stay synchronized.
</Warning>

## Validate and publish / 验证与发布

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

然后只暂存本次变更涉及的具体路径，提交并推送。`main` 分支上的 GitHub Actions 负责质量检查和 Cloudflare Worker 部署；普通开发流程不要绕过 CI 直接部署。

Then stage only the exact paths changed, commit, and push. GitHub Actions on `main` owns validation and Cloudflare Worker deployment. Do not bypass CI with a direct deployment in the normal workflow.