Skip to content

## manuscripto design spec — architecture and API surface Write a design spec f

manuscripto design spec — architecture and API surface

Write a design spec for manuscripto, a new projio subsystem for scientific manuscript assembly and rendering. Save it as docs/explanation/manuscripto-design-spec.md.

Context

  • Projio has 5 existing subsystems: indexio (retrieval), biblio (literature), notio (notes), codio (code), pipeio (pipelines)
  • manuscripto would be the 6th, handling manuscript → PDF/LaTeX/web production
  • The pixecog project has a working manuscript system documented in docs/how-to/doc/manuscript-system-audit.md — use worklog_read_file(project_id="pixecog", path="docs/how-to/doc/manuscript-system-audit.md") to read it
  • figio (packages/figio/) handles figure building: FigureSpec YAML → SVG → PDF/PNG with captions, panel labels, journal targets
  • biblio handles bibliography: Zotero ingest, citekey resolution, bib-merge, citeproc
  • notio handles structured notes with templates, frontmatter, series, cross-refs, indexing

Key design decisions to address

  1. Notio integration: Manuscript sections should be a notio note type (manuscript or section) with an order frontmatter field for explicit sequencing. This reuses notio's template system, CRUD, frontmatter parsing, and index generation. Manuscripto adds the assembly and rendering layer on top.

  2. Core primitives:

  3. ManuscriptSpec (YAML config): declares sections order, bibliography, CSL, figure bindings, pandoc settings, target format
  4. Section atoms: markdown files managed as notio notes with series = manuscript name and order field
  5. Assembly: generated master.md from section order (single source of truth, no dual-marker problem)

  6. Output: PDF, LaTeX, resolved Markdown, HTML (via MkDocs)

  7. Figure-caption binding: figio FigureSpec already has AnnotationType.caption. Manuscripto should extract captions from FigureSpec and insert proper Pandoc figure references (![Caption](fig.pdf){#fig:id}) during assembly.

  8. Pandoc integration:

  9. Single pandoc-defaults.yaml generated from ManuscriptSpec (one CSL, one engine, one filter chain)
  10. Lua filter for transclusion (reuse pixecog's include.lua pattern)

  11. OR simpler: manuscripto concatenates sections directly (no transclusion needed if we generate the assembled file)

  12. Dual output:

  13. Pandoc path: assembled markdown → citeproc → PDF/LaTeX
  14. MkDocs path: section files served directly with mkdocs-bibtex + include-markdown plugins

  15. The assembly step eliminates the dual-marker problem from pixecog

  16. Package structure: Follow biblio pattern (see packages/biblio/ for reference). Package lives at packages/manuscripto/, editable install from there.

  17. MCP tools (registered via projio MCP server like other subsystems):

  18. manuscript_init(name, template) — scaffold a new manuscript
  19. manuscript_list() — list manuscripts in project
  20. manuscript_status(name) — section completion, figure status, bib status
  21. manuscript_build(name, format) — render to PDF/LaTeX/MD
  22. manuscript_validate(name) — check citations exist, figures built, sections complete
  23. manuscript_assemble(name) — generate assembled markdown (useful for preview)

  24. manuscript_figure_insert(name, section, figure_id, position) — wire a figio figure into a section

  25. CLI surface: manuscripto init|build|validate|status|assemble

Deliverable

A markdown design spec at docs/explanation/manuscripto-design-spec.md covering: - Architecture diagram - Primitives and their relationships - Notio integration strategy (section as note type) - ManuscriptSpec schema (YAML format) - Figio/biblio/pipeio integration points - MCP tool surface with signatures - CLI surface - Migration path from pixecog's current system - Open questions

Read existing subsystem specs and CLAUDE.md for style and depth reference. Use project_context() and look at packages/biblio/ structure as the model.

  • [[task-arash-20260326-232759-001222.md]] — Manuscripto plans to build on notio by using notio note types for manuscript sections; notio reindex work directly affects the infrastructure manuscripto would depend on.
  • [[task-arash-20260328-174922-286397.md]] — Manuscripto relies on biblio for bibliography/citekey handling; biblio graph expansion extends the same biblio layer.
  • [[task-arash-20260328-145743-373331.md]] — OpenAlex reference expansion migrated into biblio is part of the bibliography infrastructure manuscripto will consume for citation resolution.