{
  "markdown": "# Publishing Assurance Toolkit\n\n> Open infrastructure for the book publishing community to observe, document,\n> and evaluate generative-AI workflows—without surrendering manuscripts,\n> judgment, or craft.\n\n![An open book connected to a provenance chain and evaluation marks](docs/assets/hero/publishing-assurance-hero.png)\n\nPublishing Assurance Toolkit (`pubassure`) gives authors, publishers,\nresearchers, and software builders a common set of building blocks for two jobs:\n\n1. **Provenance assurance** — record inspectable evidence about human and machine\n   contributions to an expressive work.\n2. **Generative-system evaluation** — test publishing systems against portable,\n   reproducible challenges and report what happened under declared conditions.\n\nThe aim is not to pronounce whether a book is “AI-generated.” That framing is\ntoo blunt for real editorial work. The aim is to help the publishing community\nbuild better instruments: tools that can preserve human choices, monitor system\nbehavior, compare declared performance, and support more informed editorial\njudgment.\n\n**Project status:** alpha reference implementation. Schemas and protocols may\nchange before 1.0.\n\n## Why this exists\n\nGenerative systems are entering workflows that already contain many forms of\nhuman expression: commissioning, research, prompting, selection, revision,\nfact-checking, design, approval, and accountability. A useful assurance layer\nmust represent that work without reducing it to a single “human percentage.”\n\nAt the same time, publishers need practical ways to ask whether a system can do\na particular publishing job—and to see the basis for the answer. A score without\nthe challenge, inputs, execution conditions, checks, and disclosures is hard to\ninterpret and harder to reproduce.\n\nThis toolkit is a practical response to the gaps documented in Fred Zimmerman's\ntrade-coverage study,\n[*Copyright Is the Headline; Capability Is the Blind Spot: AI Technology in the\nBook-Publishing Trade Press, November 2025–August 2026*](https://arxiv.org/abs/2608.00964).\nThe paper calls task-specific evaluation “publishing's missing instrument panel”\nand argues that provenance should move upstream into publishing workflows. The\nevaluation suite and provenance ledger implement those two recommendations as\nopen, reusable infrastructure.\n\n`pubassure` brings those needs into one vendor-neutral toolkit:\n\n- a local, append-only provenance ledger;\n- first-class records for human instructions, selections, edits, and approvals;\n- privacy-conscious public certificates;\n- portable challenge and submission formats;\n- deterministic checks plus separately disclosed human ratings;\n- JSON and standalone HTML reports;\n- adapters for publishing systems; and\n- hosted MCP, portable agent-skill, Python, and CLI interfaces.\n\n## What it looks like\n\n### Discover public challenges through MCP\n\nThe hosted, stateless MCP service exposes evaluator-safe challenges and tools at\n`https://bigfivekiller.online/mcp/pubassure`.\n\n![Public MCP challenge catalog with generation, classification, and repair tasks](docs/assets/screenshots/mcp-challenge-catalog.png)\n\n### Produce reports that disclose their basis\n\nReports identify the challenge, system, execution mode, scoring method,\ndisclosures, and interpretation limits. Deterministic measurements and human\nobservations remain distinguishable.\n\n![Evaluation report showing a deterministic score, checks, and disclosure](docs/assets/screenshots/evaluation-report.png)\n\n### Preserve human expressive contributions\n\nThe provenance protocol records model interactions alongside human\ninstructions, selections, edits, and approvals. Public certificates can\nsummarize a chain without publishing raw prompts or manuscripts.\n\n![Provenance timeline showing human and model events plus a verified public certificate](docs/assets/screenshots/provenance-certificate.png)\n\nInspect the [full de-attributed example provenance log](https://bigfivekiller.online/data/pubassure/community-demo/events.jsonl).\nIt contains five canonical, hash-chained events with synthetic content and\npseudonymous actor identifiers; it contains no personal or business data.\n\nThe screenshots are generated from the bundled examples and documentation\nviews in [`docs/demo`](docs/demo). They use only synthetic or public sample data.\n\n## Components\n\n| Component | What it does | What it produces |\n|---|---|---|\n| **Provenance ledger** | Stores project events in an append-only SHA-256 hash chain and keeps artifacts in a content-addressed local store. | Canonical JSONL events and artifact descriptors. |\n| **Human contribution records** | Represents instructions, selections, edits, and approvals as distinct, attributable events with exact contribution artifacts and stated effects. | Inspectable evidence of editorial intervention and decision-making. |\n| **Public certificates** | Summarizes event counts, selected claims, and the verified chain head while keeping private details local. | Portable JSON certificate with explicit limitations. |\n| **Challenge registry** | Loads and validates portable generation, classification, and repair tasks. | Public challenge catalog and evaluator-safe task inputs. |\n| **Evaluation runner** | Invokes an adapter or scores an existing submission against declared checks. | Reproducible result object with per-check observations. |\n| **Reporting** | Separates deterministic checks from disclosed human ratings and adds interpretation limits. | Machine-readable JSON and dependency-free HTML reports. |\n| **Adapter boundary** | Connects an existing publishing system without requiring it to adopt this package internally. | A standard `submission.json` plus referenced artifacts. |\n| **Release audit** | Searches a candidate release for common secrets, personal paths, private business terms, and unsafe artifacts. | A blocking privacy/release report. |\n\n## Three ways to use it\n\n### 1. Hosted MCP server\n\nUse the public service for challenge discovery, public inline evaluation, and\nverification of public or redacted provenance chains:\n\n```text\nhttps://bigfivekiller.online/mcp/pubassure\n```\n\nExample Claude Code configuration:\n\n```bash\nclaude mcp add --transport http publishing-assurance https://bigfivekiller.online/mcp/pubassure\n```\n\nThe repository also includes `.mcp.json` and Gemini extension metadata. The\nhosted service is stateless and retains no submitted artifacts, but network\ntransmission is still network transmission: **keep confidential manuscripts on\nthe local code path**.\n\nAvailable MCP tools:\n\n- `publishing_assurance_info`\n- `list_publishing_challenges`\n- `get_publishing_challenge`\n- `evaluate_publishing_submission`\n- `verify_provenance_chain`\n\nSee [`docs/hosted-mcp.md`](docs/hosted-mcp.md).\n\n### 2. Portable Codex, Claude, or Gemini skill\n\nInstall one canonical skill into the agent environment you already use:\n\n```bash\nuv run python scripts/install_agent_skill.py codex\nuv run python scripts/install_agent_skill.py claude\nuv run python scripts/install_agent_skill.py gemini --scope project\n```\n\nThe skill teaches the agent when to use hosted public tools and when to keep\nwork local. Gemini CLI users can also install the repository as an extension,\nbundling the skill and hosted MCP configuration.\n\n### 3. Python or CLI\n\nUse the package directly for confidential projects, automated pipelines, custom\nchallenges, or product integration:\n\n```python\nfrom pubassure import ChallengeRegistry, ProvenanceLedger\n\nregistry = ChallengeRegistry(\"challenges\")\nfor challenge in registry.list_public():\n    print(challenge[\"id\"], challenge[\"title\"])\n\nledger = ProvenanceLedger(\"private-ledger\", \"project:example\")\n```\n\nThe CLI exposes validation, scoring, adapter execution, provenance operations,\nand release auditing. See\n[`docs/integration-surfaces.md`](docs/integration-surfaces.md) for complete\nexamples.\n\n## How the pieces fit\n\n```mermaid\nflowchart LR\n    A[Author or editorial team] --> P[Publishing workflow]\n    G[Generative system] --> P\n    P --> L[Local provenance ledger]\n    P --> S[Portable submission]\n    C[Challenge registry] --> E[Evaluation runner]\n    S --> E\n    E --> R[JSON + HTML report]\n    L --> V[Public or redacted certificate]\n    R --> D[Editorial review and disclosure]\n    V --> D\n```\n\nThe ledger and evaluation suite are useful independently. Together they can\nshow both **how a work moved through a declared process** and **how a system\nperformed on a declared task**.\n\n## Quick start\n\nThe core package has no runtime dependencies. Development uses `uv` and the\nlocked environment in this repository.\n\n```bash\ngit clone <repository-url>\ncd publishing-assurance-toolkit\nuv sync\n\nuv run pubassure challenge validate challenges/generation/book-on-a-topic.json\nuv run pubassure challenge list\nuv run pubassure score \\\n  --challenge challenges/classification/genre-mini.json \\\n  --submission examples/submissions/genre-mini.json \\\n  --output runs/genre-mini\n```\n\nOpen `runs/genre-mini/report.html` to inspect the standalone report.\n\n## Connect any publishing system\n\nAn adapter is simply a command that receives a request path and output\ndirectory:\n\n```text\nyour-adapter --request /path/to/request.json --output /path/to/output-directory\n```\n\nIt writes `submission.json` and any referenced artifacts. Then the runner scores\nthe result:\n\n```bash\nuv run pubassure run \\\n  --challenge challenges/generation/book-on-a-topic.json \\\n  --adapter \"your-adapter\" \\\n  --output runs/my-system\n```\n\nThe adapter may wrap a desktop application, command-line tool, hosted API,\nworkflow engine, or supervised manual process. See\n[`docs/adapter-contract.md`](docs/adapter-contract.md).\n\n## Bundled challenge families\n\n### Generation\n\nGenerate a short nonfiction book from a topic brief. The reference challenge\nchecks artifact presence, minimum substance, required structure, and obvious\nplaceholders. It also names separate human-rating dimensions such as factual\nsupport, structural coherence, editorial usefulness, and voice consistency.\n\n### Classification\n\nClassify short descriptions using declared labels. The compact sample is useful\nfor testing system adapters and reproducibility end to end.\n\n### Repair\n\nRepair a deliberately damaged OCR passage. The challenge asserts specified\nrepairs and checks that known defects are absent without inviting unbounded\nrewriting.\n\nThese are seeds, not a claim of complete coverage. Community contributions can\nadd tasks for metadata quality, accessibility, citation integrity, indexing,\nlayout repair, image-description quality, editorial consistency, and other\npublishing concerns.\n\n## Trust model and limits\n\nThis project favors inspectable evidence over expansive claims.\n\n- A hash can reveal later alteration; it does not prove who controlled a key or\n  establish legal identity.\n- A recorded event can document a declared contribution; it does not decide\n  authorship, copyright ownership, or originality.\n- A challenge report measures only the checks named by that challenge under the\n  stated conditions.\n- A human rating is an attributed observation, not hidden ground truth.\n- A self-maintained certificate is not third-party certification.\n- No module is an “AI detector.”\n\nFor the complete boundary, read [`docs/limitations.md`](docs/limitations.md).\n\n## Privacy and release safety\n\nPrivacy is the default architectural posture:\n\n- unpublished artifacts stay local unless a user deliberately transmits them;\n- actors may use pseudonymous identifiers;\n- public certificates need not contain raw prompts or manuscripts;\n- the hosted MCP accepts only public or intentionally redacted material; and\n- the release audit checks for common credentials, personal paths, private terms,\n  and unsafe files before publication.\n\nRun the audit before publishing a fork or release:\n\n```bash\nuv run pubassure audit-release .\n```\n\nSee [`docs/privacy-and-release.md`](docs/privacy-and-release.md) and\n[`SECURITY.md`](SECURITY.md).\n\n## For the publishing community\n\nThis repository is intended as shared infrastructure, not a finished policy\nanswer. Useful contributions include:\n\n- new challenges grounded in real publishing tasks;\n- scorer implementations with clear measurement limits;\n- adapters for publishing and editorial systems;\n- better reporting and accessible output formats;\n- threat-model and privacy review;\n- interoperability work with provenance and content-credential standards; and\n- documentation from authors, editors, designers, production specialists,\n  researchers, and publishers.\n\nStart with [`CONTRIBUTING.md`](CONTRIBUTING.md), the\n[`architecture`](docs/architecture.md), and the [`roadmap`](docs/roadmap.md).\n\n## Development\n\n```bash\nuv sync\nuv run python -m unittest discover -s tests -v\nuv run pubassure audit-release .\n```\n\nThe project deliberately keeps the core small and dependency-free. New\ndependencies should earn their place and remain pinned.\n\n## Share the project\n\nAn eight-slide, square-format social carousel is included for introducing the\nproject to publishing audiences.\n\n![Contact sheet of the eight-slide Publishing Assurance Toolkit social carousel](docs/social/carousel-contact-sheet.png)\n\n- [Editable PowerPoint deck](docs/social/publishing-assurance-carousel.pptx)\n- [1080 × 1080 posting images](docs/social/carousel)\n- [Suggested post copy and accessibility text](docs/social/README.md)\n\n## Documentation map\n\n- [Architecture](docs/architecture.md)\n- [Integration surfaces](docs/integration-surfaces.md)\n- [Hosted MCP](docs/hosted-mcp.md)\n- [Adapter contract](docs/adapter-contract.md)\n- [Metrics](docs/metrics.md)\n- [Privacy and release safety](docs/privacy-and-release.md)\n- [Limitations](docs/limitations.md)\n- [Roadmap](docs/roadmap.md)\n\n## License\n\nApache License 2.0. See [`LICENSE`](LICENSE).\n",
  "bytes": 13754,
  "sha": "80a323b60974c0e52db1bae47108ea0613418d794f3275c1a5ea499ea022749f",
  "repo_slug": "fredzannarbor/publishing-assurance-toolkit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_fredzannarbor_publishing_assurance_toolk_13b98979/readme"
}