Manuscript Lab

Manuscript Lab is local CI for prose.

It gives long-form writing what software takes for granted: section contracts, checks, typed issues, revision trails, an evidence spine, and release gates — all in plain files in your repo, driven by a zero-dependency Node CLI that humans, agents, and CI jobs can share.

Sixty-Second Start

Requires Node.js 18 or newer. No runtime dependencies.

Start clean:

npm install -D manuscript-lab
npx mlab init

Or adopt a manuscript you already have:

npx mlab adopt existing-draft.md

Then:

npx mlab status
npx mlab report --write

init scaffolds a contracted workspace: manuscript-lab.config.json plus a manuscript/ root with section contracts, state directories, and source/claim registers (customize with --profile, --root, --title). adopt copies every markdown file into contracted draft/ sections without modifying or moving your originals.

Expect a freshly adopted draft to report blockers — that is the point. Short imported sections sit below the word floor, claims have no sources yet, and every imported contract starts confirmed: false with a provisional purpose inferred from the text: reviewing each section's purpose and acceptance, then flipping the flag to confirmed: true, is the one judgment step adopt cannot do for you. The report names each gap and the exact command or edit that closes it, so "not ready" is a work list instead of a shrug.

What You Get

• Section contracts: each draft/*.md opens with a machine-checked contract (status, target words, purpose, acceptance, checks, reviews).

• Checks: mlab check runs deterministic document checks; mlab check --fix creates any missing required scaffolding and rebuilds state/status.md / outline.md from the section contracts — statuses restated, deleted sections dropped, new sections added — then re-checks.

• Typed issues: reviews write durable work items to an issue ledger instead of advice that disappears in chat. Projects can register their own typed review lenses and prompts under the manuscript root; mlab review list shows the merged built-in/project catalog. mlab issues batch applies many decisions/closures from JSON or JSONL in one validated, locked transaction.

• Candidate trails: high-stakes revisions run as candidates, blind comparison, taste gate, merge winner, diff audit — never a silent rewrite.

• Evidence spine: claims, sources, and citation markers share one implementation across claims, citations, evidence, and the gates, with stable evidence.* requirement ids.

• Gates: section-ready, citation-ready, manuscript-ready, and export-ready decide readiness from evidence, not vibes. Sections marked todo block, prose below 33% of a section's target word count blocks, and applicable declared reviews warn when they have never completed or no longer match the section body and review definition.

• Reports with fix commands: every blocker in mlab report (terminal, JSON, HTML) carries the command that addresses it. Advisory review gaps are shown separately with exact mlab review run ... --passes ... commands. For example:

  Blockers:
  - claim_unresolved: Claim "Documentation teams recover forty percent of
    review time after adopting local prose CI." is unsupported with
    unspecified risk and blocks release.
    fix: mlab claims list --unsupported

• Export manifests: mlab export writes Markdown and HTML by default plus exports/manifest.json with input/output hashes. EPUB and PDF are explicit opt-ins (--formats md,html,epub,pdf); EPUB needs zip, PDF needs python3 with the reportlab package.

• Narrative observations: bare mlab narrative builds the manuscript convergence profile; its subcommands extract a cached structural template per section, derives discourse-level observations (how meaning, emotion, time, and resolution are handled), checks them against declared narrative_* contract intents, diffs candidates structurally, and reports manuscript-wide convergence — advisory craft diagnostics for the narrow repertoire model-assisted drafts drift into, never an "AI score". See docs/NARRATIVE.md.

The full command reference is docs/COMMANDS.md.

For Agents

Agents are the primary distribution surface. The fastest hookup is MCP:

claude mcp add manuscript-lab -- npx mlab mcp

mlab mcp is a zero-dependency MCP server over stdio that exposes the protocol as typed tools with safety annotations. Claude Desktop and Cursor snippets, exposure flags (--read-only, --all-tools, --root), and the generated tool table live in docs/MCP.md.

AGENTS.md is the standing contract for agents working in a Manuscript Lab repo. Codex users can install the repo's Codex skill with npm run codex:install-skill (see docs/CODEX_SKILLS.md). A GitHub Action for running reports in CI is documented in docs/CI.md.

The Lab

Generation and orchestration features — writers' room, the Chorus line lab, practice benchmarks, the model driver, eval snapshots, artifact inspection, and the golden path — live under mlab lab (mlab lab --help lists them; the old top-level names still work as aliases). They are contained R&D, not the product promise: they write their evidence under state/, they never silently rewrite drafts, and a lab feature graduates into the core surface only when a real case study beats a solo frontier-model baseline on a real project. Until then, the protocol is the product and the lab is where we try to earn the next piece of it.

Does It Work

We test the core claim on ourselves. The first inward case study (docs/CASE_STUDY_HARNESS_VS_DIRECT.md) ran the same model over four contracted sections three ways: a direct pass, direct plus self-revision, and the mlab loop. The mlab loop was the only arm to produce four gate-ready sections; the direct pass shipped one of four, leaving TODO placeholders and a literal [citation-needed] in finished prose that the harness sensors caught. Blind judges leaned toward the harness drafts (9–6 and 10–6) but within judge noise — the honest headline is 4/4 versus 1/4, at roughly 5x the generation tokens. Raw drafts, every judge vote, and the runner are in evals/case-studies/2026-07-harness-vs-direct/.

Fixtures

Two public fixtures demonstrate both ends of the workflow:

• examples/technical-whitepaper: a complete project that ends green — validate, check --static-only, gate manuscript, and report all pass, with an accepted issue, candidate run, diff audit, and export manifest kept as revision-trail history.
• examples/broken-whitepaper: deliberately red. Its README lists every expected blocker and the fix: command each one carries, so you can see the failure UX without breaking your own project.

Fastest demo from a clone:

cd examples/technical-whitepaper
../../bin/manuscript-lab.mjs validate
../../bin/manuscript-lab.mjs report --write

Model Providers

The core workflow is deterministic and needs no API keys. Model-backed checks, reviews, and lab commands route through scripts/lib/model-provider.mjs, which supports OpenRouter, Lightning AI, and custom OpenAI-compatible endpoints. Copy .env.example to .env for keys and never commit .env. See docs/MODEL_PROVIDERS.md.

Project-specific review charters do not need to be added to the package. Point reviews.suite in manuscript-lab.config.json at a suite under the manuscript root, keep its prompts there, then use those IDs in section contracts. The suite merges with built-ins; collisions and path escapes fail validation. See docs/FILE_PROTOCOL.md and inspect the result with mlab review list.

Successful review runs record target-body, target-file, pass-definition, and registry fingerprints. Gates use those artifacts to distinguish “no review has run,” “the latest successful review is stale,” and “completed reviews have no persisted errors.” Coverage and freshness warn by default, including for keyless projects using --mock-response. A release profile can make them blocking:

{
  "gates": {
    "profiles": {
      "release": {
        "reviews": {
          "declared_have_run": "block",
          "declared_fresh": "block"
        }
      }
    }
  }
}

Docs

• docs/COMMANDS.md: full command reference, aliases, npm-script mapping
• docs/GETTING_STARTED.md: first-project walkthrough
• docs/MCP.md: MCP server setup and tool catalog
• docs/CI.md: GitHub Actions workflow and the composite action
• docs/GATE_ENGINE.md: readiness gates and result format
• docs/EVIDENCE_SPINE.md: claims and sources design
• docs/ARCHITECTURE.md: layers and file boundaries
• docs/FILE_PROTOCOL.md: project layout and config protocol
• docs/PRODUCT_STRATEGY.md: the decision of record and roadmap

License

MIT. See LICENSE.