Follow-up: FactBase polish, cross-linking, Sources hub, entity page refactor

[OAGr]

Follow-up to #3645 and PR #3675 (restructured Data nav into Sources dropdown + standalone FactBase with sidebar).

Overview

Seven enhancement areas identified. After red-teaming each with adversarial subagents, several items were descoped or reframed. This discussion captures the refined plan.

---

1. FactBase Page Polish (Quick Win)

What: Add the missing Records Explorer card to the FactBase overview page. Currently only 3 of 4 explorer cards are shown.

Scope: ~5 lines of JSX in factbase-overview-content.tsx. Add a 4th card linking to /factbase/records.

What we're NOT doing: Breadcrumb additions (red-team found breadcrumbs already exist on all 4 detail pages — fact, entity, property, record). Header consistency is acceptable as-is (content components include their own description text). Entity page indentation cleanup is deferred to item 4.

Effort: Trivial.

---

2. Cross-Linking Between Sections (Scoped Down)

Red-team identified significant technical risks with URL-based cross-linking. Revised plan:

2a. Source Checks → FactBase fact link — ALREADY DONE

getRecordHref("fact", recordId) already returns /factbase/fact/{id}. No work needed.

2b. Resource detail → "Facts citing this resource" — FEASIBLE, needs build-time index

• 76% of facts have source URLs (751 unique URLs across 1,989 facts)
• Build a normalizedUrl → factId[] index during build-data.mjs using existing normalizeUrl() from crux/resource-utils.ts
• Emit as resourceFactLinks.json, lazy-loaded by resource detail page
• Show section on /resources/[id] when matches exist, hide when empty
• Key risk: URL normalization only handles www/trailing-slash. Need to audit match rate and consider expanding to handle protocol differences and query params. Log match statistics during build.
• Effort: Medium. The build-time index is the hard part.

2c. FactBase fact display → link to Resource — PIGGYBACKS on 2b

Same URL index, read in opposite direction (factIdToResourceId). Show resource title next to source URL on fact detail page.

• Only worthwhile if 2b is built (shared infrastructure)
• Effort: Small (if 2b exists).

2d. FactBase entity → resources on its wiki page — SKIP

Red-team found this has low value: the wiki page itself already shows resources via inline citations. The semantic mismatch ("resources cited on wiki page" ≠ "resources backing facts") would confuse users. Multi-step ID translation (entity → wikiPageId → slug → pageResources) creates fragile coupling.

What we're NOT doing:

• Runtime URL matching (performance risk, O(entities × facts × resources))
• getResourceByUrl() function (wrong approach — should be build-time index, not runtime scan)
• Adding resourceId field to FactBase YAML (correct long-term solution but scope too large for now)

---

3. Sources Hub Page at /sources (Investigate First)

Current state: /sources does a permanentRedirect("/resources"). The sources-overview-content.tsx component already exists with aggregate stats + cards linking to Resources and Publications.

Problem identified by red-team: We used permanentRedirect (308), which means browsers cache the redirect permanently. Changing /sources to a real page won't work for users who've already visited — their browser will skip the page and go straight to /resources until cache expires.

Plan:

1. Check if sources-overview-content.tsx already does what we need (it might be a 2-line fix)
2. If so, swap the redirect for rendering that component + add Source Checks and Data Sources cards
3. Consider: is this worth the 308 cache problem? For an internal wiki with few users, probably yes — just accept some users will need to clear cache

Effort: Small if the component already works. Medium if we need to build from scratch.

---

4. FactBase Entity Page Refactor (Scoped Down)

Red-team pushed back hard on the proposed 6-tier component architecture, calling it overengineered. Revised plan:

Extract only the obviously reusable pieces:

• VerdictBadge — used in multiple places across the page
• Record collection renderers (PersonCard, FundingRoundRow, ProductCard, ModelReleaseRow) — domain-specific, self-contained
• FactValueDisplay + SourceCell — core fact rendering logic
• GenericCollectionTable — generic record table

Target: 935 lines → ~500 lines. NOT 200 lines.

What we're NOT doing:

