shard-wiki/spec/UseCaseCatalog.md

# UseCaseCatalog

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

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/`,
`research/260613-twiki-deep-dive/`, `research/260613-foswiki-deep-dive/`,
`research/260614-xanadu-deep-dive/`, `research/260614-zigzag-deep-dive/`, and
`research/260614-roam-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). ZigZag deep dive reframes these views
under one vocabulary: each is a **dimension + raster** (RecentChanges along `d.recent`,
AllPages along `d.alphabetical`, SiteMap as an H-view over the namespace dimensions),
navigable via UC-47 (`research/260614-zigzag-deep-dive/findings.md` §5). Note: the
many-to-many link/backlink graph stays a **separate graph index**, not a zz-rank.  
**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`. Should record a **created-from genealogy edge** in the coordination
journal so the lineage is navigable as a dimension (UC-49,
`research/260614-zigzag-deep-dive/findings.md` §9).  
**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`) — Xanadu deep dive offers a path-independent
detection mechanism via content-identity / span-set intersection (UC-46,
`research/260614-xanadu-deep-dive/findings.md` §5, §8.2). 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, xanadu  
**Notes:** Fedwiki journal travels with page; shard-wiki coordination journal +
per-shard history. Frictionless reuse principle (~15s not ~15min). Xanadu
**transcopyright**: a reference carries provenance *and reuse terms* with it, so
attribution/permission travel with the span — but reuse policy stays configurable, not
baked into the substrate (`research/260614-xanadu-deep-dive/findings.md` §6); links the
authz-in-core L0→L4 ladder decision. Remix should also record a **genealogy edge**
(UC-49) so reuse lineage is navigable, not just attributed.  
**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. Xanadu deep dive sharpens this:
transclusion should be **content-identity based and bidirectional** (content is "knowably
in more than one place" and aware of its appearances), not a one-way path fetch —
enables UC-45 reverse lookup (`research/260614-xanadu-deep-dive/findings.md` §4). See
UC-44 for the whole-page composition-manifest form. **Roam ships this**: block embeds
transclude by `:block/uid` live (not copied), proving transclusion is a cheap data-layer
capability over an addressable store (`research/260614-roam-deep-dive/findings.md` §3,
§7) — argues for transclusion in core over the union, surfaced by UI. Depends on span
addressing (UC-51).  
**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). Roam is the modern exemplar:
`key:: value` attributes over a datom graph, queryable via Datalog
(`research/260614-roam-deep-dive/findings.md` §3, §4) — structure to preserve via
sidecar metadata, and a candidate for query delegation (UC-52).  
**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. Roam marks
the **fine extreme** — block-level writes (`block.create/update/move/delete`), the
opposite of TiddlyWiki's whole-file granularity
(`research/260614-roam-deep-dive/findings.md` §6).  
**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). **Roam Depot** is the modern
template: an extension default-exports `onload`/`onunload` and drives
`window.roamAlphaAPI` read (`q`/`pull`) + write (`block.*`/`page.create`)
(`research/260614-roam-deep-dive/findings.md` §5) — note Roam's API runs *inside* the
client, so write-through requires in-engine hosting (findings §11 Q2).  
**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`.
Foswiki shows a middle point: MetaDataPlugin stores **multiple** structured records
per topic, still as `%META%` in text (`research/260613-foswiki-deep-dive/findings.md`
§4) — the page model must allow N typed records, not one form.  
**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. Foswiki's
**PlainFile** store (timestamped whole-version copies, no RCS) is a cleaner
direct-attach target than RCS diffs (`research/260613-foswiki-deep-dive/findings.md`
§2.2).  
**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

### UC-42 — Read and write a non-Markdown shard via lossless syntax translation

**Actor:** Author or maintainer  
**Goal:** Attach a shard whose native markup is not Markdown (TWiki/Foswiki TML,
XWiki syntax) and read it into the Markdown-first model — and write Markdown overlays
back — through **bidirectional, lossless syntax translation**, instead of treating it
as read-only.  
**Source:** wikiengines, intent  
**Notes:** Realizes *Markdown-first, backend-neutral* for **prose** (UC-34/39 cover
*structure*). Feasibility proven by Foswiki's **WysiwygPlugin** (TML→HTML for editing,
HTML→TML losslessly on save) (`research/260613-foswiki-deep-dive/findings.md` §5).
Open: is round-trip lossless enough, or must overlays be stored in the shard's native
syntax to be safe (findings §9 Q2)? Without this, non-Markdown shards degrade to
read-only (UC-03) — a graceful-degradation floor, not the goal.  
**Priority:** Later

### UC-43 — Tolerate a shard's storage-backend swap without losing identity

**Actor:** Maintainer  
**Goal:** Keep a shard attached, with its provenance and history intact, when its
underlying storage backend changes — e.g. a Foswiki wiki migrated RCS→PlainFile, or a
folder shard promoted into Git.  
**Source:** wikiengines, intent  
**Notes:** Foswiki proves backends are swappable under a stable identity via its
versioned `Foswiki::Store` interface (`research/260613-foswiki-deep-dive/findings.md`
§2). shard-wiki orchestration robustness: a shard's identity/attachment is **not** its
storage format. Open: detect the swap and preserve history across it (findings §9 Q3).
Relates to UC-40 (attach path) and UC-41 (history import) but is about *change under a
live attachment*, not initial attach.  
**Priority:** Later

### UC-44 — Compose a page by reference (xanadoc / EDL manifest)

**Actor:** Author  
**Goal:** Author a page whose canonical body is an ordered list of spans pulled by
reference from one or more shards, stored as a composition manifest rather than a copy.  
**Source:** xanadu, intent  
**Notes:** Xanadu EDL/xanadoc — a document that contains no content, only span
references plus link tables, assembled by the client
(`research/260614-xanadu-deep-dive/findings.md` §2). The reference-not-copy embodiment
of INTENT "lazy projection over eager copying" and "union without erasure". Stronger
than UC-32 (single inline span): the *whole page* is a manifest. Requires the wiki page
model to admit a reference-list canonical form — flag for page-model spec. Open:
core vs. adapter vs. reference-UI; MVP vs. deferred with UC-32 (findings §11 Q2).  
**Priority:** Later

### UC-45 — Reverse transclusion: find all appearances of a span

**Actor:** Reader or maintainer  
**Goal:** Given a span (paragraph/section/page), find every page and shard where that
content appears or is transcluded.  
**Source:** xanadu, intent  
**Notes:** Xanadu content "remembers its identity and traces back to all its
appearances" (`research/260614-xanadu-deep-dive/findings.md` §4). Union BackLinks
generalized from page links to sub-page content identity. Depends on a content-identity
mechanism (UC-46) and on span addressing as an adapter capability (`SHARD-WP-0002`).
Open: exact-identity only vs. fuzzy/derived tracking (findings §11 Q4).  
**Priority:** Later

### UC-46 — Detect content-identity equivalence across shards

**Actor:** Reader or orchestrator  
**Goal:** Determine that two pages in different shards are the same or derived content
by content/span overlap, without relying on matching titles or paths.  
**Source:** xanadu, intent  
**Notes:** Xanadu compares documents by **span-set intersection** over an invariant
content pool (`research/260614-xanadu-deep-dive/findings.md` §5). Supplies the
equivalent-page identity model left open in UC-27 with a *path-independent* detection
mechanism — equivalence is detected, not enforced (parallel versions stay visible per
UC-27, not collapsed). Adapter advertises its content fingerprint (Git blob hash,
normalized-text hash, none). Open: core vs. adapter-index; cost at wiki scale without
enfilades (findings §11 Q3).  
**Priority:** Later

### UC-47 — Navigate the information space along a chosen relationship dimension

**Actor:** Reader  
**Goal:** Traverse pages along a *selected* relationship axis — namespace, created-from
genealogy, version history, owning shard, equivalence, or recent-change order — rather
than a single fixed hierarchy.  
**Source:** zigzag, intent  
**Notes:** ZigZag/zzstructure treats each relationship as a first-class **dimension**;
a page is a cell at the intersection of many independent ranks
(`research/260614-zigzag-deep-dive/findings.md` §2, §5). Reframes the existing derived
views (UC-05, UC-17–UC-20) as *dimensions + rasters* under one vocabulary. Embodies
union-without-erasure: every relationship co-equal, none privileged. Open: public
navigation API vs. internal model (findings §10 Q1).  
**Priority:** Later

### UC-48 — Pivot two relationships into a cross-tab view (H-view)

**Actor:** Reader  
**Goal:** Cross-tabulate the union by two dimensions at once — e.g. namespace × shard,
or page × versions-across-shards — and pivot to re-cross by a different pair.  
**Source:** zigzag  
**Notes:** ZigZag **H-view** shows two dimensions through a cursor, one horizontal one
vertical, with only existing cells present (`research/260614-zigzag-deep-dive/findings.md`
§3). A differentiated exploration primitive for federation/provenance. Open: reference-UI
investment vs. research-only (findings §10 Q4).  
**Priority:** Later

### UC-49 — Navigate created-from / fork genealogy as a first-class dimension

**Actor:** Reader or maintainer  
**Goal:** Follow a page's derivation lineage — what it was forked/remixed/imported
from, and what was derived from it — as a navigable rank.  
**Source:** zigzag, federation, intent  
**Notes:** Genealogy is a *functional* relation (one origin) that fits a zzstructure
dimension natively (`research/260614-zigzag-deep-dive/findings.md` §4, §5). Requires a
genealogy edge recorded at fork/remix/import time (UC-26, UC-29) in the coordination
journal. Makes provenance a traversal, not a buried footer (complements UC-24).  
**Priority:** Later

### UC-50 — Attach a block-graph database wiki as a shard, mapping blocks to the page model

**Actor:** Maintainer  
**Goal:** Attach a block-first, DB-backed graph tool (Roam-style) as a shard via its
query/CRUD API, mapping its blocks onto shard-wiki's Markdown page model without
flattening the structure.  
**Source:** roam, intent  
**Notes:** Roam's graph is a DataScript datom DB where a *page* is the node carrying
`:node/title` and nested *blocks* are addressable spans
(`research/260614-roam-deep-dive/findings.md` §2, §6). Clean mapping rule: titled node
= page, nested blocks = spans, attributes = sidecar metadata (honors UC-34 no-lossy-
flatten). DB-backed/API-attached path (like XWiki UC-38), **not** the file-store path
(UC-40). Write-through requires hosting the adapter inside the engine (Roam Depot),
else degrade to read/projection/overlay-target (findings §11 Q2).  
**Priority:** Later

### UC-51 — Adopt a shard's native span IDs as portable span addresses

**Actor:** Orchestrator / adapter  
**Goal:** Where a backend mints stable sub-page identifiers (Roam `:block/uid`), adopt
them as the span address for transclusion, overlay, and reverse-lookup, rather than
inventing one.  
**Source:** roam, xanadu, intent  
**Notes:** Roam ships the fine-grained stable address that Xanadu's tumblers
(`research/260614-xanadu-deep-dive/findings.md` §3) and the catalog left open — a short
opaque per-block UID, public and referenceable (`research/260614-roam-deep-dive/findings.md`
§2, §7). Enables UC-44/45 at sub-page granularity; falls back to content-fingerprint
(UC-46) or path+range where no native ID exists. Open: use native ID directly or wrap in
a shard-scoped address to avoid cross-shard collision and survive projection (findings
§11 Q1).  
**Priority:** Later

### UC-52 — Delegate derived views to a shard's native query engine

**Actor:** Orchestrator  
**Goal:** When a shard exposes a native query engine, compute derived views (backlinks,
recent changes, typed queries) by delegating to it instead of scanning the projection.  
**Source:** roam, intent  
**Notes:** In Roam, derived views *are* Datalog queries over the datom graph
(`research/260614-roam-deep-dive/findings.md` §4). Makes "native query" an adapter
capability the orchestrator can key off (vs. computing views itself over the
projection). Operationalizes the ZigZag "dimensions + rasters" insight
(`research/260614-zigzag-deep-dive/findings.md` §5) and relates to UC-05/UC-34.  
**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). ZigZag deep dive: treat
the namespace hierarchy as **one dimension among many** (encoded left-child/right-sibling
as two zz-dimensions), not the privileged structure — consistent with mechanism over
policy; navigate it as one axis via UC-47 (`research/260614-zigzag-deep-dive/findings.md`
§4, §7.1).  
**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. Xanadu deep dive: provenance is *structural*, not decorative —
content remembers where it came from and where it is reused (UC-45), built into the
storage model rather than added after the fact
(`research/260614-xanadu-deep-dive/findings.md` §4, §8.1).  
**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-42 | | | | ✓ | ✓ |
| UC-43 | | | | ✓ | ✓ |
| UC-44 | | | ✓† | | ✓ |
| UC-45 | | | ✓† | | ✓ |
| UC-46 | | | ✓† | | ✓ |
| UC-47 | | | ‡ | | ✓ |
| UC-48 | | | ‡ | | |
| UC-49 | | | ‡ | | ✓ |
| UC-50 | | | | § | ✓ |
| UC-51 | | | | § | ✓ |
| UC-52 | | | | § | ✓ |
| 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 |
| Lossless syntax translation for a non-Markdown shard (Foswiki WysiwygPlugin TML↔HTML) | UC-42 |
| Tolerate a shard's storage-backend swap (Foswiki RCS↔PlainFile) under stable identity | UC-43 |

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). UC-42–UC-43 come
from the **Foswiki deep dive** (`research/260613-foswiki-deep-dive/findings.md` §8),
which also enriched UC-39 (MetaDataPlugin multi-record), UC-40 (PlainFile store), and
logged the `Foswiki::Store` versioned interface as **adapter-contract prior art** for
`SHARD-WP-0002` (no UC — architecture).

### xanadu mapping

(† UC-44–UC-46 are placed in the **federation** matrix column as the nearest existing
source; their true lineage is the **Xanadu deep dive**,
`research/260614-xanadu-deep-dive/findings.md`.)

| Xanadu mechanism (findings §) | Catalog UC |
|-------------------------------|------------|
| EDL/xanadoc — document as a manifest of span references, not content (§2) | UC-44 |
| Content "knowably in more than one place," remembers its appearances (§4) | UC-45 |
| Version/document comparison by span-set intersection, content identity (§5) | UC-46 |
| Content-identity, bidirectional transclusion (§4) | UC-32 (enriched) |
| Path-independent equivalence detection for parallel versions (§5) | UC-27 (enriched) |
| Transcopyright — reuse terms travel with the reference (§6) | UC-29 (enriched) |
| Structural provenance — content remembers origin and reuse (§4, §8.1) | UC-24 (enriched) |

Note: Xanadu is **conceptual prior art, not a candidate shard backend** — it never
shipped at scale and there is nothing to attach. Its yield is *mechanism*:
**reference-not-copy** documents (validating projection + overlay + union),
content-identity transclusion, and the still-open **portable span-address** problem
(tumblers), logged as adapter-contract architecture for `SHARD-WP-0002` (span
addressing as an adapter capability; content fingerprint; composition manifests;
reuse-terms metadata — `research/260614-xanadu-deep-dive/findings.md` §10). The dive
also recorded **design-bug boundaries**: shard-wiki **rejects** Xanadu's
single-global-docuverse premise, single-canonical-instance model, and baked-in economic
policy (findings §8.2), as these violate shard sovereignty, parallel-version support
(UC-27), and mechanism-over-policy.

### zigzag mapping

(‡ UC-47–UC-49 are placed in the **federation** matrix column as the nearest existing
source; their true lineage is the **ZigZag deep dive**,
`research/260614-zigzag-deep-dive/findings.md`.)

| ZigZag / zzstructure mechanism (findings §) | Catalog UC |
|---------------------------------------------|------------|
| Each relationship is a first-class **dimension**; a page is a cell at many ranks (§2, §5) | UC-47 |
| **H-view** — pivot two dimensions into a cross-tab (§3) | UC-48 |
| **Genealogy** as a functional dimension fitting a zz-rank (§4, §5) | UC-49 |
| Hierarchy is **one dimension among many** (left-child/right-sibling) (§4, §7.1) | UC-22 (enriched) |
| Derived views = **dimensions + rasters** under one vocabulary (§5) | UC-05 (enriched; anchors UC-17–UC-20) |
| Fork/remix records a navigable genealogy edge (§9) | UC-26, UC-29 (enriched) |
| **Clone** = "same content in many places" — converges with transclusion (§5) | links UC-32, UC-44/45 |

Note: ZigZag is **a data model + visualization paradigm, not a candidate shard
backend.** Recommendation recorded in the dive: adopt zzstructure as a **navigation /
visualization / indexing lens** — a *derived dimensional projection* over the union,
like BackLinks today — and **reject it as the storage substrate**
(`research/260614-zigzag-deep-dive/findings.md` §6, §7.2). Git and sovereign shards
remain canonical (INTENT Stability Note). The many-to-many hyperlink graph does **not**
fit zzstructure's one-neighbour-per-dimension rule and stays a separate graph index.
Architecture logged for `SHARD-WP-0002`: a dimensional projection layer; genealogy
edges in the coordination journal; clone↔transclusion as a possible shared primitive
(findings §9). Pairs with the Xanadu dive (clone ↔ transclusion convergence).

### roam mapping

(§ UC-50–UC-52 are placed in the **wikiengines** matrix column as the nearest existing
source — Roam is a shipped tool — but their true lineage is the **Roam deep dive**,
`research/260614-roam-deep-dive/findings.md`.)

| Roam mechanism (findings §) | Catalog UC |
|-----------------------------|------------|
| Block-graph DataScript DB; page = `:node/title` node, blocks = spans (§2, §6) | UC-50 |
| `:block/uid` — shipped stable sub-page address (§2, §7) | UC-51 |
| Derived views = Datalog queries over the graph (§4) | UC-52 |
| Block embeds = shipped live transclusion by uid (§3) | UC-32 (enriched; + UC-44/45) |
| `key:: value` attributes + Datalog = structured/typed pages (§3, §4) | UC-34 (enriched; + UC-39) |
| Roam Depot `onload/onunload` + `roamAlphaAPI` = engine-hosts-adapter template (§5) | UC-38 (enriched) |
| Block-level write granularity = the fine extreme (§6) | UC-35 (enriched) |
| Hosted history is internal-only, not portable Git (§6, §8.2) | links UC-36 |

Note: Roam is the **modern bookend** to the Nelson dives — where Xanadu and ZigZag are
unbuilt ideals, Roam *shipped* fine-grained addressing, transclusion, bidirectional
links, and a queryable structured space. Its payoff is **empirical evidence** on
shard-wiki's open questions (span addressing is tractable via native block IDs;
transclusion is a data-layer capability; derived views are queries —
`research/260614-roam-deep-dive/findings.md` §7). **Boundary recorded:** Roam is *one
candidate shard* — DB-backed / API-attached (the XWiki family, not the file-store
family), block-first, with no portable Git history — **mapped into** shard-wiki's
Markdown-first page model, not adopted as a substrate and never the federation layer
(findings §8.2). Architecture logged for `SHARD-WP-0002` (T14): native-span-ID and
native-query capabilities, block↔page mapping, and Roam as a second
engine-hosts-adapter exemplar alongside XWiki.

---

## 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?
7. Is the **dimensional/zzstructure model** (UC-47/48) a public navigation API and UI
   paradigm, or only an internal organizing concept for the derived views?
8. How is the **many-to-many link graph** reconciled with the rank-based dimensional
   model — clones, a parallel graph index, or both? (ZigZag dive §10.)
9. Is **in-engine adapter hosting** (e.g. a Roam Depot extension for write-through) an
   accepted deployment mode generally, or do we restrict API-only backends to
   read/projection/overlay-target? (Roam dive §11 Q2; ties UC-38, UC-50.)