Docs: add CONTRIBUTING-docs.md and flesh out README

[Terastar-Paperclip]

Summary

• Adds CONTRIBUTING-docs.md at the repo root — the docs contributing bar so community PRs come in pre-shaped. Covers the Diataxis frame, the docs quality bar (verified commands, dated freshness lines, real diagrams, no abandoned drafts), the PR submission flow and review expectations, and the project voice.
• The defect-pattern section cites real findings from the 2026-05-10 docs-state audit (mixed-mode pages, stale HA UI labels, inconsistent MQTT topic prefixes, unverifiable placeholder configs, link-dump pages, component-only pages, etc.).
• Updates the previously one-line README.md to a real landing — local-dev commands, where pages live, and a pointer to CONTRIBUTING-docs.md.

Why

Until now there was no public bar for what a "good" docs PR looks like and no contributor instructions in the README. The result has been mixed-mode pages, undated freshness, and stale UI screenshots accumulating over time. Once the bar is public, drive-by contributions can hit it.

Test plan

• Markdown rendered in IDE preview — both files read cleanly.
• All internal links resolve to real files (./src/content/docs/..., ./astro.config.mjs, ./.nvmrc, ./src/content/docs/credits.md).
• No content under src/content/docs/ is touched, so no Starlight pages or sidebar entries change.
• Maintainer to confirm the voice and quality-bar items match the project's intent.

Diataxis mode of new content: explanation (CONTRIBUTING-docs.md), reference (README.md).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation contribution guide with writing standards, quality requirements, submission process, and common defects to avoid
  • Expanded README with project description, build and deployment context, local development prerequisites, and contribution guidelines

[coderabbitai]

Warning

Rate limit exceeded

@Terastar-Paperclip has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 53 minutes and 48 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 74c8995f-750f-4b7f-a58f-8b199cfc4bb0

📥 Commits

Reviewing files that changed from the base of the PR and between 9821d4d and 25b4fd5.

📒 Files selected for processing (1)

• CONTRIBUTING-docs.md

Walkthrough

This PR establishes a comprehensive contribution framework for the ESPresense documentation site. The README is expanded to provide project setup and development instructions, while a new CONTRIBUTING-docs.md file specifies the Diataxis-based organizational framework, multi-part quality standards, known defects to avoid, step-by-step PR submission workflow, site writing voice, common contribution patterns, and coordination requirements.

Changes

Documentation and Contribution Guide

Layer / File(s)	Summary
Project Overview and Setup README.md	README expanded with project description, local development prerequisites (Node 22, npm commands), build/deployment context (Astro, Starlight, Cloudflare Pages), repository structure notes, and links to contribution guide and upstream repositories.
Contribution Scope and Quick Start CONTRIBUTING-docs.md	Introduces docs contribution scope for espresense.com, differentiates from code/firmware contributions, and provides a TL;DR checklist covering Diataxis mode selection, firmware verification, freshness lines, and preview commands.
Diataxis Framework and Quality Standards CONTRIBUTING-docs.md	Defines the Diataxis organizational framework ("one mode per page"), summarizes each mode's purpose, and establishes quality bar: verified runnable commands/config, mandatory dated freshness lines, diagram/screenshot hygiene, no abandoned drafts, title/slug/sidebar consistency, and inline source citation hierarchy.
Common Defects and Anti-Patterns CONTRIBUTING-docs.md	Lists recurring defects from docs audit: mixed-mode pages, stale UI labels, inconsistent topic prefixes, non-functional placeholders, link dumps, component-only pages, empty headings, missing freshness lines, and affiliate-link rot, with guidance to fix issues in the same PR.
PR Submission Workflow and Review Expectations CONTRIBUTING-docs.md	Provides end-to-end PR submission instructions: local tooling and dev/preview commands, branching/commit/PR content conventions, review focus areas and cadence, and post-merge deployment and redirect follow-ups.
Writing Voice, Style, and Contribution Shapes CONTRIBUTING-docs.md	Documents the site's writing voice (direct, helpful, occasionally dry, plain talk, second person, short sentences) and describes expected shapes for common contributions: typo fixes, firmware update passes, new how-tos, new integrations, splitting mixed-mode pages, and converting Discussion answers into docs.
Coordination and Licensing CONTRIBUTING-docs.md	Clarifies when pre-discussion coordination is required (sidebar/slug changes, page deletions, unconfirmed firmware behavior, translations) and provides license/credit guidance with a versioned footer line.

Suggested reviewers

• DTTerastar

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the two main changes in the PR: adding CONTRIBUTING-docs.md and expanding README.md, which matches the changeset exactly.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CONTRIBUTING-docs.md`:
- Line 108: Replace the inline code span `` `## ` `` with `` `##` `` and move
any note about the required trailing space outside the backticks so the
backticked code contains no internal trailing space (this resolves MD038);
update the sentence around the heading example in CONTRIBUTING-docs.md where the
code span is used to say e.g. use `##` and then describe that two consecutive
headings with no content between them indicate an empty H2.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5c537d86-6bd3-4472-b39d-f87ab773e60d

📥 Commits

Reviewing files that changed from the base of the PR and between 8774f39 and 9821d4d.

📒 Files selected for processing (2)

• CONTRIBUTING-docs.md
• README.md

[Terastar-Paperclip]

Addressed CodeRabbit's MD038 finding in commit 25b4fd5: removed the internal trailing space from the ## inline code span on line 108 of CONTRIBUTING-docs.md and reworded the surrounding clause so the meaning is unchanged.

Re-requesting CodeRabbit re-scan; @DTTerastar still owns final maintainer review/merge per the auto-assignment.