Merge pull request #374 from rest-sh/docs/agents-skills-refresh

docs: refresh AGENTS.md and agent skills for accuracy and CI coverage

Author: danielgtaylor

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

@@ -77,8 +77,29 @@ Use examples that look like real work:
 - Explain intentional placeholders when they might look accidental.
 - Prefer JSONC for config examples when comments clarify fields.
 
+### Command Example Style
+
+These apply to every command example in docs, guides, recipes, and blog posts:
+
+- Prefer shorthand in examples over `jq` or plain JSON when possible.
+- Do not use `get` or `post` in examples when the auto mode is clear (e.g.,
+  `restish api.rest.sh/example` instead of `restish get api.rest.sh/example`).
+- Do not add options for no reason. E.g. `--rsh-no-paginate` when not talking
+  explicitly about pagination, or `--rsh-columns` when the default output is
+  fine. Extra flags complicate commands and make examples harder to read.
+  Avoid `-o lines` unless it significantly improves output readability.
+
 ### Shorthand Examples
 
+`restish-example` shortcode commands are extracted and validated by
+`scripts/check-doc-examples.rb`: CI enforces that each one is a single direct
+`restish` invocation (no pipes, redirects, `;`, `&&`, command substitution, or
+backticks) that parses cleanly with shell word-splitting, and a weekly job
+executes every one live against `api.rest.sh` and fails on non-zero exit.
+Write shortcode examples as commands that actually succeed against the public
+API; use plain fenced code blocks for pipelines, local-only setup, or
+illustrative failures.
+
 Restish shorthand examples should be shell-safe and match how the docs display
 them:
 
@@ -170,14 +191,11 @@ post reveals a gap.
 
 ### Blog Improvement
 
-Whenever you write a new blog post or modify an existing one, spin off a sub-agent to do a review of the changes and suggest improvements, which you should then apply. The review should check for:
+Whenever you write a new blog post or modify an existing one, do a separate review pass of the changes (use a sub-agent if available) and apply the resulting improvements. The review should check for:
 
 1. Clarity: Is the post easy to understand? Are there any ambiguous statements or jargon that could be clarified?
 2. Engagement: Does the post have a compelling hook? Does it maintain the reader's interest throughout?
-3. Accuracy: Are all technical details correct? Are there any factual errors or misleading statements?
-   1. Commands should prefer shorthand in examples over jq or plain JSON when possible.
-   2. Do not use `get` or `post` in examples when the auto mode is clear (e.g., `restish api.rest.sh/example` instead of `restish get api.rest.sh/example`).
-   3. Do not add options for no reason. E.g. `--rsh-no-paginate` when not talking explicitly about pagination, or `--rsh-columns` when the default output is fine. This complicates commands and makes it harder for readers. Another good example is `-o lines` unless it significantly improves readability of the output.
+3. Accuracy: Are all technical details correct? Are there any factual errors or misleading statements? Do all examples follow the Command Example Style rules above?
 4. Structure: Is the post well-organized? Does it have a logical flow from introduction to conclusion? Do the headings make sense (and are they short enough to not wrap for common screen widths)?
 5. Do all the command examples actually make sense? Are they good examples, or could they be improved to better illustrate the point? Are the examples in the right place in the post or should they be moved?
 
@@ -217,13 +235,21 @@ When migrating older docs, track whether material was retired, already migrated,
 
 ## Validation
 
-After meaningful site changes, run:
+After meaningful site changes, run what CI runs:
 
 ```bash
-hugo --source site --quiet
+hugo --source site --quiet          # site builds (quick check)
+npm --prefix site run build        # CI parity: social images + Hugo (npm ci once first)
+scripts/check-doc-examples.rb      # restish-example shortcodes are valid
+scripts/check-doc-links.rb         # internal links resolve
+go run ./cmd/restish-docgen --check # generated regions are not stale
 ```
 
-For blog changes that affect social cards, run `npm run social-images` from
-`site/` or `npm run build` if dependencies are available.
+`npm run social-images` parses front matter across `content/en` and can fail
+independently of Hugo, so run the npm build for blog and front-matter changes
+even when the quick Hugo check passes.
+
+When touching site JavaScript or interactive examples (playground, query
+runner, docs interactions), also run `npm --prefix site test`.
 
 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.

.agents/skills/rsh-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Restish Docs"
+  short_description: "Write and maintain Restish documentation"
+  default_prompt: "Use $rsh-docs to write or update Restish documentation, blog posts, or design docs for a feature or change."

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

@@ -37,28 +37,13 @@ For source-backed rationale and examples from product/UX references and popular
 
 ### 1. Frame The Opportunity
 
