feat: initialize project structure for Objectverse Diary

- Add .env.example for environment variables configuration.
- Create .gitignore to exclude sensitive files and directories.
- Introduce AGENTS.md for project overview and goals.
- Establish README.md with project description and current status.
- Set up data directories with README files for examples, training, evaluation, and traces.
- Document project overview, PRD, tech architecture, dev schedule, hackathon guide, dev guidelines, and submission guide in respective markdown files.
- Create a template for README and field notes.
- Add model card for future model documentation.
- Initialize scripts directory for planned automation scripts.
- Set up source directory with planned areas for application code.
- Add README files in each source subdirectory to outline planned components and current status.
- Create pyproject.toml and requirements.txt for project dependencies.

.codex/project.md

@@ -0,0 +1,32 @@
+# Objectverse Diary
+
+## Context
+
+Objectverse Diary is a Build Small Hackathon project for the "An Adventure in Thousand Token Wood" track.
+
+Core idea: upload an everyday object photo, identify the object, generate a hidden persona, write a first-person secret diary, support follow-up chat, and create a shareable personality card.
+
+## Non-Negotiable Constraints
+
+- Total model parameters <= 32B.
+- Gradio is required.
+- Final app must be hosted on Hugging Face Space.
+- No commercial cloud model APIs.
+- UI is English-first and Chinese-second.
+- Do not expose credit codes, tokens, credentials, or private paths.
+
+## MVP Priority
+
+1. Image upload.
+2. Object recognition JSON.
+3. Persona generation JSON.
+4. Secret diary output.
+5. Object chat.
+6. Share card.
+7. Trace logger.
+8. Gradio UI polish.
+9. README and demo materials.
+
+## Current Status
+
+Structure-only initialization. No application implementation code has been added yet.

.codex/skills/dataset-trace/SKILL.md

@@ -0,0 +1,31 @@
+# Dataset And Trace Skill
+
+Use this when creating training data, sample outputs, traces, or public reproducibility materials.
+
+## Dataset Rules
+
+- Use synthetic or authorized examples only.
+- Do not include personal sensitive data.
+- Keep raw images separate from public traces.
+- Target 200-500 training samples.
+- Manually select at least 50 high-quality examples.
+
+## Trace Rules
+
+- Public traces must be anonymized.
+- Trace JSON should show model decisions clearly enough for judges and builders to understand the pipeline.
+- Target at least 6 public traces for example objects.
+
+## Expected Trace Contents
+
+- object input metadata
+- personality mode
+- object understanding JSON
+- persona JSON
+- diary output
+- model/runtime metadata
+- fallback markers, if any
+
+## Current Status
+
+No datasets or traces have been generated yet.

.codex/skills/gradio-ui/SKILL.md

@@ -0,0 +1,39 @@
+# Gradio UI Skill
+
+Use this when implementing or reviewing the Objectverse Diary Gradio interface.
+
+## Product Direction
+
+The UI should feel like a strange archive room for everyday objects, not a default Gradio demo.
+
+Recommended mood:
+
+- dark paper texture
+- amber highlights
+- typewriter diary output
+- museum labels
+- mysterious but polished object archive
+
+## Layout
+
+Recommended structure:
+
+1. Object Intake
+2. Object File
+3. Secret Diary
+4. Chat With Object
+5. Share Card
+6. Trace Export
+
+## Requirements
+
+- Use `gr.Blocks` as the main app structure.
+- English-first, Chinese-second.
+- Main components should have `elem_id` or `elem_classes`.
+- Custom CSS belongs in `src/ui/styles.css`.
+- UI copy belongs in `src/ui/copy.py`.
+- Must work at 1366px desktop width and mobile width.
+
+## Current Status
+
+No UI implementation yet.

.codex/skills/hf-space/SKILL.md

@@ -0,0 +1,36 @@
+# Hugging Face Space Skill
+
+Use this when preparing the Hugging Face Space deployment.
+
+## Requirements
+
+- SDK must be Gradio.
+- `app_file` should point to `app.py` once implementation starts.
+- README should document model choices, parameter counts, fallback strategy, and badge evidence.
+- Do not expose secrets, private paths, credit codes, or tokens.
+
+## Planned README Header
+
+```yaml
+---
+title: Objectverse Diary
+emoji: 🗝️
+colorFrom: amber
+colorTo: gray
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+```
+
+## Deployment Checks
+
+- App launches locally.
+- App launches on HF Space.
+- Demo examples work without private assets.
+- README links are valid.
+- No commercial model APIs are required.
+
+## Current Status
+
+Deployment has not started.

.codex/skills/model-runtime/SKILL.md

@@ -0,0 +1,28 @@
+# Model Runtime Skill
+
+Use this when implementing or reviewing model runtime code.
+
+## Planned Layers
+
+- Vision Runner: object recognition and visible feature extraction.
+- Text Runner: persona, diary, and chat generation through llama.cpp / llama-cpp-python.
+- Schema: structured validation for object, persona, diary, and trace outputs.
+
+## Requirements
+
+- No commercial cloud AI APIs.
+- Text generation should support a local llama.cpp path.
+- Output must be structured JSON before rendering.
+- Invalid JSON should trigger repair or fallback behavior.
+- Total model parameters must remain <= 32B.
+- Model parameter counts must be documented in README and model card.
+
+## Fallback Strategy
+
+- VLM failure: manual object description or example gallery path.
+- Text model failure: safe template fallback.
+- JSON failure: repair, validate, and expose trace information.
+
+## Current Status
+
+No runtime implementation yet.

.codex/skills/submission/SKILL.md

@@ -0,0 +1,43 @@
+# Submission Skill
+
+Use this when preparing final hackathon submission materials.
+
+## Required Links
+
+- Hugging Face Space URL
+- GitHub Repository URL
+- Demo Video URL
+- Social Media Post URL
+- Fine-tuned Model URL
+- Dataset URL
+- Trace Dataset URL
+- Field Notes Blog URL
+- Short project description
+
+## Demo Video Flow
+
+Recommended length: under 2 minutes.
+
+1. Hook: every object has a secret life.
+2. Upload and personality mode selection.
+3. Model recognition and persona generation.
+4. Secret diary and chat.
+5. Share card.
+6. Badge checklist and technical stack.
+
+## Final Checklist
+
+- Space under official organization.
+- README complete.
+- Model parameter counts documented.
+- No commercial cloud AI APIs.
+- Fine-tuned model linked.
+- Dataset linked.
+- Traces linked.
+- Field Notes linked.
+- UI English-first, Chinese-second.
+- Submitted before June 15, 2026.
+
+## Current Status
+
+Submission materials have not started.

