docs: slim README and add docs/ tree for v0.1

[NikolayS]

Summary

Splits the 494-line READMEinto a slim landing page (280 lines) and a flat docs/ tree. Keeps the README focused on what-is-this-why-should-I-care-how-do-I-try-it; moves the long-form material into dedicated files. Resolves the BETTER_DOCS design doc (#49) at v0.1 scope — the full Diátaxis tree with per-quadrant subdirectories is deferred to v1.0 when there is enough content to justify it.

Approach

Dispatched four parallel doc-writer subagents with non-overlapping file ownership, then a style-review pass across all new/changed files, then integration (benchmarks move, docs/README.md index, CLAUDE.md layout pointer, cross-link verification).

What ships

New files under docs/

• docs/tutorial.md (344 lines) — 9-step order-processing walkthrough. Surfaces the ticker teaching moment (empty receive → force_tick + ticker → batch). Exercises send/receive/ack, nack-to-retry, max-retries-to-DLQ, observability, and pg_cron switchover. Verified every SQL snippet against sql/pgque.sql.
• docs/reference.md (475 lines) — per-function reference for the v0.1 default install. Grouped: publishing, consuming, queue management, lifecycle, observability, DLQ, PgQ primitives, trigger helpers, message type, roles, experimental.
• docs/examples.md (85 lines) — short patterns: send-with-type, batch, fan-out, exactly-once, recurring jobs, DLQ inspection. Relocated from the README's "Usage examples" section.
• docs/benchmarks.md (29 lines) — throughput table and methodology. Relocated from the README's "Benchmarks" section.
• docs/README.md (24 lines) — one-page index of the docs/ directory.

Slimmed README.md

• Removes the inlined function reference table (→ docs/reference.md).
• Removes the usage examples section (→ docs/examples.md).
• Collapses Architecture from a 7-bullet list to one paragraph linking to blueprints/SPECx.md and docs/pgq-concepts.md.
• Adds a Docs section near the top with links to each doc.
• Adds a hero-image placeholder under the tagline (for the benchmark visual).
• Fixes style-review findings: PostgreSQL → Postgres in prose (badges, URLs, extension names, and DSN schemes preserved); promotional Just/just removed; psql command-line examples now include --no-psqlrc and PAGER=cat.

Blueprint/config updates

• blueprints/PHASES.md now lists the full v0.1 shipped surface (queue management, observability, PgQ primitives, trigger helpers, roles) — previously claimed only a 9-function minimal list that hadn't kept up with what sql/pgque.sql actually exports.
• CLAUDE.md gets the docs/ tree added to the file organization map, plus PHASES.md and typescript/ entries for accuracy.

Bugs found during the audit (fixed in-place)

• set_queue_config parameter naming — callers pass the short name ('max_retries'), not the full column name ('queue_max_retries'). The function auto-prefixes queue_ internally, so 'queue_max_retries' silently becomes queue_queue_max_retries and hits the allowlist rejection. Tests use the correct form; my own PHASES.md draft and blueprints/SPECx.md:2486 both said the wrong thing. Both fixed.

Drift corrected in the old README's function-reference table

Independently surfaced by the reference writer and tutorial writer:

• status() return type was setof record in the old table; actual is table(component text, status text, detail text).
• send_at was listed under Publishing; it's experimental, not in the default install. Moved to docs/reference.md's experimental section.
• ticker() has three overloads shipped (0-arg, 1-arg, 4-arg external-ticker); only the 0-arg was documented.
• maint() description claimed it does rotation; it skips rotation step 2 (scheduled separately by start()). Clarified.

Not in this PR (intentional)

• The pre-existing Title-Case headings and PostgreSQL-in-prose slips in CLAUDE.md (8 headings + 4 prose instances) — pre-date this PR; fixing them here would balloon scope. Recommend a small separate style cleanup.
• Client library per-file docs (clients/*/README.md) — out of scope for v0.1 core docs.
• Per-quadrant docs/{tutorial,howto,reference,explanation}/ subdirectories — deferred to v1.0 when content justifies it.

Test plan

• Every SQL snippet in docs/tutorial.md verified against sql/pgque.sql.
• Every function entry in docs/reference.md verified against sql/pgque.sql.
• All cross-links resolve (README ↔ docs/ ↔ blueprints/).
• Style-review pass flagged findings; scoped fixes applied.
• CI (docs-only PR, no SQL changes — should be clean).
• make all / benchmark bench rerun is not triggered; no SQL changed.

🤖 Generated with Claude Code