docs: ship Homebrew/Scoop, add task index, polish for usefulness

[wavyx]

Completes both follow-up tracks from the docs quality audit.

Distribution (now live + verified)

• Homebrew formula pushed to wavyx/homebrew-tap, Scoop manifest to wavyx/scoop-pdcli. brew install wavyx/tap/pdcli verified end-to-end on macOS incl. --jq (formula wires JQ_PATH → Homebrew jq). Docs flipped coming-soon → working.
• release.yml dist job auto-publishes both on each stable release — needs a TAP_TOKEN PAT secret (contents:write on both tap repos); no-ops without it.

Usefulness / engagement

• New "Which command do I use?" task-to-command index (biggest discoverability gap); Start-here reordered.
• agents.mdx capability tour → scannable grouped subsections; mcp.mdx verify-note + payoff vignette.
• troubleshooting.mdx: the npm-11 jq-binary trap + 429/400/422 entries.
• analytics.mdx orientation table + asides; Home.astro self-hosted demo + clickable cards; ci dedup + small quick-wins.

Astro build green (30 pages). No terminal-mock outputs altered.

Action needed from you: add the TAP_TOKEN fine-grained PAT secret to enable auto-publish of brew/scoop on future releases.

https://claude.ai/code/session_018dRMUUj9vpKp3tqKQFsvE9

Greptile Summary

This PR ships Homebrew and Scoop distribution (previously marked "coming soon"), adds automation for publishing both on each stable release via a new dist workflow job, and makes a broad documentation pass — a new task-to-command index, restructured agent subsections, an analytics orientation table, expanded troubleshooting entries, and an SVG noscript demo fallback on the home page.

• New dist CI job (release.yml): clones each tap repo with a TAP_TOKEN PAT, commits the generated formula/manifest, and gracefully no-ops when the secret is absent or a prerelease tag is detected.
• formula_opt_bin("jq")/"jq" (gen-dist.mjs): the changed Homebrew DSL call is valid and preferred (it avoids instantiating the full formula object), confirmed against Homebrew source.
• tasks.mdx introduces a lookup example using --by email=jane@acme.com which conflicts with the --field/--value flags shown in agents.mdx — one is wrong and will produce a CLI error for users who copy it.

Confidence Score: 4/5

Safe to merge with the lookup flag discrepancy addressed; everything else is documentation polish and well-tested infrastructure.

The tasks.mdx task index shows pdcli lookup person --by email=jane@acme.com while agents.mdx shows --field email --value … for the same command — these can't both be right, and whichever one is wrong will produce an immediate CLI error for users who copy it. All other changes are straightforward and correct.

website/src/content/docs/start/tasks.mdx — the lookup command example needs to match the actual flag interface documented in agents.mdx.

Important Files Changed

Filename	Overview
.github/workflows/release.yml	Adds a new dist job that publishes Homebrew and Scoop packages on stable releases; gracefully no-ops when TAP_TOKEN is absent; push_file embeds the token in a git clone URL (standard CI pattern).
scripts/gen-dist.mjs	Replaces Formula["jq"].opt_bin/"jq" with formula_opt_bin("jq")/"jq" — confirmed valid Homebrew DSL (Utils::Path module); the new form is actually preferred for performance.
website/src/content/docs/start/tasks.mdx	New goal-oriented command index; the lookup example uses --by email=jane@acme.com syntax while agents.mdx uses --field email --value … for the same command — one of the two syntaxes is wrong.
website/src/components/Home.astro	Adds href to selectable feature cards, an SVG noscript fallback for the terminal demo, and an invisible link overlay on the demo; all changes are well-formed.
website/src/content/docs/start/distribution.mdx	Removes "coming soon" cautions and updates copy to reflect Homebrew and Scoop channels being live; no issues.
website/src/content/docs/reference/troubleshooting.mdx	Adds three new troubleshooting entries (npm-11 jq-binary trap, 429 rate-limit, and 400/422 bad-request); all accurate and well-linked.
website/src/content/docs/start/agents.mdx	Rewrites the dense capability paragraph into five grouped subsections; the lookup example still uses --field/--value flags which conflicts with tasks.mdx.
website/src/content/docs/guides/analytics.mdx	Adds a "Which command answers what" orientation table and a caution admonition about changelog-mining cost; accurate and useful.
website/src/content/docs/guides/mcp.mdx	Adds a "Verify it is running" section with the startup log line and a practical vignette showing the read-only → write-enabled progression; no issues.
packaging/README.md	Updates the automation section to document the dist job and the TAP_TOKEN requirement; matches the workflow changes accurately.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Tag push v*] --> B[release job\nnpm publish + GitHub Release + tarballs]
    B --> C[docker job\nBuild & push GHCR image]
    B --> D[dist job\nGenerate Homebrew formula + Scoop manifest]
    D --> E{Prerelease?\neg. v1.2.0-rc1}
    E -- Yes --> F[Skip tap publish\nexit 0]
    E -- No --> G{TAP_TOKEN secret\npresent?}
    G -- No --> H[Log warning\nexit 0 — no failure]
    G -- Yes --> I[push_file homebrew-tap\nFormula/pdcli.rb]
    I --> J[push_file scoop-pdcli\nbucket/pdcli.json]
    J --> K[Done — both taps updated]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[Tag push v*] --> B[release job\nnpm publish + GitHub Release + tarballs]
    B --> C[docker job\nBuild & push GHCR image]
    B --> D[dist job\nGenerate Homebrew formula + Scoop manifest]
    D --> E{Prerelease?\neg. v1.2.0-rc1}
    E -- Yes --> F[Skip tap publish\nexit 0]
    E -- No --> G{TAP_TOKEN secret\npresent?}
    G -- No --> H[Log warning\nexit 0 — no failure]
    G -- Yes --> I[push_file homebrew-tap\nFormula/pdcli.rb]
    I --> J[push_file scoop-pdcli\nbucket/pdcli.json]
    J --> K[Done — both taps updated]

Loading

Comments Outside Diff (1)

1. website/src/content/docs/start/tasks.mdx, line 693 (link)

   Lookup flag syntax conflicts with agents.mdx

   This row uses --by email=jane@acme.com, but agents.mdx documents the same command as pdcli lookup person --field email --value …. One of the two syntaxes is wrong, and a user who copies the example from the wrong page will get an immediate CLI error. Please align both pages on whichever flag form the command actually accepts.

   

_{Reviews (1): Last reviewed commit: "docs: ship Homebrew/Scoop, add a task in..." | Re-trigger Greptile}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!