Forkability audit: 6 substrate problems found onboarding fractalresonance.com

[servathadi]

Reporter: River (FRC custodian, fractalresonance.com onboarding)
Date: 2026-04-26
Working notes: agents/river/INKWELL_FRC_ONBOARDING.md in the Mumega-com/mumega-com repo
Local fork under audit: /home/mumega/fractalresonance.com/ (cloned from current Inkwell main)

I tried to fork Inkwell to host fractalresonance.com (FRC's lab + paper distribution). The fork builds (npm run build exit 0, 9 pages, 2.2 MB dist) but only after structural surgery. Six problems below, ranked by what blocks new forks today.

---

P-006 — Upstream tree ships mumega.com's actual site as default (MAJOR)

What I found after git clone + audit:

• Mumega's marketing pages: src/pages/{vision,whitepaper,about,pricing}.astro
• Mumega's site sections as page directories: team/, products/, tools/, locations/, portal/, dashboard/, plan/, course/
• Mumega's content: content/en/{team,blog,pages,docs,tools,labs,books/inkwell-manual}/
• Mumega's business components: BusinessDiscovery.tsx, PlanDashboard.tsx, ContractPortal.tsx, ContractForm.tsx, MovingQuoteForm.tsx, ChatWidget.tsx, Dashboard.astro
• Hardcoded mumega menu items in src/components/layout/{Header,Footer}.astro
• Hardcoded `https://github.com/Mumega-com/inkwell\` in Footer (should come from config)
• Hardcoded paths in src/pages/sitemap.xml.ts (`/tools`, `/team`, `/products`, `/vision`)
• Mumega-shaped collections in src/content.config.ts

To get to a clean fork I had to delete ~40 files/dirs and rewrite 6 more. The Forkable Microkernel framing in README + FORK-GUIDE doesn't survive first contact.

Proposed:

1. Move Mumega's site (pages, content, layouts, business components, dashboards) into Mumega-com/mumega-com (which already exists with Mumega-com/inkwell as upstream).
2. Strip upstream Inkwell to a clean scaffold: blank index page, generic Header/Footer that read nav from inkwell.config.ts, minimal content/en/blog/example.md + content/en/docs/example.md starters, no business components, no team/products/tools dirs.
3. Add nav.header[], nav.footer[], seo.github fields to inkwell.config.ts so layout files never hardcode brand-specific links.
4. Slim src/content.config.ts to a minimal generic schema; each fork extends.

---

P-008 — Substrate code in fork tree (STRUCTURAL, year-2 risk)

kernel/, plugins/, workers/inkwell-api/, much of src/lib/ are substrate the forker doesn't customize but lives in the same tree as forker-customized files. `git pull upstream main` is fine today (conflict surface is bounded to ~6 customized files), but as the kernel ages and a fork accumulates customizations, divergence cost grows.

Proposed (defer if controversial): workspace pattern. Extract kernel/ + plugins/ to @mumega/inkwell-kernel package. Forks become thin: config + content + plugins-local. `git pull upstream` retires; forks bump kernel via npm. Solves multi-fork drift (mumega.com, fractalresonance.com, future customers) at one stroke.

---

P-005 — Two coexisting onboarding patterns, no top-level disambiguation

FORK-GUIDE.md documents npx create-inkwell (fork-with-upstream-tracking) — the working production pattern.

instances/_template/README.md documents sos init --slug acme ... — multi-tenant pattern that's partially-implemented (instances/mumega/ only has wrangler.toml; sos init CLI doesn't exist; see P-001).

A new forker can't tell which is canonical. Cost me ~30 min before I figured out mumega.com itself uses the fork pattern.

Proposed: either delete instances/_template (if multi-tenant isn't the target), or finish it (implement sos init) + add top-level WHICH-PATTERN.md.

---

P-001 — sos init CLI does not exist

instances/_template/README.md references `sos init --slug acme ...` as the canonical instance-creation command. `/usr/bin/sos` on the server is the unrelated Linux sosreport tool. No Mumega `sos` CLI binary, no `init` script under `scripts/` or `SOS/`.

Proposed: either implement, add init.mjs to scripts/, or update README to point at the actual tool.

---

P-002 — No research / lab preset

instances/_template/presets/ ships agency, company, creator, saas. None match a research lab (papers, citations, topic graph, math, opinion-level taxonomy, submission queue, no commerce).

Proposed: add lab preset. Default plugins: content, analytics, seo, search, feedback, auth (tier gating), plus the still-missing papers and citations plugins.

---

P-007 — Pages query missing collection entries → silent empty HTML

After cleanup, several pages silently built empty HTML files because they queried pages/<slug> entries that no longer exist (/privacy, /terms, etc). Forced extra deletions to keep the dist clean.

Proposed: pages should 404 with a configuration hint when a queried collection entry is missing, not build empty HTML.

---

What works (credit where due)

• KaTeX math rendering wired in astro.config.mjs ✓
• Knowledge-graph + wikilinks built in ✓
• Pagefind search built in ✓
• Build pipeline is solid (699 packages, 46s install, 9 pages built clean) ✓
• The fork-with-upstream pattern itself is sound; mumega.com's been running on it
• inkwell.config.ts schema is well-shaped for non-mumega-coupled fields

The kernel is good. The presentation layer is contaminated. P-006 is the one I'd ship first; P-008 is the one that'll bite us in 6 months if not addressed.

---

cc: @servathadi