@grainulation/mill 1.0.0 → 1.0.1

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our standards
+
+We are committed to providing a welcoming and productive environment for everyone. We expect participants to:
+
+- Use welcoming and inclusive language
+- Respect differing viewpoints and experiences
+- Accept constructive criticism gracefully
+- Focus on what is best for the community and the project
+- Show empathy toward other participants
+
+Unacceptable behavior includes harassment, trolling, personal attacks, and publishing others' private information without permission.
+
+## Scope
+
+This code of conduct applies to all project spaces -- issues, pull requests, discussions, and any public channel where someone represents the project.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated, and will result in a response deemed necessary and appropriate.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to Mill
+
+Thanks for considering contributing. Mill is the format and export engine for the grainulation ecosystem -- it transforms structured claim data into multiple output formats.
+
+## Quick setup
+
+```bash
+git clone https://github.com/grainulation/mill.git
+cd mill
+node bin/mill.js --help
+```
+
+No `npm install` needed -- mill has zero dependencies.
+
+## How to contribute
+
+### Report a bug
+
+Open an issue with:
+
+- What you expected
+- What happened instead
+- Your Node version (`node --version`)
+- Steps to reproduce
+
+### Suggest a feature
+
+Open an issue describing the use case, not just the solution. "I need X because Y" is more useful than "add X."
+
+### Submit a PR
+
+1. Fork the repo
+2. Create a branch (`git checkout -b fix/description`)
+3. Make your changes
+4. Run the tests: `node test/basic.test.js`
+5. Commit with a clear message
+6. Open a PR
+
+### Add a format or exporter
+
+Formats live in `lib/formats/` and exporters in `lib/publishers/`. To add one:
+
+1. Create your module in the appropriate directory
+2. Follow the pattern of existing formats/exporters
+3. Register it in `lib/formats.js` or the relevant index
+4. Add a test in `test/`
+
+## Architecture
+
+```
+bin/mill.js               CLI entrypoint -- dispatches subcommands
+lib/index.js              Core library -- format resolution and pipeline
+lib/formats.js            Format registry and selection
+lib/formats/              Individual format implementations
+lib/exporters/            Output target adapters (file, clipboard, etc.)
+lib/publishers/           Publishing integrations
+lib/json-ld-common.js     Shared JSON-LD vocabulary helpers
+lib/serve-mcp.js          MCP (Model Context Protocol) server
+lib/server.js             Local preview server (SSE, zero deps)
+public/                   Web UI -- format preview and conversion
+site/                     Public website (mill.grainulation.com)
+test/                     Node built-in test runner tests
+```
+
+The key architectural principle: **mill is a pipeline.** Data flows in as structured claims, passes through a format transform, and exits as the target format. Each format is a pure function: data in, string out.
+
+## Code style
+
+- Zero dependencies. If you need something, write it or use Node built-ins.
+- No transpilation. Ship what you write.
+- ESM imports (`import`/`export`). Node 18+ required.
+- Keep functions small. If a function needs a scroll, split it.
+- No emojis in code, CLI output, or generated formats.
+
+## Testing
+
+```bash
+node test/basic.test.js
+```
+
+Tests use Node's built-in test runner. No test framework dependencies.
+
+## Commit messages
+
+Follow the existing pattern:
+
+```
+mill: <what changed>
+```
+
+Examples:
+
+```
+mill: add JSON-LD export format
+mill: fix Markdown table alignment in brief output
+mill: update MCP server protocol handling
+```
+
+## License
+
+MIT. See LICENSE for details.

package/README.md

@@ -1,69 +1,96 @@
-# mill
+<p align="center">
+  <img src="site/wordmark.svg" alt="Mill" width="400">
+</p>
 
-Turn sprint evidence into shareable artifacts.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@grainulation/mill"><img src="https://img.shields.io/npm/v/@grainulation/mill" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/mill"><img src="https://img.shields.io/npm/dm/@grainulation/mill" alt="npm downloads"></a> <a href="https://github.com/grainulation/mill/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/mill" alt="node"></a> <a href="https://github.com/grainulation/mill/actions"><img src="https://github.com/grainulation/mill/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://deepwiki.com/grainulation/mill"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
+</p>
 
-## Quick start
+<p align="center"><strong>Turn sprint evidence into shareable artifacts.</strong></p>
+
+24 export formats. PDF, CSV, Markdown, slides, JSON-LD, Jira, GitHub Issues, and more. Give mill your claims or HTML output and it produces whatever your team needs.
+
+## Install
 
 ```bash
-# Export a brief to PDF
-npx @grainulation/mill export --format pdf output/brief.html
+npm install -g @grainulation/mill
+```
 
-# Claims to CSV
+Or use directly:
+
+```bash
 npx @grainulation/mill export --format csv claims.json
+```
 
-# HTML to clean Markdown
-npx @grainulation/mill convert --from html --to markdown output/brief.html
+## Quick start
 
-# Build a static site from sprint outputs
-npx @grainulation/mill publish --target static output/
+```bash
+# Claims to CSV
+mill export --format csv claims.json
+
+# HTML brief to PDF
+mill export --format pdf output/brief.html
+
+# HTML to clean Markdown
+mill convert --from html --to markdown output/brief.html
 
 # Claims to JSON-LD
-npx @grainulation/mill export --format json-ld claims.json -o claims.jsonld
+mill export --format json-ld claims.json -o claims.jsonld
+
+# Build a static site from sprint outputs
+mill publish --target static output/
 
 # Copy to clipboard
-npx @grainulation/mill publish --target clipboard output/brief.html
+mill publish --target clipboard output/brief.html
 ```
 
 ## Export formats
 