.env.example

@@ -0,0 +1,9 @@
+# Copy this file to .env only when implementation starts.
+# Never commit real credentials, credit codes, tokens, or private paths.
+
+HF_SPACE_ID=
+HF_MODEL_REPO=
+HF_DATASET_REPO=
+TEXT_MODEL_PATH=
+VISION_MODEL_ID=
+TRACE_OUTPUT_DIR=data/traces

.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Model and generated artifacts
+models/
+*.gguf
+*.safetensors
+*.ckpt
+*.pt
+*.pth
+
+# Generated traces and exports
+data/traces/*.json
+data/traces/*.jsonl
+exports/
+
+# System files
+.DS_Store

AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md
+
+## Project
+
+Objectverse Diary is a Build Small Hackathon project.
+It is an English-first, Chinese-second Gradio application where users upload everyday object photos and small AI models generate secret object personas, diary entries, conversations, and shareable cards.
+
+## Primary Goals
+
+1. Compete in the "An Adventure in Thousand Token Wood" track.
+2. Keep total model parameters <= 32B.
+3. Use Gradio for all UI and interaction.
+4. Host the final app as a Hugging Face Space.
+5. Avoid commercial cloud AI APIs.
+6. Maximize hackathon badges.
+7. Use English as the main UI language and Chinese as secondary helper text.
+
+## Non-Negotiable Rules
+
+- Do not use OpenAI, Anthropic, Gemini, Cohere, or other commercial model APIs.
+- Do not leak private credit codes, tokens, emails, or credentials.
+- Do not hardcode secrets.
+- Do not remove Gradio.
+- Do not make the UI Chinese-first.
+- Do not exceed the 32B total model parameter limit.
+- Do not add large features that risk missing the submission deadline.
+- Do not store unconsented personal user data.
+
+## Tech Stack
+
+- Python
+- Gradio Blocks
+- Hugging Face Spaces
+- llama.cpp / llama-cpp-python for text generation
+- MiniCPM-V or fallback lightweight VLM for object understanding
+- LoRA / PEFT for fine-tuning
+- Markdown documentation
+
+## UI Requirements
+
+The interface must be English-first and Chinese-second.
+Visual style: strange object archive, not default Gradio demo.
+Recommended UI mood: mysterious archive, typewriter diary, warm dark paper, amber highlight, museum label, strange but polished.
+
+## Architecture
+
+1. Image upload
+2. Object understanding
+3. Persona generation
+4. Secret diary generation
+5. Object chat
+6. Share card rendering
+7. Trace export
+
+## Coding Guidelines
+
+- Use type hints.
+- Prefer small, composable functions.
+- Prompts belong under `src/prompts/`.
+- UI copy belongs under `src/ui/copy.py`.
+- CSS belongs under `src/ui/styles.css`.
+- Runtime code belongs under `src/models/`.
+- Trace code belongs under `src/traces/`.
+- Use Pydantic schemas for model outputs.
+- Add clear fallback behavior when model output is invalid.
+
+## Testing Requirements
+
+- App runs locally.
+- App runs on HF Space.
+- At least 6 sample objects work.
+- Share card renders correctly.
+- Trace export works.
+- No secret keys committed.
+- README links valid.
+- Demo video flow reproducible.
+
+## Current Initialization Boundary
+
+The current phase is structure-only. Do not add application implementation code until the implementation phase starts.

README.md

@@ -0,0 +1,69 @@
+# Objectverse Diary
+
+**Every object has a secret life.**
+**万物日记：每个物品都有秘密人生。**
+
+Objectverse Diary is a small-model AI toy built for the Build Small Hackathon.
+
+Upload a photo of any everyday object. The app wakes it up, gives it a secret personality, writes its diary, and lets you chat with it.
+
+## Current Status
+
+Project structure only. No application implementation code has been added yet.
+
+## Track
+
+An Adventure in Thousand Token Wood
+
+## Why This Fits the Track
+
+This is a pure digital experience that could not exist without AI:
+
+- vision understanding
+- object persona generation
+- first-person diary writing
+- consistent character chat
+- shareable personality cards
+
+## Language
+
+The interface is English-first and Chinese-second.
+
+## Badge Targets
+
+- [ ] Off the Grid
+- [ ] Well-Tuned
+- [ ] Off-Brand
+- [ ] Llama Champion
+- [ ] Sharing is Caring
+- [ ] Field Notes
+- [ ] OpenBMB Special
+
+## Planned Model Stack
+
+- Vision: MiniCPM-V or lightweight VLM fallback
+- Text: fine-tuned small LLM
+- Runtime: llama.cpp / llama-cpp-python
+- UI: Gradio Blocks
+
+## Run Locally
+
+Not available yet. `app.py` and runtime code will be added during the implementation phase.
+
+## Project Structure
+
+See `docs/02-tech-architecture.md`, `AGENTS.md`, and `.codex/skills/` for the intended structure and development rules.
+
+## HF Space README YAML Header
+
+```yaml
+---
+title: Objectverse Diary
+emoji: 🗝️
+colorFrom: amber
+colorTo: gray
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+```

data/README.md

@@ -0,0 +1,7 @@
+# Data
+
+This directory is reserved for examples, training data, evaluation samples, and anonymized traces.
+
+## Privacy Rule
+
+Do not store personal or sensitive data here. Public traces must be anonymized.

data/eval/README.md

@@ -0,0 +1,5 @@
+# Evaluation Data
+
+Reserved for evaluation examples and acceptance checks.
+
+Examples should cover cups, keyboards, shoes, and other everyday objects.

data/examples/README.md

@@ -0,0 +1,5 @@
+# Examples
+
+Reserved for public example objects and sample outputs.
+
+Target: at least 6 example objects for the demo gallery.

data/traces/README.md

@@ -0,0 +1,5 @@
+# Traces
+
+Reserved for anonymized public traces.
+
+Target: at least 6 public traces for the Sharing is Caring badge.

data/train/README.md

@@ -0,0 +1,5 @@
+# Training Data
+
+Reserved for SFT or LoRA training data.
+
+Target: 200-500 generated samples, with at least 50 manually selected high-quality samples.

docs/00-project-overview.md

@@ -0,0 +1,73 @@
+# Objectverse Diary — 项目概述
+
+> **Every object has a secret life.**
+> 万物日记：让身边物品开口讲出它的隐藏人格
+
+## 项目定位
+
+Objectverse Diary 是一个基于小模型的互动式 AI 数字玩具，参加 **Build Small Hackathon** 的 **赛道 2：An Adventure in Thousand Token Wood**。
+
+用户上传任意日常物品照片，AI 识别物品后，为它生成一个"隐藏人格"，再以第一人称写出一篇荒诞、幽默、带一点毒舌的 Secret Diary。用户可以继续追问这个物品，最后生成一张可分享的英文主视觉卡片，中文作为辅助翻译。
+
+## 一句话描述
+
+```text
+Objectverse Diary is a small-model AI toy that turns everyday objects into living characters
+with secret diaries, weird memories, and shareable personality cards.
+```
+
+中文辅助：
+
+```text
+Objectverse Diary 是一个小模型 AI 玩具：上传一个日常物品，它会拥有隐藏人格、秘密日记和可分享的人格卡片。
+```
+
+## 赛道匹配度
+
+| 官方评审点        | 对应设计                                                               |
+| ----------------- | ---------------------------------------------------------------------- |
+| 强吸引力 / 自传播 | 用户上传自己的杯子、键盘、鞋子、冰箱贴，得到荒诞人格卡，很容易截图分享 |
+| AI 是核心支撑     | 没有视觉识别 + 角色生成 + 多轮人格一致性，就无法成立                   |
+| 原创性            | 不是普通聊天，不是普通图像描述，而是"物品人格宇宙"                     |
+| Gradio 完成度     | 可以把 Gradio 魔改成复古档案馆 / 神秘博物馆 / 打字机日记界面           |
+| 小模型契合        | 任务是识图、短文生成、人格一致性、结构化输出，小模型足够               |
+| 视频演示强        | 30 秒内就能让评委理解并产生记忆点                                      |
+
+## 核心体验流程
+
+```text
+上传物品 → 选择人格模式 → AI 识别 → 生成物品人格 → 输出秘密日记 → 对话追问 → 生成分享卡片
+```
+
+详细步骤：
+
+1. User uploads an object photo
+2. User selects a personality mode
+3. VLM identifies the object
+4. Small LLM creates a structured object persona
+5. App renders a secret diary
+6. User asks follow-up questions
+7. App generates a shareable card
+8. Trace is saved anonymously
+
+## UI 语言规范
+
+**English-first, Chinese-second.**
+
+| 页面元素 | 英文主文案                | 中文辅助         |
+| -------- | ------------------------- | ---------------- |
+| Title    | Objectverse Diary         | 万物日记         |
+| Upload   | Upload an object photo    | 上传一个物品照片 |
+| Mode     | Choose a personality mode | 选择人格模式     |
+| Generate | Wake the object           | 唤醒这个物品     |
+| Output   | Secret Diary              | 秘密日记         |
+| Share    | Create share card         | 生成分享卡片     |
+| Trace    | View model trace          | 查看模型轨迹     |
+
+## 硬性约束
+
+- 模型总参数量 ≤ 32B
+- 必须基于 Gradio
+- 托管在 Hugging Face Space
+- 提交 Demo 视频和社交媒体文案
+- 截止时间：**June 15, 2026**

docs/01-prd.md

@@ -0,0 +1,133 @@
+# Objectverse Diary — PRD（产品需求文档）
+
+## 目标用户
+
+### Primary Users
+
+| 用户                 | 需求                                     |
+| -------------------- | ---------------------------------------- |
+| Hackathon judges     | 快速理解创意，看到 AI 必要性和技术完整度 |
+| AI builders          | 体验小模型也能做出有趣产品               |
+| Social media users   | 上传自己的物品，生成可截图分享的结果     |
+| Designers / creators | 获得有趣的角色设定、物品拟人灵感         |
+
+### Secondary Users
+
+| 用户                | 需求                           |
+| ------------------- | ------------------------------ |
+| 中文用户            | 通过中文辅助说明快速理解玩法   |
+| 设计师 / 文案创作者 | 用它做脑洞练习                 |
+| 教育 / 亲子场景     | 把物品拟人化，变成故事创作工具 |
+
+## 核心用户故事
+
+```text
+As a curious user,
+I want to upload a photo of an everyday object,
+so that I can discover its secret personality and diary.
+```
+
+```text
+As a judge,
+I want to understand within 30 seconds why AI is essential,
+so that I can evaluate originality and technical quality quickly.
+```
+
+```text
+As a builder,
+I want to see transparent traces and model decisions,
+so that I can learn from and reproduce the project.
+```
+
+---
+
+## MVP 功能
+
+### P0：必须完成
+
+| 功能               | 描述                     | 验收标准                                  |
+| ------------------ | ------------------------ | ----------------------------------------- |
+| Image Upload       | 用户上传物品图片         | 支持 JPG / PNG                            |
+| Object Recognition | 识别物品名称、材质、状态 | 输出结构化 JSON                           |
+| Persona Generation | 生成物品人格             | 至少包含 name、mood、backstory、complaint |
+| Secret Diary       | 生成第一人称日记         | 英文主输出，中文辅助翻译                  |
+| Chat with Object   | 用户可追问物品           | 角色保持一致                              |
+| Share Card         | 生成可截图结果卡片       | 包含标题、物品人格、3 个标签              |
+| Trace Logger       | 保存示例运行轨迹         | JSON 格式，可公开                         |
+| Gradio UI          | 完成可用界面             | 不像默认 Gradio                           |
+| README             | 完整说明                 | 包含模型、部署、徽章说明                  |
+| Demo Video         | 2 分钟内视频             | 讲清玩法 + 技术 + 勋章                    |
+
+### P1：强加分
+
+| 功能                    | 描述                                                 |
+| ----------------------- | ---------------------------------------------------- |
+| Personality Modes       | Cynical / Dramatic / Lonely / Philosopher / Romantic |
+| Bilingual Toggle        | English first / Chinese subtitle                     |
+| Advanced Model Panel    | temperature、top_p、seed                             |
+| Example Gallery         | 预置 6 个示例物品                                    |
+| Export Trace            | 一键保存 trace                                       |
+| Dataset Preview         | 展示部分训练样本                                     |
+| Local Mode Instructions | 本地 llama.cpp 运行说明                              |
+
+### P2：时间充足再做
+
+| 功能                | 描述             |
+| ------------------- | ---------------- |
+| Voice Reading       | 朗读日记         |
+| Multi-object Drama  | 多个物品互相吐槽 |
+| Poster Export PNG   | 下载结果卡片     |
+| Leaderboard         | 最奇怪物品排行榜 |
+| Daily Object Prompt | 今日物品挑战     |
+
+---
+
+## 输出内容设计
+
+### 识别结果 JSON
+
+```json
+{
+  "object": {
+    "name": "coffee mug",
+    "visible_features": ["white ceramic", "small crack", "coffee stain"],
+    "likely_context": "developer desk",
+    "confidence": 0.86
+  }
+}
+```
+
+### 人格设定 JSON
+
+```json
+{
+  "persona": {
+    "object_name": "coffee mug",
+    "character_name": "Mugworth the Overcaffeinated",
+    "mood": "tired but sarcastic",
+    "secret_fear": "being replaced by a stainless steel tumbler",
+    "core_memory": "witnessed 47 unfinished side projects",
+    "complaint": "I am not a personality substitute. I am ceramic.",
+    "tags": ["burnt optimism", "desk survivor", "caffeine witness"]
+  }
+}
+```
+
+### 日记输出示例
+
+```text
+Secret Diary — Day 417
+
+He filled me again before sunrise. No apology. No eye contact.
+Just another bitter liquid and the soft panic of a person
+pretending deadlines are a lifestyle...
+```
+
+中文辅助：
+
+```text
+秘密日记 — 第 417 天
+
+天还没亮，他又把我倒满了。没有道歉，没有眼神交流，
+只有苦咖啡和一个假装 deadline 是生活方式的人……
+```

docs/02-tech-architecture.md

@@ -0,0 +1,122 @@
+# Objectverse Diary — 技术架构
+
+## 系统架构
+
+```text
+Gradio UI
+  ↓
+Image Input
+  ↓
+MiniCPM-V / lightweight VLM
+  ↓
+Object Understanding JSON
+  ↓
+Fine-tuned small LLM via llama.cpp
+  ↓
+Persona + Diary JSON
+  ↓
+Renderer
+  ↓
+Diary View + Share Card + Trace Export
+```
+
+## 模型方案
+
+| 模块                 | 模型 / 工具                  | 目的                           |
+| -------------------- | ---------------------------- | ------------------------------ |
+| Vision Understanding | MiniCPM-V                    | 识别物品、外观、场景           |
+| Persona Writer       | Fine-tuned small LLM GGUF    | 生成人格、日记、对话           |
+| Runtime              | llama.cpp / llama-cpp-python | 冲 Llama Champion 勋章         |
+| UI                   | Gradio Blocks                | 官方硬性要求                   |
+| Hosting              | Hugging Face Space           | 官方硬性要求                   |
+| Training / Batch     | Modal                        | $250 Modal credits 做训练/批处理 |
+| Demo GPU             | HF ZeroGPU / upgraded Space  | 按需分配 GPU                   |
+
+> **注意**：MiniCPM-V 4.6 面向 edge deployment，基于轻量 LLM 架构，适合本项目需求。
+> ZeroGPU 是面向 Spaces 的动态 GPU 基础设施，hackathon org 成员有每日免费额度。
+
+## 降级方案
+
+多模态 + llama.cpp 是高风险点，必须准备降级。
+
+| 风险                 | 主方案                                | 降级方案                                       |
+| -------------------- | ------------------------------------- | ---------------------------------------------- |
+| MiniCPM-V 部署慢     | MiniCPM-V Space 推理                  | 预置 example gallery + 手动 object description |
+| VLM llama.cpp 不稳定 | VLM 用 transformers，文本用 llama.cpp | 仍然保证核心文本人格生成走 llama.cpp           |
+| 微调来不及           | LoRA 微调                             | 用 100 条高质量 SFT 数据 + prompt-tuned style  |
+| Space 资源不足       | HF upgraded Space / ZeroGPU           | CPU 模式 + 小模型 + 示例缓存                   |
+| 视频效果不够         | 实时生成                              | 使用 3 个稳定示例录制 Demo                     |
+
+## 技术栈
+
+```text
+Language:        Python
+UI:              Gradio Blocks
+Model Runtime:   llama.cpp / llama-cpp-python
+VLM:             MiniCPM-V or fallback lightweight VLM
+Training:        LoRA / PEFT / TRL
+Hosting:         Hugging Face Spaces
+Batch/Fine-tune: Modal
+Docs:            Markdown
+Package Manager: uv or pip
+```
+
+## 项目目录结构
+
+```text
+objectverse-diary/
+├─ app.py
+├─ README.md
+├─ AGENTS.md
+├─ requirements.txt
+├─ pyproject.toml
+├─ .env.example
+├─ .gitignore
+├─ src/
+│  ├─ config.py
+│  ├─ ui/
+│  │  ├─ layout.py
+│  │  ├─ styles.css
+│  │  └─ copy.py
+│  ├─ models/
+│  │  ├─ vision_runner.py
+│  │  ├─ llama_cpp_runner.py
+│  │  └─ schema.py
+│  ├─ prompts/
+│  │  ├─ object_understanding.py
+│  │  ├─ persona_generation.py
+│  │  └─ diary_generation.py
+│  ├─ renderer/
+│  │  ├─ share_card.py
+│  │  └─ html_templates.py
+│  ├─ traces/
+│  │  ├─ logger.py
+│  │  └─ anonymizer.py
+│  └─ utils/
+│     ├─ json_repair.py
+│     └─ image_utils.py
+├─ data/
+│  ├─ examples/
+│  ├─ train/
+│  ├─ eval/
+│  └─ traces/
+├─ scripts/
+│  ├─ generate_dataset.py
+│  ├─ finetune_lora.py
+│  ├─ convert_to_gguf.sh
+│  ├─ run_llama_cpp.sh
+│  └─ export_traces.py
+├─ docs/
+│  ├─ PRD.md
+│  ├─ FIELD_NOTES.md
+│  ├─ SUBMISSION_GUIDE.md
+│  └─ MODEL_CARD.md
+└─ .codex/
+   ├─ project.md
+   └─ skills/
+      ├─ gradio-ui/SKILL.md
+      ├─ model-runtime/SKILL.md
+      ├─ dataset-trace/SKILL.md
+      ├─ hf-space/SKILL.md
+      └─ submission/SKILL.md
+```

docs/03-dev-schedule.md

@@ -0,0 +1,209 @@
+# Objectverse Diary — 开发计划（Day-by-Day）
+
+```text
+周期：June 5 - June 15, 2026（共 11 天）
+目标：完成 MVP、打磨 UI、冲全部徽章、提交视频与社交文案
+```
+
+---
+
+## Day 1：立项 + 项目骨架
+
+**目标：确定项目不可变范围。**
+
+- [ ] 创建 GitHub repo
+- [ ] 创建 Hugging Face Space
+- [ ] 创建基础 Gradio app
+- [ ] 写 README 草稿
+- [ ] 确定英文主界面文案
+- [ ] 建立 `AGENTS.md`
+- [ ] 建立 `.codex/skills/`
+
+---
+
+## Day 2：MVP 交互闭环
+
+**目标：先不管模型，跑通产品流程。**
+
+- [ ] 图片上传
+- [ ] 文本描述输入
+- [ ] personality mode 选择
+- [ ] mock object JSON
+- [ ] mock diary 输出
+- [ ] trace JSON 保存
+- [ ] share card HTML 预览
+
+交付：`Upload → Generate → Diary → Share Card → Trace`
+
+---
+
+## Day 3：接入 VLM
+
+**目标：让 AI 真正看图。**
+
+- [ ] 接入 MiniCPM-V 或轻量 VLM
+- [ ] 输出 object understanding JSON
+- [ ] 做 JSON repair
+- [ ] 加 example gallery
+- [ ] 缓存示例输出
+
+验收：上传杯子/键盘/鞋子，模型能识别物品并提取外观特征。
+
+---
+
+## Day 4：文本模型 + llama.cpp
+
+**目标：让核心人格生成走小模型本地推理。**
+
+- [ ] 下载小模型 GGUF
+- [ ] 跑通 llama.cpp / llama-cpp-python
+- [ ] 封装 `generate_persona()`
+- [ ] 封装 `generate_diary()`
+- [ ] README 说明参数量与运行方式
+
+交付：`models/text_model.gguf`、`src/models/llama_cpp_runner.py`、`scripts/run_llama_cpp.sh`
+
+---
+
+## Day 5：训练数据 + 微调准备
+
+**目标：冲 Well-Tuned 勋章。**
+
+- [ ] 生成 200-500 条 object-persona 样本
+- [ ] 手工精选 50 条高质量样本
+- [ ] 设计 SFT schema
+- [ ] 上传 dataset 到 HF
+- [ ] 准备 LoRA 训练脚本
+
+数据格式示例：
+
+```json
+{
+  "instruction": "Create a secret diary persona for this object.",
+  "input": {
+    "object": "old keyboard",
+    "features": ["dusty", "mechanical keys", "developer desk"],
+    "mode": "cynical"
+  },
+  "output": {
+    "character_name": "Clackwell",
+    "diary": "He calls it productivity. I call it percussion with anxiety.",
+    "tags": ["burnout instrument", "debug witness", "plastic philosopher"]
+  }
+}
+```
+
+---
+
+## Day 6：LoRA 微调 + Hub 发布
+
+**目标：拿到可展示的自微调模型。**
+
+- [ ] 用 Modal credits 进行训练
+- [ ] 导出 LoRA adapter
+- [ ] 发布 HF model repo
+- [ ] app 中加入模型说明
+- [ ] README 加 `Well-Tuned` section
+
+交付：HF model repo、HF dataset repo、train log、model card
+
+> ⚠️ Modal credits 兑换码不应公开分享，项目文档里只写"used Modal credits"。
+
+---
+
+## Day 7：UI 魔改
+
+**目标：冲 Off-Brand 勋章。**
+
+视觉方向：
+
+```text
+A strange archive room for everyday objects.
+Dark paper texture, amber highlights, typewriter output, museum labels.
+```
+
+界面布局：
+
+```text
+Left:   Object Intake
+Middle: Object File
+Right:  Secret Diary
+Bottom: Share Card + Trace
+```
+
+- [ ] 自定义 CSS
+- [ ] 自定义 hero section
+- [ ] 隐藏 Gradio 默认风格
+- [ ] 加 typewriter animation
+- [ ] 做英文主文案 + 中文辅助
+- [ ] 做 6 个示例卡片
+
+---
+
+## Day 8：Trace + Sharing is Caring
+
+**目标：公开可复现材料。**
+
+- [ ] trace logger
+- [ ] sample traces
+- [ ] prompt templates
+- [ ] dataset preview
+- [ ] 失败案例记录
+- [ ] GitHub repo 整理
+
+---
+
+## Day 9：Field Notes
+
+**目标：完成技术博客。**
+
+英文标题：`Building Objectverse Diary: A Small-Model AI Toy Where Everyday Objects Come Alive`
+
+博客结构：
+
+1. Why I built it
+2. Why Track 2
+3. Why small models are enough
+4. Product design
+5. Model architecture
+6. Gradio Off-Brand UI
+7. llama.cpp runtime
+8. Fine-tuning dataset
+9. Traces and reproducibility
+10. What failed
+11. What I would improve next
+
+---
+
+## Day 10：Demo 视频
+
+**目标：视频必须比代码更能打。**
+
+建议长度：90 秒
+
+```text
+ 0- 8s  What if every object around you had a secret life?
+ 8-20s  This is Objectverse Diary, a small-model AI toy built with Gradio.
+20-35s  Upload a photo of any everyday object.
+35-50s  A vision model reads the object, then a small fine-tuned model creates its hidden personality.
+50-70s  Now this coffee mug writes its secret diary and complains about its owner.
+70-82s  You can chat with the object and generate a shareable personality card.
+82-90s  Built with small models, Gradio, llama.cpp, public traces, and no commercial cloud APIs.
+```
+
+---
+
+## Day 11：提交检查
+
+- [ ] Space under official org
+- [ ] Demo video ready
+- [ ] Social post ready
+- [ ] README complete
+- [ ] Model parameter count documented
+- [ ] No commercial API
+- [ ] Fine-tuned model linked
+- [ ] Dataset linked
+- [ ] Traces linked
+- [ ] Field Notes linked
+- [ ] UI English-first, Chinese-second
+- [ ] Submit before June 15, 2026

docs/04-hackathon-guide.md

@@ -0,0 +1,116 @@
+# Objectverse Diary — 参赛指南
+
+## 官方硬性要求
+
+| 要求        | 操作                      |
+| ----------- | ------------------------- |
+| 模型 ≤32B   | README 写明所有模型参数量 |
+| Gradio      | 全部交互基于 Gradio       |
+| HF Space    | 托管到官方组织下          |
+| Demo Video  | 2 分钟内，重点展示体验    |
+| Social Post | 准备英文社媒文案          |
+| 截止时间    | June 15, 2026             |
+
+---
+
+## 勋章获取方案
+
+| 勋章                  | 获取方式         | 项目实现                                                          |
+| --------------------- | ---------------- | ----------------------------------------------------------------- |
+| **Off the Grid**      | 不调用商业云 API | 推理在 HF Space / Modal / 本地闭环完成                            |
+| **Well-Tuned**        | 使用自微调模型   | 微调一个小模型做 object persona / diary style JSON 输出           |
+| **Off-Brand**         | 深度魔改 Gradio  | 用 `gr.Blocks` + CSS + JS 做成"Object Archive"界面               |
+| **Llama Champion**    | llama.cpp 驱动   | 文本人格生成模型走 GGUF + llama.cpp / llama-cpp-python            |
+| **Sharing is Caring** | 开源数据 / trace | 公开匿名化 object-persona 数据集、sample traces、prompt templates |
+| **Field Notes**       | 技术博客         | 写完整英文技术报告                                                |
+| **OpenBMB Special**   | 使用 MiniCPM     | VLM 层优先使用 MiniCPM-V 4.6                                     |
+
+---
+
+## 资源使用指南
+
+### Hugging Face
+
+- Space 托管
+- Model repo
+- Dataset repo
+- Demo page
+- ZeroGPU / upgraded Space
+
+### Modal
+
+- LoRA fine-tuning
+- batch dataset generation
+- model conversion
+- stress test
+
+> ⚠️ 不要在 repo、README、截图、视频或日志中暴露 credit codes。
+
+---
+
+## 提交材料结构
+
+```text
+Submission Package
+├─ Hugging Face Space URL
+├─ GitHub Repository URL
+├─ Demo Video URL
+├─ Social Media Post URL
+├─ Fine-tuned Model URL
+├─ Dataset URL
+├─ Trace Dataset URL
+├─ Field Notes Blog URL
+└─ Short project description
+```
+
+---
+
+## 社交媒体文案
+
+### 英文版
+
+```text
+I built Objectverse Diary for #BuildSmallHackathon.
+
+Upload any everyday object.
+A small AI model wakes it up, gives it a secret personality,
+writes its diary, and lets you chat with it.
+
+A coffee mug becomes a burned-out philosopher.
+A keyboard becomes a witness to unfinished side projects.
+A shoe becomes a tired travel historian.
+
+Built with Gradio, small models, llama.cpp, public traces,
+and no commercial cloud AI APIs.
+
+Every object has a secret life.
+```
+
+### 中文版
+
+```text
+我做了一个小模型 AI 玩具：Objectverse Diary。
+
+上传任意日常物品，它会被 AI 唤醒，拥有隐藏人格、秘密日记，
+还能继续和你聊天。
+
+一个杯子可能是厌世哲学家。
+一个键盘可能见证了 47 个没做完的 side project。
+一只鞋可能是疲惫的旅行史学家。
+
+英文界面为主，中文为辅。
+基于 Gradio、小模型、llama.cpp、公开 trace，不调用商业云模型 API。
+```
+
+---
+
+## Demo 视频脚本
+
+```text
+ 0- 8s  Hook: What if every object around you had a secret life?
+ 8-20s  Show upload and mode selection
+20-45s  Show model recognizing the object and generating persona
+45-70s  Show diary and chat interaction
+70-85s  Show share card
+85-100s Show technical badge checklist
+```

docs/05-dev-guidelines.md

@@ -0,0 +1,174 @@
+# Objectverse Diary — 开发规范
+
+## 代码规范
+
+### Python
+
+- 使用 type hints
+- 保持函数简短
+- 避免隐藏的网络调用
+- 不硬编码 secrets
+- 使用 Pydantic 验证模型 JSON 输出
+- Prompts 放在 `src/prompts/`，不要内联到 UI 代码中
+- UI 文案放在 `src/ui/copy.py`
+
+### Gradio
+
+- 使用 `gr.Blocks`，不使用 `gr.Interface` 做主应用
+- 所有主要组件必须有 `elem_id` 或 `elem_classes`
+- 自定义 CSS 放在 `src/ui/styles.css`
+- 英文文案优先，中文辅助在后
+- 应用需在 1366px 桌面和移动端宽度下可用
+
+### Model
+
+- 总模型参数量必须有文档记录
+- 不调用商业 API
+- 文本生成支持本地 llama.cpp 路径
+- VLM 降级方案必须有文档
+- 输出必须是结构化 JSON，渲染前验证
+
+### Data
+
+- 不包含个人敏感数据
+- Sample traces 必须匿名化
+- 公开数据集使用合成或已授权的示例
+- 原始图片与公开 trace 数据分离
+
+---
+
+## Git 规范
+
+### 分支策略
+
+```text
+main:    stable submission branch
+dev:     active development branch
+feat/*:  feature branches
+fix/*:   bug fixes
+docs/*:  documentation
+```
+
+### Commit 格式
+
+```text
+feat: add object persona generator
+fix: repair malformed diary JSON
+docs: add field notes draft
+style: improve off-brand gradio theme
+chore: update model config
+```
+
+---
+
+## AGENTS.md 模板
+
+> 直接放到项目根目录 `AGENTS.md`
+
+```md
+# AGENTS.md
+
+## Project
+
+Objectverse Diary is a Build Small Hackathon project.
+It is an English-first, Chinese-second Gradio application where users upload
+everyday object photos and small AI models generate secret object personas,
+diary entries, conversations, and shareable cards.
+
+## Primary Goals
+
+1. Compete in the "An Adventure in Thousand Token Wood" track.
+2. Keep total model parameters <= 32B.
+3. Use Gradio for all UI and interaction.
+4. Host the final app as a Hugging Face Space.
+5. Avoid commercial cloud AI APIs.
+6. Maximize hackathon badges.
+7. Use English as the main UI language and Chinese as secondary helper text.
+
+## Non-Negotiable Rules
+
+- Do not use OpenAI, Anthropic, Gemini, Cohere, or other commercial model APIs.
+- Do not leak private credit codes, tokens, emails, or credentials.
+- Do not hardcode secrets.
+- Do not remove Gradio.
+- Do not make the UI Chinese-first.
+- Do not exceed the 32B total model parameter limit.
+- Do not add large features that risk missing the submission deadline.
+- Do not store unconsented personal user data.
+
+## Tech Stack
+
+- Python
+- Gradio Blocks
+- Hugging Face Spaces
+- llama.cpp / llama-cpp-python for text generation
+- MiniCPM-V or fallback lightweight VLM for object understanding
+- LoRA / PEFT for fine-tuning
+- Markdown documentation
+
+## UI Requirements
+
+The interface must be English-first and Chinese-second.
+Visual style: strange object archive, not default Gradio demo.
+Recommended UI mood: mysterious archive, typewriter diary, warm dark paper,
+amber highlight, museum label, strange but polished.
+
+## Architecture
+
+1. Image upload → 2. Object understanding → 3. Persona generation →
+4. Secret diary generation → 5. Object chat → 6. Share card rendering →
+7. Trace export
+
+## Coding Guidelines
+
+- Use type hints
+- Prefer small, composable functions
+- Prompts under src/prompts
+- UI copy under src/ui/copy.py
+- CSS under src/ui/styles.css
+- Runtime code under src/models
+- Trace code under src/traces
+- Use Pydantic schemas for model outputs
+- Add clear fallback behavior when model output is invalid
+
+## Testing Requirements
+
+- App runs locally
+- App runs on HF Space
+- At least 6 sample objects work
+- Share card renders correctly
+- Trace export works
+- No secret keys committed
+- README links valid
+- Demo video flow reproducible
+```
+
+---
+
+## Codex Skills 模板
+
+以下 Skills 文件放在 `.codex/skills/` 对应目录下。
+
+### `.codex/project.md`
+
+项目上下文文件，包含 hackathon 信息、核心创意、硬性约束和开发优先级。
+
+### `.codex/skills/gradio-ui/SKILL.md`
+
+Gradio Off-Brand UI 规范：布局结构（Hero → Object Intake → Object File → Secret Diary → Chat → Share Card → Trace）、视觉方向（dark paper / amber / typewriter / museum）。
+
+### `.codex/skills/model-runtime/SKILL.md`
+
+模型运行时规范：Vision Runner、Text Runner、Schema 三层架构，以及降级策略（VLM 失败 → 手动描述、文本模型失败 → 模板降级、JSON 异常 → 修复重试）。
+
+### `.codex/skills/dataset-trace/SKILL.md`
+
+数据集与 Trace 规范：训练数据格式、trace 格式、隐私规则、验收标准（≥100 训练样本、≥6 公开 traces）。
+
+### `.codex/skills/hf-space/SKILL.md`
+
+HF Space 部署规范：必要文件、README YAML header、部署检查清单。
+
+### `.codex/skills/submission/SKILL.md`
+
+提交规范：8 项交付物、Demo 视频结构、社交文案模板、最终检查清单。

docs/06-readme-template.md

@@ -0,0 +1,75 @@
+# Objectverse Diary — README 模板
+
+> 初始化项目时直接复制到 `README.md`
+
+---
+
+# Objectverse Diary
+
+**Every object has a secret life.**
+**万物日记：每个物品都有秘密人生。**
+
+Objectverse Diary is a small-model AI toy built for the Build Small Hackathon.
+
+Upload a photo of any everyday object. The app wakes it up, gives it a secret personality, writes its diary, and lets you chat with it.
+
+## Track
+
+An Adventure in Thousand Token Wood
+
+## Why this fits the track
+
+This is a pure digital experience that could not exist without AI:
+
+- vision understanding
+- object persona generation
+- first-person diary writing
+- consistent character chat
+- shareable personality cards
+
+## Language
+
+The interface is English-first and Chinese-second.
+
+## Badge Targets
+
+- [ ] Off the Grid
+- [ ] Well-Tuned
+- [ ] Off-Brand
+- [ ] Llama Champion
+- [ ] Sharing is Caring
+- [ ] Field Notes
+
+## Model Stack
+
+- Vision: MiniCPM-V or lightweight VLM fallback
+- Text: fine-tuned small LLM
+- Runtime: llama.cpp / llama-cpp-python
+- UI: Gradio Blocks
+
+## Run Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+## Project Structure
+
+See AGENTS.md and .codex/skills for development rules.
+
+---
+
+## HF Space README YAML Header
+
+```yaml
+---
+title: Objectverse Diary
+emoji: 🗝️
+colorFrom: amber
+colorTo: gray
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+```

docs/FIELD_NOTES.md

@@ -0,0 +1,23 @@
+# Field Notes
+
+Working title:
+
+`Building Objectverse Diary: A Small-Model AI Toy Where Everyday Objects Come Alive`
+
+## Draft Outline
+
+1. Why I built it
+2. Why Track 2
+3. Why small models are enough
+4. Product design
+5. Model architecture
+6. Gradio Off-Brand UI
+7. llama.cpp runtime
+8. Fine-tuning dataset
+9. Traces and reproducibility
+10. What failed
+11. What I would improve next
+
+## Status
+
+Not started. This file is a placeholder for Day 9.

docs/MODEL_CARD.md

@@ -0,0 +1,18 @@
+# Model Card
+
+## Status
+
+Not started. No model has been selected, fine-tuned, converted, or published yet.
+
+## Planned Components
+
+- Vision understanding: MiniCPM-V or lightweight fallback VLM.
+- Text generation: fine-tuned small LLM.
+- Runtime: llama.cpp / llama-cpp-python.
+
+## Required Notes
+
+- Total model parameter count must remain <= 32B.
+- No commercial model APIs.
+- Fallback behavior must be documented.
+- Dataset provenance and privacy rules must be documented before release.

docs/README.md

@@ -0,0 +1,19 @@
+# Documentation Index
+
+This folder contains the planning source of truth for Objectverse Diary.
+
+## Core Docs
+
+- `00-project-overview.md`: product positioning, core flow, language rules, hard constraints.
+- `01-prd.md`: users, MVP scope, acceptance criteria, output examples.
+- `02-tech-architecture.md`: planned architecture, model stack, fallback strategy, target directory tree.
+- `03-dev-schedule.md`: day-by-day hackathon plan.
+- `04-hackathon-guide.md`: badges, resources, submission package, social copy.
+- `05-dev-guidelines.md`: coding, Gradio, model, data, Git, AGENTS, and Codex skills guidance.
+- `06-readme-template.md`: original README template.
+
+## Added Skeleton Docs
+
+- `FIELD_NOTES.md`: future technical blog draft.
+- `MODEL_CARD.md`: future model documentation.
+- `SUBMISSION_GUIDE.md`: final submission checklist.

docs/SUBMISSION_GUIDE.md

@@ -0,0 +1,26 @@
+# Submission Guide
+
+## Required Package
+
+- [ ] Hugging Face Space URL
+- [ ] GitHub Repository URL
+- [ ] Demo Video URL
+- [ ] Social Media Post URL
+- [ ] Fine-tuned Model URL
+- [ ] Dataset URL
+- [ ] Trace Dataset URL
+- [ ] Field Notes Blog URL
+- [ ] Short project description
+
+## Final Checks
+
+- [ ] Space is under the official organization.
+- [ ] Demo video is under 2 minutes.
+- [ ] README includes model parameter counts.
+- [ ] No commercial cloud AI APIs are used.
+- [ ] Fine-tuned model is linked.
+- [ ] Dataset is linked.
+- [ ] Traces are linked.
+- [ ] Field Notes are linked.
+- [ ] UI remains English-first and Chinese-second.
+- [ ] Submission is complete before June 15, 2026.

pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "objectverse-diary"
+version = "0.0.0"
+description = "A small-model AI toy that turns everyday objects into secret diary characters."
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.objectverse-diary]
+status = "structure-only"
+implementation = "not-started"

requirements.txt

@@ -0,0 +1,2 @@
+# Dependencies will be added when implementation starts.
+# Planned stack: gradio, llama-cpp-python, pydantic, pillow, MiniCPM-V runtime tools.

scripts/README.md

@@ -0,0 +1,13 @@
+# Scripts
+
+Planned automation scripts for dataset generation, fine-tuning, GGUF conversion, llama.cpp runtime, and trace export.
+
+Expected files during implementation:
+
+- `generate_dataset.py`
+- `finetune_lora.py`
+- `convert_to_gguf.sh`
+- `run_llama_cpp.sh`
+- `export_traces.py`
+
+Current status: no implementation code.

src/README.md

@@ -0,0 +1,14 @@
+# Source Skeleton
+
+This directory is reserved for application source code.
+
+Current status: structure-only. No implementation code has been added yet.
+
+## Planned Areas
+
+- `ui/`: Gradio layout, CSS, and copy.
+- `models/`: vision runner, llama.cpp text runner, and schemas.
+- `prompts/`: object understanding, persona generation, and diary generation prompts.
+- `renderer/`: share card and HTML rendering.
+- `traces/`: trace logging and anonymization.
+- `utils/`: JSON repair and image utilities.

src/prompts/README.md

@@ -0,0 +1,11 @@
+# Prompts
+
+Planned prompt templates.
+
+Expected files during implementation:
+
+- `object_understanding.py`
+- `persona_generation.py`
+- `diary_generation.py`
+
+Current status: no implementation code.

src/renderer/README.md

@@ -0,0 +1,10 @@
+# Renderer
+
+Planned rendering layer for diary views and share cards.
+
+Expected files during implementation:
+
+- `share_card.py`
+- `html_templates.py`
+
+Current status: no implementation code.

src/traces/README.md

@@ -0,0 +1,10 @@
+# Traces
+
+Planned trace logging and anonymization layer.
+
+Expected files during implementation:
+
+- `logger.py`
+- `anonymizer.py`
+
+Current status: no implementation code.

src/ui/README.md

@@ -0,0 +1,11 @@
+# UI
+
+Planned Gradio Blocks UI layer.
+
+Expected files during implementation:
+
+- `layout.py`
+- `styles.css`
+- `copy.py`
+
+Current status: no implementation code.

src/utils/README.md

@@ -0,0 +1,10 @@
+# Utilities
+
+Planned shared helpers.
+
+Expected files during implementation:
+
+- `json_repair.py`
+- `image_utils.py`
+
+Current status: no implementation code.