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/`,
`research/260614-roam-deep-dive/`, `research/260614-obsidian-deep-dive/`,
`research/260614-notion-deep-dive/`, `research/260614-joplin-deep-dive/`,
`research/260614-logseq-deep-dive/`,
`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/`, and
`research/260614-forge-wikis-deep-dive/`, and
`research/260614-tiddlywiki-deep-dive/`, and
`research/260614-ikiwiki-deep-dive/`, and
`research/260614-quip-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). **Wiki.js**
is the modern form: **path-based rule ACL** (allow/deny by path pattern per group) +
delegated auth modules (`research/260614-wikijs-deep-dive/findings.md` §4) — a projection
should **honor/surface restricted regions**, not silently drop or expose them.
**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). The fedwiki deep dive details the
concrete shape: fork is **own-site-only write + a `fork` journal entry recording the source
site**, and a forked journal stays **detailed enough to locate the upstream cut-point**
(`research/260614-federated-wiki-deep-dive/findings.md` §2, §4) — enabling later
carry-forward/re-fork (UC-28) and modelling the genealogy edge as **provenance** (UC-71/72).
**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. Obsidian's
**Importer** (1.4M) plugin (Evernote/Notion/Bear/Apple Notes → Markdown) shows demand
for importing from foreign tools (`research/260614-obsidian-deep-dive/findings.md` §7).
**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). Notion adds **webhooks**
(2026) delivering page/database change events — a SaaS push transport, weighed against
eventual consistency and the rate limit (`research/260614-notion-deep-dive/findings.md`
§4). **Joplin** is poll-based and turns concurrent edits into **conflict notes**
(keep-both, not silent overwrite) — conflict-as-data, links UC-07
(`research/260614-joplin-deep-dive/findings.md` §2). The **ikiwiki** dive details the
canonical pinger: an instance sends an **XML-RPC ping** to a peer when it changes, prompting
the peer to **pull and rebuild** — a subscribe/notify *mechanism* over a **git-distributed
mesh** (UC-79, `research/260614-ikiwiki-deep-dive/findings.md` §2), the federation flavor
beside fedwiki fork/journal (UC-72) and Wikibase `SERVICE` (UC-74).
**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). **Logseq** does the same on *files*: `{{embed ((uuid))}}` transcludes
by an in-file block ID (`research/260614-logseq-deep-dive/findings.md` §2).
**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). Obsidian shows the
**git-diffable in-file** variant: YAML frontmatter/properties live in the Markdown text
and are queried by the Dataview plugin (`research/260614-obsidian-deep-dive/findings.md`
§3) — structure as portable text, not DB state. **Notion** is the apex of the DB-locked
end: typed database properties with relations/rollups/formulas, lossy to Markdown —
see UC-58 (`research/260614-notion-deep-dive/findings.md` §2). **Logseq** sits between:
`key:: value` block/page properties live in the Markdown text (git-diffable) yet are
queried via a derived Datalog graph (`research/260614-logseq-deep-dive/findings.md` §2–§3)
— in-text structure at block granularity. **Trilium** adds **computed** structure: labels
+ typed relations that are **inherited + templated**, so effective metadata ≠ stored
metadata — see UC-67 (`research/260614-trilium-deep-dive/findings.md` §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. 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). The **TiddlyWiki** dive confirms the
coarse anchor and its consequence: in single-file mode a save **rewrites the whole HTML
file**, so an overlay to *any* page **conflicts with any concurrent write** (no per-page
atomicity) — whereas its Node `.tid` substrate is **file-per-tiddler** (fine), so the *same
engine* sits at both ends by substrate (UC-78,
`research/260614-tiddlywiki-deep-dive/findings.md` §1, §3; cf. UC-43/UC-62).
**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. Demand evidence:
**Obsidian Git is a top-7 plugin (2.7M)** — users manually bolt portable git history
onto a vault that has none natively (`research/260614-obsidian-deep-dive/findings.md`
§5, §7), exactly the gap the coordination journal fills as core. **Notion** is the
closed-SaaS instance: internal page history bounded by plan, **not portable** and not
exported as git (`research/260614-notion-deep-dive/findings.md` §4) — a supplementation
case like Confluence/MediaWiki, not an import case. **Joplin** keeps internal note
revisions locally, likewise not portable (`research/260614-joplin-deep-dive/findings.md`
§1) — supplement. **CRDT** shards (Anytype/AFFiNE/AppFlowy) keep a CRDT update log, not
git — also supplement, or snapshot the replica
(`research/260614-localfirst-workspaces-deep-dive/findings.md` §4). **Wiki.js** is the
*adopt* case via mirror: its Git storage module commits every change to a repo, so the
engine's history **is** git even though its canonical store is a DB (UC-68,
`research/260614-wikijs-deep-dive/findings.md` §2).
**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). **Joplin** offers
*two* surfaces: an in-app plugin host (`joplin.data`/`workspace`/`contentScripts`) **and**
a **local Data API** (REST on `localhost:41184`, token, app-running) — a local-REST attach
sub-mode between in-engine host and external API (UC-57,
`research/260614-joplin-deep-dive/findings.md` §4). **Trilium** is the same dual pattern:
**scripting** (frontend/backend code notes against a Script API) as the in-app host, plus
**ETAPI** (token REST) as a designed external surface for a self-hosted server
(`research/260614-trilium-deep-dive/findings.md` §5). **Wiki.js** generalizes the host
surface into a **pluggable module system** (storage/auth/search/render/editor); its
**storage-module** interface is — with `Foswiki::Store` — concrete **adapter-contract
prior art** (versioned, multi-provider Git/FS/S3/Azure, backup-or-source-of-truth)
(`research/260614-wikijs-deep-dive/findings.md` §2, §8).
**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. **Notion** pushes
further: a *database* is a collection with a schema whose rows are pages joined by typed
relations — see UC-58 (`research/260614-notion-deep-dive/findings.md` §2).
**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). An **Obsidian vault** is the cleanest case of all — a plain Markdown folder,
Markdown-first and git-friendly — and uniquely **dual-attachable**: file-store direct
*or* via an in-app plugin adapter for write-through + live file events (UC-53,
`research/260614-obsidian-deep-dive/findings.md` §4, §10). Counter-example: **Joplin**'s
native store is a **DB** (SQLite), so its file-attach surface is the *sync/interchange
mirror* on a WebDAV/S3 target, not the native store — see UC-60
(`research/260614-joplin-deep-dive/findings.md` §2). **Wiki.js** is the clean middle: also
DB-canonical, but its Git storage module maintains a repo of **plain Markdown** that is the
ideal engine-maintained file-store attach — see UC-68
(`research/260614-wikijs-deep-dive/findings.md` §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. **Trilium** is the
HTML-native case: text notes are HTML (CKEditor5), so participation needs HTML↔Markdown
translation — more tractable than Notion's blocks but still lossy for some constructs
(`research/260614-trilium-deep-dive/findings.md` §4, links UC-59). **Wiki.js** is
multi-format (**Markdown primary**, plus HTML and AsciiDoc) with pluggable editors — mostly
native, light translation for the non-MD pages (`research/260614-wikijs-deep-dive/findings.md`
§1).
**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. Live modern instance: **Logseq** is migrating its
substrate from Markdown-files to a SQLite "DB graph" under a stable graph identity
(`research/260614-logseq-deep-dive/findings.md` §5) — bind to capabilities, not to "it's
files".
**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). **AFFiNE** ships the commercial
proof: docs, whiteboards, and databases are *views of the same block set*
(`research/260614-localfirst-workspaces-deep-dive/findings.md` §2).
**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). **AFFiNE**'s page/edgeless/DB modes over
one block set are this idea shipped (`research/260614-localfirst-workspaces-deep-dive/findings.md`
§2).
**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). **Notion** is the
external-API variant of the same block-DB family: a server Postgres store with a real
**external** REST API, so write-through needs **no in-engine hosting** — but is bounded
by rate limits and eventual consistency (UC-57,
`research/260614-notion-deep-dive/findings.md` §4). **Logseq** is the *file-store* variant
of the block-tool family — block-graph semantics over plain Markdown files, not a DB — see
UC-62 (`research/260614-logseq-deep-dive/findings.md` §1–§2).
**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). Obsidian shows the **text-embedded** variant: `^block-id` and heading anchors
live in the Markdown text — git-diffable and portable (survives a file copy) but opt-in
(`research/260614-obsidian-deep-dive/findings.md` §2), vs Roam's mandatory DB-minted
UID. Notion is a second store-minted case: per-block **UUID v4**, exposed via the REST
API (`research/260614-notion-deep-dive/findings.md` §1). **Joplin** marks the spectrum's
middle: a store-minted **page-level** 32-char ID with `:/<id>` links that survive
rename/move (`research/260614-joplin-deep-dive/findings.md` §1) — coarser than a block
UUID, more stable than a path. **Logseq** is the **sweet spot**: a block-level `id:: uuid`
stored **in the Markdown text** — fine-grained *and* git-diffable/portable at once,
resolving the Roam(DB-minted) vs Obsidian(page-level) tension
(`research/260614-logseq-deep-dive/findings.md` §2). **CRDT** shards
(Anytype/AFFiNE/AppFlowy) mint object/block IDs as part of the CRDT structure — fine-
grained, store-assigned (`research/260614-localfirst-workspaces-deep-dive/findings.md`
§6).
**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. Obsidian
nuance: query can be an *ecosystem plugin* (Dataview), **not core** — so "native query"
is adapter/plugin-provided and must not be assumed
(`research/260614-obsidian-deep-dive/findings.md` §7). **Notion** ships a native
database **query API** (filters/sorts) — a strong delegation target
(`research/260614-notion-deep-dive/findings.md` §2, §4). **Logseq** shows the third path:
Datalog over a **derived** index built from plain files — neither native-DB nor plugin;
when no engine exists, shard-wiki can build the index itself (UC-63,
`research/260614-logseq-deep-dive/findings.md` §3). **Wikibase** is the far end:
**SPARQL** over an RDF projection with **federated `SERVICE`** cross-endpoint joins
(`research/260614-wikibase-deep-dive/findings.md` §2) — a graph-query tier above
datalog/filters, and `SERVICE` is itself a query-time federation primitive (UC-74).
**Priority:** Later

