Skip to content

## Design spec: manuscript as a notio subpackage Write a design spec for adding

Design spec: manuscript as a notio subpackage

Write a design spec for adding manuscript functionality as a subpackage within notio (notio/src/notio/manuscript/). Save it as docs/explanation/manuscript-design-spec.md in the projio repo.

Context

  • Projio has 5 subsystems: indexio, biblio, notio, codio, pipeio
  • Instead of a 6th standalone package, manuscript becomes a notio subpackage — sections are ordered notes
  • The pixecog project has a working manuscript system: use worklog_read_file(project_id="pixecog", path="docs/how-to/doc/manuscript-system-audit.md") to read the full audit
  • 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

Why subpackage, not standalone

  • Manuscript sections ARE structured notes with ordering — notio already has templates, frontmatter parsing, CRUD, series grouping, index generation
  • Adding an order field to frontmatter gives explicit sequencing (notio currently only has mtime sorting)
  • series field groups sections per manuscript (e.g., series: manuscript-paper1)
  • No new pyproject.toml, submodule, or editable install needed
  • notio.toml gets a [manuscript] section for defaults

Architecture to document

packages/notio/src/notio/
├── manuscript/           ← NEW subpackage
│   ├── __init__.py       # public API: init, assemble, render, validate, status
│   ├── schema.py         # ManuscriptSpec Pydantic model (sections, bib, CSL, figures, render config)
│   ├── assembly.py       # gather sections by series+order, concatenate → assembled markdown
│   ├── render.py         # pandoc subprocess: assembled.md → PDF/LaTeX/MD via citeproc
│   ├── figures.py        # figio caption extraction, figure ref insertion, path resolution
│   └── validate.py       # check: citekeys in bib, figures built, sections complete, pandoc available
├── core.py               # EXTEND: add 'section' note type with 'order' field in default config
├── query.py              # EXTEND: add order-aware sorting for section note type
├── config.py             # EXTEND: manuscript config section in notio.toml
└── mcp/
    └── server.py         # EXTEND: add manuscript_* tools

Key design points to cover

  1. ManuscriptSpec schema: YAML config at docs/manuscript/<name>/manuscript.yml
  2. name, title, authors, abstract_section
  3. sections: ordered list of section refs (or auto-discovered by series + order)
  4. bibliography: path to .bib file (default: bib/.bib from biblio)
  5. csl: path to CSL file
  6. pdf_engine: xelatex (default) | pdflatex | tectonic
  7. output_dir: _build/ (default)

  8. figure_bindings: map of figure_id → {figio_spec, caption_override}

  9. Section as note type: frontmatter includes order: int, series: manuscript-<name>, manuscript: <name>. Template generates numbered filename: NN-<slug>.md

  10. Assembly: concatenate sections in order, insert pandoc YAML metadata block, resolve figure paths. NO Lua filter needed — direct concatenation eliminates transclusion entirely.

  11. Rendering: shell out to pandoc with --citeproc, --bibliography, --csl, --pdf-engine. Single authoritative command (fixes pixecog's 3-engine problem).

  12. Figure integration: read figio FigureSpec → extract caption text → insert ![caption](path){#fig:id} in assembled markdown.

  13. MCP tools (registered in notio's MCP server, exposed via projio):

  14. manuscript_init, manuscript_list, manuscript_status, manuscript_build, manuscript_validate, manuscript_assemble, manuscript_figure_insert

  15. CLI: notio manuscript init|build|validate|status|assemble (subcommand of notio CLI)

  16. notio.toml extension: 

    [manuscript]
default_csl = "bib/csl/nature.csl"
default_engine = "xelatex"
bib_path = ""  # auto-detect from biblio
output_dir = "_build"

Deliverable

Save to docs/explanation/manuscript-design-spec.md in projio. Include architecture diagram, schema examples, integration points with figio/biblio/pipeio, MCP tool signatures, CLI surface, and migration notes from pixecog.

  • [[task-arash-20260331-175313-566067.md]] — Directly related: manuscripto design spec covering architecture and API surface — same initiative
  • [[task-arash-20260331-175356-958039.md]] — Follow-on task: scaffold the manuscripto package that this design spec defines
  • [[task-arash-20260331-175439-058148.md]] — Implementation task for manuscripto core (assembly, render, notio section type) — depends on this design
  • [[task-arash-20260331-175508-399347.md]] — Registration task: wiring manuscripto into projio MCP/submodule — downstream of this design spec

Batch Result

  • status: done
  • batch queue_id: 3e973e87bee2
  • session: f9189029-1adf-43a6-aa5f-93edf57dfe17
  • batch duration: 494.6s