Merge pull request 'Add docs writing guide' (#1) from docs/humanize-prose into main

README.md

@@ -46,9 +46,15 @@ public-repo checklist below.
 - **No LAN IPs / homelab topology in public docs.** Use placeholders; deploy
   runbooks live in the private ansible repo.
 
+## Docs style
+
+How to write READMEs and guides (voice, headings, no emoji fluff):
+[`docs/writing-docs.md`](docs/writing-docs.md). Cursor agents load the same
+bar via `docs-writing.mdc` in dotfiles.
+
 ## Public-repo checklist (before flipping `private: false`)
 
-- [ ] LICENSE present, README explains what/why/how for an outsider
+- [ ] LICENSE present, README explains what/why/how for an outsider (see docs style)
 - [ ] `rg "10\.0\.10\."` returns nothing
 - [ ] `rg "/Users/"` returns nothing
 - [ ] No real names/addresses/phones except your intentional public persona

docs/writing-docs.md

@@ -0,0 +1,134 @@
+# Writing READMEs and guides
+
+House style for Markdown in Levkin repos. Goal: docs that read like a
+competent human wrote them for another engineer, not like a product page
+or a chatbot reply.
+
+Agents: also follow `~/.cursor/rules/docs-writing.mdc` and the humanizer
+skill when rewriting prose.
+
+## What belongs where
+
+| Doc | Job |
+|-----|-----|
+| `README.md` | What it is, how to run it, where config and deeper docs live |
+| `docs/guides/*.md` | How-to for one task (deploy, upgrade, recover) |
+| `docs/reference/*.md` | Stable facts (URLs, ports, schema, CLI flags) |
+| `AGENTS.md` / `.cursorrules` | Short orientation for agents, not a second README |
+| `CHANGELOG.md` | What changed, by version |
+| Scratch (`*_PLAN`, `*_SUMMARY`, `FIX_*`, `HANDOFF`, `PROGRESS_*`) | Temporary. Archive or delete when done; do not polish as product docs |
+
+Do not paste the same wall of text into README and three guides. Link once.
+
+## README checklist
+
+Every repo README should answer these, in roughly this order:
+
+1. **What** — one or two plain sentences. Name the audience if it is not obvious.
+2. **Status** — active, beta, archived, research-only. Put archived status in a blockquote at the top.
+3. **Run it** — install or `make` entrypoint and one command that works.
+4. **Config** — `.env.example`, Infisical path (`/apps/<repo>`), or vault keys. Never real secrets.
+5. **Pointers** — links to guides; do not duplicate them.
+6. **License** — or say the repo is private / personal.
+
+Add when useful: short architecture sketch, known limits, deploy note
+("ops runbooks live in the ansible repo").
+
+Skip in READMEs: emoji decoration, marketing feature walls, welcome blurbs,
+kanban ceremony, and change-narration ("this was added to replace…").
+
+## Guide checklist
+
+A how-to guide should:
+
+1. State the goal in the first sentence ("Deploy X on LXC Y").
+2. List prerequisites (access, packages, secrets location).
+3. Give ordered steps with copy-pasteable commands.
+4. End with a verify step and what "done" looks like.
+5. Link related runbooks instead of restating them.
+
+One job per guide. Split if you need more than one primary verb.
+
+## Voice and formatting
+
+### Do
+
+- Write in sentence case for headings: `## Getting started`, not `## Getting Started`.
+- Prefer short paragraphs and concrete nouns (paths, hosts, commands).
+- Use tables for env vars, ports, and host inventories.
+- Use fenced code blocks with a language tag when it helps.
+- Prefer `is` / `has` / `runs` over `serves as` / `boasts` / `features`.
+- Keep bold for rare emphasis (a warning, a path). Not for every label.
+
+### Do not
+
+- Decorate headings or bullets with emoji (`🚀`, `✅`, `💡`, …). If a CLI
+  prints emoji, quote that output in a code block; do not restyle the doc around it.
+- Use bold-colon list items as fake headings:
+  `- **Web-Based**: Modern React frontend…` → write a normal sentence or table.
+- Stuff feature lists with adjectives: *state-of-the-art*, *seamless*,
+  *robust*, *powerful*, *comprehensive*, *cutting-edge*, *production-ready*,
+  *unlock*, *leverage*, *delve*, *landscape*, *tapestry*, *testament*.
+- Open with chatbot filler: "Welcome to…", "Here's what you need to know",
+  "Let's dive in", "It is important to note that…".
+- Overuse em dashes. Prefer a period, comma, colon, or parentheses.
+- Title-Case Every Heading Like A Brochure.
+- Invent facts, URLs, version numbers, or "experts say" attributions while editing.
+
+### Examples
+
+Bad:
+
+```markdown
+# 🚀 PunimTag
+
+**Modern Photo Management and Facial Recognition System**
+
+A fast, simple, and modern web application using state-of-the-art DeepFace AI.
+
+## Key Features
+
+- **Web-Based**: Modern React frontend with FastAPI backend
+- **Privacy-First**: All data stored locally, no cloud dependencies
+```
+
+Good:
+
+```markdown
+# PunimTag
+
+Local photo library with face recognition (DeepFace / ArcFace). Admin UI
+(React) and viewer (Next.js) share one monorepo and a PostgreSQL backend.
+
+## Features
+
+- Face detect and match with RetinaFace + ArcFace (or other listed models)
+- Search by person, date, tag, or folder
+- Runs on your machine; no cloud dependency for core data
+```
+
+## Public vs private repos
+
+Public READMEs and guides:
+
+- No LAN IPs, no `10.0.10.x`, no root SSH one-liners.
+- No absolute home paths (`/Users/…`).
+- No other people's PII.
+
+Private homelab docs (ansible, hermes, levkin) may name hosts and IPs.
+Still skip emoji and marketing tone.
+
+## When rewriting existing docs
+
+1. Preserve every real fact (commands, paths, versions, URLs).
+2. Cut fluff; keep the procedure.
+3. Fix formatting to match this guide in the same pass.
+4. Leave code blocks, frontmatter, and link targets intact unless the link is wrong.
+5. Scratch/status files: delete or move under `docs/archive/` rather than
+   "humanizing" a dead plan.
+
+## Related
+
+- Project skeleton: this repo's root `README.md`
+- Hard gates (CI, secrets, LICENSE): `~/.cursor/rules/new-project-standards.mdc`
+- Tone scrub: Cursor skill `humanizer`