### UC-53 — Attach a local-first Markdown vault with a live concurrent native editor

**Actor:** Maintainer
**Goal:** Attach an Obsidian-style local Markdown vault as a file-backed shard while its
own app continues to edit the files concurrently — watching for external changes,
re-projecting, and treating the app's config dir as opaque.
**Source:** obsidian, intent
**Notes:** Obsidian "file over app": vault = folder of `.md` + `.obsidian/` config;
files are canonical (`research/260614-obsidian-deep-dive/findings.md` §1). Cleanest
file-store attach (UC-40) — and uniquely **dual-mode**: zero-config direct attach
(read/projection/overlay) *or* an in-app adapter (Obsidian plugin) for write-through +
live `vault` events (UC-38, findings §4). Needs **external-writer tolerance**
(file-watch, re-project, conflict-with-live-app) distinct from multi-user write
conflicts. Exclude `.obsidian/` as shard-local config, not page content.
**Priority:** Later

### UC-54 — Define a page as a live query over the union

**Actor:** Author
**Goal:** Author a page whose body is materialized from a saved query over the union
(e.g. "all open tasks", "all pages tagged X"), refreshed as the union changes.
**Source:** obsidian, roam, intent
**Notes:** The Obsidian **Dataview** (4.4M downloads) / **Tasks** (3.6M) pattern, and
Roam `{{query}}` — query-defined dynamic pages
(`research/260614-obsidian-deep-dive/findings.md` §7). Distinct from UC-44 (reference/
span manifest) and UC-52 (delegating *computation* of an existing view): here the *page
itself* is a query. Open: core page type vs. adapter vs. reference-UI/plugin (findings
§11 Q2). May delegate execution to a shard's native query engine (UC-52). **Notion**
linked/filtered databases are the commercial instance — one row-set surfaced through many
filtered views (`research/260614-notion-deep-dive/findings.md` §2).
**Priority:** Later

### UC-55 — Carry non-Markdown content types as typed or opaque assets

**Actor:** Maintainer or author
**Goal:** Attach and present a shard's non-Markdown content — drawings (Excalidraw),
spatial canvases (JSON Canvas), images, attachments — as typed or opaque assets with
provenance, without flattening them into Markdown or dropping them.
**Source:** obsidian, intent
**Notes:** The **#1 Obsidian plugin is Excalidraw (6.4M)** — users keep non-Markdown
content in "Markdown" vaults (`research/260614-obsidian-deep-dive/findings.md` §7).
Extends UC-34's no-lossy-flatten rule from structured-text to binary/spatial content.
Pushes the **wiki page model**: page vs. typed asset vs. opaque blob — a page-model
decision, not just adapter config (findings §10). JSON Canvas is an open format worth
first-class support. **Joplin** resources (attachments, each with an ID, linked `:/<id>`)
are the same demand in a sync-mirror shard (`research/260614-joplin-deep-dive/findings.md`
§5). **Logseq whiteboards** (tldraw JSON) are the same in a file-store block shard
(`research/260614-logseq-deep-dive/findings.md` §6). **AFFiNE** edgeless canvas, **AppFlowy**
boards/calendars, and **Anytype** objects/files are the same demand in CRDT shards
(`research/260614-localfirst-workspaces-deep-dive/findings.md` §5).
**Priority:** Later

### UC-56 — Publish a curated projection to an external read-only target

**Actor:** Maintainer
**Goal:** Publish a selected projection of the union (or a shard) to an external
read-only target — a static site or hosted page set — preserving provenance.
**Source:** obsidian, intent
**Notes:** The Obsidian Publish / **Quartz** / Digital Garden pattern — outbound
publish (`research/260614-obsidian-deep-dive/findings.md` §7, §10). Formalizes the
`publish` capability from INTENT's adapter-capability list; **complements UC-37**
(inbound static-export *attach*) as its outbound mirror. Open: core vs. publish-adapter
family; interaction with overlays and projection freshness (findings §11 Q4). **Notion**
adds the closed-SaaS instance: **publish-to-web** renders pages as read-only public
pages (`research/260614-notion-deep-dive/findings.md` §4).
**Priority:** Later

### UC-57 — Attach a closed hosted shard via its external API only

**Actor:** Maintainer
**Goal:** Attach a closed, hosted SaaS (Notion-style) that has no file store and no
in-app plugin runtime, reachable only through its external REST API — honoring its rate
limits, eventual consistency, payload/pagination caps, and a scoped, revocable access
grant.
**Source:** notion, intent
**Notes:** Notion is external-REST-attachable with **no in-engine hosting** (contrast
Roam UC-50) but inside a tight operational envelope: ~3 req/s, eventual consistency,
recursive first-level-children fetch, and integrations that see **only explicitly
connected pages** (`research/260614-notion-deep-dive/findings.md` §4, §6). The capability
profile must encode this **operational envelope** and **scoped/revocable grant**;
projection is cache/poll/webhook, not a live read model. Best as projection/mirror/
overlay/backup; write-through possible but bounded. Links the authz-in-core decision and
"no silent remote mutation". Third attachment mode alongside file-store (UC-40) and
in-engine host (UC-38/50). Self-hostable variants: **AFFiNE Cloud** / **AppFlowy Cloud**
(self-host sync servers) and **Anytype**'s open API + MCP are endpoint forms within a
user's trust boundary (`research/260614-localfirst-workspaces-deep-dive/findings.md` §4,
§9) — see also UC-65 (P2P, no single endpoint). **Wiki.js** uses **GraphQL** (typed,
introspectable, selective-field) rather than REST — schema discovery + reduced over-fetch,
see UC-69 (`research/260614-wikijs-deep-dive/findings.md` §3). **Quip** adds a third payload
form: REST with an **HTML** import/export payload (vs Notion block-JSON, Wiki.js GraphQL) —
**lossy** to Markdown, embedded spreadsheets/live apps degrade, under **Salesforce**
enterprise identity (UC-80, `research/260614-quip-deep-dive/findings.md` §2, §3). So the
external-API mode carries a **payload-format facet** (block-JSON / GraphQL / HTML) in the
adapter profile.
**Priority:** Later

### UC-58 — Attach a typed database with schema, relations, and views

**Actor:** Maintainer
**Goal:** Attach a structured database (Notion-style) as a shard — preserving its
schema (typed properties), its inter-record **relations** and **rollups/formulas**, and
its multiple **views** — without flattening the schema or the relations into prose.
**Source:** notion, intent
**Notes:** The apex of UC-34/UC-39: not annotations on prose, nor one form per page, but
a **collection with a schema** whose rows are pages joined by **typed, bidirectional
relations**, shown through many views (table/board/calendar/gallery)
(`research/260614-notion-deep-dive/findings.md` §2). Presses the page model: collection +
schema + relations, not just a page (findings §9). Relations map to the union link graph
and/or a relation index (cf. ZigZag many-to-many, UC-47/48); views relate to UC-54.
Deferred to `SHARD-WP-0002`. **Local-first** variants exist: **Anytype**'s user-editable
typed object graph (types + relations = an ontology) and **AppFlowy**'s Notion-style DBs,
both CRDT-backed (`research/260614-localfirst-workspaces-deep-dive/findings.md` §1, §3) —
the typed-collection demand is not exclusive to hosted SaaS.
**Priority:** Later

### UC-59 — Translate a proprietary content model with an explicit fidelity report

