From d0858f288ada086661ec881f61cbd670a33288ab Mon Sep 17 00:00:00 2001
From: Accusys <accusys@momentry.dev>
Date: Mon, 22 Jun 2026 03:24:04 +0800
Subject: [PATCH] docs: add CLI usage for TKG Level 1 builder

- Add Usage section with CLI commands
- TKG Level 1 builder: python scripts/tkg_level1_builder.py
- Query example for person_trace nodes
---
 .../DESIGN/Appearance_Feature_System_V1.0.md  | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs_v1.0/DESIGN/Appearance_Feature_System_V1.0.md b/docs_v1.0/DESIGN/Appearance_Feature_System_V1.0.md
index 16548cd..80b2c96 100644
--- a/docs_v1.0/DESIGN/Appearance_Feature_System_V1.0.md
+++ b/docs_v1.0/DESIGN/Appearance_Feature_System_V1.0.md
@@ -256,6 +256,48 @@ else:
 
 ---
 
+## Usage
+
+### CLI Commands
+
+#### TKG Level 1 Builder
+
+Build person_trace nodes with Level 1 features:
+
+```bash
+# Basic usage (auto-detect video and pose.json paths)
+python scripts/tkg_level1_builder.py --file-uuid <uuid> --schema dev
+
+# With explicit paths
+python scripts/tkg_level1_builder.py \
+  --file-uuid <uuid> \
+  --schema dev \
+  --video /path/to/video.mp4 \
+  --pose-json /path/to/pose.json
+```
+
+Output: Creates `person_trace` nodes in `tkg_nodes` table with:
+- frame_count
+- height_estimate (from shoulder_width or head_width)
+- level1_features (body, head_top, upper_body, lower_body colors)
+
+#### Query TKG Nodes
+
+```python
+import psycopg2
+
+conn = psycopg2.connect('postgresql://accusys@localhost:5432/momentry')
+cur = conn.cursor()
+
+cur.execute("SELECT external_id, properties FROM dev.tkg_nodes WHERE node_type='person_trace'")
+
+for row in cur.fetchall():
+    external_id, props = row
+    print(f'{external_id}: height={props["height_estimate"]["estimated_height_cm"]}cm')
+```
+
+---
+
 ## Appearance Feature Location Mapping
 
 ### Environment Factors