research: git-forge wikis deep dive (Gitea/GitLab/GitHub); UC-76-77

SHARD-WP-0003 T5. The home case: a forge wiki is a separate .wiki.git repo of
Markdown -> page model, history, coordination journal map 1:1 with near-zero
adapter. git-clone universal across all three; wiki content API
capability-varying (GitLab/Gitea yes, GitHub git-only). git IS the canonical
store (not a mirror), so write-by-commit is safe -- resolves the UC-68/Q22
race for this case. UC-76 (clone .wiki.git attach), UC-77 (forge wiki API,
capability varies). Enriched UC-40/02/68/38. Marks T5 done.
Feeds SHARD-WP-0002 T14/T11.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

spec/UseCaseCatalog.md

@@ -13,7 +13,8 @@ Promoted from `research/260608-c2-wiki-origins/`,
 `research/260614-localfirst-workspaces-deep-dive/`,
 `research/260614-trilium-deep-dive/`, `research/260614-wikijs-deep-dive/`, and
 `research/260614-federated-wiki-deep-dive/`, and
-`research/260614-wikibase-deep-dive/`.
+`research/260614-wikibase-deep-dive/`, and
+`research/260614-forge-wikis-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.
 
 ## Conventions
@@ -899,7 +900,12 @@ interchange mirror (UC-60) — it is **plain Markdown** — and richer than a re
 store (UC-40): the bidirectional ingest makes **git commit a write path** (overlay/patch
 as a commit, no API). Caution: the **engine owns the DB↔git sync** — don't double-sync;
 coordinate source-of-truth (configurable). Gives **git history natively** (UC-36, adopt
-via mirror). Open: mirror-vs-DB source of truth; write-by-commit races (findings §9 Q1).  
+via mirror). Open: mirror-vs-DB source of truth; write-by-commit races (findings §9 Q1).
+**Contrast (resolves the race for forge wikis):** a **git-forge wiki** (UC-76) is the
+opposite — **git IS the canonical store, not a mirror**, so there is no engine DB↔git sync
+to race and **write-by-commit is safe**
+(`research/260614-forge-wikis-deep-dive/findings.md` §3). The dilemma here is specific to
+*engine-maintained mirrors* (DB canonical), not to git-canonical stores.  
 **Priority:** Later
 
 ### UC-69 — Attach via a typed, introspectable API (schema discovery + selective projection)
@@ -1015,6 +1021,36 @@ sub-page/per-assertion provenance even if MVP records per page. Enriches UC-24;
 SHARD-WP-0002 T12 + provenance model.  
 **Priority:** Later
 
+### UC-76 — Attach a git-forge wiki by cloning its dedicated wiki repo
+
+**Actor:** Orchestrator / adapter  
+**Goal:** Attach a **Gitea / GitLab / GitHub wiki** by **cloning its dedicated
+`<repo>.wiki.git`** — Markdown files are pages, the **git log is the coordination journal**,
+and **commit/push is the write path** with no engine to race.  
+**Source:** wikiengines, intent  
+**Notes:** A forge wiki is a *separate git repo of Markdown*
+(`research/260614-forge-wikis-deep-dive/findings.md` §1, §3) — the **home case**: page
+model, history, and journal map 1:1 to shard-wiki's medium with minimal adapter. Unlike a
+Wiki.js engine-maintained mirror (UC-68), **git IS the canonical store**, so write-by-commit
+is safe (resolves catalog open-Q22). The **universal** attach path across all three forges.
+INTENT names Gitea wikis explicitly. Feeds SHARD-WP-0002 T14 (file-store attach), T11.  
+**Priority:** MVP
+
+### UC-77 — Attach/write a forge wiki via the forge's wiki API (capability varies)
+
+**Actor:** Orchestrator / adapter  
+**Goal:** Attach or write a forge wiki via the **forge's wiki API** (GitLab Wikis API,
+Gitea wiki endpoints) where git-clone is unavailable or API-write is preferred — with a
+**git-only fallback** for forges lacking a wiki API (**GitHub**).  
+**Source:** wikiengines, intent  
+**Notes:** Capability **varies by forge**: GitLab and Gitea expose REST wiki endpoints
+(list/get/create/edit/delete); **GitHub has no wiki content API** — git-only
+(`research/260614-forge-wikis-deep-dive/findings.md` §2). The adapter models the API as an
+**optional capability** over the universal git path; both converge on one git history. An
+external-API host sub-mode (UC-38) beside the file-store attach (UC-76). Feeds
+SHARD-WP-0002 T11 (capability flag), T14 (binding).  
+**Priority:** Later
+
 ---
 
 ## B. Knowledge work and collaboration
@@ -1287,6 +1323,8 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-73 | | | | ⬡ | ✓ |
 | UC-74 | | | | ⬡ | ✓ |
 | UC-75 | | | | ⬡ | ✓ |
+| UC-76 | | | | ⎇ | ✓ |
+| UC-77 | | | | ⎇ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -1759,6 +1797,36 @@ graph-query tier (UC-74), not the union default. Architecture logged for `SHARD-
 (T12/T16): typed-graph page payload, opaque identity, native-query tiering (SPARQL +
 federated SERVICE), sub-page provenance model.
 