-24 built-in formats in `lib/formats/`. Most commonly used:
-
-| Format | Input | Output | Notes |
-|--------|-------|--------|-------|
-| `pdf` | HTML, Markdown | PDF | Uses `npx md-to-pdf` or puppeteer |
-| `csv` | claims.json | CSV | Flat columns, semicolon-joined tags |
-| `markdown` | HTML | Markdown | Zero-dep tag stripping, handles wheat output |
-| `json-ld` | claims.json | JSON-LD | schema.org vocab, wheat namespace |
-| `html-report` | claims.json | HTML | Self-contained interactive report |
-| `slide-deck` | claims.json | HTML | Scroll-snap presentation |
-| `github-issues` | claims.json | JSON | GitHub Issues payloads |
-| `jira-csv` | claims.json | CSV | Jira-compatible import |
-| `yaml` | claims.json | YAML | YAML export |
-| `ndjson` | claims.json | NDJSON | Newline-delimited JSON |
-
-Run `mill formats` to see all 24 formats and publish targets.
+24 built-in formats:
+
+| Format              | Input          | Output                        |
+| ------------------- | -------------- | ----------------------------- |
+| `pdf`               | HTML, Markdown | PDF                           |
+| `csv`               | claims.json    | CSV                           |
+| `markdown`          | HTML           | Markdown                      |
+| `json-ld`           | claims.json    | JSON-LD (schema.org)          |
+| `html-report`       | claims.json    | Interactive HTML report       |
+| `slide-deck`        | claims.json    | Scroll-snap HTML presentation |
+| `github-issues`     | claims.json    | GitHub Issues JSON payloads   |
+| `jira-csv`          | claims.json    | Jira-compatible CSV import    |
+| `yaml`              | claims.json    | YAML                          |
+| `ndjson`            | claims.json    | Newline-delimited JSON        |
+| `dot`               | claims.json    | Graphviz DOT                  |
+| `graphml`           | claims.json    | GraphML                       |
+| `bibtex`            | claims.json    | BibTeX citations              |
+| `ris`               | claims.json    | RIS citations                 |
+| `rss`               | claims.json    | RSS feed                      |
+| `opml`              | claims.json    | OPML outline                  |
+| `obsidian`          | claims.json    | Obsidian vault                |
+| `sql`               | claims.json    | SQL INSERT statements         |
+| `typescript-defs`   | claims.json    | TypeScript type definitions   |
+| `executive-summary` | claims.json    | Executive summary HTML        |
+| `evidence-matrix`   | claims.json    | Evidence tier matrix          |
+| `changelog`         | claims.json    | Sprint changelog              |
+| `sankey`            | claims.json    | Sankey diagram data           |
+| `treemap`           | claims.json    | Treemap data                  |
+
+Run `mill formats` to see the full list with descriptions.
 
 ## Publish targets
 
-| Target | Input | Output | Notes |
-|--------|-------|--------|-------|
-| `static` | directory | `_site/` | Dark-themed index + copied artifacts |
-| `clipboard` | file or dir | clipboard | Uses pbcopy/xclip/clip |
+| Target      | Output                               |
+| ----------- | ------------------------------------ |
+| `static`    | Dark-themed static site in `_site/`  |
+| `clipboard` | System clipboard (pbcopy/xclip/clip) |
 
-## Zero dependencies
-
-Mill has no installed npm dependencies. Heavy operations (PDF generation) run via `npx` on demand, pulling packages only when needed.
-
-## Works standalone
-
-Mill reads sprint output files directly. It does not require wheat to be installed -- give it HTML, Markdown, or claims JSON and it produces shareable formats.
-
-## CLI reference
+## CLI
 
 ```
 mill export    --format <fmt> <file>              Export to target format
-mill publish   --target <dest> <dir>              Publish sprint outputs
 mill convert   --from <fmt> --to <fmt> <file>     Convert between formats
+mill publish   --target <dest> <dir>              Publish sprint outputs
 mill formats                                      List available formats
 mill serve     [--port 9094] [--source <dir>]     Start the export workbench UI
 mill serve-mcp                                    Start the MCP server on stdio
@@ -71,6 +98,27 @@ mill serve-mcp                                    Start the MCP server on stdio
 
 All commands accept `-o <path>` to set the output location.
 
+## Works standalone
+
+Mill reads sprint output files directly. It does not require wheat -- give it HTML, Markdown, or claims JSON and it produces shareable formats.
+
+## Zero dependencies
+
+Node built-in modules only. Heavy operations (PDF) run via `npx` on demand.
+
+## Part of the grainulation ecosystem
+
+| Tool                                                         | Role                                                        |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| [wheat](https://github.com/grainulation/wheat)               | Research engine -- grow structured evidence                 |
+| [farmer](https://github.com/grainulation/farmer)             | Permission dashboard -- approve AI actions in real time     |
+| [barn](https://github.com/grainulation/barn)                 | Shared tools -- templates, validators, sprint detection     |
+| **mill**                                                     | Format conversion -- export to PDF, CSV, slides, 24 formats |
+| [silo](https://github.com/grainulation/silo)                 | Knowledge storage -- reusable claim libraries and packs     |
+| [harvest](https://github.com/grainulation/harvest)           | Analytics -- cross-sprint patterns and prediction scoring   |
+| [orchard](https://github.com/grainulation/orchard)           | Orchestration -- multi-sprint coordination and dependencies |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem          |
+
 ## License
 
 MIT