diff --git a/.agents/skills/sync-error-docs/SKILL.md b/.agents/skills/sync-error-docs/SKILL.md index 9a09a38a..209c6791 100644 --- a/.agents/skills/sync-error-docs/SKILL.md +++ b/.agents/skills/sync-error-docs/SKILL.md @@ -88,11 +88,13 @@ Rules: - Only add an explicit `{ slug, label }` object if the auto-derived title is wrong; the existing error entries all rely on the derived title. - Append after the last existing error entry unless a grouping order is obvious from the surrounding entries. The list is not alphabetized and has no section labels. -### Step 6: Add the underscore-to-hyphen redirect +### Step 6: Add the underscore-to-hyphen redirects (only when the forms differ) Error codes are underscored (`insufficient_credits`) but page slugs are hyphenated (`insufficient-credits`). Add redirects to `vercel.json` (at the repo root) so the underscore form resolves. -**Add two entries, not one.** Every error code currently in `vercel.json` has both a no-trailing-slash and a trailing-slash source (34 entries covering 17 codes, with no code having only one form). Adding a single variant leaves the new code with half the coverage of every existing one, and the `/errors/:code/` catch-all forwards a trailing slash through, so the slashed underscore path would not resolve. +**Skip this step entirely for a code that contains no underscore.** Its hyphenated slug is the same string as the code, so there is nothing to redirect: the no-slash entry would be a redundant trailing-slash normalization, and the trailing-slash entry would have `source` equal to `destination` — a self-redirect, which is an infinite loop. `conflict` is the current example. It has no redirect entries in `vercel.json`, and that is correct, not a gap. Only add redirects when `{underscore_code}` and `{hyphen-code}` actually differ. + +**Otherwise add two entries, not one.** Every multi-word error code currently in `vercel.json` has both a no-trailing-slash and a trailing-slash source (34 entries covering 17 codes, with no code having only one form). Adding a single variant leaves the new code with half the coverage of every existing one, and the `/errors/:code/` catch-all forwards a trailing slash through, so the slashed underscore path would not resolve. Check for existing entries first, to stay idempotent across re-runs: @@ -186,6 +188,7 @@ Summarize what was found: - Number of existing doc pages - New codes that were missing pages (list them) - Pages created, `src/sidebar.ts` entries added, redirects configured +- Any codes skipped for redirects because they contain no underscore - Or confirm everything is already in sync Follow the actionable-only Slack rule in `.agents/references/skill-authoring-guidelines.md`: a run that finds everything already in sync writes this report to the run output and posts nothing. diff --git a/.agents/skills/sync-error-docs/references/redirect-patterns.md b/.agents/skills/sync-error-docs/references/redirect-patterns.md index 94ba8114..cf0f5e0e 100644 --- a/.agents/skills/sync-error-docs/references/redirect-patterns.md +++ b/.agents/skills/sync-error-docs/references/redirect-patterns.md @@ -19,7 +19,7 @@ https://docs.warp.dev/reference/api-and-sdk/troubleshooting/errors/insufficient- Two gaps separate them: 1. **Path prefix** — `/errors/{code}` versus the full `/reference/api-and-sdk/troubleshooting/errors/{code}` path. -2. **Separator** — error codes are underscored (`insufficient_credits`); page slugs are hyphenated (`insufficient-credits`). +2. **Separator** — error codes are underscored (`insufficient_credits`); page slugs are hyphenated (`insufficient-credits`). A single-word code such as `conflict` has no separator to convert, so this gap does not exist for it. Both are handled by entries in `vercel.json` at the repo root. All redirects for the site live in that one file. @@ -40,7 +40,7 @@ Catch-alls already cover every error code, current and future, in both slash for } ``` -`:code` is forwarded unchanged, so `/errors/insufficient_credits` lands on the underscored path, which the separator redirects below then resolve. Note that the trailing-slash catch-all preserves the slash into the destination, which is why the separator step must also cover the slashed form. +`:code` is forwarded unchanged, so `/errors/insufficient_credits` lands on the underscored path, which the separator redirects below then resolve. For a single-word code the forwarded path is already the canonical slug, so nothing further is needed. Note that the trailing-slash catch-all preserves the slash into the destination, which is why the separator step must also cover the slashed form whenever it applies. Because these rules are generic, **adding a new error code requires no change here.** Just confirm both still exist: @@ -53,9 +53,13 @@ If either is missing, restore that rule rather than adding one entry per code. There are also bare `/errors` and `/errors/` redirects pointing at the errors index, which likewise need no per-code maintenance. -## 2. Separator redirects (two entries per code) +## 2. Separator redirects (zero or two entries per code) -These are the only redirects a new error code needs. They map the underscored form to the hyphenated page slug, in both slash forms: +These are the only redirects a new error code can need, and some codes need none. + +**First check whether the code contains an underscore.** If it does not, its hyphenated slug is the same string, there is no separator to bridge, and you add nothing — skip to the rules below for why. Only codes whose underscored and hyphenated forms actually differ get entries, and those get two. + +For a code that does differ, map the underscored form to the hyphenated page slug in both slash forms: ```json { @@ -70,7 +74,7 @@ These are the only redirects a new error code needs. They map the underscored fo } ``` -Example for `insufficient_credits`: +Example for `insufficient_credits`, whose forms differ: ```json { @@ -87,7 +91,8 @@ Example for `insufficient_credits`: Rules: -- **Add both slash variants.** All 17 codes currently in `vercel.json` have both (34 entries); none has only one. A single variant leaves the new code less covered than every existing one, and the trailing-slash catch-all in section 1 forwards its slash through, so the slashed underscore path would otherwise 404. +- **Skip a code with no underscore.** If `{underscore_code}` and `{hyphen-code}` are the same string, there is nothing to bridge. The no-slash entry would be a redundant trailing-slash normalization and the trailing-slash entry would be a self-redirect with `source` equal to `destination` — an infinite loop. `conflict` is the current example and correctly has no entries. +- **Otherwise add both slash variants.** All 17 multi-word codes currently in `vercel.json` have both (34 entries); none has only one. A single variant leaves the new code less covered than every existing one, and the trailing-slash catch-all in section 1 forwards its slash through, so the slashed underscore path would otherwise 404. - `source` has a **leading slash** and no file extension. - `destination` has a **trailing slash** in both entries. Every existing error redirect does. - Always set `"statusCode": 308`.