**Actor:** Orchestrator / adapter
**Goal:** Project and edit a shard whose content model does not round-trip to Markdown
(Notion blocks/rich-text, databases, relations) by translating **lossily but
transparently** — surfacing what degraded or did not map, rather than silently dropping
it.
**Source:** notion, intent
**Notes:** Notion is the heaviest translation case — proprietary block + rich-text model,
and its own Markdown/CSV export is lossy (`research/260614-notion-deep-dive/findings.md`
§3). **Distinct from UC-42** (Foswiki TML↔HTML *lossless* round-trip): here translation
is fundamentally lossy, so **fidelity becomes data** — a per-shard/per-page report of
what projects cleanly vs. degrades, with non-mappable elements preserved as
provenance/sidecar. Embodies union-without-erasure by making *loss of fidelity* visible.
Open: report format and where it surfaces (findings §10 Q3).
**Priority:** Later

### UC-60 — Attach a tool's documented sync / interchange representation

**Actor:** Maintainer
**Goal:** Attach a backend's documented **sync or interchange representation** — a folder
of per-item files a tool writes to a third-party storage target — as a file-store shard,
without running the tool and without touching its native store.
**Source:** joplin, intent
**Notes:** Joplin's native store is **SQLite**, but on sync it serializes to per-item
**Markdown+metadata files** on filesystem / WebDAV / **Nextcloud** / Dropbox / OneDrive /
**S3** (`research/260614-joplin-deep-dive/findings.md` §2). That mirror is attachable
offline and app-independently *if* the adapter understands the documented item format
(body + metadata footer, `:/id` links, resources). **Distinct from UC-40** (native
on-disk store) and **UC-53** (app files *are* the store): here the attach surface is the
**interchange/sync representation**, and the tool **owns the format** → treat
read/projection/overlay-mostly, never re-sync (INTENT not-a-file-sync-daemon). Realizes
INTENT's WebDAV/Nextcloud/S3 participants. Needs a **format profile** in the adapter
(findings §8).
**Priority:** Later

### UC-61 — Attach an encrypted-at-rest shard with content opacity

**Actor:** Maintainer
**Goal:** Attach a shard whose stored content is encrypted (E2EE sync target) and
participate correctly when bodies are undecryptable — as backup / mirror / structure-
shell — without ever presenting ciphertext as readable content.
**Source:** joplin, intent
**Notes:** Joplin encrypts items **before** they leave the device, so the sync target
holds ciphertext (`research/260614-joplin-deep-dive/findings.md` §3). Introduces a new
capability dimension — **content opacity** (`plaintext → encrypted-at-rest/opaque`) —
proposed as a twelfth spectrum for the adapter contract (findings §8; extends
`research/260614-shard-spectrum-synthesis/findings.md` §2). Graceful degradation extreme:
IDs/counts/timestamps may be visible while bodies are opaque; never silently surface
undecryptable content. Open: does shard-wiki ever hold keys, or only treat such shards as
opaque backups (findings §9 Q1)? Ties [[shard-wiki-auth-in-core-decision]]. **Anytype**
reinforces this: any-sync is **E2EE by default** — backup nodes hold ciphertext they
cannot read (`research/260614-localfirst-workspaces-deep-dive/findings.md` §1), and it is
**P2P** (UC-65). **Trilium** refines the dimension to **per-item**: protected (encrypted)
notes coexist with plaintext notes in one shard, so opacity is per-note, not whole-shard
(`research/260614-trilium-deep-dive/findings.md` §6).
**Priority:** Later

### UC-62 — Attach a block-graph-on-plain-files shard

**Actor:** Maintainer
**Goal:** Attach a Logseq-style local outliner — block-graph semantics stored as plain
Markdown/Org files — preserving its in-file block IDs, block/page properties, and outline
tree, with a derivable query index.
**Source:** logseq, intent
**Notes:** Logseq is **file-over-app *and* block-graph**: blocks carry an in-file
`id:: <uuid>` property, `((uuid))` refs, and `key:: value` properties, with a DataScript
graph **derived** from the files (`research/260614-logseq-deep-dive/findings.md` §1–§2).
The addressing **sweet spot** — block-level *and* git-diffable (UC-51) — resolving the
Roam(DB-minted)/Obsidian(page-level) tension. Attach **file-store direct with a Logseq
format profile** (parse `id::`/`((uuid))`/`key::`/outline) or via the in-app plugin
(`logseq.Editor`/`logseq.DB`). Distinct from UC-50 (Roam: block-DB, not files) and UC-53
(Obsidian: page-level, path-addressed). Watch the file→SQLite substrate migration
(UC-43).
**Priority:** Later

### UC-63 — Serve structured queries over a file-backed shard via a derived index

**Actor:** Reader or orchestrator
**Goal:** Run structured queries (tasks, tagged blocks, typed properties) over a
file-backed shard that exposes no native query engine, using an index the orchestrator or
adapter builds and rebuilds from the files.
**Source:** logseq, intent
**Notes:** Logseq proves a **file-backed** store supports rich **Datalog** queries via a
**derived DataScript index** (files canonical, graph derived —
`research/260614-logseq-deep-dive/findings.md` §1, §3). The converse of UC-52 (delegate to
a *native* engine): here shard-wiki **builds** the index over the projection when none
exists. Operationalizes the ZigZag dimensions / Roam-Notion query model on a file shard.
Open: built by adapter (per-shard) or core (over the union); persisted vs rebuilt
(findings §10 Q2). Belongs to the T16 navigation layer + T11 capabilities.
**Priority:** Later

### UC-64 — Attach a CRDT-synced local-first shard with native merge

**Actor:** Maintainer
**Goal:** Attach a CRDT-based local-first store (Anytype any-sync, AFFiNE Yjs, AppFlowy
Yrs) whose backend performs **conflict-free merge itself** — consuming a replica or
sync endpoint, respecting CRDT semantics rather than imposing git/text merge.
**Source:** localfirst-workspaces, intent
**Notes:** The cohort's defining trait: the store is a CRDT, so concurrent edits merge
mathematically (`research/260614-localfirst-workspaces-deep-dive/findings.md` §4). Adds a
**merge-model** capability (`none → git/text → native-CRDT`) — a proposed **thirteenth
spectrum** for the adapter contract (with Joplin's content-opacity twelfth). shard-wiki
must **not** git-merge a CRDT shard: speak the CRDT (hold a replica) for live/writable, or
stay **projection/overlay** that respects CRDT merge. History is the **CRDT update log**,
not git → supplement (UC-36). Attach a **local replica** (offline, full state) or a
self-host sync endpoint (UC-57). Like Joplin, do **not** re-drive the backend's sync
(not-a-file-sync-daemon). Open: embed a CRDT client vs consume snapshots; overlays as CRDT
ops vs out-of-band patches (findings §10 Q1–Q2).
**Priority:** Later

### UC-65 — Attach a peer-to-peer / decentralized shard with no single endpoint

**Actor:** Maintainer
**Goal:** Attach a decentralized shard (Anytype any-sync: P2P, E2EE) that has **no single
canonical URL** — binding via a local replica or a named peer/backup node, with content
that may be encrypted.
**Source:** localfirst-workspaces, intent
**Notes:** any-sync is P2P with sync/file/consensus/coordinator nodes; **backup nodes hold
ciphertext they cannot read**; changes signed/encrypted with the user's key
(`research/260614-localfirst-workspaces-deep-dive/findings.md` §1, §4). The shard's
"address" is a space ID + replica/peer/invite, **not a URL** — a new binding mode beside
file-store / in-engine-host / external-API (UC-40/38/57). Combines with **content opacity**
(UC-61): E2EE shards are replica-only / opaque without keys. Open: shard address form;
whether shard-wiki holds keys (findings §10 Q3–Q4). Ties [[shard-wiki-auth-in-core-decision]].
**Priority:** Later

### UC-66 — Attach a shard with a DAG hierarchy (note cloning)

**Actor:** Maintainer
**Goal:** Attach a shard where a page may occupy **multiple namespace locations at once**
(Trilium note cloning) — representing the multi-location membership, with page identity
separated from placement, without forcing a single canonical path.
**Source:** trilium, intent
**Notes:** Trilium models a **note** (identity, `noteId`) separately from its **branches**
(placements, `branchId`); a note with several branches is **cloned** into several tree
locations — so the hierarchy is a **DAG, not a tree**
(`research/260614-trilium-deep-dive/findings.md` §2). Breaks UC-22's single-path
assumption. shard-wiki should borrow the **identity ≠ placement** split (one page entity,
N placements/paths/shards) — also the right model for a page appearing under multiple
paths or across shards. The namespace-level form of the clone/reference primitive (T16;
cf. Xanadu/ZigZag clone, UC-44/45). Open: model as one page with N placements vs
transclusion into N locations (findings §11 Q1).
**Priority:** Later

### UC-67 — Preserve inherited and templated attributes (effective vs own metadata)

**Actor:** Reader or maintainer
**Goal:** Project a structured shard whose metadata is **computed** — a page's effective
attributes derive from its own values plus inherited (ancestor) and templated values —
distinguishing **effective vs own** with per-attribute provenance, not flattening.
**Source:** trilium, intent
**Notes:** Trilium attributes (labels `#tag`, typed relations `~relation`) can be
**inherited down the subtree** and injected by **templates** (`~template`), so effective
metadata = own + inherited + templated (`research/260614-trilium-deep-dive/findings.md`
§3). Extends UC-34/UC-58 with a new wrinkle: **metadata is computed, not just stored** —
record each attribute's provenance (own / inherited-from / template). Open: materialize
effective values (snapshot) vs compute live from the shard's tree/templates (findings §11
Q2). Templates also reinforce UC-15 (blueprints).
**Priority:** Later

