typeglish 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+TypeGlish
+Copyright (c) 2026 Voiceflow, Inc.
+
+This product includes rule lexicons and detection-pattern families adapted from
+PromptLint (https://www.promptlint.dev/), licensed under the Apache License,
+Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0). The hedge/vagueness
+word lists (src/core/diagnostics.ts) and the leaked-secret / injection pattern
+families (src/core/security.ts) were reimplemented natively for TypeGlish.
+
+The optimizer in src/core/gepa/ implements the GEPA algorithm (Genetic-Pareto
+reflective prompt evolution) described in arXiv:2507.19457, with the reference
+implementation at https://github.com/gepa-ai/gepa (MIT License). The TypeScript
+implementation here is original code.

package/README.md

@@ -0,0 +1,301 @@
+# TypeGlish
+
+> **Turning English into logically consistent, controlled, maintainable, executable programs for LLMs.**
+
+A controlled language with the rigor of a programming language — operators, declarations, types, and a
+static consistency checker — that compiles English to clean, XML-tagged prompts. Think *the TypeScript
+of English*: you still write English, but a grammar, a type system, and a solver have your back.
+
+The long-term goal: make English **safe for agents to work with** — a static analyzer for the
+instructions, policies, and knowledge agents consume, run at corpus scale to catch contradictions the
+way a compiler does for code. This repo is **the rules and the compiler** for TypeGlish, plus a
+playground to build and work on the language. See **[ROADMAP.md](ROADMAP.md)** for where it's headed.
+
+## Why
+
+A prompt is a program written in English — but English has no compiler. Nothing tells you when
+two instructions contradict each other, when a constraint is impossible to satisfy, or when a
+reference is undefined. TypeGlish adds that missing layer.
+
+```typeglish
+Persona IS a customer support agent for Acme.
+
+# Role
+"You are @{Persona}."
+
+# Constraints
+- NEVER state a specific price; ALWAYS direct pricing questions to sales.
+- MUST keep every response to at most 3 sentences.
+- IF you are unsure THEN say so AND offer to escalate.
+```
+
+- **Operators** — modals (`MUST` / `NEVER` / `SHOULD` …), control flow (`IF … THEN … OTHERWISE`),
+  connectives (`AND` / `OR` / `NOT`), and the copula (`IS` / `ARE` / `AM`). Case-insensitive.
+- **Statement terminators** — every statement ends with `.` `!` `?` (a lead-in may end with `:`);
+  unterminated is a **compile error**, one-click fixable — the semicolon rule, one level up. The
+  terminator never leaks into a bound value: `Tone IS warm.` binds `warm`.
+- **Layout is syntax** — the indent unit is 2 spaces and **indentation mirrors section nesting**
+  (a nested tag one unit deeper, its content one deeper than that); one space between things.
+  Alignment columns, trailing whitespace, and tabs are **compile errors** with one-click fixes — "LLM
+  spacing" doesn't compile. Blank lines, by contrast, are free: **the compiler packs the emitted prompt**
+  — consecutive prose statements join onto one line, a run of blank lines collapses to a single break, and
+  structure (lists, headings, tags, fences) keeps its own line. Fences and literal zones stay verbatim,
+  and cosmetic indent is stripped at compile, so the model reads clean packed text either way.
+- **A strict character set** — the instruction plane is plain ASCII text: em-dashes, curly quotes,
+  arrows, bullets, math symbols, emoji, and invisible characters are **compile errors** with
+  one-click ASCII fixes. Not aesthetics: each mark hides meaning from the checker (a curly
+  apostrophe conceals a possession contradiction; `≤ 3` hides the bound `at most 3` proves).
+  Human language never flags — accents, scripts, currency stay legal — and symbols keep their
+  literal homes (`<examples>`, `<"…">` zones, fences, quotes).
+- **Declarations** — `Persona IS a support agent` defines a reusable object; `{Persona}` expands it
+  (references resolve case-insensitively).
+- **Types** — `Animals ARE one of alligator, orangutan` declares a closed, mutually-exclusive set.
+- **String literals** — `"…"` escapes to literal prose: no operators parsed inside, quotes stripped
+  on compile, `@{refs}` still expand.
+- **Sections & structure** — group with `#` headings or `<xml_tags>` (same-line and inline content
+  welcome); `<$name>` strips control-plane scaffolding, `<?name>` strips just the wrapper tag,
+  `<"name">` keeps its body **verbatim** (a literal zone for reference tables and syntax samples —
+  quotes are the one escape, here at section scale), and `<examples>` is the literal zone by name. Structure is enforced: content must live in a
+  section, `#` headings must sit inside XML sections once you use any, and section names must be
+  **distinct and meaningful** — duplicate/near-duplicate names error, vague ones warn.
+- **Definition lists** — `term:: definition` rows for glossaries and cheat-sheets: position-insensitive
+  to author (agents never break alignment), parse-literal (samples inside never open zones or bind) yet
+  **content-checked** — one statement per line holds inside a body (the editor wraps; a hard-wrapped
+  continuation is a compile error), terminators and the character set apply — and the compiler owns
+  the emitted layout (nested sub-bullets, fenced samples) so the model reads clean markdown regardless
+  of authoring; duplicate terms flagged.
+- **Statement annotations & references** — `@@ a note` documents the statement below it (a docstring
+  that compiles away and is inert to every analysis tier); `@@ name: …` also **names** that statement.
+  References are typed sigils, each validated at compile time: `@{variable}` reads host state,
+  `@<section>` inlines a section, `@[tool]` references a tool — inline it emits the checked bare
+  name, alone on a line it surfaces `name — description` (a dangling reference is an error, and an
+  exact tool name in bare prose is too: point it or quote it).
+- **A consistency checker** — propositional + SMT (Z3). Catches `MUST escalate` vs `NEVER escalate`,
+  and numeric contradictions like `at most 3 sentences` vs `at least 5 sentences` that propositional
+  logic provably can't decide. Its **quantifier layer** gives the English of quantity its logic:
+  the square of opposition (`all` / `some` / `no` / `most` / `only`), set sizes (`there is only one
+  tool` vs `there are many tools`; nouns fold by lemma, so `people` ⇄ `person`), action counts
+  (`call five tools` vs `call six tools` — one count per directive slot), supply vs demand
+  (`there is only one tool` vs `call five tools`), definite reference (`the tool` with two tools
+  declared), and transitive syllogism chains. Claims key by what they are about (noun + restrictor
+  tail); frame, subject, and owner are refinement fields that must agree where present but never
+  exempt a claim from checking. Directives default to the ADDRESSEE — a bare rule, `You must…`, a
+  declared alias (`You are Claude.` → `Claude must…`), and a declared role (`You are a support
+  agent.` → `the support agent must…`) are one subject's rules, while an undeclared `the assistant`
+  stays scoped (no guessing; opt nouns in via glish.tgc `$CONFIG addressee one of …`) and `the user` is
+  never you. Guards parse in both spellings — `IF … THEN …` and the comma form English writes
+  (`If the user is angry, never quote prices.`); `Don't` reads as `DO NOT`.
+- **A predicate system** — actions parse into `verb + theme + roles + tool binding` against a curated
+  catalog, so the checker also proves verb-level facts: synonyms merge (`output`/`print`), antonyms
+  conflict (`MUST output` vs `MUST suppress` flips the badge), bare imperatives are obligations, and
+  `fire book_appointment` ≡ `call book_appointment`.
+- **A semantic auditor (advisory)** — per-line **residual value** and **overlap**, scored at the atom
+  level by a local NLI model with an LLM-judge escalation (every verdict distilled as training data
+  for an offline replacement). Heavy duplication warns; proposed cuts are behaviorally verified;
+  a greedy reducer consolidates toward a minimal, orthogonal prompt.
+- **The TG score** — one proof-backed number per prompt (`tg score`, CI-gateable with `--min B`).
+  Proven errors **gate** to F; graded facets measure enforceability (the checker's own visibility),
+  consistency, structure, **annotation coverage** (every statement should carry a `@@` note saying
+  what it's for), style, security, and density; every deducted point cites a finding + fix
+  (the ledger is the to-do list). Calibrated against an authored good/bad corpus with a tested
+  separation margin.
+- **`$TEST` — the file carries its own eval suite** — cases whose `- input::` / `- expect::` bullets
+  live beside the rules they test, or in an auto-discovered sibling `<name>.test.tg`, and compile away
+  entirely. Deterministic asserts (`contains`, `matches`, `at most N sentences`) are code-checked; prose
+  expectations are judge-scored. Run them with `tg test`; feeds coverage (`prompt/untested-rule`), the
+  profile, promptfoo emit, portability, and the optimizer.
+- **`$EXAMPLE` — the file carries its own few-shot** — one exchange per block (`- input::` / `- good::`,
+  optional `- bad::`), the same bullet record. Each `- good::` compiles into the prompt as a labelled
+  few-shot exchange; `- bad::` is held out — never shown to the model, so it can't be imitated. A
+  malformed block is a `structure/bad-example` error.
+- **The profile** — per-statement attribution, keyed by content hash (survives comments, reordering;
+  an edited statement is a new hash, so staleness is impossible): what a line says (IR, predicates),
+  what duplicates it (residual), which cases exercise it, and the measured ablation **Δ per case**
+  (`tg profile --behavioral`, budget-confirmed). Those fold into a per-statement **verdict** — potency
+  (Δ) crossed with redundancy (residual) and coverage → **keep / cut** (implied or dead) **/ test**, with
+  attribution and honest degradation when a tier hasn't run. `tg annotate` writes it into the margin as
+  `//@` machine comments — compile-stripped, human comments untouched; the editor shows it on hover.
+- **Portability, measured** — `tg portability` runs the suite across a model panel (promptfoo owns
+  the matrix; TypeGlish owns zero dependencies) and reports cross-model agreement WITH per-model
+  pass rates beside it — consistency ≠ correctness is encoded, not footnoted.
+- **A dependency map** — the playground's **Map** view renders the prompt as the graph it already is:
+  the depended-upon symbols (inputs with their domains, tools, variables, tests) on one side, the
+  section skeleton with a reference chip on every wired line on the other, and hover to light up an
+  edge — where a symbol is used, or what a line depends on. Broken edges (a `<closing>` that resolves
+  to nothing, an unused import) are marked in place, from the **same resolution engine as the
+  squiggles**, so the map can never disagree with the checker. Deterministic and free.
+- **A fix list, ranked by score impact** — the playground's **Fixes** panel is the score ledger made
+  actionable: every deduction below 100, ordered by the points it costs, pinned to its line, with a
+  one-click fix where one exists. Deterministic and free — it updates as you type, and it never
+  spends a model call. This is "highlight what needs changing," computed, not judged.
+- **A GEPA optimizer with the compiler in the loop** — `tg optimize` (a deliberate CLI opt-in — the
+  editor highlights, the human changes) runs reflective prompt evolution (per-instance Pareto,
+  minibatch acceptance) where provably-broken mutants are rejected **free** before any eval spend,
+  mutants that touch their own `$TEST` blocks are rejected as fitness hacking, and the accept rule
+  breaks ties toward **fewer tokens** — the bloat spiral of naive optimization loops structurally
+  loses. Every model call (evals AND reflections) is charged against the budget, so the pre-run
+  quote is a hard spend ceiling; the result lands as a new `.optimized.tg`, never overwriting the seed.
+- **Conditionals, resolved** — deterministic `IF` chains / guarded sections make a prompt a template: `(source, state)
+  → prompt`. Two stages, one seam (`prepareTemplate`): **render** is state-free and *total* — an
+  unresolved chain compiles to conditional English (`If voice is true: … / Otherwise: …`), never a
+  leaked sigil; **resolve** is state-dependent and *partial* — it collapses only the branches the bag
+  can decide. The playground's **values panel** exposes it: set an input and the Compiled view resolves
+  that chain to the one branch the model gets; leave it unset and it stays conditional.
+- **A compiler** — `text → parse → IR → check → XML`: references expand, declarations and comments
+  strip, and each `# block` becomes a semantic tag (`<role>`, `<constraints>`, …).
+- **Agent files** — a single `.tg` file can be a whole agent: `$CONFIG` sets the model and settings,
+  `$TOOL` / `$SERVICE` define tools as YAML-shaped code with HTTP bindings, and `compile()` emits the
+  prompt **plus** an agent bundle (settings + JSON-Schema tool definitions). `npm run tg:run agent.tg`
+  runs it live — tool-use loop, bindings, and `{env.*}` secrets included.
+
+The full language reference is in **[SPEC.md](SPEC.md)**.
+
+## The repo
+
+```
+src/core/        the language + compiler (pure TS — runs in Node, browser, and tests alike)
+  typeglish-grammar.ts   the grammar (Peggy / PEG)
+  parser.ts, ast.ts      parse a clause → statement AST
+  ir.ts                  lower the AST → logical-form IR (directives, conditions, numeric bounds)
+  prompt.ts              the compiler: declarations, references, quotes, comments, render
+  compile.ts             render → semantic XML + the agent bundle
+  tool.ts                $TOOL / $SERVICE definitions (tool schemas + HTTP bindings)
+  agent.ts               the runner: the tool-use loop + HTTP bindings (Node-side, like z3)
+  solver/z3.ts           the SMT consistency checker (deontic + numeric)
+  predicate.ts, verbs.ts the predicate system: action parser + the curated verb catalog
+  semantic/              the advisory tier: atoms, NLI engine, judge + distillation, reducer
+src/lib/         the published surface — the `typeglish` bin (check / build / score / resolve /
+                 reference / mcp / claude-hook), build.ts (artifact + hash manifest), deploy-gate.ts,
+                 claude-hook.ts, project.ts (glish.tgc discovery), `typeglish/monaco`, `typeglish/spell`
+src/mcp/         the MCP head — `typeglish mcp`: five stateless tools over stdio, results
+                 byte-shaped like the CLI --json (the LSP pattern, one transport over)
+lsp/             the stdio LSP head (editor language services)
+plugin/          the Claude Code plugin — skill + PostToolUse check hook + PreToolUse deploy gate
+                 (served by .claude-plugin/marketplace.json at the repo root)
+docs/agents/     TYPEGLISH.md — the GENERATED agent language reference (AGENTS.md-style consumers)
+src/web/         the playground — a Monaco editor that consumes `src/lib` (it's the first consumer)
+server/          the Node side (LLM calls + the server-side Z3 logic check) as Vite middleware
+```
+
+**Changing the language?** Every operator, type, character rule, and diagnostic code lives in exactly one
+**single-source-of-truth** module — see the **SSOT registry** in [`CLAUDE.md`](CLAUDE.md) (invariant #1). Edit
+the SSOT, run `npm run gen:syntax`, and let the drift-lock tests tell you what else to update; a hardcoded copy
+anywhere else fails CI.
+
+## Install
+
+Zero-setup — the CLI has **no runtime dependencies**, so `npx` cold-starts in seconds:
+
+```bash
+npx typeglish check prompts/*.tg [--json]   # exit 1 on any provable error
+npx typeglish build prompts/*.tg            # passing files → .typeglish/dist/*.txt artifacts
+                                            #   + a hash manifest (.typeglish/build-manifest.json)
+npx typeglish score prompt.tg --min B          # the TG score; exit 1 below the floor (the CI gate)
+npx typeglish resolve prompt.tg --vars '{"tier":"premium"}'
+npx typeglish --explain logic/contradiction    # what any diagnostic code means
+npx typeglish mcp                              # the same tools over MCP stdio (for shell-less agent hosts)
+```
+
+`build` is the deploy contract: the artifact — `compile(source).xml` — is what a prompt-taking system
+(a system prompt, an assistant API, Voiceflow) should receive, and the manifest proves any payload
+byte-for-byte ("this exact prompt came out of a passing compile"). A file with a blocking error
+refuses to build; nothing failing can enter the manifest.
+
+In a project, install it and add the proof tiers you want — both are optional peers, and the
+deterministic core works identically without them:
+
+```bash
+npm i -D typeglish
+npm i -D z3-solver                                # + SMT proofs (contradictions, unsatisfiable bounds)
+npm i -D nspell dictionary-en dictionary-en-gb    # + spell-check (the typeglish/spell module)
+```
+
+Without `z3-solver`, `check` runs the synchronous tier (still the full language/consistency/structure
+check); with it, the same command adds the Z3 numeric + exhaustiveness proofs. Requires Node ≥ 20.19.
+
+## Embed in your product (Monaco)
+
+Any product with a Monaco editor gets the full TypeGlish experience — syntax highlighting,
+the object-record hover, completion, live consistency squiggles, object-reference
+highlighting, and list/operator authoring — in a couple of calls:
+
+```ts
+import * as monaco from 'monaco-editor';
+import { setupTypeGlish, attachTypeGlish } from 'typeglish/monaco';
+import 'typeglish/monaco.css';
+
+setupTypeGlish(monaco);                                              // once per monaco instance
+const editor = monaco.editor.create(el, { language: 'typeglish', theme: 'typeglish-dark' });
+attachTypeGlish(monaco, editor);                                    // per editor → squiggles, highlights, authoring
+```
+
+Need just the compiler (no editor)? The core runs anywhere — Node or browser:
+
+```ts
+import { compile } from 'typeglish';
+const { diagnostics, consistent, xml } = compile(source);
+```
+
+Every rule lives in the framework-agnostic core; `typeglish/monaco` only wires it to Monaco's
+APIs. The playground in `src/web/` is the first consumer of exactly this surface.
+
+## Develop
+
+```bash
+npm install
+npm run dev          # the playground at http://localhost:5273
+npm run typecheck
+npm test             # ~2,200 unit tests cover the language, checker, score, and semantic kernel
+npm run check -- prompt.tg [--json]               # compiler errors + warnings, agent-friendly (exit 1 on errors)
+npm run score -- prompt.tg [--full] [--min B]     # the TG score + ledger (exit 1 below --min: the CI gate)
+npm run tg:test -- prompt.tg [--dry] [--min 0.7]  # run the suite (inline + sibling .test.tg): per-case pass/fail
+npm run fmt -- prompt.tg [--write]                # join wrapped fragments, split compound rules
+npm run profiles -- prompt.tg [--behavioral --yes] # per-statement attribution (static free; Δ costs, confirmed)
+npm run annotate -- prompt.tg [--write|--clean]   # write the profile into //@ margin comments
+npm run emit -- promptfoo prompt.tg               # the file's $TEST suite as a promptfoo config
+npm run portability -- prompt.tg --models a,b     # cross-model agreement (then --results out.json)
+npm run optimize -- prompt.tg --budget 24 [--estimate] [--json]  # GEPA; --estimate quotes cost (free), --json = agent-readable result
+npm run semantic -- prompt.tg              # per-line residual/overlap audit (add --reduce, --actions)
+npm run semantic:bench                     # regenerate the golden-pair benchmark report
+```
+
+The compiler core has no browser dependencies, so the grammar, the IR, and the solver behave
+identically in Node, the browser, and Vitest.
+
+## Agents in the loop
+
+The compiler talks back to agents at the moment their work SETTLES — the turn boundary — never
+mid-typing (half-written text is legitimately broken). The mental model everywhere is **TypeScript for
+prompts**: the `.tg` is source in git, the deployed prompt is a build artifact, and the gate between
+them is mechanical.
+
+- **In Claude Code**, install the plugin and the whole loop runs itself:
+
+  ```
+  /plugin marketplace add Bradenream/TypeGlish
+  /plugin install typeglish@typeglish
+  ```
+
+  - A **skill** teaches the workflow — author `.tg` → check → score → build → deploy the artifact
+    verbatim — with the generated language reference as its deep material.
+  - A **PostToolUse hook** re-checks every settled `.tg` edit and feeds blocking diagnostics straight
+    back to the model as fix-now feedback (advisories ride along as context; clean files stay silent).
+  - A **PreToolUse deploy gate** hashes outgoing prompt payloads (Voiceflow MCP tools by default;
+    configurable via `.typeglish/deploy-gate.json`) against `.typeglish/build-manifest.json`: a prompt
+    no passing build produced is **denied** with the fix in the message, and a verified one still goes
+    through the normal permission flow — the gate never auto-approves. Escape hatches:
+    `TYPEGLISH_DEPLOY_GATE=off|ask`.
+- **In the playground**, the Copilot gets a **turn-end compiler report**: when its edits land, the
+  merged diagnostics are diffed against the turn-start snapshot and reported — as a ⚙ row in the
+  transcript and as compiler truth in the model's history. A turn that *introduced* errors triggers
+  one automatic fix round (toggleable, never recursive).
+- **Any other agent with a shell** (Cursor, a CI bot, …) gets the same truth from
+  `npx typeglish check|score|build --json` — data on stdout, diagnostics on stderr, exit codes as
+  gates, `typeglish --explain <code>` for what any code means. Wire the same loop into any hook system.
+- **Shell-less hosts** (claude.ai, any MCP client) get the compiler as five MCP tools —
+  `npx -y typeglish mcp` — check / build / score / explain / reference, results byte-identical to the
+  CLI's `--json`. A host with no filesystem passes `source` inline; `build` returns the artifact + its
+  sha256 without persisting.
+- **Teaching the language**: `typeglish reference` prints the generated agent reference
+  ([docs/agents/TYPEGLISH.md](docs/agents/TYPEGLISH.md) is the same document, committed for
+  AGENTS.md-style consumers), so an agent that has never seen TypeGlish can learn it in one read.