shard-wiki/spec/UseCaseCatalog.md

# UseCaseCatalog

Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-13

Promoted from `research/260608-c2-wiki-origins/`,
`research/260608-yawex-prior-art/`, `research/260608-federation-concepts/`, and
`research/260608-wikiengines-overview/`.
See InfoTechPrimers on coulomb.social for use-case catalog conventions.

## Conventions

Each use case lists:

- **Actor** — who initiates the action
- **Goal** — observable outcome
- **Source** — research lineage (`c2`, `yawex`, `federation`, `wikiengines`, `intent`, or combined)
- **Notes** — shard-wiki-specific constraints or open design points

Priority hints: **MVP** = likely early value; **Later** = important but not first slice.

---

## A. Information space and federation

*shard-wiki orchestration scenarios (INTENT + yawex federation seeds).*

### UC-01 — Standalone open wiki (L0)

**Actor:** Anonymous contributor  
**Goal:** Read and write wiki pages with full history and no external dependencies.  
**Source:** intent, c2  
**Notes:** Ward Cunningham / c2-style open mode (`WhyWikiWorks`). Recovery via Git
history, not gatekeeping. Aligns with L0 in `spec/ArchitectureBlueprint.md`.
**Priority:** MVP

### UC-02 — Attach a shard to an information space

**Actor:** Maintainer  
**Goal:** Attach a repository, directory, or other backend as a shard of a root entity.  
**Source:** intent, yawex  
**Notes:** yawex `Conf::TestWiki / FriendsWiki` foreshadows multiple roots/shards.
Preserve shard sovereignty and adapter capability profile.  
**Priority:** MVP

### UC-03 — Project a remote shard page locally

**Actor:** Reader  
**Goal:** View a page from a remote or read-only shard as a local projection with
provenance and freshness visible.  
**Source:** intent, yawex  
**Notes:** yawex `VIRTUAL` state = projection/cache. Lazy projection; no silent
mutation.  
**Priority:** Later

### UC-04 — Overlay edit on read-only shard

**Actor:** Author  
**Goal:** Propose changes to a remote/read-only page as overlay, draft, or patch
before destructive apply.  
**Source:** intent, yawex  
**Notes:** yawex append/comment workflow; c2 ThreadMode → refactor pattern.
Overlay-before-mutation principle.  
**Priority:** Later

### UC-05 — Union derived views

**Actor:** Reader  
**Goal:** Navigate BackLinks, RecentChanges, AllPages, SiteMap, or Search across
all attached shards as a federated graph.  
**Source:** intent, c2, yawex  
**Notes:** Present on both c2 (community nerve center) and yawex core pages.
BackLinks over the union link-graph is the strongest core candidate; per-shard
vs union scope remains open (see UC-19–UC-21).  
**Priority:** Later

### UC-06 — Authenticated team wiki (L2+)

**Actor:** Authenticated principal  
**Goal:** Read and write under role-based authorization with identity from an
external provider.  
**Source:** intent, yawex  
**Notes:** yawex htpasswd + per-topic `AccessControl` is prior art only;
shard-wiki delegates authentication, owns authorization
(`spec/ArchitectureBlueprint.md`).  
**Priority:** Later

### UC-07 — Detect and reconcile cross-shard divergence

**Actor:** Maintainer  
**Goal:** Identify when equivalent pages in different shards have diverged and
reconcile them under explicit policy.  
**Source:** intent  
**Notes:** Union without erasure — conflicts visible, not hidden. Complements
UC-27 (multi-version view) and SHARD-WP-0002 consensus-policy task.  
**Priority:** Later

### UC-26 — Fork page from remote shard into writable shard

**Actor:** Author  
**Goal:** Copy a page from a remote or read-only shard into a local writable
shard for independent editing, with provenance preserved.  
**Source:** federation, intent  
**Notes:** Fedwiki fork primitive. shard-wiki may realize as import, overlay
seed, or writable copy per policy — distinct from UC-04 (overlay without copy)
and UC-03 (projection only). Fork vs overlay vs import decided in
`SHARD-WP-0002`.  
**Priority:** Later

### UC-27 — View multiple versions of equivalent page

**Actor:** Reader  
**Goal:** See coexisting versions of the same topic from different shards or
authors without collapsing them into one canonical page.  
**Source:** federation, intent  
**Notes:** Fedwiki "chorus of voices"; INTENT union without erasure. Equivalent-
page identity model TBD (`SHARD-WP-0002`). Links UC-07 divergence detection.  
**Priority:** Later

