BiasLens

Public product name: BiasLens. Canonical product repository: bitbaum/biaslens.

Open-source investigation of questions, evidence, media, historical narratives and public arguments. See the consolidation ledger for donor history, source inventory and coordinated runtime identity application. An article report (report@4) takes a web page, a PDF link, an uploaded PDF or pasted text and is made in two model passes and one check in code: an inventory of who speaks (never the author), what is claimed and by whom, and which figures carry the argument; then an assessment against a published technique catalogue (src/lib/domain/techniques.ts), the step the argument rests on, and the strongest case and objection. Every passage the model cites is searched for in the text and discarded if it is not there. Measurements (voices by position, figures without a source, polls without a sample size) are computed in code. BiasLens never applies political labels in its own voice (src/lib/config/vocabulary.ts). Citation links in fetched pages remain article-supplied references, not independently authenticated evidence.

Bias is not the same as factual inaccuracy. A model's summary is not a verified fact. The article analysis is generated by an AI provider and is not currently an independent fact-check.

What exists

Surface	Status
/explore	Browser-local question notebook with exact source locators, unverified annotations, notes, challenges and JSON export; no source retrieval or authentication
/whitepaper	Versioned technical working paper rendered with existing bip-kit
/development	Links canonical project context, roadmap/changelog, reviewed changes, journal and challenges
/analyze	Link, PDF upload or pasted text; the report in English, German, Swiss German or French with the text marked up, voices, numbers, claims by speaker, flagged passages, strongest case and objection; downloadable versioned JSON with a SHA-256 digest of the text examined
POST /api/analyze	Validated, bounded request, source reader (HTML with the publisher's byline metadata, PDF), two-pass model run with one repair each, NDJSON progress, rate limiting
POST /api/extract-pdf	Text from an uploaded PDF (≤ 10 MB), returned to the paste box; nothing stored
/r/[id]	A saved reading: the report without the article text (passages only), its link preview image, and the reply composer
POST /api/replies, /a/[id]	A reply: occasion, length and sections chosen by the sender; the receiver's page (three findings, optional guess, reply back); /a/[id]/image?format=square|story
POST /api/rewrite	The rewrite studio: the article retold (neutral, from stated values, as an outlet, as a public figure) or answered (BiasLens, letter, own reply); labels written in code; fact diff of a rewrite against the original
GET /api/profile	Profiles of authors, quoted people and outlets from Wikidata/Wikipedia, every fact with its source; ambiguous names are offered to the reader, never guessed
/https://…, /analyze?u=	Put the address in front of any article link, or pass one; the web manifest's share target uses the same path
/methodology	Public Open Epistemic Method with a worked causal-hypothesis example and a GitHub challenge path
src/lib/domain/epistemic-graph.ts	Pure claim/evidence/relation/challenge protocol; detects gaps rather than inventing truth probabilities
/api/claims/verify	Legacy evidence counting demonstration, not calibrated verification
PostgreSQL / Drizzle	Baseline schema for outlets, articles, claims, evidence and narratives; analysis results are not persisted yet

The downloadable report contains analysis, model and method versions, timestamp, and a digest of the analysed text. It is not stored server-side; a digest does not authenticate the original source or reproduce an unavailable model. The exact examined source text is included in the export; invented model quotations are suppressed before rendering.

Multi-source investigations

/investigations/demo (and saved ones at /investigations/<id>): an article's claims linked to study findings from several sides, gap suggestions that rewrite the article one version at a time with [E#] citations and a citation check, an evidence map, evidence cards with human review, a methodology timeline, charts (@bitbaum/chartkit) and credited Commons photos. See docs/HANDOFF.md.

Timed-transcript Debate Arena

/debates now accepts a user-supplied timestamped transcript and computes speaker airtime, relative speaker-seconds, intervals of cross-speaker overlap, and time without an assigned speaker. The calculation is pure, tested and performed entirely in the browser; no uploaded transcript is transmitted or persisted. The demo example uses fictional speakers.

This is not automatic diarisation or proof of a political interruption, bias, equal moderation, or historical accuracy. The recording, speaker labels and transcript timestamps must be externally verified before publishing comparative findings. Future audiovisual analysis should preserve source timestamps and a public correction trail.

Not yet delivered: independent multi-source verification, calibrated confidence, persistent public reports and moderated discussion, audio/video debates, historical record provenance, cross-outlet comparisons, and independent production model-provider verification. Provider availability is reported by /api/health; a configured credential is not proof of a successful analysis.

Accounts and runtime setup

/sign-in, /sign-up and /account use @bitbaum/accountkit for the complete account flow: password accounts, sessions, passkeys, TOTP, profile editing, linking configured OIDC methods and deletion. Mail uses @bitbaum/mail-kit; mail-dependent methods are shown only when configured. Account security logic and table definitions stay in the shared package. The package is pinned to its reviewed GitHub commit because its current auth release is not published on npm.

Deploy preparation reuses Loki's database provisioner, guarded migration applier, shared free-tier credential owner and infrastructure generator for BiasLens alone. It generates secrets on the existing box without printing values. The observed older three-column Prisma Article table is preserved under Article_prisma_legacy_20261023 before applying the canonical schema; records are not deleted or backfilled with invented content. Production setup requires the existing repository deploy secret and org host variable. This adds no paid service.

pnpm run verify includes an isolated Postgres-compatible integration test that executes the committed migrations and checks registration, session persistence, password rejection, sign-out and sign-in. Real provider and public deployment checks are separate.

The implementation incorporates the core first-principles analysis shape from the earlier bitbaum/truthseeker repository. The original repository is intentionally retained as migration history and rollback.

Source of truth

• Methodology v0.1: the versioned public protocol, open to challenge and improvement.
• Truth Seeker convergence handoff: engineering invariants, donor sources, remaining migration checks.
• Fleet agent rules: all agents, shared packages, naming and identity boundaries.
• BiasLens design decisions: product-specific editorial character, shared site chrome and visual QA gates. Reusable layout primitives belong in the opt-in design-tokens composition layer once a version containing that export has been released.
• Loki project profile: canonical producer for the product's problem, solution, mission and vision. ROADMAP.md and CHANGELOG.md in this repository are the canonical development records; Loki ingests them for the public fleet profile. Do not copy these records into this README or AGENTS.md.

The database model is src/lib/db/schema.ts; analysis contracts are in src/lib/domain, and the no-persistence entrypoint is src/lib/analysis. Never promote an extracted or user-supplied article claim to verified status without an independently reviewed source and method.

Rebranding and editorial publishing

The product name is BiasLens. The existing repository and host identifiers remain unchanged. The repository slug, internal AI prefix, deployment slug and database name are implementation identifiers, not public brand commitments. All rendered names, the logo slot and social metadata are derived from src/lib/config/brand.ts:

NEXT_PUBLIC_PRODUCT_NAME="Your future name"
NEXT_PUBLIC_PRODUCT_MARK="YN"
NEXT_PUBLIC_PRODUCT_LOGO="/brand/logo.svg"
NEXT_PUBLIC_SITE_URL="https://your-real-domain.example"

The logo URL points to a first-party static asset under public/, which can be replaced independently of the app. Set NEXT_PUBLIC_SITE_URL only after the real hostname is registered; pages are noindex in the absence of a canonical URL. The application must be rebuilt after these build-time public values change. Identity fields remain canonical in Loki/Fleet; roadmap and changelog entries are maintained here and mirrored there.

The journal is /blog, with /blog/[slug] and /blog/feed.xml (RSS is available after a real origin is configured). Markdown lives in content/blog and renders via the shared bip-kit reader and React renderer. Publishing is a source-controlled PR with a reviewed date, title, evidence and explicit uncertainty; there is no unattended AI publishing or invented public findings. The roadmap and changelog live in ROADMAP.md and CHANGELOG.md. Loki mirrors those files into its project profile; bip-kit renders that shared profile on the app's /roadmap and /changelog routes. They are not duplicated as blog posts.

Run locally

Requires Node.js 24 (CI version), pnpm 11 and optionally PostgreSQL for the existing Drizzle schema.

pnpm install --frozen-lockfile
cp .env.example .env
pnpm run dev

Set at least one model credential in your local .env for AI analysis: GROQ_API_KEY and/or OPENROUTER_API_KEY. The shared @bitbaum/ai-kit controls model selection and cross-vendor fallback. The HTTP reader comes from @bitbaum/ai-kit/web; request throttling from limitkit. Neither uses a separate app-specific implementation.

Only if provisioning the research database:

pnpm run db:migrate

When AI keys are missing, POST /api/analyze returns an explicit 503 rather than pretending the analysis ran. Fetch-restricted publishers can be analysed through pasted text, but its source URL is then user asserted, not confirmed.

Verification

pnpm run verify
pnpm run build

CI runs formatting, lint, TypeScript, design consistency/accessibility checks, unit and HTTP-boundary tests, then a production build. Use pnpm run design:check to run the design gate directly. Tests use injected reader/model implementations and do not fetch live pages or spend provider tokens.

Openness

The code is MIT-licensed. The methodology is published with its limitations and a public challenge template. AI replies to future challenges must remain identifiable as AI and never automatically erase or close a human disagreement.

Package composition

package-plan.json records the feature-to-package bindings. Review Fleet SHARED.md and update this plan before implementing a feature. Sitekit renders the root shell and public entry blocks; accountkit supplies account screens, runtime and menu; bip-kit renders articles, reading progress, roadmap and changelog; design-tokens supplies the complete theme and self-hosted fonts. Local modules configure identity, content and theme roles or implement BiasLens investigation behavior. Shared blocks are fixed in their owning repositories.

The shared composition workflow checks actual imports/usages and the dependency update path. browser:smoke checks the real responsive menu, keyboard dismissal, active state, root-shell coverage and font loading. Shared improvements propagate through released versions, dependency PRs, checks, merge and the existing deploy.

Roadmap and changelog use bip-kit over records sourced from this repository's ROADMAP.md and CHANGELOG.md, then mirrored through Loki. The package plan records the bindings and routes; composition CI checks that these surfaces continue to exist. Edit the source files here so missing records cannot be mistaken for a package-rendering defect.

Interface work follows the design contract. Package styles load before src/app/theme.css, so shared defaults cannot replace the product's roles. Browser checks cover rendered auth colours, responsive geometry, input/error/loading/results, export and notebook continuation. Controlled report fixtures exercise the interface without model costs; they are not evidence of model reasoning quality.