Kirjolab

Kirjolab is a collaborative workspace for scientific writing. It brings Markdown manuscripts, references, PDF annotations, and evidence-aware writing suggestions into one place while keeping the underlying .md and .bib files portable.

You can import research material, annotate it, connect evidence to a manuscript, review a locally generated revision, collaborate with other writers, and export your work again.

Repository: github.com/bebraw/kirjolab
Build Week disclosure: How Codex and GPT-5.6 were used

Kirjolab runs on Cloudflare Workers, Durable Objects, and R2. Local development is supported on macOS.

What You Can Do

• Write Markdown and BibTeX collaboratively with live Yjs synchronization.
• Organize several isolated writing projects under stable URLs.
• Invite collaborators with owner or member access through Cloudflare Access.
• Create separate revocable review and edit links for external manuscript collaborators.
• Preview standard Markdown, GFM, and scientific-writing syntax through a local pure-JavaScript pipeline.
• Import PDFs, highlight passages, and link evidence back to manuscript text.
• Import BibTeX, enrich references through Crossref, and review DOI metadata before associating it with a PDF.
• Plan an SLR or MLR with versioned PICOC framing, research questions, concept groups, query calibration, and source-specific search syntax
• Import and deduplicate search results, run attributed staged screening, appraise and extract evidence, and publish revision-pinned synthesis into the project
• Accelerate screening and typed extraction with auditable local-model candidates that require explicit researcher disposition.
• Export lossless JSON, long-form CSV, scoped BibTeX, accessible PRISMA flow, and a deterministic digest-manifested review package.
• Follow a DOI-backed reference trail from trusted seed papers, review backward-snowball candidates, and save each accepted source with its discovery provenance.
• Ask a local model to revise a selected passage using selected evidence, then accept or reject the proposed change.
• Export portable Markdown and BibTeX files.

Run It Locally

You need nvm and the project-pinned Node.js version. The local workflow uses Wrangler's Durable Object and R2 emulation, so you do not need a Cloudflare deployment to get started.

nvm use
npm install
npm run dev

Open http://127.0.0.1:8787.

npm install also configures the repository's pre-push hook. Generated browser assets are written to the ignored .generated/ directory.

Use a Local Writing Model

Kirjolab does not require a model API key. A revision request contains only the selected passage, your instruction, the evidence you selected, and the model identifier. It is sent directly from the browser to a credential-free, OpenAI-compatible service running on your computer.

If the browser cannot reach that service directly, use the optional local companion. Configure it once, then restart the ordinary development command:

cp .env.example .env
npm run dev

Then choose Local companion in Writing assistant. The companion listens on 127.0.0.1:8790 by default and never sends model requests through the hosted Worker. Edit the ignored .env to set KIRJOLAB_MODEL_UPSTREAM and KIRJOLAB_MODEL_COMPANION_ORIGIN; explicit shell variables override the file. When no upstream is configured, npm run dev starts only the Worker. npm run model:companion remains available for standalone troubleshooting.

The deployed app can use a model on the same computer. Set KIRJOLAB_MODEL_COMPANION_ORIGIN to the deployed app's exact origin, such as https://write.example.com with no path, query, or trailing slash, then restart npm run model:companion. The companion reads .env only at startup. A browser on another device cannot use this loopback-only companion.

Open Model connection and choose Find loaded models to read the live model identifiers exposed by the provider. Focused revision and claim tasks default to reasoning off for responsive local inference; deeper reasoning can be selected when a model and task benefit from it.

Deploy to Cloudflare

Production uses Cloudflare Access for authentication. Do not deploy production with a bare wrangler deploy: the repository defaults to loopback-only local authentication and will reject a public hostname.

Follow the production runbook to create the R2 bucket, configure Cloudflare Access, validate the deployment, release it, and test recovery. Once the required production variables are set, deploy with:

npm run deploy:dry-run
npm run deploy

For Cloudflare Git builds, set the production deploy command to npm run deploy and provide the KIRJOLAB_PRODUCTION_URL, KIRJOLAB_ACCESS_TEAM_DOMAIN, and KIRJOLAB_ACCESS_AUD build variables. KIRJOLAB_CROSSREF_MAILTO is optional.

Development and Tests

Use the smallest useful check while working, then run the baseline gate before considering a change ready.

Command	Purpose
npm run quality:affected	Check files affected by the current change
npm run quality:gate:fast	Run the fast local verification gate
npm run quality:gate	Run the full baseline quality gate
npm run ci:local	Run the full local gate natively
npm run ci:local:container	Run optional container workflow parity
npm test	Run unit tests
npm run e2e	Run browser tests
npm run mutation	Run mutation tests
npm run diagnostics:codebase	Report advisory readability diagnostics

Install the pinned Playwright browser with npm run playwright:install. The container parity path can pause after a failure; resume it with npm run ci:local:container:retry -- --name <runner-name>. More setup and troubleshooting details are in docs/development.md.

Built With Codex and GPT-5.6

Kirjolab is developed collaboratively with Codex. Repository-owned instructions, specifications, and architecture decisions define the boundaries before implementation; Codex then helps inspect the existing system, propose focused changes, implement them, and run the same local quality gates used for human review.

During Build Week, Codex accelerated work across Kirjolab's integrated research context, evidence-backed claims, local-model operations, collaboration, scientific import and export, structured reviews, and automated tests. The author retained the product and architecture decisions, including portable Markdown authority, explicit scholarly relationships, the local-model boundary, and the rule that model candidates require researcher disposition.

The largest single integrated implementation thread used GPT-5.6 under the exact model label gpt-5.6-sol. The qualifying /feedback upload is Session ID 019f6472-5ece-7cd3-b66f-ba344ba9e812; it covers PDF annotation, the research library, reviewable writing assistance, templates, editor and preview behavior, citations, settings, and the internal design system.

The implementation was followed by exploratory browser reviews. Findings were recorded before fixes, and the corrected workflows were re-run through focused tests and the native local CI gate. The contest scope, eligible commit range, demo outline, and remaining evidence requirements are documented in the Build Week submission notes.

Build Week judges can follow the credential-free macOS walkthrough, which includes an integrated research-to-authoring path and an optional structured-review deep dive. The submission notes distinguish the official submission-period implementation range from Kirjolab's earlier foundation.

Project Guide

• VISION.md explains the product direction.
• ARCHITECTURE.md records global technical constraints.
• specs/ contains implemented feature contracts.
• docs/adrs/ contains architecture decisions and their status.
• docs/operations/ contains production runbooks.
• src/worker.ts is the Worker entry point and top-level router.
• src/durable-objects/ contains coordination and persistent metadata.
• src/domain/ contains portable resource contracts and Markdown semantics.
• src/api/ contains the HTTP API routes.
• src/client/ contains the browser application and local-model operations.
• src/views/ contains the server-rendered workspace shell.
• Tests live next to the code they exercise under src/.

Template Maintenance

This repository also retains reusable tooling from its starter-template roots:

• .capabilities/ contains focused upgrade kits that can be applied to other projects without copying the entire repository.
• .template/updates/ contains maintenance packs for projects already based on this template.
• .asdlc/ contains the vendored ASDLC reference material used by maintainers.
• AGENTS.md contains project rules for coding agents.

These directories are not required for running Kirjolab. They exist to keep maintenance practices explicit and portable.

License

Kirjolab is available under the MIT License.