English | 中文

OPL Book Forge

An OPL-standard book-writing agent for turning a storyline into a finished manuscript package

Storyline architecture · Chapter drafting · Figures and tables · Style control · Export handoff

Writing a book is long-form delivery work. The hard part is keeping the reader promise, chapter logic, source grounding, voice, figures, tables, layout, and owner review on one line until the manuscript can be handed off.

OPL Book Forge is built around that work:

• What is the book's promise, audience, argument arc, and chapter thesis chain?
• Which source material supports each chapter, figure, table, and claim?
• Can chapters keep one voice across many drafting and revision passes?
• Can the prose read like human editorial writing, with direct affirmative phrasing and concrete language?
• Can exported DOCX/PDF files, figure plans, table plans, style reports, and owner gates stay traceable?

It organizes a stage-led route from storyline architecture into focused materialization stages, then keeps quality checks and handoff evidence attached to the same book project.

Who It Serves Authors, experts, researchers, educators, and operators turning source material into a coherent book

What It Organizes Storyline, chapter thesis chain, manuscript body, figure and table plans, style contract, quality reports, exports, and owner gates

How To Start Provide the book brief, audience, source corpus, voice expectations, and desired export handoff

Core Highlights

Storyline First
Book Forge starts with the book's premise, reader promise, source map, argument arc, chapter thesis chain, and style contract before materializing chapters.

Materialization Split Into Focused Stages
After storyline approval, materialize-book enters chapter-production-planning directly. That stage admits storyline refs and plans production; chapter drafting, source/style review, and proof/export handoff remain separate top-level stages.

Voice And Style Stay Inspectable
The style contract travels with the book project. Checks look for consistent terminology, concrete phrasing, affirmative editorial language, and repeated patterns that make prose feel generated.

First Drafts Should Already Read Like Book Prose
Book Forge keeps chapter tasks, target budgets, source refs, asset status, QC notes, and blockers in briefs and reports. The manuscript body is expected to open from reader-facing scenes, questions, tensions, and consequences instead of exposing production scaffolding.

Figures, Tables, And Layout Are Part Of The Work
Book Forge treats figures, tables, captions, export shape, rendered pages, and layout review as book-delivery surfaces.

Meta Review Routes The Repair Level
After whole-book review or serious critique, Book Forge decides whether repair starts at artifact target, storyline architecture, outline sequence, chapter function, evidence/model, publication design, local prose, or an owner/source blocker before editing.

PDF Export Uses A Real Typesetting Backend
Book Forge includes a native PDF export helper that compiles Markdown through Pandoc with XeLaTeX and renders pages for inspection when Poppler is available. Quarto book rendering and Typst are planned backend families for richer book projects.

Publication Proof Has Its Own Gates
Review PDFs remain progress-first reading checkpoints. Publication proofs add design tokens, component inventory, font readback, rendered-page QA, front matter and TOC cleanliness, page rhythm/density/orphan checks, asset coverage, and pre-ship proof review. Final export still requires owner/export acceptance.

Owner-Gated Publication Boundary
Book Forge can produce evidence, drafts, exports, and typed blockers. Publication approval, owner acceptance, and production-ready claims still require the right owner receipts and runtime evidence.

Built Through OMA And Agent Lab
This baseline includes OPL Meta Agent takeover evidence, independent AI reviewer evidence, and an external-suite self-evolution pass. New-agent delivery must go through that loop rather than ending at scaffold readiness.

One-Sentence Quick Start

You can start with prompts like:

• "Use this source corpus to shape a book storyline, define the reader promise, chapter thesis chain, and style contract, then stop for owner review."
• "Turn this approved storyline into a short book manuscript with chapter drafts, figure plans, table plans, style checks, layout QC, and DOCX/PDF export handoff."
• "Run a whole-book meta-review and decide whether the repair should start from storyline, outline, chapter function, evidence/model, publication design, or local prose."

What It Helps With

• Turning notes, source packs, lectures, reports, or research material into a book-shaped storyline.
• Keeping chapter logic, evidence references, voice, and editorial constraints coherent across a manuscript.
• Planning illustrations and tables before export, with captions and placement intent.
• Running style consistency, AI-flavor, wording, layout, and export checks as part of the book route.
• Producing handoff evidence that distinguishes generated drafts from owner-accepted publication material.

