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/, and research/260614-localfirst-workspaces-deep-dive/. See InfoTechPrimers on coulomb.social for use-case catalog conventions.

Conventions

Each use case lists:

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

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

---

A. Information space and federation

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

UC-01 — Standalone open wiki (L0)

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

UC-02 — Attach a shard to an information space

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

UC-03 — Project a remote shard page locally

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

UC-04 — Overlay edit on read-only shard

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

UC-05 — Union derived views

Actor: Reader
Goal: Navigate BackLinks, RecentChanges, AllPages, SiteMap, or Search across all attached shards as a federated graph.
Source: intent, c2, yawex
Notes: Present on both c2 (community nerve center) and yawex core pages. BackLinks over the union link-graph is the strongest core candidate; per-shard vs union scope remains open (see UC-19–UC-21). ZigZag deep dive reframes these views under one vocabulary: each is a dimension + raster (RecentChanges along d.recent, AllPages along d.alphabetical, SiteMap as an H-view over the namespace dimensions), navigable via UC-47 (research/260614-zigzag-deep-dive/findings.md §5). Note: the many-to-many link/backlink graph stays a separate graph index, not a zz-rank.
Priority: Later

UC-06 — Authenticated team wiki (L2+)

Actor: Authenticated principal
Goal: Read and write under role-based authorization with identity from an external provider.
Source: intent, yawex
Notes: yawex htpasswd + per-topic AccessControl is prior art only; shard-wiki delegates authentication, owns authorization (spec/ArchitectureBlueprint.md). yawex's model traces to TWiki's per-topic ALLOW/DENY TOPICVIEW/CHANGE/RENAME — the origin reference for shard-wiki's optional per-page ACL at L4 (research/260613-twiki-deep-dive/findings.md §4).
Priority: Later

UC-07 — Detect and reconcile cross-shard divergence

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

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

Actor: Author
Goal: Copy a page from a remote or read-only shard into a local writable shard for independent editing, with provenance preserved.
Source: federation, intent
Notes: Fedwiki fork primitive. shard-wiki may realize as import, overlay seed, or writable copy per policy — distinct from UC-04 (overlay without copy) and UC-03 (projection only). Fork vs overlay vs import decided in SHARD-WP-0002. Should record a created-from genealogy edge in the coordination journal so the lineage is navigable as a dimension (UC-49, research/260614-zigzag-deep-dive/findings.md §9).
Priority: Later

UC-27 — View multiple versions of equivalent page

Actor: Reader
Goal: See coexisting versions of the same topic from different shards or authors without collapsing them into one canonical page.
Source: federation, intent
Notes: Fedwiki "chorus of voices"; INTENT union without erasure. Equivalent- page identity model TBD (SHARD-WP-0002) — Xanadu deep dive offers a path-independent detection mechanism via content-identity / span-set intersection (UC-46, research/260614-xanadu-deep-dive/findings.md §5, §8.2). Links UC-07 divergence detection.
Priority: Later

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

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

UC-35 — Attach a shard with coarse write granularity

Actor: Maintainer
Goal: Attach a backend whose unit of write is not the page — a single-file wiki (TiddlyWiki) or a whole-space/DB-transaction engine — and have shard-wiki respect that granularity instead of assuming per-page writes.
Source: wikiengines, intent
Notes: Capability-aware adapters: the capability profile must encode write granularity (per-page / per-file / per-space / append-only). Overlay and patch flows must adapt (findings §5 #1). Affects conflict scope and locking. Roam marks the fine extreme — block-level writes (block.create/update/move/delete), the opposite of TiddlyWiki's whole-file granularity (research/260614-roam-deep-dive/findings.md §6).
Priority: Later

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

Actor: Maintainer
Goal: Attach an engine whose revisions live only in its own database (Confluence, MediaWiki) and give the information space a portable, git-backed history it otherwise lacks.
Source: wikiengines, intent
Notes: Many engines expose revisions but not portable, git-style history. The coordination journal supplies the Git-addressable layer (INTENT). Open: is the journal authoritative or a mirror reconciled back to the engine (findings §6 Q3)? Complements UC-07 divergence and UC-24 provenance. XWiki's internal RCS table (xwikircs) is a concrete instance (research/260613-xwiki-deep-dive/findings.md §2.4). This UC is supplementation (the engine's past is DB-locked); where history is already in an open file format (TWiki RCS .txt,v) it can instead be imported — see UC-41. 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).
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).
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).
Priority: Later

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

