@fernforge/alchemy - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

package.json

 {
   "name": "@fernforge/alchemy",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn AI prose into human-quality writing. A drop-in ruleset that tells your coding agent how to write docs, READMEs, commits, and replies without the tell-tale LLM patterns.",
@@ -19,5 +19,13 @@ "bin": {
     "llm",
+    "ai-writing",
     "writing",
+    "writing-assistant",
+    "technical-writing",
     "prose",
     "humanize",
+    "humanize-ai",
+    "documentation",
+    "readme",
+    "commit-messages",
+    "coding-agent",
     "claude",
@@ -29,3 +37,2 @@ "cursor",
     "style-guide",
-    "ai-detection",
     "rules"
@@ -32,0 +39,0 @@ ],

README.md

@@ -0,67 +1,109 @@
+<p align="center">
+  <img src="./cover.png" alt="Alchemy — write like a human, not an LLM" width="100%">
+</p>
+
 # Alchemy
 
-Turn lead into gold: AI prose into writing that reads like a person wrote it.
+Alchemy is a drop-in ruleset that stops your AI coding agent from writing like an LLM: no em-dash pile-ups, no "not just X, it's Y", no stray *delve*. You add it once, your agent reads it before it writes, and the READMEs, commits, and docs it produces start sounding like a person wrote them.
 
-Hand this ruleset to your coding agent (Claude Code, Cursor, Copilot, any LLM) and the
-docs, READMEs, commit messages, and replies it writes stop carrying the usual generated-text
-tells. You know the ones. The em-dash in every other sentence. "It's not just a tool, it's a
-workflow." The stray *delve* and *robust* and *seamless*. The conclusion that restates the
-intro and adds nothing.
+Turn lead into gold. It's one file, about 1000 tokens, that lives next to your agent's other instructions: [`ALCHEMY.md`](./ALCHEMY.md). Everything else here just gets it into your project.
 
-The whole thing is one file: [`ALCHEMY.md`](./ALCHEMY.md). Everything else just gets it into
-your project.
+## How do I stop my AI from writing like an LLM?
 
-## Install
+Install it in your project and point your agent at it. Pick whichever fits your stack:
 
 ```bash
+# Node / npm
 npx @fernforge/alchemy init
+
+# Python / pip
+pip install alchemy-writing
+alchemy init
 ```
 
-That writes `ALCHEMY.md` and links it from your `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or
-Copilot instructions if you have one. Your agent reads the rules whenever it writes after that.
+`init` writes `ALCHEMY.md` into your project and links it from whatever agent config you already have: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or Copilot instructions. From then on the agent reads the rules as part of its normal context. To print the ruleset to stdout without installing anything:
 
-Just want to read or paste them?
-
 ```bash
-npx @fernforge/alchemy print
+npx @fernforge/alchemy print   # or: alchemy print
 ```
 
-Or copy [`ALCHEMY.md`](./ALCHEMY.md) into wherever your tool reads project instructions. It's
-plain Markdown and tied to no particular agent.
+Prefer to do it by hand? Copy [`ALCHEMY.md`](./ALCHEMY.md) into your repo and reference it from your agent's instruction file. That's the whole mechanism. No service, no API, no account.
 
-## What's in it
+## Before and after
 
-The rules are grounded in what people actually flag as AI writing, not guesses: Wikipedia's
-"Signs of AI writing," the Kobak et al. study measuring which words spiked in research papers
-after ChatGPT, Pangram's phrase-frequency data, and the long-running arguments on Reddit and
-in r/Professors about spotting it.
+Here's the kind of sentence Alchemy catches. Same fact, two ways of saying it:
 
-They cover the banned constructions ("not just X, but Y," the rule-of-three flourish, the
-helpful-assistant outro), the vocabulary that fingerprints LLM text, the punctuation tells led
-by em-dash overuse, vague attribution, and a self-check the agent runs over its own prose
-before handing it back.
+**Before**
 
-One rule sits above the rest: no single word or dash proves anything. The tell is density,
-the same handful of tics clustered together over flat, evenly-weighted text. So the rules
-weight co-occurrence over any one hit, and they never tell you to cut a word that happens to
-be the right one.
+> Redis isn't just a database — it's a powerful, robust caching layer that unlocks the full potential of your entire stack.
 
-This README follows its own rules. If it reads fine, that's the pitch.
+**After**
 
-## Why "Alchemy"
+> Redis is an in-memory store. Put your cache and sessions in it and your database stops being the bottleneck.
 
-Alchemists tried to turn base metal into gold and never managed it. This is the easier
-version of the trick, and it mostly works by subtraction: cutting the padding the model adds
-by default until what's left could pass for human.
+The "before" stacks four tells in one sentence: the "isn't just X, it's Y" non-contrast, the adjective pile (`powerful`, `robust`), the lone dramatic em-dash, and "unlocks the full potential". None of it says what Redis does. The "after" drops all of it and states one concrete thing you can act on. That's the whole move, applied everywhere the agent writes.
 
-The goal was never to beat an AI detector. It's to write something worth reading. Specific,
-uneven, willing to have a point of view. A fooled detector is a side effect.
+## Which LLM tells does it remove?
 
+The concrete ones, by name:
+
+- Empty contrasts: "not just X, it's Y", "it's not about A, it's about B".
+- Staccato trios and rule-of-three padding: "fast, reliable, scalable", "No X. No Y. Just Z."
+- Stacked adjectives standing in for facts: robust, seamless, powerful, comprehensive.
+- Em-dash pile-ups. The real tell is density, so the rule is: use them rarely.
+- Filler vocabulary: delve, leverage, harness, unlock, elevate, tapestry, realm, showcase.
+- Throat-clearing openers ("In today's fast-paced world", "At its core") and recap closers ("In conclusion", "Ultimately").
+- Restating the prompt before answering it.
+
+The fix is never a synonym swap. It's replacing the vague word with a specific fact: not "robust" but "handles 10k req/sec". The rules push the agent toward the fact.
+
+The principle underneath: no single word proves a machine wrote something. The signal is many of these clustered together over flat, evenly-weighted text. Alchemy targets the clustering, so it thins the tells without stripping a word that's genuinely the right one.
+
+## Use it with Claude, Cursor, or Copilot
+
+`init` detects the config files already in your project and links the ruleset from them, so the same `ALCHEMY.md` works across agents:
+
+- Claude Code / Claude reads it via `CLAUDE.md`.
+- Cursor reads it via `.cursorrules`.
+- Copilot reads it via its instructions file.
+- Any agent that supports `AGENTS.md` picks it up there.
+
+One ruleset, whichever agent you're driving.
+
+## Use it as an MCP server
+
+To serve the rules on demand across every project instead of committing a file to each repo, run Alchemy as an MCP server. Add it to your client config (Claude Desktop, Cursor, Cline):
+
+```json
+{
+  "mcpServers": {
+    "alchemy": { "command": "npx", "args": ["-y", "@fernforge/alchemy-mcp"] }
+  }
+}
+```
+
+It exposes a `get_writing_rules` tool and an `alchemy://rules` resource, so any MCP-aware agent can pull the ruleset when it's about to write prose. See [`mcp/`](./mcp) for details.
+
+## Three ways to install, one ruleset
+
+All three ship the same rules from the same source, so pick by your toolchain and mix freely:
+
+- npm: `@fernforge/alchemy` — `npx @fernforge/alchemy init`
+- PyPI: `alchemy-writing` — `pip install alchemy-writing`
+- MCP: `@fernforge/alchemy-mcp` — `npx @fernforge/alchemy-mcp`
+
+## Where the rules come from
+
+They're grounded in what people actually flag as AI writing, not guesses: Wikipedia's "Signs of AI writing", the Kobak et al. study measuring which words spiked in research papers after ChatGPT, Pangram's phrase-frequency data, and the long-running arguments on Reddit and in r/Professors about spotting it. It's kept short on purpose: concrete guidance an agent can hold in context, not an essay.
+
+This README follows its own rules. If it reads fine, that's the pitch.
+
 ## Contributing
 
-Found a tic the rules miss? Open an issue or a PR with a real before/after example. Keep it
-concrete. The rules earn their place by being specific, not by being long.
+Found a tell it misses? Open an issue or a PR with a real before-and-after pair. Concrete examples are worth more than new abstract rules.
 
+Edit the root [`ALCHEMY.md`](./ALCHEMY.md) only. The copies under `python/` and `mcp/` are generated from it by `node scripts/sync-rules.mjs`, and CI fails if they drift. The npm, PyPI, and MCP packages publish from GitHub Releases (see [`.github/workflows`](./.github/workflows)).
+
 ## License
 
 MIT

No alert changes

Improved metrics

Total package byte prevSize

15169

23.82%

Number of lines in readme file

110

61.76%

No dependency changes