Metadata-Version: 2.5
Name: agentic-scriptorium
Version: 0.3.0
Summary: An agentic scriptorium for scholarly writing — coordinated AI capabilities for manuscripts, grants, and reviews.
Project-URL: Homepage, https://github.com/seandavi/scriptorium
Project-URL: Documentation, https://github.com/seandavi/scriptorium#readme
Project-URL: Issues, https://github.com/seandavi/scriptorium/issues
Project-URL: Source, https://github.com/seandavi/scriptorium
Author-email: Sean Davis <seandavi@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agentic,citation-audit,claude-code,editorial,grants,manuscripts,peer-review,scholarly-writing,scientific-writing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: jsonschema>=4.21
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pyrefly>=0.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-jsonschema>=4.21; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: yamllint>=1.35; extra == 'dev'
Description-Content-Type: text/markdown

# scriptorium

> Single-responsibility AI skills that work on prose the author has
> written. Each skill reads a shared editorial state file and is
> grounded in a curated, peer-reviewed evidence base.

Scriptorium is a collection of focused AI skills — citation audit,
reviewer simulation, argumentative-flow analysis, terminology
normalization, page-limit compression, and ten more — that coordinate
around a single editorial-state file
([`MANUSCRIPT_STATE.yaml`](schemas/manuscript-state.schema.json)). It
is built for authors revising their own manuscripts and grants who
want structured, anchored critique on prose they have already
written.