### UC-28 — Carry forward pages from closed or archived shard

**Actor:** Maintainer or author  
**Goal:** Selectively import or re-project valuable pages from an archived,
read-only, or retired shard into an active information space.  
**Source:** federation  
**Notes:** Caulfield bounded conversation / reverse bit-rot. Optional space
lifecycle policy. Complements UC-02 attach and UC-26 fork at scale.  
**Priority:** Later

### UC-29 — Remix with portable attribution

**Actor:** Author  
**Goal:** Reuse content across shards or spaces with attribution and edit
history intact, without manual copy-paste.  
**Source:** federation, intent  
**Notes:** Fedwiki journal travels with page; shard-wiki coordination journal +
per-shard history. Frictionless reuse principle (~15s not ~15min).  
**Priority:** Later

### UC-30 — Time-bounded collaboration space

**Actor:** Facilitator  
**Goal:** Run a collaboration period on a dedicated information space or shard
subset, then archive it while allowing selective carry-forward.  
**Source:** federation  
**Notes:** Fedwiki "happening"; lifecycle is configurable policy, not a hard-
coded core behavior. Relates to UC-28.  
**Priority:** Later

### UC-31 — Subscribe to remote shard changes

**Actor:** Maintainer or reader  
**Goal:** Receive timely notice when pages change on attached remote shards,
triggering projection refresh or reconciliation review.  
**Source:** federation, intent  
**Notes:** ikiwiki pinger/pingee; ActivityPub Create/Update; polling fallback.
Transport is adapter concern; freshness surfaced in UC-24.  
**Priority:** Later

### UC-32 — Transclude remote span with live freshness

**Actor:** Author or reader  
**Goal:** Embed a portion of a remote page inline with visible origin and
refreshable content.  
**Source:** federation, intent  
**Notes:** Xanadu transclusion pattern; stronger than UC-03 whole-page
projection. Provenance and staleness must be explicit.  
**Priority:** Later

### UC-33 — Git-branch an information space

**Actor:** Maintainer  
**Goal:** Fork the coordination journal and attached shard configuration into a
divergent information space without destroying the original.  
**Source:** federation, intent  
**Notes:** ikiwiki wiki-branch pattern; Git-backed coordination per INTENT.
Space-level fork — distinct from UC-26 page-level fork.  
**Priority:** Later

### UC-34 — Attach a structured or semantic shard without lossy flattening

**Actor:** Maintainer  
**Goal:** Attach an engine whose pages carry structured or queryable data beyond
Markdown (Semantic MediaWiki annotations, XWiki objects/forms) and project it
without silently discarding the structure.  
**Source:** wikiengines, intent  
**Notes:** Engine scan shows "wiki page" spans flat Markdown to queryable
knowledge objects. Markdown-first must **degrade gracefully**, not flatten:
needs a passthrough / sidecar-metadata / provenance escape hatch. Page-model
question deferred to `SHARD-WP-0002` (findings §6 Q1). Distinct from UC-02
(assumes Markdown-shaped pages).  
**Priority:** Later

### UC-35 — Attach a shard with coarse write granularity