Current Delivery Focus

• storyline-architecture: premise, reader promise, argument arc, source map, chapter thesis chain, style contract, and owner handoff.
• chapter-production-planning: direct materialize-book entry, storyline-ref admission, route-back, target extent, chapter budgets, production queue, chapter task cards, context plan, and book-memory refs.
• chapter-materialization: chapter context packs, reader-entry plans, per-chapter Markdown draft refs, chapter QC, and chapter repair back-propagation.
• source-style-integrity-review: claim/source integrity, style consistency, AI-flavor scan, independent meta-review routing, and repair entrypoint refs.
• publication-proof-handoff: review/proof/export handoff refs, figure/table readiness, rendered-page QA refs when claimed, owner decisions, blockers, and artifact-role boundary.
• OMA Agent Lab: baseline takeover suite, AI reviewer evaluation, mechanism proposal refs, external-suite self-evolution, and no-patch work-order receipt.
• real book pilot: a short-book pilot produced storyline artifacts, manuscript body, two PNG figures, table plan, DOCX/HTML/PDF exports, rendered PDF pages, quality receipts, and typed owner blockers.

Current Boundary

• OPL Book Forge is an OPL-standard Foundry Agent domain pack for book authoring.
• In the OPL family, Book Forge is an OPL Package(kind=agent): Book Forge keeps executor-neutral identity, capabilities, book work, typed views, and book authority, while OPL owns generic runtime, generated interfaces, and hosted surfaces.
• The Book Forge owner independently publishes complete Package bytes to its own GHCR latest-stable. Codex Plugin is the current carrier projection and Codex CLI is the current executor; neither defines Package identity or complete installed truth.
• Ordinary Package dependencies require only identity presence and required capability callability. Cross-Package version/ABI solving, lock, payload, digest, Release Set, or atomic closure is not a readiness gate.
• OPL owns generated interfaces, framework runtime projection, Agent Lab, work-order execution, registry/discovery, and promotion gates.
• Book Forge owns book-domain truth, manuscript quality rules, style policy, figure/table planning, export/publication verdict boundaries, artifact authority, memory body, and owner receipts.
• Current evidence supports structural baseline, generated interface descriptors, OMA Agent Lab evaluation, and a real short-book pilot with export/render checks.
• Book Forge exposes a refs-only OPL Ledger artifact registration contract for long-term book deliverables: OPL Ledger may register refs, hashes, index refs, review refs, and receipt refs, while artifact bodies, verdicts, owner receipt bodies, typed blockers, queues, and provider attempts stay outside the registration surface.
• Current evidence does not authorize a production-ready book-writing claim. The real pilot remains passed_with_owner_gate_blocker / production_ready_claim_allowed=false until human owner acceptance and live OPL StageRun or hosted artifact-handoff parity evidence exist.

Technical OPL / operator boundary

• The package exposes action contracts for shape-storyline and materialize-book; current generated MCP/OpenAI/AI SDK descriptors are descriptors only unless a runtime surface proves execution.
• scripts/verify.sh runs the fast policy lane. structural adds OPL scaffold/interface/source-hygiene readback, and helpers adds native-helper probes and adapter tests.
• scripts/verify.sh pdf runs two proof-backend PDF compile/render E2E cases and requires pandoc plus xelatex; negative gate variants run in-process against the canonical gate.
• OMA evidence lives under docs/evidence/oma-agent-lab/.
• The real pilot evidence lives under docs/evidence/production-readiness/bookforge-real-book-pilot-2026-06-18/.
• Pilot exports include DOCX, HTML, PDF, rendered pages, generated figures, quality receipts, and typed owner blockers. They are evidence artifacts, not owner publication acceptance.
• Kami-inspired publication proof rules are absorbed as Book Forge-owned domain contracts plus helper machine-baseline proof plumbing. They do not import Kami's visual language, WeasyPrint runtime, font installer, update checker, or a second proof truth source, and they do not replace human publication-design review, final-export acceptance, or owner proof readiness evidence.
• Scaffold validation, generated interface readiness, OMA takeover evidence, external-suite no-patch receipts, pilot exports, or rendered pages cannot become owner receipt, publication approval, production readiness, or hosted runtime parity by themselves.
• contracts/opl_ledger_artifact_registration.json is a refs-only registration contract and contracts/generated_surface_handoff.json exposes its OPL Ledger projection/readback locator. Ledger visibility is not manuscript body storage, owner acceptance, publication/final-export verdict, runtime queue, or provider-attempt authority.