**Documentation site:** <https://seandavi.github.io/scriptorium/>
(includes a [worked case study](https://seandavi.github.io/scriptorium/concepts/case-study/)
showing real reviewer-simulation output and a before/after argumentative-flow run).

## What scriptorium does

- **Reads prose the author has already declared** and emits structured,
  anchored findings — one finding per claim, one per section, one
  per figure-text mismatch. No overall quality score. No letter grade.
- **Grounds every design decision in a curated knowledge layer**
  (fifty-plus notes on citation accuracy, hallucination evidence,
  reviewer-archetype research, reporting guidelines, the AI-writing
  failure-mode literature). Each skill's `manifest.yaml` cites the
  knowledge notes its design comes from.
- **Preserves what the author owns.** Critique skills modify nothing.
  Transformation skills operate under an explicit preservation
  contract (citations, statistics, declared terminology, declared
  core claims, hedging style — see [voice preservation](#voice-preservation-the-honest-version)).
- **Doesn't invent.** No skill names a citation from model memory.
  By default no skill drafts a section from a blank page; the
  [`declared-work-scope`](knowledge/conventions/declared-work-scope.md)
  convention applies across every conversation-bearing skill.
- **Leaves the call to the author.** By default, skills decline
  blank-slate generation and uses that funder or publisher AI
  policies restrict. Each such refusal is a declared policy or scope
  guard, and the author can override it for one run or in
  `MANUSCRIPT_STATE.yaml`; the skill's output then lists it under
  "Overrides applied". Accuracy guards, such as no citations from
  model memory, can't be overridden. See
  [`author-authority`](knowledge/conventions/author-authority.md).

## What scriptorium will not do

These are explicit non-goals, grounded in the
[roadmap](docs/roadmap.md#explicit-non-goals) and the knowledge layer.
Naming them up front is the point — a pre-submission tool earns trust
by being concrete about its limits.

- **No blank-slate prose generation by default.** Scriptorium does
  not draft sections from nothing. The proposer role (Hayes 2012) is
  the author's; scriptorium occupies the translator and evaluator
  roles. See [`declared-work-scope`](knowledge/conventions/declared-work-scope.md).
  This is a scope guard, so an author can override it for a skill
  that declares it.
- **No autonomous reviewing.** `reviewer-simulation` and
  `desk-rejection-risk` are built for authors. Editorial-side use
  would mean uploading a confidential manuscript and delegating the
  critique to AI, which current NIH and publisher reviewer policies
  restrict
  ([`peer-review-platforms`](knowledge/prior-art/peer-review-platforms.md)).
  Run by a reviewer or editor on a submitted manuscript, the skills
  state that concern and ask before proceeding.
- **No overall writing-quality score.** No letter grade, no
  Flesch-Kincaid, no aggregate number. Those systematically misrate
  scientific prose and would be theater rather than information.
- **No image-forensics or sleuth replacement.** Bik-style figure
  integrity review, tortured-phrase detection, and statistical
  forensics (Carlisle, Statcheck, GRIM, SPRITE) require domain
  experts. Scriptorium is a pre-submission first pass.
- **No reference-manager replacement.** Citation audit works with
  the bibliography Zotero, Mendeley, Paperpile, or BibTeX already
  produced; scriptorium does not manage references itself.
- **No discipline-specific defaults outside biomedical / clinical at
  v0.1–v0.3.** The evidence base is biomedical-coded. Physics,
  CS/ML, mathematics, qualitative social science, and humanities
  defaults need per-discipline knowledge layers that don't exist
  yet — PRs welcome.
- **No native `.docx` round-trip.** Scriptorium operates on
  markdown-converted prose; tracked changes and Word field codes
  are not preserved through the conversion.
- **No skill-degradation defence.** Whether extended AI use atrophies
  the author's underlying skill is plausible but under-evidenced.
  The author retains responsibility for their writing.

## Where scriptorium fits in the writing workflow

The seven lifecycle stages in `MANUSCRIPT_STATE.yaml` (`outline` →
`draft` → `review` → `revision` → `submission` → `post-submission` →
`accepted`) map onto four roles in
[Hayes' 2012 cognitive-process model](knowledge/scientific-writing/hayes-flower-writing-model.md):
**proposer, translator, evaluator, transcriber**. Scriptorium occupies
the *translator* and *evaluator* roles when the author has already
proposed. It does not propose for the author.

| Lifecycle stage | Typical scriptorium skills |
|---|---|
| **`outline`** (proposer phase — author-owned) | `init`, `tour`, `explain`, `venue-fit`. No critique skills — outline-phase prose isn't yet declared. |
| **`draft`** | `citation-audit`, `gap-finder`, `figure-text-alignment`, `reporting-guideline-fit`, `terminology-normalization`, `argumentative-flow` (per section). |
| **`review` · `revision`** | All of the above plus `reviewer-simulation`, `author-contribution-audit`, `reporting-guideline-compliance`. |
| **`submission`** | All of the above plus `desk-rejection-risk`, `compression`. |

The [skill reference](https://seandavi.github.io/scriptorium/reference/skills/)
lists every shipped skill by category and lifecycle stage.

## Voice preservation, the honest version

A common (correct) fear about AI editing tools is that they will
flatten the author's voice. Scriptorium's posture on this is split
into two claims — one that is enforced, one that is not.

**Enforced (the preservation contract).** Transformation skills
(`argumentative-flow`, `compression`) operate under an explicit
preservation contract:

- Every citation key in the source is preserved; none are added.
- Every numerical value, p-value, confidence interval, and unit is
  preserved verbatim.
- Whatever the author declares in `terminology.preferred` /
  `terminology.forbidden` / `terminology.synonyms` is respected.
- The author's hedging strength (over-cautious vs assertive) is
  honoured — any shift is reported as a per-edit note rather than
  absorbed silently.
- Declared `core_claims` are preserved; no claim is added, no
  declared claim is dropped.

Critique skills (`citation-audit`, `reviewer-simulation`,
`gap-finder`, `desk-rejection-risk`, `figure-text-alignment`,
`reporting-guideline-compliance`, `author-contribution-audit`,
`venue-fit`, `reporting-guideline-fit`) rewrite nothing at all.

**Not promised (sentence-level voice preservation).** Scriptorium
does not claim that running a transformation skill leaves your
prose "sounding like you" at the sentence level. The evidence is
the Kobak et al. 2025 lexical-fingerprint work: LLM-edited prose
is detectable at corpus scale, and correcting it at sentence scale
is not reliable. The conservative-edit posture above minimizes the
surface area of changes; it does not promise that nothing about
the author's distinctive voice shifts. See
[`ai-writing-failure-modes`](knowledge/prior-art/ai-writing-failure-modes.md)
for the evidence we're calibrating against.

The defence is structural: the author reviews each per-edit diff
and chooses what to accept.

## Light, standard, full — author chooses

Critique can be paralyzing if it arrives all at once and presents
as authoritative. `meta.guidance_level` in `MANUSCRIPT_STATE.yaml`
lets the author dial in how much framing scriptorium adds around
its work:

- **`terse`** — questions and confirmations only. No prose between
  turns. For authors on their second-or-later project.
- **`standard`** (default) — one-line "why" before non-obvious
  questions. For returning users who appreciate anchoring without
  a lecture.
- **`full`** — upfront orientation, 2–3 sentence rationale before
  each elicited field, end-of-phase recap. For first-time users
  who want to learn the workflow as they go.

The structured output of each skill — the citation-audit table, the
four reviewer-lens sections, the argumentative-flow diff — does not
change with guidance level. What changes is the framing around the
structured work. See
[`guidance-level`](knowledge/conventions/guidance-level.md).

## Install

### Claude Code (recommended)

Scriptorium hosts its own plugin marketplace at
[`seandavi/scriptorium`](https://github.com/seandavi/scriptorium).
Easiest install — no Python toolchain needed:

```text
/plugin marketplace add seandavi/scriptorium
/plugin install scriptorium@scriptorium
```

(`seandavi/scriptorium` is the GitHub `owner/repo` shorthand for
<https://github.com/seandavi/scriptorium>. Append `@v0.3.0` or any
ref to pin.)

Once installed, run:

```text
/scriptorium:tour
```

A short conversational walk-through — three or four turns — that
orients you to scriptorium and ends with one concrete next command.
It writes nothing and invokes no other skill; it's the single entry
point we recommend pointing new users at instead of linking them
to documentation.

Updates: `/plugin marketplace update` then
`/plugin update scriptorium@scriptorium`.

If you also want the Python CLI (`scriptorium init`,
`scriptorium validate`, `scriptorium trace`), or you want a
live-linked dev install, see [INSTALL.md](INSTALL.md).

### Other agents (Codex, Gemini, Hermes, ChatGPT, …)

For agents that load skills from a directory (Codex, Cursor, Gemini
CLI, Claude Code, and others), install with the
[`skills` CLI](https://skills.sh):

```bash
npx skills add seandavi/scriptorium                      # all skills
npx skills add seandavi/scriptorium --skill citation-audit
```

See [INSTALL.md](INSTALL.md#npx-skills-any-supported-agent) for agent
selection, global installs, updates, and what the plugin adds on top.

For agents without skill directories, each skill ships with a platform-neutral `prompt.md` you can paste
into any LLM directly. To get all skills concatenated into a single
prompt-pack file:

```bash
scriptorium prompt-pack -o scriptorium-prompts.md
```

See [INSTALL.md](INSTALL.md) for per-platform recipes.

## Quick start

```bash
# 1. Scaffold editorial state for your manuscript
scriptorium init /path/to/your/manuscript

# 2. Populate it. Two ways:
#    a) Edit /path/to/your/manuscript/MANUSCRIPT_STATE.yaml directly.
#    b) In Claude Code inside the manuscript repo, run the conversational
#       bootstrap that walks you through core_claims, known_weaknesses,
#       terminology, audience, and tone:
#       /scriptorium:init

# 3. Validate the result
scriptorium validate /path/to/your/manuscript/MANUSCRIPT_STATE.yaml

# 4. Run the leaf skills in Claude Code, inside the manuscript repo:
/scriptorium:citation-audit
/scriptorium:reviewer-simulation
/scriptorium:argumentative-flow
```

`MANUSCRIPT_STATE.yaml` is a local file in your repository. It is
not uploaded to scriptorium and is not shared unless you commit it
to a shared branch. Whether to commit it is your call.

A fully-populated reference manuscript lives at
[`templates/MANUSCRIPT_STATE.example.yaml`](templates/MANUSCRIPT_STATE.example.yaml)
(an imaginary biomedical paper that exercises every field in the
schema). Use `scriptorium init --example /tmp/example` to drop a
copy anywhere as a learning aid.

A worked case study showing the full citation-audit /
reviewer-simulation / argumentative-flow run on a realistic
discussion paragraph (constructed for the walk-through, not real)
lives at
[`docs/src/content/docs/concepts/case-study.md`](docs/src/content/docs/concepts/case-study.md).

## What ships today

Sixteen skills across critique, validation, normalization,
transformation, meta, and utility categories. The full list,
organised by category and lifecycle stage, is the
[skills reference page](https://seandavi.github.io/scriptorium/reference/skills/).
A short summary:

- **Critique** — `citation-audit`, `reviewer-simulation`,
  `gap-finder`, `figure-text-alignment`, `desk-rejection-risk`,
  `venue-fit`, `author-contribution-audit`, `reporting-guideline-fit`,
  `outlier-sentence-detector`.
- **Validation** — `reporting-guideline-compliance`.
- **Normalization** — `terminology-normalization`.
- **Transformation** — `argumentative-flow`, `compression`.
- **Meta / utility** — `tour`, `explain`, `init`.

The `scriptorium` CLI exposes six subcommands: `install`, `init`,
`validate`, `prompt-pack`, `list`, and `trace`. See
`scriptorium --help`.

Deliberately *not* shipped (see [DESIGN.md](DESIGN.md) and the
[roadmap](docs/roadmap.md) for build order): the
`manuscript-pipeline` orchestrator (held until the leaves have been
exercised on more real manuscripts); blank-slate drafting skills
(out of scope by design); Codex/Gemini installer scripts.

## Companion tools

Scriptorium is the editorial layer; these tools are useful neighbors
for the rest of the scholarly-writing workflow:

- **[Semantic Scholar MCP](https://github.com/zongmin-yu/semantic-scholar-fastmcp-mcp-server)**
  and **[PubMed MCP](https://github.com/JackKuo666/PubMed-MCP-Server)**
  — bibliographic lookup and full-text retrieval as MCP servers,
  consumable by Claude Code (and any MCP-aware agent). Pair well with
  `scriptorium:citation-audit` when claims need to be checked against
  primary literature.
- **[quartobot](https://github.com/seandavi/quartobot)** — resolves
  persistent-identifier cite keys (`@pmid:`, `@doi:`) in Quarto
  documents before citeproc renders them. Used inside the
  scriptorium docs build for the `knowledge/` evidence base; useful
  standalone for any Quarto-based scholarly writing.

These are external projects, not bundled with scriptorium. Install
them separately following each project's own instructions.

## Design principles

The system separates:

- **generation** (write new prose — out of scope at v0.1–v0.3)
- **critique** (assess existing prose; emit structured findings)
- **validation** (check against an external standard)
- **normalization** (enforce declared style and terminology)
- **transformation** (modify prose under a preservation contract)

And prefers:

- inspectable transformations over opaque rewrites
- structured outputs over freeform rambles
- semantic diffs over surface rewrites
- explicit checkpointing over hidden state

See [DESIGN.md](DESIGN.md) for the full design philosophy and the
[roadmap](docs/roadmap.md) for what ships when.

## Status

v0.3 shipped (CHANGELOG: [`[0.3.0]`](CHANGELOG.md#030---2026-10-20)),
adding `compression`, `figure-text-alignment`,
`reporting-guideline-compliance` and `outlier-sentence-detector`. Sixteen skills total, fifty-plus
knowledge notes, the consolidated `scriptorium` CLI (six subcommands),
the shared-state schema, the trace schema, the Venice example. Pre-1.0
shape: the skill catalog is growing; CLI surface and schema may still
adjust.

## License

Dual-licensed by category:

- **Code** — source under `src/`, tests, schemas, scripts, and
  configuration files — is [MIT](LICENSE).
- **Documentation and knowledge layer** — the `docs/` site, the
  `knowledge/` evidence base, top-level prose files (`README.md`,
  `DESIGN.md`, `INSTALL.md`, `CONTRIBUTING.md`), and per-skill
  `README.md` files — is [CC BY 4.0](LICENSE-DOCS).