-Write the smallest useful product frame before designing commands:
+Before designing commands, write the smallest useful product frame: who the user is (first-time user, daily CLI user, API integrator, plugin operator, plugin author, or maintainer), the job they are doing outside Restish, their current workaround, the pain, the intended outcome, and the evidence (issue text, failing example, repeated support question, code/test signal). If evidence is thin, propose the lightest validation instead of inventing a large feature.
 
-- **User**: Who is this for? First-time user, daily CLI user, API integrator, plugin operator, plugin author, or maintainer?
-- **Job**: What is the user trying to get done outside Restish?
-- **Current workaround**: What command sequence, script, config edit, docs lookup, or mental model do they use today?
-- **Pain**: Is the problem failure, slowness, repeated typing, poor discoverability, unsafe behavior, bad output, weak automation, or missing capability?
-- **Outcome**: What should be easier, safer, faster, or more understandable after the change?
-- **Evidence**: Point to issue text, user report, failing example, design-doc gap, docs search, repeated support question, or code/test signal.
-
-If evidence is thin, propose the lightest validation instead of inventing a large feature.
+Concrete evidence sources for Restish: the v1 issue tracker (`rest-sh/restish` on GitHub — dozens of open issues and PRs represent real user demand), `docs/design/000-restish-v1-baseline.md` for v1 behavior, `docs/design/031-compatibility-and-migration.md` for compatibility promises, and `docs/design/037-v2-command-surface-review.md` for prior command-surface decisions.
 
 ### 2. Classify The Investment
 
-Classify the work so scope and validation match risk:
-
-- **Reliability**: Makes existing behavior more correct, predictable, secure, or recoverable.
-- **Usability**: Makes existing behavior easier to discover, understand, compose, or debug.
-- **Feature**: Adds a new user-visible capability.
-- **Compatibility**: Preserves or improves v1, plugin, OpenAPI, shell, or documented behavior.
-- **Platform**: Improves internal architecture only when it unlocks user-facing reliability, velocity, or simplicity.
-
-Favor reliability and usability improvements when a new feature would deepen existing confusion.
+Classify the work — reliability, usability, feature, compatibility, or platform — so scope and validation match risk. Favor reliability and usability improvements when a new feature would deepen existing confusion. Platform work counts only when it unlocks user-facing reliability, velocity, or simplicity.
 
 ### 3. Shape The Product Bet
 
@@ -141,7 +126,7 @@ Use validation proportional to risk:
 - **Product validation**: Compare against user jobs, known feedback, current docs, and one or two realistic command transcripts.
 - **Usability review**: Run a heuristic pass for status visibility, vocabulary, control/escape, consistency, error prevention, recognition over recall, efficiency, minimal output, error recovery, and help.
 - **CLI contract tests**: Cover TTY vs non-TTY when behavior differs, `stdout`/`stderr`, exit codes, help text, output formats, malformed input, cancellation, auth/config precedence, and shell composition.
-- **Golden output tests**: Use for intentional formatter/help changes; do not accept drift casually.
+- **Output regression tests**: Use for intentional formatter/help changes; do not accept drift casually.
 - **Docs checks**: Update `site/` for user behavior and `docs/design/` for significant subsystem behavior; link guides and reference pages both ways.
 - **Compatibility checks**: Test v1-style workflows, generated OpenAPI command shape, plugin boundaries, and scripting behavior when touched.
 

.agents/skills/rsh-release-qa/references/release-gates.md

@@ -91,8 +91,14 @@ chmod 600 "$RUN_DIR/empty.json"
 
 ```bash
 env GOCACHE="$RUN_DIR/go-cache" GOPATH="$RUN_DIR/go-path" go run ./cmd/restish-docgen --check
+scripts/check-doc-links.rb
+scripts/check-doc-examples.rb
 ```
 
+The example check's `--mode live` variant executes every docs `restish-example`
+against `api.rest.sh`; include it when the release touches command surface or
+docs examples and the network allows it.
+
 For the docs site, use a disposable npm cache if the user cache is not writable
 or contains permission problems. These commands must run against `site/`, which
 contains the docs site's `package.json` and lockfile.

.agents/skills/rsh-release-qa/references/release-risk-map.md

@@ -15,7 +15,7 @@ checks after reading recent commits.
 - Pagination and hypermedia: page params, Link headers, item extraction,
   limits, metadata filters, and streaming output.
 - Output formatting: terminal color, JSON/table stability, scalar utility
-  output, plugin formatter behavior, and golden/reference drift.
+  output, plugin formatter behavior, and fixture/reference drift.
 - Plugin lifecycle: command plugins, formatter plugins, hook plugins,
   `restish-mcp`, subprocess cleanup, and protocol compatibility.
 - User-facing docs and generated command reference.

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

@@ -60,13 +60,13 @@ Review code changes with a bug-finding mindset. Prioritize correctness, regressi
 
 ## Restish-Specific Watchlist
 
