miniml/.plan/04-prerequisites-and-sequencing.md

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

# 04 — Prerequisites and Phased Sequencing

**The single most important structural fact of this plan: it is conditional.** The tribunal's verdict pre-commits to a day-90 evidence gate (`VERDICT.md` §6). A 12-month content plan that ignores that gate re-creates the sunk-cost drift the gate exists to prevent. So: Phases 0–1 are committed; **Phase 2 (months 4–12) executes only if the day-90 criteria pass.** Every platform doc in this plan is annotated accordingly.

The second structural fact: **nothing goes public before the product stops contradicting its own marketing.** The panel was unanimous that the current repo fails a hostile 30-second inspection: the canonical Quick Start command errors on copy-paste (`wave1_target_user.md` step 4), the advertised AST allowlist never executes (`wave1_principal_engineer.md`), and "mcp" is a keyword with no code (every brief). "Launching" this state converts attention into documented reputational damage — the Security Auditor: "Discovering this took one probe; a hostile reviewer would close the tab."

---

## Phase 0 — Earn the right to be trusted (Weeks 1–2, ~20–25 hrs)

Scope is the VERDICT's, ruthlessly cut ("do NOT add a third dialect, do NOT add `SELECT *` fallback, do NOT refactor `dialect.ts`. None of that moves the crux."):

