aibreze 0.1.0 → 0.1.4

package/README.md

@@ -1,12 +1,17 @@
+<p align="center">
+  <img src="site/static/logo.svg" alt="aiBreze" width="128" />
+</p>
+
 # aiBreze
 
 An installable writing rule set for AI agents.
 
-aiBreze strips the performative, faux-profound register from prose.
+Editorial rules for prose that actually says something instead of just
+sounding like it. AI-assisted or not.
 Written **aiBreze**. npm **`aibreze`**. A spray, not a breeze.
 
-Direct > clever. Clear > profound. Useful > insightful-sounding. No em
-dashes in publishable prose.
+Direct > clever. Clear > profound. Useful > insightful-sounding. Em dashes
+earn their place; most don't.
 
 Spray the prose, not the author. Earn the word.
 
@@ -22,9 +27,9 @@ software does that reliably.
 
 ## What it is
 
-A composable editorial system for agent-generated prose (and for human
-prose in the same register). Markdown you install and point an agent at.
-Not a CLI (yet), not an editor, not a list of "words ChatGPT uses."
+A composable editorial system for agent-generated prose, and for human
+prose in the same register. Markdown you install and point an agent at.
+v1 has no CLI.
 
 ```text
 core.md          shared law (register, bans, cadence, heuristic)
@@ -40,12 +45,11 @@ claims.md        substance first, then voice
 Genre files assume `core.md` and are additive: surface law only, no
 copied bans. Do not fork `core.md`.
 
-The **applicability heuristic** is the load-bearing idea. The problem is
-unearned language, not the dictionary. Earn the word: "transformative"
-is fine if something transformed and you can say from what into what.
+The **applicability heuristic** is the rule. The problem is unearned
+language, not the dictionary. Earn the word: "transformative" is fine
+if something transformed and you can say from what into what.
 "Inflection point" is fine if there was one. Overlay the terms that
-usually pass *here*, with one-line why. The heuristic is the rule; the
-list is not exhaustive.
+usually pass *here*, with one-line why. The list is not exhaustive.
 
 `claims.md` is substance first, voice after. A clean-smelling wrong
 essay is still wrong. Do not polish a lie.
@@ -89,10 +93,9 @@ either way. If the prose smells, spray it.
 
 Adjacent tools tend to be humanizers ("make this sound human"), banned-word
 anti-slop lists, or general style linters (Vale, write-good). This package
-is the layered law: genre surfaces, an applicability heuristic (earn the
-word), claims before cologne, overlays instead of forks, and both
-prevention at draft time and audit after. Authorship is irrelevant. Prose
-quality is the subject.
+layers genre files, an earn-the-word test, claims before voice, and overlays
+instead of forks. Use it while drafting or on a finished pass. Authorship
+is irrelevant. Prose quality is the subject.
 
 ## Use from Node
 
@@ -141,7 +144,9 @@ pnpm site:build
 
 ## Publishing to npm
 
-The maintainer publishes. Agents must not run `npm publish`,
+The maintainer publishes. `pnpm publish` runs a gate first: `pnpm whoami`,
+then `pnpm login` if that fails, then a patch bump if this version is
+already on npm (or behind it). Agents must not run `npm publish`,
 `pnpm publish`, or `yarn npm publish`.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aibreze",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Installable writing rule set for AI agents. Sprays the performative, faux-profound register off prose. Core bans, smell audit, claims review, genre overlays.",
@@ -48,9 +48,10 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "tsc && node --test dist/index.test.js",
+    "test": "tsc && node --test dist/index.test.js dist/publish-gate.test.js",
+    "ship": "pnpm --dir site run ship",
     "site:dev": "pnpm --dir site dev",
     "site:build": "pnpm --dir site run build",
-    "site:deploy": "pnpm --dir site run deploy"
+    "site:deploy": "pnpm --dir site run ship"
   }
 }

package/rules/audit.md

@@ -53,9 +53,11 @@ pass that skips the house bans.
 Hunt every hard ban and cadence tell in `core.md`: escalation formula,
 honest framing, validation+profundity, mechanism inflation, narrative
 theater, genuinely-stacks, dramatic apology, suspense, setup sentences,
-em dashes, triad packing including prefix-repetition, empty marketing
+em-dash furniture, triad packing including prefix-repetition, empty marketing
 vocab, helper theater, signpost openers, mic-drop closers, intensifier
-filler, parallel-zinger density, bold-lead lists. Apply the
+filler, parallel-zinger density, bold-lead lists, riddle labels, cozy
+machinery, operator notes in the brochure, hand-holding the obvious,
+unparseable sentences. Apply the
 corpus-applicability heuristic before rewriting overlay terms. Teaching
 antithesis is allowed only when categories differ, never as
 synonym-escalation. One concrete landing chant is a named exception,
@@ -123,10 +125,6 @@ product names, and words that would get less precise if swapped for
 
 ### Structural extras
 
-- **Em dashes.** Core already bans them in publishable prose. Still flag
-  density and the clause-then-punchline construction as a smell signal
-  (some human writers use them heavily; combined with other tells they
-  are a strong signal).
 - **Emoji as content furniture.** Checkmarks, rockets, and lightbulbs
   doing the work that words or design should do, especially in lists and
   result badges.

package/rules/claims.md

@@ -119,10 +119,12 @@ Only after Passes A-D:
 1. Score AI smell 1-10 with one-paragraph justification (same scale as
    `audit.md`).
 2. Flag hard bans from `core.md`: escalation formula, honest-framing,
-   validation+profundity, narrative theater, em dashes, setup-only
+   validation+profundity, narrative theater, setup-only
    sentences, synonym antithesis, helper theater.
 3. Flag cadence budgets: signpost openers, mic-drop closers, intensifier
-   filler, parallel-zinger density, bold-lead lists.
+   filler, em-dash furniture, parallel-zinger density, bold-lead lists,
+   riddle labels, cozy machinery, operator notes in the brochure,
+   hand-holding the obvious, unparseable sentences.
 4. Apply **corpus-applicability**: do not "correct" overlay terms when
    they are structural.
 5. Quote lines to **protect** (distinctive human voice).

package/rules/core.md

@@ -42,8 +42,9 @@ across with minimal ceremony.
 Direct > clever. Clear > profound. Useful > insightful-sounding.
 
 Contractions. Short sentences mixed with longer ones. Point first, support
-second. Concrete over abstract. No em dashes in publishable prose (commas,
-periods, or parentheses).
+second. Concrete over abstract. Em dashes earn their place, like everything
+else, and most don't. A comma, period, or colon usually does the job with
+less drama.
 
 Pronouns are a project decision (I / we / you). Pick one per surface and
 hold it. Do not let an agent default to corporate "we" on a personal essay,
@@ -154,7 +155,6 @@ Do not withhold the answer while building drama. Answer first.
 
 ### Also still banned
 
-- Em dashes in publishable prose
 - Alliterative triads and stacked-negation chants, except protected
   maxims the overlay names, or **one concrete chant a genre file
   explicitly allows** (landing). **Prefix-repetition triads count**
@@ -184,11 +184,42 @@ not single instances.
 - **Intensifier repetition.** "actually," "whole," "real," "very"
   recurring as filler. Keep only where the word marks a true contrast;
   cut the padding uses.
+- **Em-dash furniture.** Clause-then-punchline, a dash in every heading,
+  or stacks. One earned dash is not a finding. Density plus other tells
+  is. Do not treat the mark as an AI tell to erase.
 - **Parallel-zinger density.** Chiasmus and mirror sentences ("X is a
   performance. Y is a practice.") are spice. Track the count per piece;
   protect native pairs, trim assistant-added ones first.
 - **Bold-lead lists.** Every bullet "**Label.** Explanation" is a
   template when the whole piece does it.
+- **Riddle labels.** A bold lead-in or heading that is an aphorism the
+  reader can only decode after reading the body: "**Names you actually
+  say.**" over a paragraph about custom vocabulary. Core already bans the
+  setup sentence that announces the next sentence; this is the same waste
+  in reverse, withholding instead of announcing. Test: cover the body and
+  read the label alone. If it does not say which thing this is, name the
+  thing. The aphorism can go in the prose if it earns a place there.
+- **Cozy machinery.** Infrastructure written the way a fond craftsman
+  would talk: the model is "asleep," a worker stays "warm," heavy jobs go
+  to a "quieter" box, "the mesh is the door." Terms of art pass the
+  applicability heuristic (warm cache, cold start, daemon), and one idiom
+  is not a finding. The tell is the register standing in for a fact the
+  writer already has: "asleep" covers suspended, unreachable, and
+  misconfigured at once, so it tells the reader less than "unreachable"
+  would. Keep it where the machine literally sleeps.
+- **Operator notes in the brochure.** Recovery commands, internal folder
+  names, settle timers, gitignore facts, and "doctor and /health run the
+  same probes" listed as what the product is good at. The tell is
+  *placement*, not the fact. A recovery CLI belongs under Run. A Syncthing
+  wait belongs next to Syncthing. Test: would you say this first to a
+  friend who asked what it does? If not, it is later, or not at all.
+- **Hand-holding the obvious.** "config.json is gitignored." One trap
+  warning is fine. Stating what a competent reader already knows, in the
+  voice of a tour guide, is the tell.
+- **Unparseable sentence.** A finished-sounding line the reader cannot
+  repeat: "This is meant to live on a desktop you already leave on."
+  Related to riddle labels, but at sentence level. Rewrite until a smart
+  friend can say it back.
 
 ---
 
@@ -197,7 +228,7 @@ not single instances.
 | Mode | Extra watch |
 | --- | --- |
 | **Agent chat** | Honest framing, validation theater, suspense, dramatic apology, genuinely-stack, helper theater |
-| **Drafts / posts / pages** | Escalation formula, insight-labeling without evidence, setup sentences, em dashes, triad packing |
+| **Drafts / posts / pages** | Escalation formula, insight-labeling without evidence, setup sentences, riddle labels, cozy machinery, operator notes in the brochure, hand-holding, unparseable sentences, em-dash furniture, triad packing |
 
 The table is extra watch, not a partition. Chat theater infects drafts.
 Publish tells show up in chat.
@@ -240,6 +271,29 @@ Good: Just state the idea.
 Bad: "Brain — the model plus the loop."  
 Good: "Brain: the model plus the loop."
 
+**Riddle label**  
+Bad: "**Names you actually say.** `promptTerms` seeds the decoder."  
+Good: "**Custom vocabulary.** `promptTerms` seeds the decoder."
+
+**Cozy machinery**  
+Bad: "If the cleanup model is asleep, you still get raw text."  
+Good: "If the cleanup model is unreachable, you still get raw text."  
+(Still fine: "the laptop was asleep," when it was.)
+
+**Operator notes in the brochure**  
+Bad: "**Two settle timers.** Watched folders wait 30 minutes." as the
+first item under "What it is good at."  
+Good: Mention the wait next to Syncthing. Lead the feature list with
+what a friend would hear first.
+
+**Hand-holding**  
+Bad: "`config.json` is gitignored." after `cp config.example.json`.  
+Good: Omit it. They already copied the example.
+
+**Unparseable sentence**  
+Bad: "This is meant to live on a desktop you already leave on."  
+Good: "Run it on a computer you leave turned on."
+
 ---
 
 ## How to audit

package/rules/cursor.mdc

@@ -17,7 +17,7 @@ not copy genre law into this file.
 ## Target
 
 Sharp, slightly tired colleague. Direct > clever. Clear > profound.
-Useful > insightful-sounding. No em dashes in publishable prose.
+Useful > insightful-sounding. Em dashes earn their place; most don't.
 Judge the sentence, not the byline. Spray the prose, not the author.
 Earn the word.
 
@@ -51,8 +51,23 @@ Earn the word.
 - Mic-drop closer fragments ending every section.
 - Intensifier filler: "actually / whole / real / very" where no contrast
   is marked.
+- Em-dash furniture: stacks and unearned drama. One earned dash is not a
+  finding.
 - Parallel-zinger (chiasmus) density; trim assistant-added ones first.
 - Bold-lead lists on every bullet.
+- Riddle labels: a bold lead-in or heading the reader can only decode
+  after the body ("**Names you actually say.**" over custom vocabulary).
+  Name the thing instead.
+- Cozy machinery: the model is "asleep," the worker stays "warm," a
+  "quieter" box. Terms of art pass; the tell is register replacing a fact
+  you have ("unreachable" says more than "asleep").
+- Operator notes in the brochure: recovery CLIs, internal folder names,
+  settle timers, gitignore facts listed as what the product is good at.
+  Placement is the tell. Would you say this first to a friend?
+- Hand-holding the obvious: "config.json is gitignored" after they
+  already copied the example.
+- Unparseable sentence: a finished-sounding line the reader cannot
+  repeat ("a desktop you already leave on").
 
 ## Corpus-applicability carve-out (standing rule)
 

package/rules/landing.md

@@ -11,8 +11,8 @@ brand-metaphor budget.
 
 ## Voice extras (on top of core)
 
-Core already has the register: contractions, mixed sentence length, no
-em dashes, concrete over abstract. On a page, also:
+Core already has the register: contractions, mixed sentence length,
+concrete over abstract. On a page, also:
 
 1. **Not a salesperson, not a professor.** Punchy hook, then substance.
 2. **Practical over aspirational.** Hours saved and bottlenecks fixed,
@@ -45,9 +45,8 @@ Everything else in this file works under either choice.
 
 ### Mechanical
 
-- Em dashes in `<title>` and meta description. Core already bans them in
-  body copy; pages hide them in chrome. Zero tolerance including
-  metadata.
+- Unearned em dashes in `<title>` and meta description. Chrome is a bad
+  place for the drama; a comma or colon almost always does it.
 - Emoji as content (result badges, pain-list icons). Replace with type
   or cut.
 - Title Case On Every Card. Sentence case reads more human.
@@ -107,8 +106,8 @@ page.** The rest go to plain language.
 
 A revised page passes when:
 
-1. Zero em dashes in `<title>` and meta description (body already
-   covered by core).
+1. Unearned em dashes in `<title>` and meta description; prefer a comma
+   or colon unless the dash earns the drama.
 2. Pronoun decision made and applied consistently; builder claims
    aligned to it.
 3. Max 2 "not X, but Y" constructions, max 1 triadic negation chant, max