MarcelLeon · MarcelLeon · May 28, 2026 · May 26, 2026 · May 26, 2026 · May 28, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -57,7 +57,6 @@ NORTH_STAR.md
 - [ ] **本轮启动时已做 Step 1b 对齐检查并显式输出**(覆盖 NORTH_STAR / Phase / ROUNDS / 跳序四问)
 - [ ] `mvn17 test -pl graph-rag-core` 全绿
 - [ ] 没有跳过的测试(`@Disabled` / `@Ignore`)
-- [ ] 没有引入 `com.kuaishou.*` 或其他内部包
 - [ ] 如改动了 `GraphDatabaseClient` 接口:Neo4j 实现 + 所有 stub 都已同步
 - [ ] 没有删除任何 `Noop*Impl` 类
 - [ ] 单类 < 500 行,单方法 < 100 行(超出需在 ROUNDS 里说明理由)
@@ -74,7 +73,6 @@ NORTH_STAR.md
 ## AI 禁止事项(违反即视为损坏 SSOT)
 
 - ❌ 跳过测试直接 commit
-- ❌ 在 `graph-rag-core` 任意层 import 内部包(`com.kuaishou.*` / 私有 SDK)
 - ❌ 修改 `GraphDatabaseClient` 接口而不同步更新所有实现
 - ❌ 删除 `Noop*Impl` 实现(它们是测试与 examples 的兜底)
 - ❌ 在 `application/` 或 `domain/` 层直接引用 `org.neo4j.driver.*`(必须走接口)

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,28 @@
 
 ## [Unreleased]
 
+### Added — Pre-release polish (Round 7 + 7.1)
+
+- **Lightweight hero GIF** (`docs/assets/demo-short.gif`, ~553 KB / ~27 s / 1240×760): `--variant=graph`, real local Ollama, one short DAU question, full graph context + explicit lineage trail rendered. Now sits at the top of README / README.zh.md so first-time visitors on slow networks see a structured graph answer before the longer side-by-side GIF loads. Reproducible via new `docs/assets/demo-short.tape`. The existing 60-second `demo-side-by-side.gif` is preserved as the linked "extended demo".
+- **`run-cli.sh` now honors `VARIANT=` env** (defaults to `both`), so the same launcher script is used by both the hero tape (`VARIANT=graph`) and the extended tape (default).
+- **Status wording switched from `public alpha` to `public preview`** across README badge / README body / README.zh.md / SECURITY.md / CONTRIBUTING.md. R6's "Public alpha polish" CHANGELOG heading kept as-is (historical record).
+- **Bilingual README**: added `README.zh.md` (full 中文 translation, same 13-section structure as English) with language switcher links at the top of both files. README badges now point at the real `MarcelLeon/graph-rag-harness` GitHub Actions CI workflow instead of the `OWNER/REPO` placeholder, and the GIF-recipe wording references the in-repo `./docs/assets/run-cli.sh` launcher (was a stale `/tmp/run-cli.sh` path).
+- **Troubleshooting section in README + CONTRIBUTING**: explains why `mvn -pl graph-rag-examples -am spring-boot:run` fails with "Unable to find a suitable main class" (the `-am` includes the root pom module, which has no main class), and gives two safe recipes: (1) split into a one-time `install` for upstream modules + a plain `spring-boot:run` for the example, or (2) just run the pre-built fat jar. Quick-start commands updated accordingly so first-time cloners do not hit this trap.
+- **Side-by-side dogfooding GIF** (`docs/assets/demo-side-by-side.gif`, 820 KB / 60 s / 1320×1100): a real local Ollama run (`qwen3:8b` chat + `nomic-embed-text` embedding) that shows the dogfooding CLI answering one DAU question in `--variant=both` mode, with `PLAIN` and `GRAPH` blocks visible in the same frame and the graph answer carrying the explicit `(Graph lineage: DAU --[FORMULA_USES]--> ...)` trail. README front page now embeds this GIF directly.
+- **Repo-tracked recording recipe**: `docs/assets/demo.tape` (vhs script, Dracula theme, hides JVM warm-up, deterministic timings) and `docs/assets/run-cli.sh` (port-8088 wrapper that runs `--mode=cli --variant=both` with quiet logs). Anyone can re-record the GIF with `brew install vhs && vhs docs/assets/demo.tape` — the README "Record the demo GIF yourself" section is now a 3-line recipe.
+- **GitHub-friendly README rewrite**: added status / CI / license / Java / Spring AI badges, a 60-second terminal preview, an honest "what is solid / what is in progress" summary, and now an embedded demo GIF instead of an ASCII mock-up.
+- **`docs/assets/` directory**: now hosts the demo GIF, the vhs tape, and the launcher script that produces it.
+- **`docs/playbooks/sample-graph-v2-design.md`** rewritten as a zero-touch, conditionally-go fixture upgrade: locks the design to `graph-rag-examples/` only (no `graph-rag-core` enum / interface changes), maps every new business relation onto existing `STRUCTURAL_TYPES`, defines a 12-node / 14-edge ceiling, adds a regression / rollback / acceptance checklist, and gates the start of v2-mini behind "L3 < +1.0 after Round 7-8 prompt and judge tuning".
+
+### Changed
+
+- **Public eval headline updated**: latest real Ollama run shows L3 plain 2.50 / graph 3.00 (**Δ = +0.50**), overall plain 2.80 / graph 3.00 (Δ = +0.20). README, STATUS, and CHANGELOG aligned. NORTH_STAR milestone of L3 ≥ +1.0 is still tracked honestly as "not yet".
+- **Test suite reference numbers refreshed**: `mvn17 test -pl graph-rag-core` now reports 65 tests green (12 + 6 + 4 + 43), up from the 62 figure quoted in earlier docs.
+
+### Notes
+
+- Round 7 itself touched no production code in `graph-rag-core`, `graph-rag-spring-boot-starter`, or `graph-rag-examples`. Round 7.1 added only documentation assets (`docs/assets/*`). The 65-test `graph-rag-core` baseline is unchanged.
+
 ### Added — Public alpha polish (Round 6)
 
 - **Interactive dogfooding CLI** (`graph-rag-examples/.../cli/CliRunner.java`): run the example app with `--mode=cli --variant=plain|graph|both` and ask questions directly from the terminal using local Ollama. This reuses the same answer services as the HTTP demo and eval harness.