**Actor:** Maintainer  
**Goal:** Attach a backend whose unit of write is not the page — a single-file
wiki (TiddlyWiki) or a whole-space/DB-transaction engine — and have shard-wiki
respect that granularity instead of assuming per-page writes.  
**Source:** wikiengines, intent  
**Notes:** Capability-aware adapters: the **capability profile must encode write
granularity** (per-page / per-file / per-space / append-only). Overlay and
patch flows must adapt (findings §5 #1). Affects conflict scope and locking.  
**Priority:** Later

### UC-36 — Supply a git-addressable history to an internal-history engine

**Actor:** Maintainer  
**Goal:** Attach an engine whose revisions live only in its own database
(Confluence, MediaWiki) and give the information space a portable, git-backed
history it otherwise lacks.  
**Source:** wikiengines, intent  
**Notes:** Many engines expose revisions but not portable, git-style history.
The **coordination journal** supplies the Git-addressable layer (INTENT). Open:
is the journal authoritative or a mirror reconciled back to the engine
(findings §6 Q3)? Complements UC-07 divergence and UC-24 provenance.  
**Priority:** Later

### UC-37 — Attach a static engine export as a read-only backup shard

**Actor:** Maintainer  
**Goal:** Attach a one-shot export with no live origin — a MediaWiki XML dump, an
HTML mirror, or an archived/read-only C2 — as a read-only cache/backup/patch
target.  
**Source:** wikiengines, intent  
**Notes:** Graceful degradation — a frozen export is still a legitimate
participant. Distinct from UC-03 (live projection with a reachable origin) and
UC-28 (carry pages *forward* into a new space); here the dump itself is the
shard. Read-only mode in `spec/ArchitectureBlueprint.md`.  
**Priority:** Later

---

## B. Knowledge work and collaboration

*Patterns from c2 social conventions and yawex authoring workflows.*

### UC-08 — Quick idea capture

**Actor:** Contributor  
**Goal:** Capture a thought as a page and link to related pages, including ones
that do not exist yet.  
**Source:** c2  
**Notes:** c2 *incremental* and *open* design principles; Wiki = "quick web."
Markdown-first wikilink/red-link extension (yawex TRANSFORM) applies.  
**Priority:** MVP

### UC-09 — Sandbox first edit

**Actor:** New contributor  
**Goal:** Learn editing mechanics in a safe sandbox without affecting production
pages.  
**Source:** c2  
**Notes:** c2 `WikiWikiSandbox`, `WelcomeVisitors` onboarding path.  
**Priority:** MVP

### UC-10 — Discussion to consensus document

**Actor:** Contributor (often acting as WikiMaster)  
**Goal:** Refine a ThreadMode conversation into an unsigned DocumentMode page
that reflects community consensus.  
**Source:** c2  
**Notes:** ADD / EDIT / SPLIT / CAPTURE thread contributions; prefer rewrite
over stacked clarifications (`DocumentMode`, `GoodStyle`). Mechanism in core
vs reference UI TBD.  
**Priority:** Later

### UC-11 — Distill experience into reusable knowledge

**Actor:** Practitioner  
**Goal:** Turn field notes, threads, or project experience into durable,
reusable artifacts (patterns, methods, checklists).  
**Source:** c2, yawex  
**Notes:** c2 `PatternMode`, PPR "People, Projects & Patterns"; yawex blueprint
pages (UC-15). Not an encyclopedia (`WikiIsNotWikipedia`).  
**Priority:** Later

### UC-12 — Practitioner field notes

**Actor:** Contributor  
**Goal:** Maintain informal, subjective programming and project history that is
explicitly work-in-progress.  
**Source:** c2  
**Notes:** `InformalHistoryOfProgrammingIdeas`, `WorkInProgress`. Complements
UC-11; distinct from reference-grade documentation in `docs/` or `spec/`.  
**Priority:** MVP

### UC-13 — Community presence

**Actor:** Visitor  
**Goal:** Signal participation and discover who is active in the information
space.  
**Source:** c2  
**Notes:** c2 `RecentVisitors`, `PeopleIndex`. Optional attribution at L1+
(`ArchitectureBlueprint` L1 Attributed mode).  
**Priority:** Later

### UC-14 — Self-curating knowledge base

**Actor:** Community  
**Goal:** Improve collective quality through open editing, refactoring, and
convergent deduplication rather than gatekeeping.  
**Source:** c2  
**Notes:** `WhyWikiWorks`, `RefactorDontDelete`, `Convergent` design principle.
shard-wiki adds Git history as structural safety net beyond social norms.  
**Priority:** MVP

### UC-15 — Create page from blueprint

**Actor:** Author  
**Goal:** Instantiate a new page or topic structure from a template, duplicating
an agreed layout or subtree.  
**Source:** yawex  
**Notes:** yawex blueprint pages. Distinct from UC-08 (blank capture) and UC-10
(refactoring existing discussion).  
**Priority:** Later

### UC-16 — Append or comment without full edit

**Actor:** Author  
**Goal:** Add material to a page without replacing the entire body — lightweight
patch, comment, or append workflow.  
**Source:** yawex, c2  
**Notes:** yawex append/comment; c2 ThreadMode ADD. Maps to overlay model (UC-04)
for read-only/remote shards; direct append where adapter allows.  
**Priority:** Later

---

## C. Discovery and navigation

*Derived views and browse patterns from c2 and yawex.*

### UC-17 — Change radar

**Actor:** Reader or maintainer  
**Goal:** See what changed recently across pages and who changed it.  
**Source:** c2, yawex  
**Notes:** c2 `RecentChanges`, `QuickChanges`, `RecentChangesJunkie`; yawex
`RecentChanges` core page. Union scope in UC-05; this UC covers the user need
at any scope.  
**Priority:** MVP

### UC-18 — BackLinks navigation

**Actor:** Reader  
**Goal:** Find pages that link to the current page.  
**Source:** c2, yawex  
**Notes:** Link-graph query. Strong core candidate for federated union (UC-05).  
**Priority:** Later

### UC-19 — All pages and site map browse

**Actor:** Reader  
**Goal:** Survey the full page inventory or hierarchical site structure.  
**Source:** c2, yawex  
**Notes:** yawex `AllPages`, `SiteMap` core pages; c2 `WikiList`, categories,
`RoadMaps`. Namespace/path model affects presentation (UC-22).  
**Priority:** Later

### UC-20 — Full-text search

**Actor:** Reader  
**Goal:** Find pages by content keyword or phrase.  
**Source:** c2, yawex  
**Notes:** yawex `SearchPage`; c2 `FindPage`, `SearchHelper`. Core vs
adapter-provided indexing TBD.  
**Priority:** Later

### UC-21 — Serendipitous browse

**Actor:** Reader  
**Goal:** Discover unexpected relevant pages without a specific search target.  
**Source:** c2  
**Notes:** `RandomPages`, `VisualTour`, `LikePages`, `StartingPoints`.  
**Priority:** Later

### UC-22 — Namespace and path navigation

**Actor:** Reader or author  
**Goal:** Resolve and navigate pages using relative (`../`), absolute (`/`), and
normalized paths within a topic hierarchy.  
**Source:** yawex  
**Notes:** yawex topics-as-directories; page-resolution state space is
inspiration only for federation design (not inherited as API).  
**Priority:** Later

### UC-23 — Soft topic creation via red link

**Actor:** Author  
**Goal:** Follow a link to a nonexistent page and create it on first write.  
**Source:** c2, yawex  
**Notes:** c2 `PageName?`; yawex red-`?` link semantics. TRANSFORM to
CommonMark wikilink + red-link extension.  
**Priority:** MVP

---

## D. Provenance and page metadata

*yawex `Page::info` and c2 attribution norms.*

### UC-24 — Inspect page provenance

**Actor:** Reader  
**Goal:** See source shard, modification time, freshness, editor attribution,
edit count, and whether the page has local overlays or diverges elsewhere.  
**Source:** yawex, c2, intent  
**Notes:** yawex `Page::info`; c2 optional `UserName` signing. INTENT explicit
provenance principle.  
**Priority:** Later

### UC-25 — Collaborative glossary and precise naming

**Actor:** Community  
**Goal:** Build a shared vocabulary of precise page titles and linked terms that
reduce ambiguity across the information space.  
**Source:** c2, yawex  
**Notes:** c2 flat namespace + `WikiWord` / `Precise` principle; yawex
CamelCase and `[[free links]]`. Markdown-first link semantics TBD.  
**Priority:** Later

---

## Traceability

| UC | c2 research | yawex research | federation research | wikiengines research | INTENT |
|----|-------------|----------------|---------------------|----------------------|--------|
| UC-01 | ✓ | | | | ✓ |
| UC-02 | | ✓ | | | ✓ |
| UC-03 | | ✓ | ✓ | | ✓ |
| UC-04 | ✓ | ✓ | ✓ | | ✓ |
| UC-05 | ✓ | ✓ | ✓ | | ✓ |
| UC-06 | | ✓ | | | ✓ |
| UC-07 | | | ✓ | | ✓ |
| UC-26 | | | ✓ | | ✓ |
| UC-27 | | | ✓ | | ✓ |
| UC-28 | | | ✓ | | |
| UC-29 | | | ✓ | | ✓ |
| UC-30 | | | ✓ | | |
| UC-31 | | | ✓ | | ✓ |
| UC-32 | | | ✓ | | ✓ |
| UC-33 | | | ✓ | | ✓ |
| UC-34 | | | | ✓ | ✓ |
| UC-35 | | | | ✓ | ✓ |
| UC-36 | | | | ✓ | ✓ |
| UC-37 | | | | ✓ | ✓ |
| UC-08 | ✓ | | |
| UC-09 | ✓ | | |
| UC-10 | ✓ | | |
| UC-11 | ✓ | ✓ | |
| UC-12 | ✓ | | |
| UC-13 | ✓ | | |
| UC-14 | ✓ | | ✓ |
| UC-15 | | ✓ | |
| UC-16 | ✓ | ✓ | |
| UC-17 | ✓ | ✓ | |
| UC-18 | ✓ | ✓ | |
| UC-19 | ✓ | ✓ | |
| UC-20 | ✓ | ✓ | |
| UC-21 | ✓ | | |
| UC-22 | | ✓ | |
| UC-23 | ✓ | ✓ | |
| UC-24 | ✓ | ✓ | ✓ |
| UC-25 | ✓ | ✓ | |

### c2 synthesis mapping

| Research ID | Catalog UC |
|-------------|------------|
| UC-C2-01 Quick idea capture | UC-08 |
| UC-C2-02 Collaborative glossary | UC-25 |
| UC-C2-03 Discussion → consensus doc | UC-10 |
| UC-C2-04 Pattern mining | UC-11 |
| UC-C2-05 Community guest book | UC-13 |
| UC-C2-06 Change radar | UC-17 |
| UC-C2-07 Self-curating knowledge base | UC-14 |
| UC-C2-08 Sandbox learning | UC-09 |
| UC-C2-09 Serendipitous browse | UC-21 |
| UC-C2-10 Practitioner field notes | UC-12 |
| UC-C2-11 Team memory for methods | UC-11, UC-12 |
| UC-C2-12 Soft creation of missing topics | UC-23 |

### yawex KEEP mapping

| yawex KEEP item | Catalog UC |
|-----------------|------------|
| Derived views (BackLinks, RecentChanges, AllPages, SiteMap, Search) | UC-05, UC-17–UC-20 |
| Topic = namespace hierarchy | UC-22 |
| Append/comment workflow | UC-04, UC-16 |
| Blueprint pages | UC-15 |
| Provenance hooks | UC-24 |
| Page classes (local/global/virtual) | UC-02, UC-03 (shard roles) |
| Wikilink / red-link semantics | UC-08, UC-23, UC-25 |

### federation research mapping

| Research ID (findings §7) | Catalog UC |
|---------------------------|------------|
| UC-FED-01 Fork page from remote shard | UC-26 |
| UC-FED-02 View multiple versions of equivalent page | UC-27 |
| UC-FED-03 Carry forward from closed/archived shard | UC-28 |
| UC-FED-04 Remix with portable attribution | UC-29 |
| UC-FED-05 Time-bounded collaboration space | UC-30 |
| UC-FED-06 Subscribe to remote shard changes | UC-31 |
| UC-FED-07 Transclude remote span | UC-32 |
| UC-FED-08 Git-branch information space | UC-33 |

### wikiengines mapping

| Engine-landscape finding | Catalog UC |
|--------------------------|------------|
| Structured/semantic engines (Semantic MediaWiki, XWiki) — pages as queryable objects | UC-34 |
| Coarse write granularity (TiddlyWiki single-file; whole-space DB writes) | UC-35 |
| Internal-only revision history (Confluence, MediaWiki) needs portable git history | UC-36 |
| Static exports / read-only archives (MediaWiki XML dump, archived C2, HTML mirror) | UC-37 |

Note: the scan mostly **reinforced** existing UCs and the L0→L4 ladder rather than
adding scenarios — its primary yield is adapter-contract constraints
(`research/260608-wikiengines-overview/findings.md` §3, §5), tracked in
`workplans/SHARD-WP-0002-federation-architecture.md`. UC-34–UC-37 are the
genuinely new attachment scenarios it surfaced.

---

## Open questions

1. Which UC items are **MVP for L0 standalone** vs requiring federation or L2+?
2. Which derived views (UC-05, UC-17–UC-20) are **core orchestrator** vs
   **adapter-provided**?
3. Do c2 collaboration patterns (UC-10, UC-14) belong in **core**, **reference
   UI**, or **`wiki/` social convention** only?
4. Should UC-12 and `WikiIsNotWikipedia` be elevated into
   `ProductRequirementsDocument.md` as explicit product identity?
5. Which federation UCs (UC-26–UC-33) are **MVP** vs deferred until
   `SHARD-WP-0002` architecture decisions land?
6. Does UC-32 (transclusion) belong in core orchestrator or adapter/UI layer?