Merge pull request #363 from rest-sh/blog

docs: add Restish blog

Author: danielgtaylor

.agents/skills/rsh-docs/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: rsh-docs
-description: Documentation writer and maintainer
+description: Write and maintain Restish documentation, blog posts, release announcements, tutorials, recipes, and user-facing product explanations.
 ---
 
 # Restish Documentation
 
-You write and maintain Restish documentation. Help users succeed with the CLI, and help maintainers preserve design intent. Docs are part of the product, not release-note filler or a wrapper around implementation details.
+You write and maintain Restish documentation and product writing. Help users succeed with the CLI, and help maintainers preserve design intent. Docs and posts are part of the product, not release-note filler or a wrapper around implementation details.
 
 ## Scope
 
-Maintain user docs in `site/`, design docs in `docs/design/`, user-facing Markdown elsewhere, examples, tutorials, recipes, plugin docs, and Go doc comments for exported APIs.
+Maintain user docs in `site/`, blog posts in `site/content/en/blog/`, design docs in `docs/design/`, user-facing Markdown elsewhere, examples, tutorials, recipes, plugin docs, and Go doc comments for exported APIs.
 
 When user-visible behavior changes, update user docs. When architecture or subsystem behavior changes significantly, update or add a design doc.
 
@@ -23,6 +23,7 @@ Choose one primary mode before writing:
 - Reference: complete factual lookup; terse, predictable, example-backed.
 - Troubleshooting: symptom, cause, confirm, fix, prevention.
 - Design doc: why the system is shaped this way; alternatives and consequences.
+- Blog post or announcement: product story, release context, technical idea, or design rationale; narrative entry point backed by concrete Restish behavior.
 
 Do not blur modes casually. If reference needs context, link to a guide. If a design doc changes user behavior, write the user-facing explanation too.
 
@@ -125,6 +126,48 @@ Config reference: include scope, precedence, file location, fields, types, defau
 
 Troubleshooting: repeat the shape `Symptom`, `Likely cause`, `How to confirm`, `Fix`, `Prevention`, `Related docs`. Good topics include auth failures, OpenAPI loading/cache, content negotiation, pagination, shorthand parsing, plugin discovery, and output formatting.
 
+Blog post or announcement: lead with the user problem, product change, or technical bet. Keep the narrative grounded in examples users can try. Use the post to create interest and explain why the work matters, then route exact syntax and long-lived procedures to docs pages.
+
+## Blog Posts And Announcements
+
+Use blog posts for release stories, API tooling ideas, OpenAPI/CLI design notes,
+automation patterns, plugin/MCP stories, and deeper product decisions. Blog
+posts can be warmer and more narrative than reference docs, but they must stay
+technically specific and useful.
+
+General notes for blog posts:
+
+- Reintroduce the project without assuming readers know older posts.
+- State what stayed familiar before explaining what changed.
+- Frame comparisons generously: `curl`, Postman, SDKs, and Swagger UI all have
+  valid jobs; Restish owns the shell-native, API-aware workflow between them.
+- Keep product vocabulary explicit. Command naming, stdout/stderr behavior,
+  auth placement, pagination, and plugin boundaries are user-facing design.
+- Put runnable `restish-example` shortcodes near the claims they support.
+- Use plain fenced commands when setup is local-only or not suitable for the
+  browser preview.
+- Prefer public `api.rest.sh` examples and call out when the browser preview
+  has built-in API mappings that differ from local setup.
+- Include a concise "try it locally" section with install, first request, API
+  connect, and 3-5 durable next links.
+- Use front matter consistently: `title`, `linkTitle`, `date`, `author`,
+  `description`, `canonical_url`, `categories`, and `tags`.
+
+Good blog shape:
+
+1. Hook: name the user pain, product change, or timely technical idea.
+2. Thesis: say where Restish fits and what the reader will learn.
+3. Concrete path: show direct request, generated API command, output/filtering,
+   auth, pagination, plugin, or MCP behavior as relevant.
+4. Why it matters: explain tradeoffs, compatibility, security, or design
+   reasoning without turning the post into a design doc.
+5. Try it: include local install or upgrade steps and link to maintained docs.
+
+Avoid turning posts into vague marketing copy. Avoid dunking on adjacent tools.
+Avoid making blog posts the only source for exact commands, migration steps, or
+security-sensitive behavior; link to durable docs and update those docs when the
+post reveals a gap.
+
 ## Plugin Docs
 
 Always separate operator docs from author docs. Operators need install/configure/run/verify/debug. Authors need contract, inputs/outputs, lifecycle, testing, compatibility, packaging, and distribution. Do not make operators read authoring internals to use a plugin.
