# TypeGlish docs

> The language reference for TypeGlish - typed English for system prompts - generated from the compiler's own source of truth. Human pages: https://typeglish.dev/docs. Every page below has a Markdown twin: append .md to its URL (the landing page is https://typeglish.dev/docs/index.md). The whole reference in one file: https://typeglish.dev/docs/llms-full.txt. The site around it: https://typeglish.dev/llms.txt

## Start here (agents)
- https://typeglish.dev/docs/reference.md - the agent language reference, byte-for-byte what `npx typeglish reference` prints: a copyable skeleton first, then what counts as a rule, placement, coverage, exit codes
- https://typeglish.dev/docs/quickstart.md - one replayable session: write, review, break, prove, pin, build
- Run it: `npx typeglish review <file>` after every edit (check + score + `test --dry` in one report)

## docs · Getting started
- [TypeGlish documentation](https://typeglish.dev/docs): Write and scale prompts like code — the TypeGlish language, checker, tests, and CLI.
- [Quickstart](https://typeglish.dev/docs/quickstart): Run the TypeGlish CLI with npx, review your first prompt, watch the checker prove a contradiction, and pin the fix with a test — in five minutes.

## docs · Concepts
- [Why typed English](https://typeglish.dev/docs/why-typed-english): A prompt is a program written in untyped prose — TypeGlish gives it a type system.
- [English on top, types underneath](https://typeglish.dev/docs/two-planes): Everything the model reads is prose; the types live underneath, checked then stripped.
- [Sound over clever](https://typeglish.dev/docs/sound-over-clever): The checker only reports a conflict it can prove — never a guess.
- [Errors vs advisories](https://typeglish.dev/docs/errors-advisories): Provable defects block the build; best-practice violations warn and lower the score.
- [Compiled away](https://typeglish.dev/docs/compiled-away): Deterministic conditionals are resolved at build — the model never reads a branch it didn’t take.

## docs · Writing
- [The language at a glance](https://typeglish.dev/docs/language): Every meaning layer of TypeGlish and the one law it enforces — the whole language on a page.
- [Statements](https://typeglish.dev/docs/statements): Every line declares its type — the statement grammar and operators of TypeGlish.
- [Proper English](https://typeglish.dev/docs/grammaticality): The grammaticality net — typo pairs, agreement, and articles, convicted on seat evidence with one-edit repairs.
- [Declarations & structure](https://typeglish.dev/docs/declarations): Binding names with the copula, and the section/tag structure of a prompt.
- [Modality](https://typeglish.dev/docs/modality): MUST, NEVER, SHOULD, MAY — how TypeGlish grades rule strength and what the checker enforces.
- [Quantity](https://typeglish.dev/docs/quantity): The quantifier square — all, some, none, only, most — and the contradictions it proves.
- [Frequency](https://typeglish.dev/docs/frequency): ALWAYS, NEVER, sometimes, usually, rarely — the quantifier square over occasions.
- [Definiteness](https://typeglish.dev/docs/definiteness): How “the X is …” names exactly one X and declares that unique object.
- [Possession](https://typeglish.dev/docs/possession): Every English spelling of owner.property = value, folded to one checkable fact.
- [Order](https://typeglish.dev/docs/order): Comparative, temporal, and process orderings — cycles, only-gates, and guard priority.
- [Time](https://typeglish.dev/docs/time): The nouns of time — clocks, dates, years, unix stamps, durations — and the interval proofs over them.
- [Money](https://typeglish.dev/docs/money): The currency catalog, the money token, and the interval proofs over money slots.
- [Plurality](https://typeglish.dev/docs/plurality): The number inheritance law: what a noun's form claims, and the exactness of counting.
- [Directness](https://typeglish.dev/docs/directness): Explicit vs implicit: the encoded doer, the resolved pointer, and the five advisories.
- [Temporal](https://typeglish.dev/docs/temporal): The adverbs of time — immediately, wait, eventually — and the delay bounds they prove.
- [Vocabulary](https://typeglish.dev/docs/vocabulary): The visibility net — an unknown word in a claim is a loud, fixable error, never a silent miss.
- [References & literals](https://typeglish.dev/docs/references): Pointers (@{var}, @[tool], @<section>) and literal zones the checker holds verbatim.
- [Types](https://typeglish.dev/docs/types): The machine-plane type grammar for tool params and required variables.
- [Control flow](https://typeglish.dev/docs/control-flow): Deterministic $IF / $SWITCH chains the compiler resolves, and prose conditionals the model weighs.
- [Character set](https://typeglish.dev/docs/charset): TypeGlish is plain ASCII — the checker names the rewrite for anything else.

## docs · Testing
- [Tests & examples](https://typeglish.dev/docs/tests-examples): $TEST blocks that prove rules, $EXAMPLE few-shots, and the comment syntax.

## docs · Compiling
- [Diagnostics](https://typeglish.dev/docs/diagnostics): Every checker code — what it proves, its severity, and whether it blocks the build.
- [Configuration](https://typeglish.dev/docs/config): $-command directives and the project glish.tgc config.

## docs · Optimizing
- [TG score](https://typeglish.dev/docs/score): The deterministic prompt-quality score — eight facets (nine with the advisory density tier) across two planes.

## best-practices · Overview
- [Best practices](https://typeglish.dev/docs/best-practices): How to work with TypeGlish — the systems, conventions, and workflows that keep a prompt codebase honest.

## best-practices · Writing TypeGlish
- [Grade rules by force](https://typeglish.dev/docs/bp-grade): MUST / SHOULD / NEVER — grade every rule by how much it matters, and let the checker prove the hard ones can’t contradict.
- [Be specific & measurable](https://typeglish.dev/docs/bp-specific): Replace vague adjectives with bounds the model — and the checker — can act on.
- [State each fact once](https://typeglish.dev/docs/bp-once): One source of truth per rule — the checker proves you don’t contradict yourself.
- [Show, don’t tell](https://typeglish.dev/docs/bp-examples): Pin the shape of a good answer with $EXAMPLE few-shots instead of describing it.
- [Anatomy of a prompt](https://typeglish.dev/docs/bp-anatomy): Sections, prose blocks vs typed lines, and the order that reads like a brief.
- [Annotate & comment](https://typeglish.dev/docs/bp-annotate): Keep the **why** in the source and out of the model — @@ doc-notes vs // comments.
- [Modularize with $IMPORT](https://typeglish.dev/docs/bp-modularize): Split large prompts, share snippets, and let the compiler catch cycles and missing anchors.
- [Type tools & variables](https://typeglish.dev/docs/bp-types): Give tool params and required variables a type — the one grammar that keeps machine-plane values honest.

## best-practices · Customizing the compiler
- [The compiler is the gate](https://typeglish.dev/docs/bp-gate): You decide what “good” means; the compiler enforces it on every prompt — yours or an agent’s.
- [Anatomy of glish.tgc](https://typeglish.dev/docs/bp-glishtgc): The project config file: where it lives, how it’s found, and what it sets.
- [Set the quality bar](https://typeglish.dev/docs/bp-quality-bar): Score floors, required tests, and which findings are allowed to block.
- [Add project rules](https://typeglish.dev/docs/bp-project-rules): Cross-field requirements, a strictness policy, and house vocabulary the whole team shares.
- [Models & services](https://typeglish.dev/docs/bp-models-services): Set the model, its transport service, and the defaults every prompt compiles against.

## best-practices · AI agents writing prompts
- [Why the gate matters for agents](https://typeglish.dev/docs/bp-agents): AI writes prompts fast and fluently — and sometimes confidently wrong. The compiler is the guardrail.
- [Claude Code](https://typeglish.dev/docs/bp-claude-code): The plugin: a skill, a check hook on every edit, and a deploy gate on every push.
- [Codex, Cursor and other IDEs](https://typeglish.dev/docs/bp-ide): The MCP head and the check-hook pattern — wire the gate into any agent runner.
- [Prompt the agent to write good TG](https://typeglish.dev/docs/bp-agent-prompt): Give it the grammar, and ask for the conventions the compiler rewards.
- [Close the loop](https://typeglish.dev/docs/bp-agent-loop): Write → check → fix → build → verify. The agent runs the cycle; the gate seals the end.

## best-practices · Testing & evaluation
- [Pin every rule with $TEST](https://typeglish.dev/docs/bp-test): One test per obligation — a rule the model can pass or fail, not just read.
- [Cover the rules that matter](https://typeglish.dev/docs/bp-coverage): Test the obligations whose failure costs you — and let the checker name the ones still bare.
- [Dry vs live runs](https://typeglish.dev/docs/bp-dryrun): Two ways to run a suite: offline validation on every change, real model behavior when it counts.

## best-practices · Integrating with CI
- [Gate on check](https://typeglish.dev/docs/bp-ci-check): Make a blocking error fail the build — the one gate no prompt gets past.
- [Gate on score](https://typeglish.dev/docs/bp-ci-score): Set a quality floor and fail below it — the grade becomes a merge requirement.
- [Run tests in CI](https://typeglish.dev/docs/bp-ci-test): Dry on every PR, live on a schedule — coverage cheap, behavior proven.
- [Keep generated prompts fresh](https://typeglish.dev/docs/bp-ci-fresh): Re-build in CI and diff — a stale artifact fails the job.

## best-practices · Working with Git
- [Source vs artifact](https://typeglish.dev/docs/bp-git-source): Commit the .tg and its build; deploy the artifact, never the source.
- [Review English diffs](https://typeglish.dev/docs/bp-git-review): A prompt diff reads like prose — review it like prose, and watch the score move.
- [Release & provenance](https://typeglish.dev/docs/bp-git-release): Tag the release, and let the manifest prove which source built which prompt.
- [The deploy gate](https://typeglish.dev/docs/bp-git-deploygate): Hash-verify a prompt push against the manifest — nothing un-built ships.

## best-practices · Optimizing cost
- [Check & score offline](https://typeglish.dev/docs/bp-cost-offline): The whole correctness-and-quality loop runs with zero API calls.
- [Proof vs judge tiers](https://typeglish.dev/docs/bp-cost-tiers): Deterministic proofs are free; the LLM judge costs — and it’s off by default.
- [Spend fewer tokens](https://typeglish.dev/docs/bp-cost-tokens): A denser prompt is a cheaper prompt — every token ships on every call.

## best-practices · Model switches
- [Write once, compile per model](https://typeglish.dev/docs/bp-switch): One generic source; the compiler resolves the conditionals at build and aims the prompt at one target.
- [Target a model set](https://typeglish.dev/docs/bp-model-set): One source, one build per target — each run resolves the switches and writes its own artifact.
- [What to branch](https://typeglish.dev/docs/bp-branch): Branch the few things a target genuinely needs differently; keep everything else shared.
- [Configure & test across the set](https://typeglish.dev/docs/bp-model-test): Set each target with $CONFIG model, then re-run the $TEST suite per model — behavior is model-specific.

## best-practices · Team & tooling
- [Share config via glish.tgc](https://typeglish.dev/docs/bp-team-config): A project glish.tgc gives every .tg the same target, the same score floor, and the same house rules.
- [Editor setup](https://typeglish.dev/docs/bp-editor): The LSP in VS Code and on the web, the live ✓ compiles badge, and the zero-install playground.
- [Conventions & ownership](https://typeglish.dev/docs/bp-conventions): Naming, one-owner-per-section, and onboarding a teammate to the gate instead of a style doc.

## cookbook · Overview
- [Cookbook](https://typeglish.dev/docs/cookbook): Runnable TypeGlish recipes — copy, check, score, ship.

## cookbook · From prose to typed
- [Convert a prose prompt to typed rules](https://typeglish.dev/docs/recipe-prose-to-typed): A vibes prompt ("be helpful but never overpromise") hides a contradiction the model resolves differently every call.
- [Split a wall of text into sections](https://typeglish.dev/docs/recipe-sections-and-tags): One undifferentiated block gives the model no structure to follow, so rules blur together and edits are hard to place.

## cookbook · Rules that hold
- [Scope two rules so they can't contradict](https://typeglish.dev/docs/recipe-scope-contradiction): Two rules fire on the same action and demand opposites, so the model resolves it differently every conversation.
- [Make a vague rule checkable](https://typeglish.dev/docs/recipe-make-it-checkable): "Be concise and helpful" cannot be graded, tested, or enforced — the checker cannot see a rule in it.
- [State each fact once](https://typeglish.dev/docs/recipe-say-it-once): The same rule appears twice (or a broad rule already covers a narrow one), so an edit to one copy drifts out of sync with the other.
- [Retire a rule that can never fire](https://typeglish.dev/docs/recipe-retire-dead-rule): A rule whose IF-condition can never hold does nothing, but it still reads as policy, so it hides that the real case is unhandled.
- [Grade rules by force](https://typeglish.dev/docs/recipe-grade-by-force): Flat "do X" prose gives the model no priority, so a hard safety rule and a soft default read as equally negotiable.

## cookbook · Conditionals & branching
- [Compile one prompt per model](https://typeglish.dev/docs/recipe-switch-per-model): A frontier model wants a terse instruction; a small model needs the steps spelled out, but you do not want to fork the file.
- [Branch behavior with $IF / $ELSE](https://typeglish.dev/docs/recipe-if-else-branch): The same task needs a different response depending on an input, and one flat instruction cannot say "do this here, that there."
- [Cover every case with $SWITCH ON](https://typeglish.dev/docs/recipe-switch-exhaustive): A branch that forgets a case leaves the model to improvise the one you missed, and the gap ships silently.

## cookbook · Tools, types & variables
- [Require a typed input variable](https://typeglish.dev/docs/recipe-require-variable): The prompt assumes a value like tier or order id that was never declared, so nothing says what it is or constrains what gets filled in.
- [Type a tool's parameters](https://typeglish.dev/docs/recipe-type-tool-params): An untyped tool call lets the model pass anything, so a bad enum value or a missing field only surfaces at the API, mid-conversation.
- [Configure the model with $CONFIG](https://typeglish.dev/docs/recipe-config-model): The prompt never says which model or transport it targets, so the same file silently runs on a different model, or none, depending on the runtime.

## cookbook · Prove it
- [Pin behavior with $TEST](https://typeglish.dev/docs/recipe-pin-with-test): A rule that matters has no guard against regressions, so a later edit can silently break it and nobody notices.
- [Anchor format with $EXAMPLE](https://typeglish.dev/docs/recipe-anchor-with-example): The model gets the output shape subtly wrong -- a missing field, the wrong order -- because prose describes the format instead of showing it.
- [Cover every rule with a test](https://typeglish.dev/docs/recipe-coverage): Some rules are never exercised by a case, so a green suite is misleading -- you cannot trust what nothing checks.

## cookbook · Fixing diagnostics
- [Fixing diagnostics](https://typeglish.dev/docs/fixing-diagnostics): Every diagnostic code the checker can raise, and the recipe that resolves it.

## cli · Reference
- [Commands](https://typeglish.dev/docs/cli): Every typeglish command and flag.
- [The workflow](https://typeglish.dev/docs/workflow): Author → check → score → test → build → deploy.