miniml/.eval/wave1_community_architect.md

A minimal, embeddable semantic data modeling language for generating SQL queries from YAML model definitions. Inspired by LookML.

# Wave 1 — Community Architect (DevRel)

## Position (2 sentences)
MiniML has a genuinely well-timed pitch (safe vocabulary layer for LLM text-to-SQL) attached to a repo with zero community machinery and zero measured traction: 1 star, 0 forks, 0 issues, 0 PRs, and 57 npm downloads/month after 13 months on npm. The product story could sell itself in the current agent wave, but nothing about the repo page, the contribution surface, or the distribution effort (which is currently "none") converts a stranger into a user — and the keyword "mcp" in package.json is a promise the repo doesn't keep.

## Evidence

### Star-test verdict: FAIL (a near-miss fail — fixable in one afternoon)
- [MEASURED] Above the fold of README.md (/home/user/projects/miniml/README.md, lines 1–15): five dense text paragraphs, no logo, no badges (no npm version, no license, no CI — there is no CI to badge), no GIF, no screenshot, no hero demo. A stranger sees a wall of prose before the Table of Contents.
- [MEASURED] The hero paragraph (line 12) contains a typo — "repeatible" — in the single most important sentence of the pitch. First-impression damage in the exact place first impressions are formed.
- [MEASURED] The Quick Start (lines 29–153) is actually strong: YAML in, `npx miniml sales.yaml --dimensions=date --measures=total_amount`, SQL out. This is a real hero demo — it's just buried below ~30 lines of prose and rendered as static text. Converted to a 20-second terminal GIF and moved to line 5, this passes the star test.
- [SOURCED] (https://github.com/dtempx/miniml) GitHub page confirms: 1 star, 0 forks, 0 watchers, 0 open issues, 0 PRs, no badges. The repo page currently signals "abandoned personal project," which contradicts the polished README beneath it.
- [SPECULATION] The name collides with MiniML the classic typed-lambda-calculus teaching language; organic search discovery is compromised, making pushed distribution (below) the only realistic acquisition channel.

### README: manual, not marketing
- [MEASURED] 925 lines. Lines 1–197 are marketing/onboarding and are good. Lines 199–925 are a reference manual (model spec, date semantics, API, security model). The security section (lines 834–901) and the honest fan-out warning (line 316) are the most credible marketing assets in the repo and they're buried at the bottom. Verdict: the length isn't the problem; the ordering is. Split into README (200 lines, pitch + quickstart + security highlights) and docs/ (the rest).

### Contribution friction audit: high friction, low trust signals
- [MEASURED] No CONTRIBUTING.md, no .github/ directory at all — no issue templates, no PR template, no GitHub Actions. The "Contributing" section is 5 generic lines (README lines 916–921).
- [MEASURED] `git ls-files` shows compiled output IS committed despite `.gitignore` listing `*.d.ts`: `lib/*.d.ts` (9 files), `command.d.ts`, `index.d.ts`, `test/*.d.ts`, and even `test/models/snowflake/sales.d.ts`. A contributor's first `npx tsc` dirties their tree with files that are half-ignored, half-tracked. Sloppy hygiene, visible in 10 seconds of cloning.
- [MEASURED] README dev instructions are stale: line 913 says `npx mocha test/**/*.test.js` while package.json defines `"test": "npx mocha"`. A newcomer's first command may not match the maintainer's.
- [MEASURED] TASKS.md (committed, root) openly lists 10 unfixed bugs including "date_from == date_to returns no rows" — honest, but paired with zero issue tracker usage it reads as "I track bugs privately; the issue tracker is dead," which discourages filing issues. devnotes.md (personal notes) is also committed to the public root.
- [MEASURED] Test story: a single meaningful test file (test/validation.test.ts) — 68 tests, nearly all SQL-injection validation. A contributor touching query generation has almost no safety net and no CI to run it anyway.

### Issue hygiene
- [SOURCED] (https://github.com/dtempx/miniml) 0 open issues, 0 PRs, no Discussions visible. There is no issue hygiene because there are no issues — 13 months, zero inbound. This is the clearest single measurement that no distribution has ever been attempted.

### THE DISTRIBUTION PLAN (named channels, verified)
Sequencing matters: ship the MCP server FIRST (see "one artifact" below), then execute in this order over ~4 weeks.

1. **awesome-mcp-servers (punkpeye)** — [SOURCED] (https://github.com/punkpeye/awesome-mcp-servers) verified active, ~90k stars. Highest-leverage single listing for this project's stated positioning — but ONLY once a real MCP server exists in the repo. Today the listing would be rejected: package.json says "mcp" and there is no MCP code [MEASURED]. Also submit to the GitHub `semantic-layer` topic page [SOURCED] (https://github.com/topics/semantic-layer) — note: my search found NO "awesome-semantic-layer" list exists; the topic page is the substitute, and MiniML currently has no topics set on the repo [SOURCED via repo fetch].
2. **Show HN** — draft below. Fires only after the MCP demo GIF exists, because HN will click the repo within 30 seconds.
3. **dbt Slack** (#tools-and-utilities / #analytics-craft) — [SOURCED] (https://www.getdbt.com/community) verified, 66k+ members. Framing: "the semantic layer for people who found MetricFlow too heavy to embed."
4. **Locally Optimistic Slack** — [SOURCED] (https://locallyoptimistic.com/community/) verified, ~9k analytics leaders, invite-gated with explicit anti-vendor norms. Do NOT pitch; ask a question ("how are you constraining LLM SQL generation?") and let the repo appear in the answer.
5. **r/dataengineering** — [SPECULATION on exact reception; subreddit existence/activity is well established] Post as a lessons-learned write-up ("I stopped letting the LLM write SQL; here's the 1,000-line library I wrote instead"), not a launch. Secondary: **r/LocalLLaMA** (agent-builder audience, tolerant of Show-your-project posts) and **r/BusinessIntelligence** (the "chat with your data" buyer). Avoid r/programming — name collision with the ML teaching language invites derailment.
6. **Newsletters** — **Data Engineering Weekly** (Ananth Packkildurai) is verified active and demonstrably covers exactly this beat: recent issues feature Lyft's YAML metric layer and Netflix DataJunction [SOURCED] (https://www.dataengineeringweekly.com/p/data-engineering-weekly-275). Submit the fan-out doc + security model as the hook, not the project itself. Also **Ju Data Engineering Newsletter** (Julien Hurault) [SOURCED] (https://juhache.substack.com/) — covers lightweight/DuckDB-adjacent tooling; MiniML's zero-infrastructure angle fits. I could not verify a "TLDR Data" newsletter exists — do not plan around it.
7. **MCP Discord / Anthropic community channels** — [SPECULATION: activity assumed, not verified this session] worth a demo post once the MCP server ships; treat as tertiary.

Disqualification check: this plan is not "post it and hope" — items 3–6 each carry a channel-specific framing, item 1 has an explicit precondition, and the sequencing gates everything on the one missing artifact.

### Show HN draft
**Title:** Show HN: MiniML – a small semantic layer so your LLM never writes raw SQL

**First paragraph:** I build conversational analytics at work, and letting an LLM generate free-form SQL against a warehouse was a recurring source of wrong numbers and scary queries. MiniML is my answer: you define dimensions, measures, and joins once in a YAML model; the LLM only ever picks from that vocabulary ("dimensions: date, store; measures: total_sales"); MiniML compiles the selection into correct BigQuery/Snowflake SQL. It's ~1,000 lines of TypeScript, MIT, embeds in any Node process with no server or account — the un-heavy alternative to Cube/MetricFlow. The `where` clause is the one place raw user SQL gets through, so there's an AST-based allowlist validator (no subqueries, no DDL, model-checked column refs) with 68 tests behind it. I've written up the fan-out problem — one-to-many joins silently over-counting SUMs — and why MiniML deliberately doesn't hide it from you. Would love feedback on the security model and what dialect you'd need next.

### The ONE missing artifact
[MEASURED: keywords claim "mcp", no MCP code exists in the repo] A working MCP server (`miniml-mcp`: tools = `describe_model`, `run_query`) plus a 30-second GIF of Claude answering "what were sales by store last month?" through it. This single artifact simultaneously (a) makes the keywords honest, (b) unlocks the awesome-mcp-servers listing, (c) becomes the Show HN demo, and (d) is the hero GIF the README lacks. Every other gap (CONTRIBUTING.md, CI badge, hosted playground) is secondary to this.

## Strongest point FOR the project
The positioning is exactly right for mid-2026 and the README's substance backs it up: an embeddable, zero-infrastructure vocabulary layer for LLM SQL generation, with a real AST-based injection validator and rare intellectual honesty (the fan-out warning, the committed bug list). The newsletters that matter are actively covering this exact problem — Lyft and Netflix write-ups prove editorial appetite [SOURCED]. The story is sellable; it just has never once been told anywhere.

## Strongest point AGAINST
Thirteen months public, and the funnel is empty at every stage: 1 star, 0 issues, 0 PRs, 57 npm downloads/month [SOURCED/MEASURED] — while the repo's own trust signals (no CI, no CONTRIBUTING, gitignore-contradicting committed build output, stale test instructions, a personal devnotes.md in root) tell any developer who does arrive that this is one person's scratch project. Worse, the flagship differentiator ("mcp" keyword) is vaporware in the repo, and the recent commit revival is README polish rather than the MCP server or the TASKS.md bug fixes — marketing effort pointed at a page nobody visits.

## Viability score: 30/100

## The one question that would change my mind
Will the author ship the MCP server and commit to a 4-week distribution sprint (the sequenced plan above), or is MiniML content to remain Wayvia's internal tool with a public mirror? A shipped `miniml-mcp` + one accepted awesome-mcp-servers PR + one Show HN post within 60 days would move my score 25+ points, because every structural problem I found is cheap to fix — the only unproven variable is the author's will to distribute.