How To Read This Repository

1. Potential users should start here, then continue to the Docs Guide.
2. Technical readers should read Project, Status, Architecture, Invariants, and Decisions.
3. Operators should inspect contracts/, agent/, docs/evidence/oma-agent-lab/, and the real pilot evidence pack before making readiness or owner-acceptance claims.

For Codex / Agents

opl-bookforge is the Codex Plugin carrier for the OPL Package whose canonical agent_id/package_id is obf. The carrier and Package identities are intentionally different.

From a local clone, add this repository marketplace and install the carrier:

cd /absolute/path/to/opl-bookforge
codex plugin marketplace add "$(pwd -P)" --json
codex plugin marketplace list --json
codex plugin list --marketplace opl-bookforge --available --json
codex plugin add opl-bookforge@opl-bookforge --json
codex plugin list --marketplace opl-bookforge --json

For Codex in the ChatGPT desktop app, restart the app after adding the marketplace, open Plugins, select OPL Book Forge, and install opl-bookforge. Start a new conversation before testing the bundled opl-bookforge Skill.

To remove the local carrier and its configured marketplace:

codex plugin remove opl-bookforge@opl-bookforge --json
codex plugin marketplace remove opl-bookforge --json

These commands prove only that Codex can discover, install, list, and remove the Plugin carrier. They do not prove that the complete OPL Package/runtime is installed, callable, current, or ready. When the OPL runtime is available, use its readback surfaces:

opl packages list --json
opl packages status --package-id obf --json
opl app state --profile fast --json
scripts/verify.sh

Keep manuscript truth, quality/export verdicts, final artifact bytes, publication approval, and owner acceptance bound to Book Forge owner gates. Neither a Plugin install nor an OPL status projection grants those authorities, and neither should be treated as a legacy Package transaction or lifecycle receipt.

Agent And Operator Quick Start

Start here if you are handing this repo to Codex or another agent

• Cloning this repo does not install the OPL Framework or a hosted Book Forge runtime. If hosted execution is needed, prepare the current one-person-lab checkout or release bundle first.
• Read this README, Docs Guide, Status, and AGENTS.md before editing.
• Treat OPL Book Forge as the book-domain owner and OPL as generated/runtime surface owner.
• Use OMA / Agent Lab evidence when evaluating the baseline. Do not stop at scaffold or interface validation when claiming a new-agent delivery is complete.
• Keep publication, export acceptance, and production-ready claims fail-closed until owner receipts and runtime parity evidence exist.

Commands

scripts/verify.sh
scripts/verify.sh structural
scripts/verify.sh helpers
scripts/verify.sh pdf
scripts/verify.sh full
opl pack native-helper probe --descriptor runtime/native_helpers/bookforge_pdf_export.native-helper-probe.json --json
python3 docs/evidence/production-readiness/bookforge-real-book-pilot-2026-06-18/tools/verify_pilot.py

scripts/verify.sh is the fast local policy verifier. structural adds OPL scaffold, interface, and source-hygiene readback; helpers checks native-helper descriptors and adapters; pdf runs exactly two real compile/render paths (review PDF and publication proof); full executes their deduplicated union. The PDF gate's negative blocker matrix is exercised directly against the canonical gate function rather than recompiling identical input. None of these lanes proves publication approval, final-export readiness, or owner acceptance. The pilot verifier checks the existing pilot evidence pack, exports, rendered pages, style scan, figures, and owner-gate blockers.

Further Reading

• Docs Guide
• Project
• Status
• Architecture
• Invariants
• Decisions
• Contracts