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/, research/260608-wikiengines-overview/, research/260613-xwiki-deep-dive/, and research/260613-twiki-deep-dive/. 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). yawex's model traces to TWiki's per-topic ALLOW/DENY TOPICVIEW/CHANGE/RENAME — the origin reference for shard-wiki's optional per-page ACL at L4 (research/260613-twiki-deep-dive/findings.md §4).
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. XWiki deep dive adds a concrete push transport: an engine event bus (ObservationManager DocumentUpdatedEvent) consumed by a listener, vs polling REST history (research/260613-xwiki-deep-dive/findings.md §2.5, §8 Q4).
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). XWiki is the concrete exemplar: pages carry typed XObjects against an XClass schema (research/260613-xwiki-deep-dive/findings.md §2.3); UC-39 covers the extreme where the page is only structure. TWiki shows the git-friendly variant: TWiki Forms store fields as %META:FIELD% inside the topic text file, so structure is diffable rather than locked in a DB (research/260613-twiki-deep-dive/findings.md §2.3).
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. XWiki's internal RCS table (xwikircs) is a concrete instance (research/260613-xwiki-deep-dive/findings.md §2.4). This UC is supplementation (the engine's past is DB-locked); where history is already in an open file format (TWiki RCS .txt,v) it can instead be imported — see UC-41.
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

UC-38 — Make a wiki engine federation-capable via its native extension API

Actor: Engine developer / integrator
Goal: Turn an existing wiki engine into a federation participant by hosting a shard-wiki adapter inside the engine through its own extension interface, rather than scraping it from outside.
Source: wikiengines, intent
Notes: Realizes INTENT composable integration — first UC for the engine-side direction (others attach engines from outside). XWiki is the proof case: its component model (@Component + role hint) can replace auth/storage/rights, its REST API and ObservationManager give transport + change events, and UIX adds surfacing — enough to host a high-fidelity adapter (research/260613-xwiki-deep-dive/findings.md §3). Trade-off vs an external REST adapter (needs deploy access, higher fidelity) is open (findings §8 Q3). Generalizes beyond XWiki: TWiki's plugin handler API (beforeSaveHandler, afterRenameHandler, REST handlers) is an equivalent host surface (research/260613-twiki-deep-dive/findings.md §3).
Priority: Later

UC-39 — Attach a wiki-as-application-platform shard (pages as typed records)

Actor: Maintainer
Goal: Attach an engine where pages are structured records or forms with little or no prose body (XWiki AppWithinMinutes apps / XObjects), and represent them in the union without inventing a fake Markdown body.
Source: wikiengines, intent
Notes: The extreme of UC-34 — not annotations on prose but bodiless structured pages. Forces the question: does the page model require a Markdown body, or can a page be purely typed data (research/260613-xwiki-deep-dive/findings.md §8 Q2)? Affects union views, diff, and search. Deferred to SHARD-WP-0002.
Priority: Later

UC-40 — Attach a file-backed engine's on-disk store directly

Actor: Maintainer
Goal: Attach a live engine whose content is plain files on disk — TWiki data/<Web>/<Topic>.txt, DokuWiki pages, a Gollum/ikiwiki repo — by reading its backing store directly as a folder shard, instead of (or alongside) going through its runtime API.
Source: wikiengines, intent
Notes: One backend, two attachment paths with different fidelity/consistency: the on-disk store (offline-capable, git-native for repo-backed engines, but risks reading inconsistent state under a running engine) vs the runtime API (consistent, respects engine logic, but requires the engine up). Capability profile must express the choice (research/260613-twiki-deep-dive/findings.md §5–§6, §8 Q1). Distinct from UC-37 (no live origin) and broader than UC-02's generic attach.
Priority: Later

UC-41 — Import an engine's native file history into the coordination journal

Actor: Maintainer
Goal: When an engine already keeps history in an open file format (TWiki/yawex RCS .txt,v), import that history into the Git-backed coordination journal preserving authorship and timestamps — not just start a fresh journal going forward.
Source: wikiengines, intent
Notes: History migration with fidelity, distinct from UC-36 supplementation (where the engine's past is locked in a DB and the journal can only begin now). Open: is the imported history authoritative or a one-time backfill (research/260613-twiki-deep-dive/findings.md §8 Q2)? Strengthens recoverability (INTENT History as the safety net).
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-38				✓	✓
UC-39				✓	✓
UC-40				✓	✓
UC-41				✓	✓
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
Engine hosts adapter via native extension API (XWiki components/REST/UIX)	UC-38
Wiki-as-application-platform, bodiless typed pages (XWiki AppWithinMinutes/XObjects)	UC-39
Attach a file-backed engine's on-disk store directly (TWiki data dir, DokuWiki)	UC-40
Import an engine's native file history (TWiki RCS .txt,v) into the journal	UC-41

Note: the landscape 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 attachment scenarios it surfaced. UC-38–UC-39 come from the XWiki deep dive (research/260613-xwiki-deep-dive/findings.md §7); UC-40–UC-41 from the TWiki deep dive (research/260613-twiki-deep-dive/findings.md §7), which also enriched UC-06 (TWiki per-topic ACL → yawex), UC-34 (file-embedded %META%), UC-36 (RCS vs DB history), and UC-38 (TWiki plugin handlers as an adapter host).

---

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?