yamcodes/arkenv/the-voice

The voice

ArkEnv docs sound like turborepo.dev plus the pages already in that register: getting-started, Introduction, Installation, Community, and a framework guide (for example Vite). docs-writer is Gemini CLI boilerplate for mechanics. This skill is the register and the second pass. The second pass cuts chatbot tells after the meat is in. It must not strip why.

Read references/canons.md before rewriting a page. Read references/examples.md when the task is a voice pass (the AI guide is the worked example). Read references/humanize.md for the second pass. Do not run stop-slop or an external humanizer.

What "fix the voice" means

Rewrite how the page sounds. Keep facts, IA, APIs, and deep-link headings unless the user also asked to change those.

Each section needs what, why, and how. Skinny pages fail on what/why ("do this, do that"). Inflated pages fail by dumping internals (marketplace.json, diagnostic field lists) that belong in reference.

A good H2 starts in the reader's world, then what ArkEnv provides. Do not open with "@scope/pkg is the [category noun]" unless the page is API reference.

1. Name the ecosystem thing (plugins, skills) and what it is made of.
2. Say what ArkEnv provides and why.
3. Show the command or snippet.
4. Bullet what it teaches or enables, not only what it runs.

Pick a default path. Fallbacks are "instead," not "or also." Put that fork in a fumadocs <Callout> (usually type="info" with a title), not a body sentence. Match apps/www/content/docs/core-concepts/defining-your-schema.mdx (title="Already on ArkType?"). Use warn / error for risk, not for navigation. Do not use GitHub > [!NOTE] alerts on the docs site.

The page lead is two sentences, product name in both, like Turbo:

Turborepo is designed to work seamlessly with AI coding assistants.

Turborepo provides features that help AI understand your repository

and work more efficiently.

Do not open with commands, "It gives them…", or a feature list. Name the outcome; let H2s name the features. Keep "seamlessly" in this cadence. The second pass must not flatten that lead.

House terms

• Typesafe (one word), not "Type-safe".
• Headings and SEO: "environment variables". Body: "env vars" is fine.
• "Zero runtime dependencies" only for @arkenv/core (peer arktype) and

@arkenv/standard. Never "zero dependencies" for the CLI or plugins.

• Nub is a real Node runner. Do not "correct" it to Bun.
• Address the reader as you. Present tense, contractions, US

English. No "please", no Latin abbreviations in running copy, no anthropomorphism.

Install fences

Commands the reader runs (init, npm install, npx …) use fumadocs package-install fences, not bash. Author npm form only: npx … or npm install …. Never npm i, pnpm add, yarn add, bun add, or nub add in the source. The site tabs the other managers (including Nub as nubx / nub add). See apps/www/content/docs/frameworks/nextjs.mdx and apps/www/lib/package-install-fences.test.ts.

Leave bash for non-install shell (git, curl, file copies) and for Nub-only runner examples that are not package-install tabs. Leave json MCP configs as JSON even if a field is "npx". Prompt fences stay text.

Not this voice

Workflow

1. Load the canons, then the target page.
2. Diagnose: skinny, stuffed, slop, or wrong surface.
3. Rewrite in the Turbo H2 shape. Add why with product facts, not

filler. Do not invent features to add meat.

1. Point at reference for shapes, flags, and APIs.
2. Run references/humanize.md. Cut tells.

Keep the why bullets, the lead, and every claim from step 3.