Actor: Maintainer
Goal: When an engine already keeps history in an open file format (TWiki/yawex RCS .txt,v), import that history into the Git-backed coordination journal preserving authorship and timestamps — not just start a fresh journal going forward.
Source: wikiengines, intent
Notes: History migration with fidelity, distinct from UC-36 supplementation (where the engine's past is locked in a DB and the journal can only begin now). Open: is the imported history authoritative or a one-time backfill (research/260613-twiki-deep-dive/findings.md §8 Q2)? Strengthens recoverability (INTENT History as the safety net).
Priority: Later

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

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

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

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

---

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).
Priority: Later

UC-16 — Append or comment without full edit

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

---

C. Discovery and navigation

Derived views and browse patterns from c2 and yawex.

UC-17 — Change radar

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

UC-18 — BackLinks navigation

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

UC-19 — All pages and site map browse

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

UC-20 — Full-text search

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

UC-21 — Serendipitous browse

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

UC-22 — Namespace and path navigation

Actor: Reader or author
Goal: Resolve and navigate pages using relative (../), absolute (/), and normalized paths within a topic hierarchy.
Source: yawex
Notes: yawex topics-as-directories; page-resolution state space is inspiration only for federation design (not inherited as API). ZigZag deep dive: treat the namespace hierarchy as one dimension among many (encoded left-child/right-sibling as two zz-dimensions), not the privileged structure — consistent with mechanism over policy; navigate it as one axis via UC-47 (research/260614-zigzag-deep-dive/findings.md §4, §7.1).
Priority: Later

UC-23 — Soft topic creation via red link

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

---

D. Provenance and page metadata

yawex Page::info and c2 attribution norms.

UC-24 — Inspect page provenance

Actor: Reader
Goal: See source shard, modification time, freshness, editor attribution, edit count, and whether the page has local overlays or diverges elsewhere.
Source: yawex, c2, intent
Notes: yawex Page::info; c2 optional UserName signing. INTENT explicit provenance principle. Xanadu deep dive: provenance is structural, not decorative — content remembers where it came from and where it is reused (UC-45), built into the storage model rather than added after the fact (research/260614-xanadu-deep-dive/findings.md §4, §8.1).
Priority: Later

UC-25 — Collaborative glossary and precise naming

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

---

Traceability

UC	c2 research	yawex research	federation research	wikiengines research	INTENT
UC-01	✓				✓
UC-02		✓			✓
UC-03		✓	✓		✓
UC-04	✓	✓	✓		✓
UC-05	✓	✓	✓		✓
UC-06		✓			✓
UC-07			✓		✓
UC-26			✓		✓
UC-27			✓		✓
UC-28			✓
UC-29			✓		✓
UC-30			✓
UC-31			✓		✓
UC-32			✓		✓
UC-33			✓		✓
UC-34				✓	✓
UC-35				✓	✓
UC-36				✓	✓
UC-37				✓	✓
UC-38				✓	✓
UC-39				✓	✓
UC-40				✓	✓
UC-41				✓	✓
UC-42				✓	✓
UC-43				✓	✓
UC-44			✓†		✓
UC-45			✓†		✓
UC-46			✓†		✓
UC-47			‡		✓
UC-48			‡
UC-49			‡		✓
UC-50				§	✓
UC-51				§	✓
UC-52				§	✓
UC-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-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.

---

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.)