**Code truth (blocking — nothing publishes without these):**
1. Fix the dead AST validator (`validation.ts:280` — handle the object return from `astify`) **and add the regression test that asserts the allowlist blocks `SESSION_USER()`**. Then build the red-team corpus (100+ hostile WHERE/HAVING expressions, both dialects) — agents can generate the corpus (`VERDICT.md` §4, AI-leverage plan).
2. Fix the two date bugs: `query.ts:119` duplicated `date_from` null-check (the `date_to: null` bypass that "lies to her LLM" — Maya step 8), and single-day `BETWEEN` on TIMESTAMP fields (TASKS.md item 3).
3. Fix the README so every command runs verbatim (hyphen vs underscore CLI flags — Maya's "single worst finding for adoption").
4. **Correct or remove the security claims until #1 is proven** — License Counsel: the README's "only safe SQL constructs are permitted" is "a latent misrepresentation exposure" as written (`wave2_panel_updates.md`).
5. Minimal CI (GitHub Actions: build + test on push/PR) + npm publish of the actual current state (the Bull found the entire 2026 revival "has not even been published to npm yet" — latest on npm was 1.0.16).

**Legal/IP (start now — latency is outside your control):**
6. **The Wayvia employer-IP question, in writing.** 24/25 commits from a pricespider.com address on a library inside Wayvia's line of business (Wayvia MCP is their flagship launch) means "the person granting the MIT license may not actually own the thing he is licensing" (`wave1_license_counsel.md` §3). This is a *campaign blocker*, not a legal footnote: every piece of content amplifies the exposure, and Q3 in `03-positioning.md` can't be answered without it. Use License Counsel's five lawyer-questions verbatim. Also adopt the hygiene now: personal email, personal machine, off hours.
7. **Adopt a DCO (not a CLA-transfer) + CONTRIBUTING.md + issue/PR templates before the first stranger's PR** — the relicensing option stays open only while Dave is sole copyright holder; "this door can close any week" once the repo is marketed (`wave1_license_counsel.md` §5, `VERDICT.md` §5).

**Repo hygiene (cheap, high trust-yield — Community Architect's audit):**
8. Untrack the committed `.js`/`.d.ts` build artifacts (they contradict `.gitignore`); move `devnotes.md` out of root; migrate TASKS.md items into GitHub Issues (open issues signal life; a private bug list next to an empty tracker signals "the issue tracker is dead"); set GitHub topics (`semantic-layer`, `text-to-sql`, `mcp`, `snowflake`, `bigquery`); add badges (npm, license, CI); fix the "repeatible" typo in the hero paragraph (line 12 — "first-impression damage in the exact place first impressions are formed").
9. Restructure the README: keep lines 1–197 (pitch + quickstart), move the 700-line reference manual to `documentation/` — "the length isn't the problem; the ordering is."
10. Buy a domain (e.g. `miniml.dev`) — needed for attribution links and to fight the name-collision search problem. Decision on renaming: see README decision list; default recommendation is **keep the name, own the domain, win the qualified searches** (renaming resets what little equity exists, and the collision mostly taxes *brand* search, which this plan doesn't depend on — every channel here is push or listing, not brand search).

## Phase 1 — Ship the hero, then launch once, properly (Weeks 3–13, ~8–10 hrs/wk)

**Weeks 3–5 — the MCP server.** `miniml mcp` subcommand or `@miniml/mcp`: `list_models`, `get_model_info`, `render_query` (+ optional `run_query` with a user-supplied connection). The AI Futurist measured the fit: "the API surface maps one-to-one onto the canonical semantic-layer MCP tool set… ~200 LOC with @modelcontextprotocol/sdk." The VERDICT's One Thing: "It is the wedge, the hero demo, the awesome-list ticket, and the crux test — all four at once. Nothing else on this list matters until it exists."

**Weeks 6–8 — the demo assets + template gallery.**
- The hero GIF at the top of the README: Claude Desktop connected to MiniML's MCP server, "revenue by plan tier last month," the governed SQL, the result. ("This is the artifact that earns a star in 30 seconds; today the repo has none." — `VERDICT.md`)
- The hero video (V1 in `06-youtube-plan.md`) — same loop, 6 minutes, with the why.
- **Template gallery: 5–10 ready-to-fork models for common schemas (Stripe, Shopify, GA4, Postgres `pg_stat_*` once relevant).** This is the VERDICT's designated growth *loop* ("each fork is a visible endorsement that recruits the next user. This is the repeatable mechanism, not 'post and hope'"), and each template doubles as a video/blog artifact later.
- The launch blog post: "Why we put the LLM *outside* the SQL path" (VERDICT's title), on the owned domain.

**Weeks 9–10 — the launch sequence** (Community Architect's verified, sequenced channel plan — details in docs 07–09):
- Day 0: PR to `punkpeye/awesome-mcp-servers`; list on PulseMCP/mcp.so; GitHub topics live.
- Day 1 (Tue–Thu, ~9am ET): Show HN (draft in `09-other-platforms.md`).
- Week 1: dbt Slack #tools-and-utilities; MCP Discord demo post; newsletter submissions (Data Engineering Weekly, Ju) pitching the *ideas* (fan-out doc, security write-up), not the project.
- Week 2: r/dataengineering lessons-learned post; r/LocalLLaMA show-project.

**Weeks 11–13 — respond, instrument, measure.** Answer every issue/comment within 24h. Weekly metrics snapshots. Direct outreach begins (`12-non-content-paths.md`). Day-90 clock runs from launch day.

## The gate (day 90 after launch)

The VERDICT's four pre-registered criteria, verbatim, measured and published (`11-metrics-kill-criteria-and-fallback.md`). **≥3 of 4 → Phase 2. ≤1 of 4 → archive the ambition** (keep the code, stop the campaign). 2 of 4 → free-channels-only holding pattern, re-measure once at day 135, then decide with no further extension.

## Phase 2 — Compound (Months 4–12, conditional, ~6–8 hrs/wk)

- YouTube moves to its full cadence (`06-youtube-plan.md`).
- **Postgres dialect ships months 4–5** — the highest-leverage product move in the entire plan (`05-database-support.md`) and a second launch moment.
- Direct outreach scales; podcast/CFP submissions begin; OSI participation (`12-non-content-paths.md`).
- Discord threshold armed but not fired (`10-community-space.md`).
- Month-6 and month-12 checkpoints per doc 11.

## Effort summary

| Phase | Duration | Hours/week | Content share |
|---|---|---|---|
| 0 | Weeks 1–2 | ~10–12 | 0 — all product/legal/hygiene |
| 1 | Weeks 3–13 | 8–10 | ~3–4 (assets + launch posts); rest is MCP server + templates + response time |
| Gate | Day 90 | — | Publish the checkpoint post regardless of outcome |
| 2 | Months 4–12 | 6–8 | ~4–5 (1 video/mo + X system + blog twins); rest product + outreach |