@@ -28,7 +50,7 @@
 
 ### Notes
 
-- Latest real Ollama eval now shows **early positive L3 uplift** of graph-RAG over plain-RAG (**+0.25** on the latest run, overall **+0.10**), which is enough to support honest public alpha positioning but still **below** the NORTH_STAR milestone of **+1.0** on L3.
+- Latest real Ollama eval now shows **positive L3 uplift** of graph-RAG over plain-RAG (**+0.50** on the 2026-05-26 run, overall **+0.20**), which supports honest public alpha positioning but is still **below** the NORTH_STAR milestone of **+1.0** on L3.
 
 ### Added — Spring AI demo end-to-end (Round 5)
 
@@ -86,5 +108,4 @@
 - 20 个单元测试,全绿
 
 ### Removed
-- 所有内部依赖:KGraph SDK / Cortex / KsBoot
-- 内部包名 `com.kuaishou.*`,统一改为 `io.github.graphrag.*`
+- 所有内部依赖:KGraph SDK / Cortex / KsBoot
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
 
 Thanks for your interest in contributing to `graph-rag-harness`.
 
-This repository is currently in **public alpha**:
+This repository is currently in **public preview**:
 
 - the demo is runnable,
 - the core abstractions are real,
@@ -106,6 +106,12 @@ JAVA_HOME=$JAVA17_HOME mvn -pl graph-rag-examples -am -DskipTests compile -q
 If your change touches the example app, also try a manual smoke test:
 
 ```bash
+# Install upstream modules into the local cache once (or whenever they change).
+JAVA_HOME=$JAVA17_HOME mvn -pl graph-rag-core,graph-rag-spring-boot-starter -am -DskipTests install -q
+
+# Then run the example app on its own — DO NOT add -am here. With -am, Maven
+# would try to run spring-boot:run on the root pom module first and fail with
+# "Unable to find a suitable main class". See README "Troubleshooting".
 JAVA_HOME=$JAVA17_HOME mvn -pl graph-rag-examples spring-boot:run \
   -Dspring-boot.run.arguments="--mode=cli --variant=both --server.port=8086"
 ```