### UC-68 — Attach an engine-maintained bidirectional Git mirror of clean Markdown

**Actor:** Maintainer
**Goal:** Attach a DB-canonical engine that bidirectionally syncs its content to a Git
repo of **clean Markdown + YAML frontmatter** (Wiki.js Git storage module): use the repo
as a file-store shard (with git history) and optionally **write-through by committing
Markdown the engine ingests** — coordinating which side is source of truth, without
double-syncing.
**Source:** wikijs, intent
**Notes:** Wiki.js commits every page change to git as clean `.md`
(`injectMetadata()` prepends YAML frontmatter), bidirectionally with the remote repo
(`research/260614-wikijs-deep-dive/findings.md` §2). Cleaner than Joplin's proprietary
interchange mirror (UC-60) — it is **plain Markdown** — and richer than a read-only native
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).
**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)

**Actor:** Orchestrator / adapter
**Goal:** Attach a shard through a typed, introspectable API (Wiki.js GraphQL) — using
**schema introspection** for capability/shape discovery and **selective-field queries** to
fetch only what a projection needs.
**Source:** wikijs, intent
**Notes:** Wiki.js exposes a **GraphQL** API over all resources
(`research/260614-wikijs-deep-dive/findings.md` §3). Two advantages over a REST
external-API (UC-57): **introspection** = self-describing schema → feeds capability
discovery (T11); **selective fields** = fetch body vs metadata vs tags as needed →
reduces over-fetch (projection efficiency, operational envelope). An external-API
sub-mode beside Notion's REST.
**Priority:** Later

---

### UC-70 — Attach a Federated Wiki site as a shard (page JSON + CORS)

**Actor:** Orchestrator / adapter
**Goal:** Attach a **Federated Wiki** site as a shard via its **page JSON** served over
**HTTP with CORS** (`/<slug>.json`); project its pages and **fork** them to overlay
non-destructively.
**Source:** federation, intent
**Notes:** A fedwiki site is a sovereign server (Node.js, static-file, or serverless)
serving `{ title, story[], journal[] }` page JSON
(`research/260614-federated-wiki-deep-dive/findings.md` §1, §3). A **REST/file-store
hybrid** attachment mode: CORS-readable JSON over HTTP, or a static pile of `.json` files.
Writes are **own-site-only** — to change a remote page you **fork** it (UC-26), so this
shard is naturally a read/project + overlay target, never silent remote mutation. Feeds
SHARD-WP-0002 T14 (attachment mode), T11 (capability profile).
**Priority:** Later

### UC-71 — Coordination journal as an append-only semantic-action log with provenance

**Actor:** Core orchestrator
**Goal:** Model the coordination journal as a **per-page append-only log of semantic
actions** (`create`/`add`/`edit`/`move`/`remove`/`fork`) carrying **provenance entries**
(fork records the source site), with the page state **derived by replaying** the log and
divergence **located by comparing** logs.
**Source:** federation, intent
**Notes:** Directly adopts the fedwiki **journal** shape — the story is a materialized
view of the journal, fork entries serialize a **provenance DAG**, and per-entry sequence
numbers make the fork cut-point identifiable
(`research/260614-federated-wiki-deep-dive/findings.md` §2, §6). This is concrete prior art
for INTENT's coordination journal: a **third merge model** beside git 3-way and CRDT
auto-merge — a coarse semantic op-log applied manually via fork. Feeds SHARD-WP-0002 T13
(history portability / merge model) and T1–T5 (federation).
**Priority:** Later

### UC-72 — Federate by fork-with-provenance across a neighborhood / chorus

**Actor:** Reader / curator
**Goal:** Assemble a **union from sovereign peer shards** discovered by **link and fork**
(a *neighborhood*) or by an explicit **roster**, **search across that set**, and preserve a
**chorus of co-equal, provenance-linked versions** without forcing a canonical — pulling
another's changes by forking them.
**Source:** federation, intent
**Notes:** Fedwiki's neighborhood (dynamic, link/fork-discovered) vs roster (curated)
membership and "chorus of voices" no-canonical stance
(`research/260614-federated-wiki-deep-dive/findings.md` §3, §4) model
**union-without-erasure** at the coordination layer: divergence is normal and visible,
reconciliation is an explicit human/policy step (mechanism over policy). Open: does a
chorus compose with shards that assert a canonical? Feeds SHARD-WP-0002 T1–T5; relates
UC-05/UC-27 (union/chorus), UC-26 (fork).
**Priority:** Later

### UC-73 — Attach a typed entity-statement (RDF) knowledge-graph shard

**Actor:** Orchestrator / adapter
**Goal:** Attach a **Wikibase** instance as a **typed entity-statement shard** — items and
properties, statements = claim + qualifiers + references + rank — and project entities to a
rendered page view (lossy to Markdown) **without flattening away the graph**.
**Source:** wikiengines, intent
**Notes:** The **structure far-end** beyond Notion DB / XWiki XObjects / Trilium relations:
a true typed knowledge graph with `somevalue`/`novalue` known-unknowns
(`research/260614-wikibase-deep-dive/findings.md` §1). Content **is not Markdown** — render
is a lossy projection (UC-55), so attach as a structured shard and either keep the graph as
the canonical payload (T12) or offer a rendered view, never a silent flatten. Feeds
SHARD-WP-0002 T12 (typed-graph page payload), T16 (stable opaque identity).
**Priority:** Later

### UC-74 — Graph-query the union (SPARQL) and federate queries across endpoints

**Actor:** Reader / analyst
**Goal:** Query graph-capable shards with a **graph query language (SPARQL)** and **federate
queries across endpoints** (`SERVICE`) — a query-time cross-shard join distinct from
structural (fork/neighborhood) federation.
**Source:** wikiengines, intent
**Notes:** SPARQL over the RDF projection (Wikidata Query Service / Blazegraph) is the
**native-query far-end** above Roam/Logseq datalog and Notion filters (UC-52); `SERVICE` is
a **query-time federation** primitive beside fedwiki's structural federation (UC-72)
(`research/260614-wikibase-deep-dive/findings.md` §2). Open: union-level common query vs
pass-through to graph-capable shards. Feeds SHARD-WP-0002 native-query tiering; relates
UC-63 (derived index — WDQS is one).
**Priority:** Later

### UC-75 — Preserve statement-level provenance (references + rank)

**Actor:** Core orchestrator
**Goal:** Preserve **provenance at the assertion level** — references and **rank** attached
to each *statement*, not just per page or per shard — so contradictory values can coexist
with a curation signal.
**Source:** wikiengines, intent
**Notes:** Wikibase attaches **references** (sources) and a **rank**
(`preferred`/`normal`/`deprecated`) to each statement
(`research/260614-wikibase-deep-dive/findings.md` §1, §5) — provenance granularity **finer**
than shard-wiki's per-page model, and the *structured* analogue of fedwiki's chorus (UC-72)
and "view multiple versions" (UC-27). The page model + coordination journal should **allow**
sub-page/per-assertion provenance even if MVP records per page. Enriches UC-24; feeds
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

### UC-78 — Attach a single-file self-contained wiki (whole-file write granularity)

**Actor:** Orchestrator / adapter
**Goal:** Attach a **single-file self-contained wiki** (a TiddlyWiki HTML file that bundles
both content and the app engine) as one shard — **parse the tiddler store out of the
container**, project pages, and treat **writing as rewriting the whole file**.
**Source:** wikiengines, intent
**Notes:** Classic TiddlyWiki is *one HTML file* = engine + every tiddler
(`research/260614-tiddlywiki-deep-dive/findings.md` §1) — the **portability and
write-granularity extreme**. Write granularity is **whole-file** (the coarsest tier): an
overlay to any one page still rewrites the entire artifact, so per-page atomicity does not
exist (T11) — model overlays/locks accordingly, or require the Node.js **`.tid`
file-per-tiddler** substrate for fine-grained write-through and keep single-file as
read/projection/backup. Treat the HTML as a **container format** (extract content tiddlers,
ignore the embedded engine). Feeds SHARD-WP-0002 T11 (whole-file tier), T14 (single-file vs
`.tid` binding; cf. UC-43/UC-62).
**Priority:** Later

### UC-79 — Attach a git-backed compile-to-static wiki (source is the shard)

