From 64babc0d915f88e006f4c3778803058806dbe44d Mon Sep 17 00:00:00 2001
From: yiekheng <yiekheng@04080616.xyz>
Date: Sun, 12 Apr 2026 19:01:52 +0800
Subject: [PATCH] Update CLAUDE.md for submodule workflow

Replaces the earlier subtree docs with submodule clone/pull/push flow
and notes where local-only files live.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 49 +++++++++++++++++++++++++++++++------------------
 1 file changed, 31 insertions(+), 18 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 425cdbb..7020249 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository layout
 
-`sunnymh` is the umbrella repo for the 晴天漫画 · Sunny MH product. Each sub-project is its own git repo with its own remote on Gitea (`gitea.04080616.xyz/yiekheng/sunnymh-*`). The umbrella ties them together via **git subtree** so a single clone contains the whole system, while the sub-repos remain independently pushable.
+`sunnymh` is the umbrella repo for the 晴天漫画 · Sunny MH product. Each sub-project is its own git repo with its own remote on Gitea (`gitea.04080616.xyz/yiekheng/sunnymh-*`). The umbrella ties them together via **git submodules** — the umbrella pins a commit SHA per sub-project, and `cd`-ing into a sub-dir gives you that sub-repo's own `.git`, history, and branch.
 
 | Path | Role | Remote | Detailed guide |
 |---|---|---|---|
@@ -13,32 +13,45 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 More sub-projects may be added over time. Always read the sub-project's own `CLAUDE.md` before touching its code — the two stacks have very different invariants (Playwright/CDP anti-bot in `manga-dl`; placeholder-shift invariants in `manga-site/PageReader.tsx`).
 
-## Subtree workflow
+## Submodule workflow
 
-The sub-dirs currently still hold their own `.git` (independent clones). To convert a sub-dir into a tracked subtree of this umbrella:
+First clone — must recurse, otherwise the sub-dirs come up empty:
 
 ```bash
-# one-time, per sub-project — run from sunnymh root
-git remote add manga-dl-origin   https://gitea.04080616.xyz/yiekheng/sunnymh-manga-dl.git
-git remote add manga-site-origin https://gitea.04080616.xyz/yiekheng/sunnymh-manga-site.git
-
-# archive the existing working copy, then subtree-add from the remote
-mv manga-dl manga-dl.bak && rm -rf manga-dl.bak/.git   # keep local-only files like .env, .browser-data
-git subtree add --prefix=manga-dl manga-dl-origin main --squash
-# then copy .env / .browser-data / cookies.txt / debug/ back into manga-dl/
+git clone --recurse-submodules https://gitea.04080616.xyz/yiekheng/sunnymh.git
+# or, after a plain clone:
+git submodule update --init --recursive
 ```
 
-Day-to-day:
+Day-to-day inside a sub-project:
 
 ```bash
-# pull upstream changes for one sub-project
-git subtree pull --prefix=manga-dl manga-dl-origin main --squash
-
-# push umbrella-side edits back to the sub-repo's remote
-git subtree push --prefix=manga-dl manga-dl-origin main
+cd manga-dl
+# sub-dir has its own .git file pointing to ../.git/modules/manga-dl/
+# `git log`, `git status`, `git commit`, `git push` all talk to the sub-repo's remote (sunnymh-manga-dl.git)
+git pull origin main
+# edit, commit, push — this goes to the sub-repo's remote, NOT the umbrella
 ```
 
-Local-only files that must NOT be pushed to the sub-repo remote (already in each sub-repo's own `.gitignore`): `.env`, `manga-dl/.browser-data/`, `manga-dl/cookies.txt`, `manga-site/node_modules/`, `manga-site/.next/`, `manga-site/tsconfig.tsbuildinfo`.
+After a sub-repo is updated, bump the pinned SHA in the umbrella:
+
+```bash
+cd ..   # back to umbrella root
+git add manga-dl           # stages the new submodule SHA
+git commit -m "Bump manga-dl to <short-sha>"
+git push
+```
+
+Pull upstream updates that bumped submodule SHAs:
+
+```bash
+git pull
+git submodule update --recursive   # check out the SHAs the umbrella now points at
+```
+
+Local-only files inside each submodule (gitignored at the sub-repo level, never pushed anywhere): `.env`, `manga-dl/.browser-data/`, `manga-dl/cookies.txt`, `manga-site/node_modules/`, `manga-site/.next/`, `manga-site/tsconfig.tsbuildinfo`, `manga-site/.claude/`, `manga-site/.agents/`, `manga-site/reference/`.
+
+The umbrella also has a root-level `.env` — shared R2 + DB credentials, single source of truth. It's untracked (not in a remote). Sub-projects currently still read their own `.env` copies; see the migration note in `MEMORY.md` / conversation history.
 
 ## Cross-project invariants