@@ -167,4 +210,7 @@ After meaningful site changes, run:
 hugo --source site --quiet
 ```
 
+For blog changes that affect social cards, run `npm run social-images` from
+`site/` or `npm run build` if dependencies are available.
+
 Also verify new links, check examples against current CLI behavior, grep touched docs for stale `api.example.com` placeholders and leftover `Source material:` sections, and prefer examples that can later be validated against `api.rest.sh` or promoted into tests.

.gitignore

@@ -1,4 +1,4 @@
-/.DS_Store
+.DS_Store
 
 # Local build outputs from `go build ./cmd/...`.
 /restish
@@ -15,6 +15,7 @@
 /refactor.md
 /testing.md
 /test-findings.md
+/blog.md
 
 # Local Codex skill installs.
 /skills-lock.json

README.md

@@ -44,7 +44,7 @@ Andy Warhol mural in Miami gif     /images/gif
 Use Homebrew for the easiest managed install on macOS:
 
 ```bash
-brew install rest-sh/tap/restish
+brew install restish
 restish --version
 ```
 

docs/release-packaging.md

@@ -35,9 +35,15 @@ older version such as `0.21.2`.
 GoReleaser injects the tag version into
 `github.com/rest-sh/restish/v2/internal/cli.Version`.
 
-## Homebrew Tap
+## Homebrew
 
-The public tap is:
+The primary Homebrew install path for the current v2 CLI is Homebrew core:
+
+```bash
+brew install restish
+```
+
+The public tap still exists for legacy and plugin formulae:
 
 ```text
 rest-sh/tap
@@ -49,28 +55,29 @@ The GitHub repository backing that tap must be named:
 rest-sh/homebrew-tap
 ```
 
-Stable v2 releases update the main formula:
+Stable v2 releases should update the Homebrew core `restish` formula. After
+publishing, verify the core formula installs the current v2 binary:
 
 ```bash
-brew install rest-sh/tap/restish
+brew install restish
+restish --version
+restish api.rest.sh/
 ```
 
-The tap also keeps a separate `restish@1` formula for the last v1 release. That
-formula is intentionally keg-only so it can coexist with the current `restish`
-formula without fighting for the same linked executable.
+The tap keeps a separate `restish@1` formula for the last v1 release. That
+formula is intentionally keg-only so it can coexist with the current core
+`restish` formula without fighting for the same linked executable.
 
 ```bash
 brew install rest-sh/tap/restish@1
 ```
 
 The release workflow uses the existing Restish Releaser GitHub App secrets
 (`RELEASER_APP_ID` and `RELEASER_APP_PRIVATE_KEY`) to mint a short-lived token
-with access to `rest-sh/homebrew-tap`. GoReleaser uses it to update v2 formulae,
-and the workflow seeds the v1 formula from `packaging/homebrew/restish@1.rb`.
-
-Do not use unqualified `brew install restish` for v2 verification until the
-tap/core state is checked. The documented user path is the official tap:
-`brew install rest-sh/tap/restish`.
+with access to `rest-sh/homebrew-tap`. The workflow seeds the v1 formula from
+`packaging/homebrew/restish@1.rb` and updates first-party plugin formulae in the
+tap. Do not advertise `rest-sh/tap/restish` as the normal v2 install path while
+Homebrew core is current.
 
 ## mise
 

site/README.md

@@ -25,7 +25,8 @@ npm run build
 
 ## Notes
 
-- Content lives under `content/en/docs/`.
+- Documentation content lives under `content/en/docs/`.
+- Blog content lives under `content/en/blog/`.
 - The theme is provided through Hugo Modules.
 - Social preview images are generated into `static/images/social/` before
   Hugo runs. That directory is ignored because CI regenerates it for deploys.