marmotte

Open questions ​

Decisions we have not taken yet. Each entry records what we know, so the discussion can resume without redoing the research. Resolved questions move to the relevant page of this section.

Ship the docs in the npm tarballs? ​

Status: not for now. Revisit later.

The idea. Add docs to each package's files, so an agent (or a person) working in a project that depends on @mrmt/* can read node_modules/@mrmt/<pkg>/docs/ without internet access.

What we found.

  • Vite+ does this: its package ships docs/ and an AGENTS.md (readable in node_modules/vite-plus), which is a precedent for agent-facing docs inside a package.
  • The published .d.ts files keep the JSDoc (comment blocks, @default tags, …), and agents can already browse the types. The generated docs/api/ markdown is therefore mostly a second view of what the types contain: shipping it adds weight for little. Handwritten docs (index.md, guides) carry what the types can't: intent, recipes, gotchas.
  • Handwritten docs are small. docs/api/ (now only for @mrmt/vite and @mrmt/vite-ui) is generated by the build and is the bulk of the folder, so files could include docs and exclude docs/api.
  • Relative links between pages keep working from node_modules as long as the linked pages ship too. Links into other packages (../../vite/docs/…) would dangle there, since each package is installed on its own.

To decide.

  1. Ship handwritten docs only, nothing, or everything?
  2. Cross-package links: keep relative links and accept dangling ones in tarballs, or add a build step rewriting them to site URLs?
  3. Should the marmotte CLI add a pointer to node_modules/@mrmt/*/docs in a project's AGENTS.md / CLAUDE.md when you scaffold or setup it?
  4. Versioning: docs in the tarball always match the installed version, which the website can't promise.