-These are high-value repo-specific checks, not an exhaustive checklist. Use them when relevant; do not force them into unrelated reviews.
+These are high-value repo-specific checks, not an exhaustive checklist. Use them when relevant; do not force them into unrelated reviews. For the full catalog of historical bug classes found in past releases, see `../rsh-release-qa/references/findings-mining.md`. When a changed subsystem has a design doc (`docs/design/README.md`), check the diff against its stated invariants.
 
 ### Path-specific cues
 
 - `internal/cli/`: flags, exit codes, stdin/stdout/stderr, config precedence, generated commands
 - `internal/request/`: content negotiation, auth headers, redirects, pagination, retries, streaming, cancellation
-- `internal/output/`: formatter drift, golden tests, terminal width behavior, stable ordering
+- `internal/output/`: formatter drift, regression fixtures, terminal width behavior, stable ordering
 - `internal/config/`: defaults, file permissions, migrations, backward compatibility
 - `internal/plugin/` and `cmd/restish-*`: plugin protocol, subprocess lifecycle, wire compatibility
 - `cmd/restish` and `site/`: user-facing CLI behavior, examples, docs impact
@@ -99,27 +99,42 @@ Config fields should not be added unless their behavior is implemented. Otherwis
 
 Spec-loading or command-generation changes can break existing workflows indirectly. Check for backward compatibility in generated command shape, naming, argument expectations, and operation discovery.
 
-### Output formatting and golden tests
+### Spec and operation cache invalidation
 
-Intentional formatter changes should usually come with targeted regression coverage or golden updates. Unintentional output drift is a common source of user-visible regressions.
+A recurring source of fixes: stale generated commands after config or spec changes. Caches are keyed by base URL, operation base, server variables, and raw spec hash. Changes to `api edit`/`api connect`, profiles, base URLs, or spec loading must invalidate or refresh the relevant caches, and concurrent `api connect` runs must not clobber each other's entries.
+
+### OAuth and auth concurrency
+
+Token refreshes must stay serialized; discovery transports and OAuth state are shared across generated commands. Changes to `internal/auth` should be checked for refresh races, cache-key reuse across profiles/issuers, and browser-launch behavior (`$BROWSER` handling, Linux flows).
+
+### v1 → v2 migration of persisted state
+
+Changing config schema, cache key formats, or credential storage breaks existing user state unless migrated. Past fixes migrated legacy token cache keys, legacy `tls.cert`/`tls.key` fields, and added migration warnings. New formats need a mapping from the old one or an explicit, tested migration error.
+
+### Command surface and help contracts
+
+`internal/cli/command_surface_test.go` locks the built-in command tree, help grouping, error-message UX, and removed pre-release names. Adding, renaming, or regrouping commands should update it deliberately — treat unexplained churn there as a regression signal.
+
+### Output formatting
+
+Intentional formatter changes should usually come with targeted regression coverage. Unintentional output drift is a common source of user-visible regressions.
 
 ### Auth, pagination, filtering, and caching flows
 
 Changes in these areas often regress behavior only in realistic end-to-end paths. Review interactions, not just isolated helpers.
 
 For auth, redaction, and cache metadata changes, check both positive behavior and negative leakage boundaries: where credentials are applied, where they must not be applied, what gets persisted, and what appears in errors or traces. Keep findings tied to the PR's changed paths.
 
+`internal/secrets` holds the central allow-lists for recognizing credential-like fields; new secret-ish field names belong there, not in ad-hoc checks. Past fixes covered suffixed fields (`confirm_password`), URL userinfo and query credentials in network errors, and avoiding false positives on ordinary fields like `max_tokens`.
+
 ### Test buffer races
 
 Tests that share a `bytes.Buffer` across concurrent writers can hide data races, especially when subprocess stderr/stdout is wired into test buffers.
 
 ## Verification Hints
 
-- Prefer the narrowest meaningful test first: `go test ./internal/cli/...`, `go test ./internal/request/...`, `go test ./internal/output/...`, or another touched package.
-- Run `go test ./...` for broad or shared changes.
-- Run `go test -tags=integration ./...` before approving CLI or plugin behavior changes with integration risk.
-- Update golden files only when behavior intentionally changed.
-- Consider `go test -race ./...` when concurrency, subprocess handling, or shared buffers are touched.
+- Run the AGENTS.md verification ladder: narrowest touched package first, then `go test ./...`, then `-tags=integration` for CLI/plugin behavior changes, and `-race` when concurrency, subprocess handling, or shared buffers are touched.
+- Run `go run ./cmd/restish-docgen --check` when CLI surface or help text changed; CI fails on stale generated docs regions.
 
 ## Example Findings
 

.agents/skills/rsh-review/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Restish Review"
+  short_description: "Find bugs and risks in Restish changes"
+  default_prompt: "Use $rsh-review to review the current Restish code changes for bugs, regressions, missing tests, and repo-specific risks."