docs(solutions): compound refresh — fix reference drift, grow CONCEPTS.md

Refresh audit of all 13 docs/solutions learnings against the current
codebase. Core guidance verified accurate everywhere; three docs had
reference drift:

- dual-repo-submodule-workflow: point worktree setup/teardown at the
  make worktree-new/worktree-rm targets (manual procedure misses
  .worktree-env isolation)
- docker-exec-root-owned-bind-mount-files: tracked-plugin list now
  includes entry-actions; fix-perms description matches actual target
- grav-plugin-config-without-code-wont-enable: 3-category model's
  custom-in-repo list now includes entry-actions

CONCEPTS.md: add Container, Content repo, Outer repo, Pin, Env tree,
Remote-only plugin; refresh Active Trip (switching is one setting now).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0195b3cDdMeize2Mm1FgC2aU
This commit is contained in:
2026-07-08 23:37:56 +02:00
co-authored by Claude Fable 5
parent f3816bfc3e
commit 24867524a1
4 changed files with 36 additions and 21 deletions
@@ -56,33 +56,28 @@ Production is unaffected either way: prod pulls `user/` directly via the content
The payoff. Because `docker-compose.yml` mounts `./user` **relative to the compose file**, and a worktree is a full copy of the outer tree (compose file included), each worktree serves *its own* `user/`. Two worktrees = two independent sites, no gitlink collisions.
Set up a feature worktree off `main`:
**Use the make targets — don't do the steps by hand.** From the main checkout:
```bash
# outer worktree on a new feature branch
git worktree add .worktrees/<feature> -b feat/<feature> main
cd .worktrees/<feature>
# populate user/ at the pinned SHA, then branch it for the cross-repo work
git submodule update --init user
git -C user checkout -b feat/<feature>
# its own dev server — separate project name + port from the main checkout's :8081
docker compose -p itte-<feature> up -d
make worktree-new NAME=<feature> # create + start its own dev server
make worktree-rm NAME=<feature> # tear down cleanly
```
`worktree-new` does, in order: `git worktree add .worktrees/<feature> -b feat/<feature> main`, `git submodule update --init user`, branches `user/` onto `feat/<feature>`, writes a git-ignored `.worktree-env` (own compose project name, container name, auto-assigned port `8090+`) so every `make`/compose command run inside that worktree targets its own server, and starts the Grav service. The manual equivalent misses `.worktree-env` — without it, make commands in the worktree hit the main checkout's container on `:8081`.
`.worktrees/` is kept out of git via `.git/info/exclude` (local, shared across worktrees — no committed `.gitignore` change needed).
### Teardown
A submodule inside a linked worktree stores its git dir under `.git/modules/user/worktrees/<name>`, so removing the outer worktree needs a second cleanup step:
A submodule inside a linked worktree stores its git dir under `.git/modules/user/worktrees/<name>`, so teardown needs a submodule-deinit step before the worktree can be removed — skipping it is what leaves orphaned `.worktrees/` dirs. `make worktree-rm NAME=<feature>` runs the full sequence:
```bash
docker compose -p itte-<feature> down
cd "$(git rev-parse --show-toplevel)" # back to the main checkout
git -C .worktrees/<feature> submodule deinit user # detach the submodule worktree
git worktree remove .worktrees/<feature> # remove the outer worktree
git branch -d feat/<feature> # if merged
# what worktree-rm does internally
make -C .worktrees/<feature> stop # compose down (its own server)
git -C .worktrees/<feature> submodule deinit -f user # detach the submodule worktree
git worktree remove --force .worktrees/<feature>
git worktree prune
git branch -d feat/<feature> # manual, if merged
```
### Landing a commit on main without disturbing the main checkout