**Actor:** Orchestrator / adapter
**Goal:** Attach a **compile-to-static** wiki (ikiwiki) where the **git Markdown source is
the shard** and the **compiled static HTML is a derived publish/projection**; optionally
participate in **git-distributed clone federation** with change-**pings**.
**Source:** wikiengines, federation, intent
**Notes:** ikiwiki compiles a VCS-backed (git) Markdown tree to static HTML; web edits are
commits, so git is canonical and HTML is regenerable build output
(`research/260614-ikiwiki-deep-dive/findings.md` §1, §3). **Attach the source repo, never
the build output** (the static site is a projection, UC-37/UC-56). Its federation is **git
replication + an XML-RPC pinger** (notify a peer to pull/rebuild, UC-31) — a third
federation flavor beside fedwiki fork/journal (UC-72) and Wikibase `SERVICE` (UC-74). Shares
the git+Markdown adapter with forge wikis (UC-76). Feeds SHARD-WP-0002 T4 (federation), T6
(publish/projection).
**Priority:** Later

### UC-80 — Attach a SaaS live-doc shard with embedded structured objects

**Actor:** Orchestrator / adapter
**Goal:** Attach a **SaaS live-document shard** (Salesforce Quip) whose pages **mix prose
with embedded live structured objects** (spreadsheets, live apps) via a **REST API with
lossy HTML import/export**, under **enterprise (Salesforce) identity**.
**Source:** wikiengines, intent
**Notes:** Quip is a closed-SaaS document+spreadsheet hybrid — a page is prose interleaved
with **inline spreadsheets/live apps**, reachable only by REST, content crossing as **HTML**
(lossy to Markdown; embedded objects degrade) (`research/260614-quip-deep-dive/findings.md`
§1, §2). Generalizes the external-API mode (UC-57) with an **HTML payload** variant beside
Notion block-JSON and Wiki.js GraphQL, and adds **inline embedded structured objects** to
the page model (UC-55/UC-58) — surface them with provenance, never silent-flatten (UC-59).
Honor **Salesforce ACL** (UC-06); default to read/projection/overlay given rate limits +
lossy export. Feeds SHARD-WP-0002 T11 (payload-format + content-opacity), T12 (inline
objects), T14.
**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). Obsidian's popular **Templater** (4.6M) / **QuickAdd**
(1.9M) plugins show templated creation is a top real-world need
(`research/260614-obsidian-deep-dive/findings.md` §7). **Trilium** templates (`~template`
relation) inject an attribute set + structure into instances — blueprint-as-typed-template
(`research/260614-trilium-deep-dive/findings.md` §3, links UC-67).
**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). **Trilium** pushes further: its hierarchy is a **DAG** — a note can sit in
multiple locations (cloning), with **identity (note) separated from placement (branch)** —
so there is no single canonical path (UC-66,
`research/260614-trilium-deep-dive/findings.md` §2).
**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). **Wikibase** pushes provenance
*finer than the page*: **references + rank per statement** let sourced, even contradictory,
values coexist with a curation signal (UC-75,
`research/260614-wikibase-deep-dive/findings.md` §1, §5) — the page model should allow
sub-page/per-assertion provenance even if MVP records it per page.
**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-53 | | | | ¶ | ✓ |
| UC-54 | | | | ¶ | ✓ |
| UC-55 | | | | ¶ | ✓ |
| UC-56 | | | | ¶ | ✓ |
| UC-57 | | | | ◊ | ✓ |
| UC-58 | | | | ◊ | ✓ |
| UC-59 | | | | ◊ | ✓ |
| UC-60 | | | | ‖ | ✓ |
| UC-61 | | | | ‖ | ✓ |
| UC-62 | | | | ※ | ✓ |
| UC-63 | | | | ※ | ✓ |
| UC-64 | | | | ⌘ | ✓ |
| UC-65 | | | | ⌘ | ✓ |
| UC-66 | | | | ⊕ | ✓ |
| UC-67 | | | | ⊕ | ✓ |
| UC-68 | | | | ⚓ | ✓ |
| UC-69 | | | | ⚓ | ✓ |
| UC-70 | | | ✓⊞ | | ✓ |
| UC-71 | | | ✓⊞ | | ✓ |
| UC-72 | | | ✓⊞ | | ✓ |
| UC-73 | | | | ⬡ | ✓ |
| UC-74 | | | | ⬡ | ✓ |
| UC-75 | | | | ⬡ | ✓ |
| UC-76 | | | | ⎇ | ✓ |
| UC-77 | | | | ⎇ | ✓ |
| UC-78 | | | | ⊡ | ✓ |
| UC-79 | | | ✓ | ⊟ | ✓ |
| UC-80 | | | | ◧ | ✓ |
| 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.

### obsidian mapping

(¶ UC-53–UC-56 are placed in the **wikiengines** matrix column as the nearest existing
source — Obsidian is a shipped tool — but their true lineage is the **Obsidian deep
dive**, `research/260614-obsidian-deep-dive/findings.md`.)

| Obsidian mechanism (findings §) | Catalog UC |
|---------------------------------|------------|
| File-over-app vault; cleanest file-backed Markdown shard, dual-attachable (§1, §4) | UC-53 (new); enriches UC-40, UC-02, UC-38 |
| Dataview/Tasks: a page materialized from a query (§7) | UC-54 (new) |
| Excalidraw/Canvas/attachments: non-Markdown content (§7) | UC-55 (new) |
| Obsidian Publish/Quartz: outbound publish (§7) | UC-56 (new) |
| In-file `^block-id` / heading anchors = git-diffable opt-in span IDs (§2) | UC-51 (enriched) |
| YAML frontmatter/properties = git-diffable in-file structured data (§3) | UC-34 (enriched) |
| Git plugin (top-7) = bolt-on portable history (§5, §7) | UC-36 (enriched) |
| Query is a plugin (Dataview), not core (§7) | UC-52 (enriched) |
| Importer plugin = import from foreign tools (§7) | UC-28 (enriched) |
| Templater/QuickAdd = templated creation (§7) | UC-15 (enriched) |
| MetadataCache: files-canonical / index-derived (§1, §6) | reinforces UC-05/17–20 derived-view model |

#### Plugin-popularity → use-case signal

Per the research brief (let ecosystem popularity inform the catalog). All-time download
ranks read as **demand evidence** — full table in
`research/260614-obsidian-deep-dive/findings.md` §7. Headlines:

- **#1 is drawings** (Excalidraw 6.4M) → non-Markdown content is a *primary* real-world
  use, not an edge case → **UC-55**.
- **Query-as-DB** (Dataview 4.4M, Tasks 3.6M) is top-tier but an *add-on* → query is an
  adapter/plugin capability (**UC-52**) and motivates query-defined pages (**UC-54**).
- **Git is top-7** (2.7M) → users manually bolt on portable history → direct demand for
  the coordination journal (**UC-36**).