• 6-tier architecture with EntityPageLayout orchestrator
• Tier 5 "layout components" for a single SectionHeader (that's silly)
• Separate hero-stats.tsx for a single StatCard component
• Premature type centralization into a shared types.ts

New file: apps/web/src/components/factbase/entity-detail-components.tsx — all extracted components in one file. If it grows beyond 300 lines, split further then.

Also fix: Entity page indentation (cosmetic cleanup during the refactor).

Effort: Medium.

---

5. Orphaned MDX Cleanup (Architectural Decision)

Red-team raised important point: deleting the MDX files is an architectural decision about canonical URLs, not just cleanup. The 5 FactBase MDX files create dual paths — the same content is available at both /factbase (App Router) and /wiki/E1019 (MDX route).

Decision needed: Are FactBase explorer pages wiki articles or standalone app pages?

Recommendation: Standalone app pages (which is what the restructuring in #3675 established). The MDX files are pure component wrappers with zero prose content.

Plan:

• Keep MDX files (they're harmless and removing them risks breaking the ID registry)
• Add next.config.ts redirects: /wiki/E1019 → /factbase, etc.
• Do NOT "free up" wiki IDs — that risks broken references in session logs, things table, etc.

Effort: Small (just redirect entries).

---

6. Make Dropdown Label Clickable (SKIP)

Red-team identified this as a UX anti-pattern: making a single element both a link AND a dropdown trigger creates confusing behavior, especially on touch devices where there's no hover. The hover-to-open + click-to-navigate interaction creates a state machine conflict.

Better alternatives:

• Add "Overview" as the first item in the Sources dropdown (simple, no UX risk)
• Or just keep the dropdown as-is (users can reach any section in one click via dropdown items)

Decision: Skip the clickable label. If a Sources hub page is built (item 3), add "Overview" as the first dropdown item instead.

---

7. Data Sources Page — Real Implementation (DEFER)

Red-team correctly noted: the current /data-sources page already shows real data (entity type breakdown, resource type breakdown, enrichment stats, 4-step pipeline description). Calling it a "placeholder" overstated the gap.

The real Data Sources feature (pipeline tracking, freshness monitoring, snapshots via wiki-server API) doesn't exist on main yet. Building UI for a backend that doesn't exist guarantees a mismatch. When someone builds the pipeline tracking backend, they'll add the appropriate UI.

Decision: Defer. The existing page is adequate.

---

Priority Order

Priority	Item	Effort	Why
1	Records card (item 1)	Trivial	Genuine gap, 5 lines
2	MDX redirects (item 5)	Small	Prevents dual-path confusion
3	Sources hub (item 3)	Small-Medium	Needs investigation of existing component + 308 cache issue
4	Entity page refactor (item 4)	Medium	Maintainability improvement
5	Cross-linking (item 2b, 2c)	Medium	Needs build-time index infrastructure
—	Item 6 (clickable label)	—	Skipped (anti-pattern)
—	Item 7 (data sources)	—	Deferred (no backend yet)

Open Questions

1. How bad is the 308 redirect cache problem for /sources? With few users, is it acceptable?
2. Should cross-linking (item 2b) use build-time URL index or add resourceId to FactBase YAML long-term?
3. Is the entity page refactor worth doing now, or should it wait until someone actually needs to modify that page?

[OAGr]

Branch: claude/skill-fixes-discussion-cleanup

This discussion is 0-comment / 0-linked-issue since creation on 2026-04-03 and risks becoming vapor. The body already does the decomposition work — the priority table lists 5 concrete items. Suggested breakdown: (1) "FactBase overview: add Records Explorer card" (trivial), (2) "MDX redirects for /wiki/E1019 etc. → /factbase/*" (small), (3) "Sources hub at /sources: swap 308 redirect for real page" (small-medium), (4) "FactBase entity detail page refactor: extract reusable components" (medium), (5) "Cross-linking: build-time resource↔fact URL index" (medium). Deadline: by 2026-04-22, either link concrete issues for the items above or relabel this as a reference doc and close — otherwise the "4 phases, 0 done" status is misleading. — Discussion review 2026-04-08.