+### forge-wikis mapping
+
+(⎇ UC-76–UC-77 are placed in the **wikiengines** matrix column; lineage = the **git-forge
+wikis deep dive**, `research/260614-forge-wikis-deep-dive/findings.md`.)
+
+| Forge-wiki mechanism (findings §) | Catalog UC |
+|-----------------------------------|------------|
+| Wiki = separate `<repo>.wiki.git` of Markdown; git log = journal; clone/push = write (§1) | UC-76 (new) |
+| Wiki content API varies: GitLab/Gitea yes, GitHub git-only (§2) | UC-77 (new) |
+| git **is** the canonical store (not a mirror) → write-by-commit safe (§3) | UC-40 (enriched); resolves UC-68 Q22 |
+| Dual-path attach: git clone vs forge wiki API (§2) | UC-02 (enriched) |
+| git-IS-store vs Wiki.js engine-maintained git mirror (§3) | UC-68 (enriched) |
+| Forge as API host for the wiki resource (GitLab/Gitea) (§2) | UC-38 (enriched) |
+| Page = file; sub-page = path; identity = path (§1, §4) | links UC-25 |
+| Overlay = branch/commit; forge lacks wiki-MRs → shard-wiki supplies review (§5) | links UC-04 |
+
+Note: The git-forge wikis (Gitea, GitLab, GitHub) are the **home case** — a wiki that is
+*literally a separate git repository of Markdown* (`<repo>.wiki.git`), so the **page model,
+history, and coordination journal map 1:1** to shard-wiki's medium with a near-zero adapter.
+The **git-clone path is universal** (all three); a **wiki content API** is an *optional,
+capability-varying* alternative (GitLab/Gitea have one, **GitHub is git-only**) — exactly
+the capability-awareness INTENT mandates (UC-77). The decisive contrast with Wiki.js
+(UC-68): there the DB is canonical and git is a *mirror* (write carefully, open-Q22); here
+**git IS the store**, so **write-by-commit is safe with no engine to race** — which
+*resolves Q22 for this case*. **Boundary recorded:** identity = path (cross-shard identity
+layered above, like a `wiki/` subdir shard); forge wikis lack wiki-MRs, so the
+overlay→review→apply flow is shard-wiki's to provide. Architecture logged for
+`SHARD-WP-0002` (T14/T11): `.wiki.git` clone as the canonical file-store attach, wiki API as
+an optional per-forge capability, git log adopted directly as the journal.
+
 ---
 
 ## Open questions
@@ -1820,5 +1888,11 @@ federated SERVICE), sub-page provenance model.
     query** (UC-74) a union-level capability or a pass-through to graph-capable shards? At
     what granularity is **provenance** recorded — per page (MVP) or per statement (UC-75)?
     (Wikibase dive §8.)
+25. For a **git-forge wiki** (UC-76/77), when a forge offers **both** git-clone and a wiki
+    API (GitLab/Gitea), which does the adapter prefer by default — git (universal, full
+    history) with API as fallback? And does the **code-repo `wiki/` subdir** shard share one
+    git+Markdown adapter with the **forge wiki repo** shard (parameterized by repo/path), or
+    stay distinct? Since forge wikis lack wiki-MRs, does shard-wiki supply the
+    overlay→review→apply layer? (Forge-wikis dive §8.)
 23. How does shard-wiki **honor/surface a shard's path-based access rules** (UC-06) in a
     projection without re-implementing its ACL engine? (Wiki.js dive §9.)