- **Sync-to-anywhere** (Remotely Save 2.0M: S3/Dropbox/OneDrive/GDrive/WebDAV) →
  demand to connect a vault to the heterogeneous backends INTENT targets — while
  reaffirming the **not-a-file-sync-daemon** boundary (attach as shards, don't mirror).

Note: an Obsidian vault is **one file-backed candidate shard** — the cleanest,
INTENT-named, and the file-store counterpart to the DB-backed Roam shard — mapped into
the Markdown-first page model; **not** the federation layer and **not** a file-sync
target (`research/260614-obsidian-deep-dive/findings.md` §8.2). Architecture logged for
`SHARD-WP-0002` (T14): dual attachment mode, consume-native-derived-index capability,
non-Markdown content types in the page model, outbound publish, external-writer
tolerance.

### notion mapping

(◊ UC-57–UC-59 are placed in the **wikiengines** matrix column as the nearest existing
source — Notion is a shipped tool — but their true lineage is the **Notion deep dive**,
`research/260614-notion-deep-dive/findings.md`.)

| Notion mechanism (findings §) | Catalog UC |
|-------------------------------|------------|
| Closed hosted SaaS, external-REST-only, rate-limited/eventually-consistent, scoped grant (§4, §6) | UC-57 (new) |
| Database = schema + typed properties + relations + rollups + views (§2) | UC-58 (new) |
| Proprietary block/rich-text, lossy to Markdown (§3) | UC-59 (new) |
| Per-block UUID v4 via REST = store-minted span address (§1) | UC-51 (enriched) |
| Server Postgres + external REST API = block-DB without in-engine hosting (§4) | UC-50 (enriched) |
| Database query API; filtered/linked DBs (§2, §4) | UC-52, UC-54 (enriched) |
| Database-as-pages apex; typed records + relations (§2) | UC-34, UC-39 (enriched) |
| Webhooks (2026) as push transport (§4) | UC-31 (enriched) |
| Internal-only page history, not portable (§4) | UC-36 (enriched) |
| Publish-to-web outbound (§4) | UC-56 (enriched) |
| Scoped, revocable per-integration grant; no silent mutation (§6) | UC-57 + [[shard-wiki-auth-in-core-decision]] |

Note: Notion is the **closed/hosted/schema-rich** extreme and the dive that stress-tests
*graceful degradation*, *no silent remote mutation*, and *Markdown-first that must
degrade*. It adds the **third attachment mode** — external-API-only (full write-through
without in-engine hosting, but bounded by rate limits and eventual consistency) —
alongside file-store (UC-40) and in-engine host (UC-38/50). It also *enforces* no silent
mutation via scoped, revocable per-integration page grants
(`research/260614-notion-deep-dive/findings.md` §6). **Boundary recorded:** one
external-API candidate shard — best as projection/mirror/overlay/backup — not a
substrate and not the federation layer. Architecture logged for `SHARD-WP-0002` (T14):
an operational-envelope capability section (rate limit, consistency class, payload caps,
push-vs-poll), access-grant semantics, a translation-fidelity capability, and the
three-way attachment-mode taxonomy.

### joplin mapping

(‖ UC-60–UC-61 are placed in the **wikiengines** matrix column as the nearest existing
source — Joplin is a shipped tool — but their true lineage is the **Joplin deep dive**,
`research/260614-joplin-deep-dive/findings.md`.)

| Joplin mechanism (findings §) | Catalog UC |
|-------------------------------|------------|
| SQLite-local, Markdown-on-sync; per-item files on WebDAV/Nextcloud/S3 (§2) | UC-60 (new) |
| E2EE → ciphertext at rest; content opacity (§3) | UC-61 (new) |
| Store-minted page-level 32-char ID, rename-stable `:/id` links (§1) | UC-51 (enriched) |
| Native store is a DB; attach surface is the sync mirror, not the store (§2) | UC-40 (enriched) |
| Internal revisions, not portable (§1) | UC-36 (enriched) |
| Plugin host + local Data API (localhost:41184, token) (§4) | UC-38 (enriched; links UC-57) |
| Resources (attachments) with IDs (§5) | UC-55 (enriched) |
| Poll sync; conflict notes (keep-both) (§2) | UC-31 (enriched; links UC-07) |

Note: Joplin is the **SQLite-local / Markdown-on-sync** case — its best attach surface is
the **interchange/sync representation** (per-item files on a WebDAV/Nextcloud/S3 target),
offline and app-independent, landing on INTENT's named backends. It adds two findings for
the adapter contract: the **interchange/sync-representation attach surface** (distinct
from native on-disk store UC-40 and app-files UC-53), and **content opacity** (a proposed
twelfth capability spectrum for encrypted-at-rest shards, extending
`research/260614-shard-spectrum-synthesis/findings.md` §2). **Boundary recorded:** Joplin
is a **file-sync daemon over one store**; shard-wiki attaches its **mirror as pages** and
never re-syncs, and treats the DB-local store and encrypted content as opaque
(`research/260614-joplin-deep-dive/findings.md` §6). Architecture logged for
`SHARD-WP-0002` (T11/T14): interchange-format attach, content-opacity field, local-REST
sub-mode, format-aware file-store profiles.

### logseq mapping

(※ UC-62–UC-63 are placed in the **wikiengines** matrix column as the nearest existing
source — Logseq is a shipped tool — but their true lineage is the **Logseq deep dive**,
`research/260614-logseq-deep-dive/findings.md`.)

| Logseq mechanism (findings §) | Catalog UC |
|-------------------------------|------------|
| Block-graph semantics on plain MD/Org files; in-file `id::`/`((uuid))`/`key::` (§1–§2) | UC-62 (new) |
| Datalog over a **derived** DataScript index built from files (§1, §3) | UC-63 (new) |
| In-file block `id::` = block-level **and** git-diffable addressing (the sweet spot) (§2) | UC-51 (enriched) |
| File→SQLite "DB graph" substrate migration under stable identity (§5) | UC-43 (enriched) |
| Block-graph that is **files, not a DB** — file-store variant of the block-tool family (§1) | UC-50 (enriched) |
| Datalog over a derived index (third path: not native-DB, not plugin) (§3) | UC-52 (enriched) |
| `key:: value` block/page properties in-text (§2) | UC-34 (enriched) |
| Whiteboards (tldraw JSON) = non-Markdown content (§6) | UC-55 (enriched) |
| Block embeds `{{embed ((uuid))}}` = in-file transclusion (§2) | links UC-32 |

Note: Logseq is the **block-graph-on-plain-files** point the other modern tools leave
empty — the bridge between Roam (block-DB) and Obsidian (file-over-app) — and it
**resolves the addressing-spectrum tension**: block-level addressing that is also
git-diffable in-file text (`id::`). It confirms a **file-backed shard can serve rich
Datalog queries via a derived index** (files canonical, graph derived). **Boundary
recorded:** one block-graph-on-files candidate shard (the addressing sweet spot), best
attached file-store-direct with a Logseq **format profile**; not the federation layer;
substrate migrating file→SQLite (UC-43). Architecture logged for `SHARD-WP-0002`
(T11/T14/T16): Logseq format profile, derived-query-index capability, substrate-migration
tolerance, in-file block addressing as the concrete T16 span-address target.

### localfirst-workspaces mapping (Anytype · AFFiNE · AppFlowy)

(⌘ UC-64–UC-65 are placed in the **wikiengines** matrix column as the nearest existing
source — these are shipped tools — but their true lineage is the **local-first workspaces
cohort dive**, `research/260614-localfirst-workspaces-deep-dive/findings.md`.)

| Cohort mechanism (findings §) | Catalog UC |
|-------------------------------|------------|
| CRDT store with native conflict-free merge (any-sync / Yjs / Yrs) (§4) | UC-64 (new) |
| P2P, no single canonical endpoint; E2EE (Anytype any-sync) (§1, §4) | UC-65 (new) |
| CRDT update log ≠ portable git history → supplement (§4) | UC-36 (enriched) |
| One block set as page / canvas / DB views (AFFiNE) (§2) | UC-47, UC-48 (enriched) |
| Edgeless canvas / boards / objects = non-Markdown content (§5) | UC-55 (enriched) |
| Self-host sync server (AFFiNE/AppFlowy Cloud) + Anytype open API/MCP (§4, §9) | UC-57 (enriched) |
| Typed object graph / user-editable ontology + Notion-style DBs, local-first (§1, §3) | UC-58 (enriched) |
| E2EE by default; backup nodes hold ciphertext (Anytype) (§1) | UC-61 (enriched) |
| Object/block IDs CRDT-assigned (fine-grained) (§6) | UC-51 (enriched) |
| Lossy Markdown export (§5) | links UC-59 |

Note: Anytype, AFFiNE, and AppFlowy form the **CRDT local-first workspace** family — the
first studied shards whose **store is a CRDT** (the backend merges concurrent edits
itself). This changes the adapter math: shard-wiki must **not impose git/text merge**
(speak the CRDT via a replica, or stay projection/overlay), history is a **CRDT update
log** (supplement), and the attach surface is a **replica or self-host sync endpoint** —
Anytype adding **P2P + E2EE** (no single endpoint, opaque without keys). **Boundary
recorded:** CRDT local-first candidate shards — attach a replica/projection as pages,
respect native merge, never re-drive their sync; not substrates and not the federation
layer (`research/260614-localfirst-workspaces-deep-dive/findings.md` §7). Architecture
logged for `SHARD-WP-0002` (T11/T14): a **merge-model** capability (proposed thirteenth
spectrum: `none / git / native-CRDT`), a **CRDT-replica** substrate + **P2P/no-central-
endpoint** attach mode, an **endpoint-model** capability, and MCP as an integration
surface.

### trilium mapping

(⊕ UC-66–UC-67 are placed in the **wikiengines** matrix column as the nearest existing
source — Trilium is a shipped tool — but their true lineage is the **Trilium deep dive**,
`research/260614-trilium-deep-dive/findings.md`.)

| Trilium mechanism (findings §) | Catalog UC |
|--------------------------------|------------|
| Note cloning → DAG hierarchy; note (identity) vs branch (placement) (§2) | UC-66 (new) |
| Attributes inherited + templated → effective vs own metadata (§3) | UC-67 (new) |
| DAG / multi-parent vs tree; identity ≠ placement (§2) | UC-22 (enriched) |
| Labels (`#tag`) + typed relations (`~relation`), computed (§3) | UC-34 (enriched) |
| Templates (`~template`) inject attribute sets (§3) | UC-15 (enriched) |
| HTML-native (CKEditor) → HTML↔Markdown lossy translation (§4) | UC-42 (enriched; links UC-59) |
| Per-note encryption (protected notes) = per-item opacity (§6) | UC-61 (enriched) |
| Scripting (code notes) in-app host + ETAPI external REST (§5) | UC-38 (enriched; links UC-57) |
| Render/script notes + attribute queries = dynamic content (§4–§5) | links UC-54 |
| Typed relations = knowledge graph (§3) | links UC-58 |
| `noteId`/`branchId` 12-char IDs (§1) | links UC-51 |

Note: Trilium (active fork **TriliumNext**) is a SQLite-local PKB whose standout is **note
cloning** — a **DAG hierarchy** with **note identity separated from placement** (note vs
branch), the namespace-level form of the clone/reference primitive and the clean model for
a page in multiple locations/shards. It also makes **metadata computed** (own + inherited +
templated, UC-67) and refines **content opacity to be per-item** (per-note encryption,
UC-61). HTML-native (lossy to Markdown), dual extension surface (scripting + ETAPI).
**Boundary recorded:** one SQLite-local candidate shard, best attached via ETAPI; not a
substrate and not the federation layer. Architecture logged for `SHARD-WP-0002`
(T11/T12/T14/T15/T16): DAG namespace + identity/placement split, computed/inherited
metadata, per-item content opacity, HTML source model, scripting + ETAPI host surfaces.

### wikijs mapping

(⚓ UC-68–UC-69 are placed in the **wikiengines** matrix column as the nearest existing
source — Wiki.js is a shipped engine — but their true lineage is the **Wiki.js deep dive**,
`research/260614-wikijs-deep-dive/findings.md`.)

| Wiki.js mechanism (findings §) | Catalog UC |
|--------------------------------|------------|
| Bidirectional Git storage module → clean Markdown + YAML frontmatter in a repo (§2) | UC-68 (new) |
| GraphQL API: introspectable schema + selective-field projection (§3) | UC-69 (new) |
| Pluggable **storage modules** (Git/FS/S3/Azure) = adapter-contract prior art; modular auth/search/render/editor (§2, §8) | UC-38 (enriched) |
| Git storage = clean Markdown in git — ideal engine-maintained file-store attach (§2) | UC-40 (enriched) |
| Git history natively via the storage module (adopt via mirror) (§2) | UC-36 (enriched) |
| GraphQL external-API variant (typed/introspectable/selective) (§3) | UC-57 (enriched) |
| Multi-format: Markdown primary; HTML/AsciiDoc (§1) | UC-42 (enriched) |
| Path-based rule ACL; delegated auth modules (§4) | UC-06 (enriched; links authz decision) |
| Engine-maintained clean git shard (§2, §5) | links UC-02 |

Note: Wiki.js is the **most shard-wiki-shaped engine** studied — DB-canonical but with a
**pluggable storage-module abstraction** that bidirectionally syncs **clean Markdown to
Git** (also FS/S3/Azure), each provider acting as **backup or source of truth**. That
interface is, with **Foswiki::Store**, concrete **prior art for the adapter contract**
(and the closer one — its medium is Markdown in Git). Its Git mirror is the **ideal
engine-maintained file-store attach** (clean MD + frontmatter + git history) and, being
**bidirectional**, makes **git commit a write path** (UC-68). It also uses **GraphQL**
(introspection → capability discovery; selective fields → efficient projection, UC-69) and
ships **authn-delegated auth modules + path-based rule ACL**. **Boundary recorded:** one
server-engine candidate shard; the Git mirror is the preferred attach surface but the
engine owns the DB↔git sync (don't double-sync); honor its access rules; not the federation
layer. Architecture logged for `SHARD-WP-0002` (T11/T14): storage-module abstraction as a
second adapter-contract prior art, engine-maintained Git mirror as attach+write surface,
GraphQL introspection for capability discovery + selective projection.

### federated-wiki mapping

(⊞ UC-70–UC-72 are placed in the **federation** matrix column — Federated Wiki was first
surfaced in `research/260608-federation-concepts/` — but their deepened lineage is the
**Federated Wiki deep dive**, `research/260614-federated-wiki-deep-dive/findings.md`.)

| Federated Wiki mechanism (findings §) | Catalog UC |
|---------------------------------------|------------|
| Page JSON `{title, story[], journal[]}` over HTTP+CORS; static-file sites (§1, §3) | UC-70 (new) |
| Per-page append-only **journal** of semantic actions; story = derived replay; `fork` = provenance entry (§1, §2) | UC-71 (new) |
| **Neighborhood** (link/fork-discovered) + **roster** (curated) + chorus of forks (§3, §4) | UC-72 (new) |
| **fork** = non-destructive copy with source-site attribution (§2, §4) | UC-26 (enriched) |
| Forked journal carries upstream cut-point → carry-forward + re-fork (§2) | UC-28 (enriched) |
| **Happenings** = time-bounded collaboration leaving durable forks (§3) | UC-30 (enriched) |
| Chorus of co-equal, provenance-linked versions; no canonical (§4) | UC-05 / UC-27 (enriched) |
| Story-item (paragraph) write granularity; stable 16-hex item `id` (§1, §5) | links UC-35 |
| Journal-replay op-log = third merge model (vs git 3-way, CRDT) (§5, §8) | links UC-36 / UC-64 |

Note: Federated Wiki is the one studied system whose *core job is shard-wiki's own* — a
**union of pages from sovereign sites preserving provenance, assembled non-destructively**.
It is therefore prior art not for a *shard* but for three of our **pillars**: the
**coordination journal** (its per-page append-only **journal** of semantic actions, with
the **story** as a derived replay view, UC-71), **overlay-before-mutation** (its **fork** —
own-site-only writes, source-site attribution, UC-26), and **union-without-erasure** (its
**neighborhood/roster** membership and **chorus** of provenance-linked forks, UC-72). As a
shard it attaches as a **REST/file-store hybrid** (page JSON + CORS, UC-70). **Boundary
recorded:** adopt the *model* (journal shape, fork-with-provenance, neighborhood) not the
client-only union-assembly locus or slug-as-identity; layer our cross-shard identity (T16)
above fedwiki's fork-DAG provenance edges. Architecture logged for `SHARD-WP-0002`
(T1–T5, T11, T13, T16): journal-as-coordination-journal, story-item write granularity,
journal-replay as a third merge model, fork entries as identity≠placement provenance edges.

### wikibase mapping

(⬡ UC-73–UC-75 are placed in the **wikiengines** matrix column; lineage = the **Wikibase
deep dive**, `research/260614-wikibase-deep-dive/findings.md`.)

| Wikibase mechanism (findings §) | Catalog UC |
|---------------------------------|------------|
| Items/properties + statements (claim+qualifiers+refs+rank); not-Markdown graph (§1) | UC-73 (new) |
| RDF projection + SPARQL (WDQS/Blazegraph) + federated `SERVICE` (§2) | UC-74 (new) |
| References + rank per statement = assertion-level provenance + coexistence (§1, §5) | UC-75 (new) |
| Typed records → typed *graph* entities (§1) | UC-34 (enriched) |
| Inter-record relations → typed graph edges with qualifiers (§1, §2) | UC-58 (enriched) |
| Native query → SPARQL/RDF + federated SERVICE (§2) | UC-52 (enriched) |
| Provenance → statement/value granularity (§1, §5) | UC-24 (enriched) |
| Opaque stable Q/P IDs; labels = annotations; identity ≠ label/placement (§3) | links UC-51 / T16 |
| WDQS = derived SPARQL index over canonical JSON entities via update stream (§3) | links UC-63 |
| Rank: contradictory values coexist with a curation signal (§1, §5) | links UC-27 / UC-72 |

Note: Wikibase (the engine behind **Wikidata**) is the **structure and native-query
far-end** of the studied set — a **typed knowledge graph** where a "page" is a set of
**statements** (claim + qualifiers + **references** + **rank**), not prose, queried with
**SPARQL** over an **RDF** projection (incl. **federated `SERVICE`** cross-endpoint joins).
Three things transfer cleanly: **opaque stable identity with labels-as-annotation** (the
cleanest real instance of identity ≠ placement, T16); **assertion-level provenance** —
references + rank let contradictory values coexist with curation (the *structured* chorus,
UC-75/UC-27); and **a derived graph index over a canonical entity store** (WDQS = UC-63 at
scale). **Boundary recorded:** content is **not Markdown** — attach as a structured shard
and render lossily (UC-55/UC-73), never silent-flatten the graph; expose SPARQL as a
graph-query tier (UC-74), not the union default. Architecture logged for `SHARD-WP-0002`
(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.

### tiddlywiki mapping

(⊡ UC-78 is placed in the **wikiengines** matrix column; lineage = the **TiddlyWiki deep
dive**, `research/260614-tiddlywiki-deep-dive/findings.md`.)

| TiddlyWiki mechanism (findings §) | Catalog UC |
|-----------------------------------|------------|
| One HTML file = engine + all tiddlers; save rewrites whole file (§1) | UC-78 (new) |
| Whole-file write granularity = coarsest tier; no per-page atomicity (§1, §6) | UC-35 (enriched) |
| Single HTML file as a container-format file-store shard (§1) | UC-40 (enriched) |
| Tiddler = flat record with arbitrary fields + tags (§2) | UC-34 (enriched) |
| Filter expressions `[tag[x]sort[...]]` = native-query tier (§4) | UC-52 (enriched) |
| Single-file ↔ Node `.tid` file-per-tiddler substrate swap (§3) | UC-43 (enriched); links UC-62 |
| Transclusion `{{tiddler}}` / `{{tiddler!!field}}` (§2) | links UC-32 |
| Identity = `title` (file-local) (§2, §5) | links UC-25 |

Note: TiddlyWiki is the **write-granularity and portability extreme** — a complete wiki
(content **plus** the app engine) in **one self-contained HTML file**, where every save
**rewrites the whole file** (whole-file write granularity, the coarsest tier: no per-page
atomicity — model overlays/locks accordingly). Its Node.js substrate stores **one `.tid`
file per tiddler**, git-diffable and fine-grained — so TiddlyWiki **spans the granularity
spectrum by substrate** exactly as Logseq spans file/DB (UC-62) and UC-43 anticipates. The
tiddler is a **flexible record with arbitrary fields** (UC-34), and **filter expressions**
are a real native-query tier (UC-52). **Boundary recorded:** treat the single HTML file as a
**container format** — extract content tiddlers, ignore the embedded engine; prefer the
`.tid` substrate for fine-grained write-through, single-file as read/projection/backup.
Architecture logged for `SHARD-WP-0002` (T11/T14): whole-file as the coarsest write tier,
single-file-container vs `.tid`-dir dual binding.

### ikiwiki mapping

(⊟ UC-79 lineage = the **ikiwiki deep dive**, `research/260614-ikiwiki-deep-dive/findings.md`;
marked in both federation and wikiengines columns.)

| ikiwiki mechanism (findings §) | Catalog UC |
|--------------------------------|------------|
| VCS(git)-backed Markdown source compiled to static HTML; web edits = commits (§1, §3) | UC-79 (new) |
| `pinger`/`pingee` XML-RPC = notify a peer to pull/rebuild (§2) | UC-31 (enriched) |
| Compile union/shard to a static site = outbound publish (§3) | UC-56 (enriched) |
| Static HTML = read-only regenerable backup (§3) | UC-37 (enriched) |
| Clone/pull/push between instances; wiki = git branch-space (§2) | UC-33 (enriched) |
| `aggregate` (RSS/Atom → pages) = inbound feed projection (§2) | links UC-03 |
| VCS-agnostic backend behind a plugin layer (§1) | links UC-43 |

Note: ikiwiki is a **wiki compiler** — git-canonical Markdown **source** built into **static
HTML** — so it mostly **reinforces** the git-IS-store home case (UC-76/40), but adds two
genuinely new things: **compile-to-static** as a clean *canonical-source vs derived-output*
separation (attach the **source repo**, treat static HTML as a regenerable
projection/publish target, UC-37/UC-56), and a **third federation flavor** — **git
replication + an XML-RPC change-ping** (peers hold clones, merge to reconcile, notify to
pull) beside fedwiki fork/journal (UC-72) and Wikibase `SERVICE` (UC-74). **Boundary
recorded:** never attach the build output as canonical; the pinger is a subscribe/notify
*mechanism* (peers/timing/conflict stay policy). Architecture logged for `SHARD-WP-0002`
(T4/T6/T14): git-replication+ping federation, compile-to-static publish, source-repo attach
sharing the git+Markdown adapter.

### quip mapping

(◧ UC-80 lineage = the **Quip deep dive**, `research/260614-quip-deep-dive/findings.md`.)

| Quip mechanism (findings §) | Catalog UC |
|-----------------------------|------------|
| Closed-SaaS doc + embedded spreadsheets/live apps; REST + HTML import/export (§1, §2) | UC-80 (new) |
| External-API mode with **HTML payload** variant (vs Notion block-JSON, Wiki.js GraphQL) (§2) | UC-57 (enriched) |
| Inline spreadsheets/live apps = non-Markdown content (§1) | UC-55 (enriched) |
| Embedded structured objects within a prose page (§1) | UC-58 (enriched) |
| Internal revisions, API-limited (§2) | UC-36 (enriched) |
| Salesforce-tied enterprise ACL + SSO (§3) | UC-06 (enriched) |
| HTML→Markdown lossy; embedded objects degrade (§2) | links UC-59 |
| Section/anchor HTML splice = mid write granularity (§2) | links UC-35 |

Note: Quip is the **enterprise document-collab** contrast to Notion — a **document +
spreadsheet hybrid** where a page is **prose interleaved with embedded live structured
objects** (spreadsheets, kanban/calendar "live apps"), reachable **only by REST** with
content crossing as **HTML** (lossy to Markdown; embedded objects don't round-trip), gated by
**Salesforce identity/ACL**. It generalizes the external-API mode with an **HTML payload**
variant (beside Notion block-JSON and Wiki.js GraphQL) and pushes the page model toward
**inline embedded structured objects** (not just whole-page-as-record). **Boundary
recorded:** surface embedded spreadsheets/apps **as what they are** with provenance and make
the HTML→Markdown lossiness explicit (never silent-flatten, UC-59); honor Salesforce ACL;
default to read/projection/overlay given rate limits + lossy export. Architecture logged for
`SHARD-WP-0002` (T11/T12/T14): external-API payload-format facet + a "proprietary
lossy-exportable" content-opacity tier, inline-embedded-object page model, enterprise-ACL
binding.

---

## 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.)
10. How does shard-wiki represent **non-Markdown content** (UC-55) — typed asset with a
    Markdown stub, opaque blob with provenance, or a pluggable content-type registry?
11. Is a **query-defined page** (UC-54) a core page type, an adapter feature, or a
    reference-UI/plugin concern? (Shared with catalog Q7.)
12. Is **external-API-only write-through** under a tight rate limit (Notion) viable at
    wiki scale, or do we default such shards to read/projection/overlay/backup? (Notion
    dive §10 Q1; ties UC-57.)
13. How are **inter-database relations** (UC-58) represented in the union — typed links
    in the link graph, a separate relation index (cf. ZigZag many-to-many), or both?
14. For an **encrypted shard** (UC-61), what is visible without keys (IDs/structure vs
    nothing), and does shard-wiki ever hold keys or only treat it as an opaque backup?
15. Is writing to a tool's **sync mirror** (UC-60) ever safe, or are interchange-format
    shards read/projection/overlay-only by policy? (Joplin dive §9.)
16. Is the **derived query index** (UC-63) built by the adapter (per-shard) or the core
    orchestrator (over the union), and is it persisted or rebuilt? (Logseq dive §10.)
17. When a tool offers **both file and DB substrates** (Logseq), does shard-wiki prefer
    the git-diffable file graph or the richer DB graph, and can one binding follow the
    migration? (UC-43, UC-62.)
18. For a **CRDT shard** (UC-64), does shard-wiki embed a CRDT client (Yjs/Yrs) to hold a
    live replica, or consume periodic snapshots — and are overlays CRDT ops or out-of-band
    patches? (Local-first workspaces dive §10.)
19. For a **P2P shard** (UC-65), what is the shard's address (space ID + peer / replica
    path / invite-key), and does shard-wiki ever hold E2EE keys or only treat it as an
    opaque replica? (UC-61.)
20. For a **DAG/cloned page** (UC-66), is it one page with multiple path placements, or a
    page transcluded into multiple locations? Does shard-wiki adopt Trilium's identity ≠
    placement (note/branch) split as its own page model? (Trilium dive §11.)
21. Are **inherited/templated attributes** (UC-67) materialized (snapshot) or computed
    live from the shard's tree/templates, and how is per-attribute provenance recorded?
22. For an **engine-maintained Git mirror** (UC-68), is the mirror or the engine DB the
    source of truth, and how do we write-by-commit without racing the engine's own sync?
23. Should the **coordination journal** (UC-71) adopt fedwiki's exact semantic-action
    vocabulary (create/add/edit/move/remove/fork) at item granularity, or an abstract op
    set other shards can also emit — and does a **chorus / no-canonical** union (UC-72)
    compose with shards that assert a canonical? (Federated Wiki dive §9.)
24. Does shard-wiki model a **typed-graph page** natively (entities + statements, UC-73) or
    always project Wikibase to a lossy Markdown/table view (UC-55) — and is **SPARQL/graph
    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.)
26. For a **single-file wiki** (UC-78), does shard-wiki support per-page overlays by
    buffering and re-serializing the whole file, or require the Node `.tid` substrate for
    write-through and treat single-file as read/projection/backup only? (TiddlyWiki dive §9.)
27. For a **compile-to-static** wiki (UC-79), does shard-wiki ever *drive* the build to
    **publish the union** as a static site (act as the compiler), or only attach existing
    source repos — and is the **pinger** modeled as shard-wiki's own subscribe/notify
    primitive or only recognized when bridging two ikiwiki instances? (ikiwiki dive §8.)
28. For a **SaaS live-doc shard** (UC-80), is an **embedded live spreadsheet** a typed
    sub-object with provenance (preferred) or a flattened static Markdown table — can
    overlays target a spreadsheet cell or only prose — and given HTML-only lossy interchange,
    is Quip ever write-through or read/projection/overlay/backup by default? (Quip 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.)