# unknown

> > Semantic colors must remain muted and compatible with the mid-tone theme. Never use neon.

- Author: SinergaOptima
- Repository: SinergaOptima/Clarum
- Version: 20260208011622
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/SinergaOptima/Clarum
- Web: https://mule.run/skillshub/@@SinergaOptima/Clarum~unknown:20260208011622

---

# Clarum

Clarum is an editorial, evidence-first geopolitics publication and workspace that turns major claims into auditable ledgers backed by peer-reviewed research and living consensus hubs.

## What Clarum is

- **Hub**: A living topic page (for example Infrastructure, Sanctions effectiveness) with scoped core claims, status buckets, evidence links, and changelog.
- **Ledger**: A claim-by-claim audit of a specific source article with verdicts, confidence, scope warnings, evidence stack, and correction trail.
- **Evidence vs Interpretation**: Evidence verdicts are method-neutral and structured. Interpretation appears in a separate, explicitly labeled `Interpretation (Multipolar Lens)` block and does not override evidence judgments.

## Stack

- Next.js App Router + React + TypeScript (strict)
- TailwindCSS + Radix primitives + shadcn-style UI components
- Zod schemas for strict content contracts
- TanStack Table for claim table interactions
- Fuse.js for command palette and `/search`
- File-based content in MDX + frontmatter under `content/`

## Project structure

- `app/` routes
- `components/clarum/` Clarum signature components
- `components/ui/` shared UI primitives
- `components/motion/` motion tokens
- `content/hubs/`, `content/ledgers/`, `content/evidence/`
- `config/outlets.ts`, `config/researchSources.ts`
- `src/lib/content/schema.ts`, `src/lib/content/loaders.ts`, `src/lib/content/rules.ts`
- `lib/content.ts`, `lib/search.ts`, `lib/access.ts` (compat surface)
- `scripts/build-search-index.ts`
- `scripts/validate-content.ts`
- `public/searchIndex.json`, `public/taxonomy.json` (generated)
- `docs/content-rules.md`
- `skill.md` (design spec source of truth)

## Local run

```bash
pnpm install
pnpm dev
```

Optional local paid-feature bypass:

```bash
NEXT_PUBLIC_DEV_BYPASS_SUBSCRIPTION=true
```

Production build:

```bash
pnpm build
```

Static export output is generated in `out/` (GitHub Pages artifact directory).

## Deploy to GitHub Pages

1. Push this repository to GitHub.
2. In GitHub, open `Settings -> Pages`.
3. Under **Build and deployment**, set **Source** to **GitHub Actions**.
4. Push to `main` (or run the workflow manually) to trigger `.github/workflows/deploy-pages.yml`.

Deployment behavior:

- Repository named `<user>.github.io`: site is served from `/`.
- Any other repository name: site is served from `/<repo-name>` via automatic `basePath`/`assetPrefix`.

Local production-style check:

```bash
pnpm build
```

Then serve `out/` with any static server.

## Content validation and publishing rules

- `pnpm validate:content` checks frontmatter schemas, URL hygiene, evidence cross-links, and publishable tier gating.
- `pnpm build` runs `validate:content` and fails fast on violations.
- Public pages render only Tier A + `publishable: true` content.
- Development visibility override:
  - `NEXT_PUBLIC_SHOW_NON_TIER_A=true`
  - or `?show=all` in non-production routes.

Note: GitHub Pages deployment is fully static and does not use request-time query handling for visibility toggles.

See `docs/content-rules.md` for the full policy.

## Content authoring (MDX)

Frontmatter is parsed and validated with Zod:

- `content/hubs/*.mdx` -> `Hub`
- `content/ledgers/*.mdx` -> `Ledger`
- `content/evidence/*.mdx` -> `Evidence`

When adding content:

1. Create a new `.mdx` file in the relevant folder.
2. Fill required frontmatter fields from `src/lib/content/schema.ts`.
3. Link claims to valid evidence IDs.
4. Run `pnpm validate:content`.
5. Run `pnpm build:index` to refresh search/taxonomy outputs.

## Publish a new hub or ledger

1. Add new MDX file with valid frontmatter (`published: true` when ready).
2. Promote content to Tier A by setting:
   - `dataQuality: "tier_a"`
   - `publishable: true`
3. For hubs, include sections with structured claims and valid evidence links.
4. For ledgers, include deep-link `source.url` metadata and structured claim evidence refs.
5. Run `pnpm validate:content`, then `pnpm build:index` and `pnpm build`.

## Search indexing pipeline

- `pnpm build:index` executes `scripts/build-search-index.ts`.
- Output:
  - `public/searchIndex.json`: unified entries (`hub`, `ledger`, `evidence`, `section`)
  - `public/taxonomy.json`: tags + counts
- `pnpm dev` and `pnpm build` both run validation + indexing first.

## Workspace drafts and export

- Route: `/workspace/drafts`
- Local-first persistence keys:
  - `clarum.drafts.ledgers`
  - `clarum.drafts.hubs`
  - `clarum.drafts.evidence`
- Supports:
  - Draft Ledger Builder
  - Draft Hub Claim Builder
  - Draft evidence notes
  - Export to MDX / JSON or copy-to-clipboard

## Access model

- Public: all published content
- Individual ($15/month): private workspace drafts, exports, watchlists, saved library
- Enterprise/Team ($40/month): shared workspace + review workflow
- Billing integration is scaffolded safely: app remains usable if billing env vars are missing and shows `Billing not configured`.

## Roadmap

- Accounts/auth persistence beyond local-first draft storage
- Billing checkout + webhook subscription state updates
- Monitoring automation for claim ingestion pipelines
- BYOK AI assistance (optional only, manual workflows remain primary)