Add redirect from /getting-started to /quickstart - #2

Memory was sitting in the #2 slot, right after 'Getting started' and
above 'Warp Agents'. Reorder so the research-preview section sits at
the bottom of the Agents tab (after 'Oz Cloud Agents & Orchestration'),
matching the visual hierarchy of stable → preview content.

Co-authored-by: Oz <oz-agent@warp.dev>

Second review round, focused on the quickstart.

- Number the step headings ("## 1. Install...") to match the sibling Oz CLI
  and API/SDK quickstarts; ours was the only quickstart not numbering steps.
  Convert the nested numbered lists to prose so steps aren't double-numbered.
- Put the install commands in Tabs/TabItem for macOS+Linux and Windows,
  matching the pattern in getting-started/quickstart/installation-and-setup.
- Add a sign-up link to the account prerequisite for developers new to Warp,
  and note the CLI doesn't require the Warp app.
- Tighten the login section along the lines of the Oz CLI quickstart's
  authenticate step, drop the colon from the start-screen sentence, and
  reword the API key pointer.
- Update the inbound /cli/quickstart/#log-in anchor, now #2-log-in.

Co-Authored-By: Oz <oz-agent@warp.dev>

The second drift-watch validation run surfaced three ways the skill misleads an
unattended agent. All three are documentation gaps in the skill, not code bugs.

1. Working directory. Every path in the skill is relative to the docs repo root,
   but the skill never says so, and a sandbox commonly starts one level up. The
   failure mode is the problem: python3 exits 2 with "can't open file", which is
   the same exit code audit_docs.py uses to fail loud on a broken environment.
   An agent that reads the code and not the message concludes a sanity guard
   tripped and stops. State the cwd requirement up front, name the collision,
   and repeat it at the release-gate step and in the scheduled-agent prompt --
   the prompt is the only one of the three a cron run is guaranteed to read.

2. npm install. `npm run build` is the only validation this repo has and it
   needs node_modules, which a fresh sandbox does not have. Add `npm ci` as a
   stated precondition in Requirements and at both build sites.

3. Surface-map key edits. A rename sweep run across feature_surface_map.md
   corrupted an    corrupted an    corrupted an    corrupted an    corrupted an    corrupted aon    corrupted an    corrupted an    corrupted an    corrupted an    corrupted an map entry is a literal code identifier that only matches
   because it matches ex   because it matches ex   because it matches ex   beCo-Authored-By: Warp <agent@warp.dev>

… footguns (#619)

* docs: request reviewers for real and lead ambient PRs with a feature summary

Two fixes to the ambient new-feature docs pipeline (GROW-6093).

1. Actually request reviewers. The drafted PR only named reviewers in
   prose, which puts nothing in GitHub's review queue: docs #414, #415,
   #416 and #417 all named reviewers in the body and received zero
   reviews, three with an empty requested-reviewers list. Wire a required
   `gh pr edit --add-reviewer` step into missing_docs drift-watch step 7
   and into the create_pr skill, with the `dannyneira` fallback that
   release-docs-update.yml already uses, plus a verification read-back so
   a silently skipped assignment is caught. The prose /cc mention stays.

   suggest_reviewers.py gains `--reviewers-only` so the step can consume
   the resolved set without scraping the human-readable table.

2. Lead the PR body with a feature summary. Drafting PRs must open with
   `## What this feature does`: plain language, what the feature does for
   the user, ending with the shipped-in version and date read from
   check_new_release.py --json. Budget 75 words. check_pr_body.py gains
   `--require-lead-section`, asserting the heading is present once, is the
   first heading, is non-empty, and is within budget.

Co-Authored-By: Warp <agent@warp.dev>

* docs: address review — per-reviewer requests, first-content check, CI wiring

Blocking fix. The reviewer verification was emptiness-only, so the owning
engineer could be dropped silently — the exact bug this PR exists to fix.
`gh pr edit --add-reviewer a,b,c` is one atomic mutation, so a single
unassignable entry rejected the whole list and the `||` then replaced every
resolved owner with the fallback; a non-empty readback still passed. This is
live: `warpdotdev/oss-maintainers` is the root-rule owner in the warp client
repo and appears in most resolutions, but `/repos/warpdotdev/docs/teams` is
empty, so it cannot be requested here. Now each reviewer is requested in its
own call and the readback is compared against the resolved set, with partial
results reported. Also fixed the readback jq: the old
`[.reviewRequests[].login // .reviewRequests[].name]` silently drops teams
from a mixed list (verified).

Also:
- check_lead_section now asserts the summary is the first *content*, not just
  the first heading. A body opening with unheaded spec/workflow/run-ID
  preamble previously exited 0, which is the shape the check exists to stop.
- _iter_non_code_lines skips HTML comments, so a `##` inside a multi-line
  comment no longer displaces the lead section — same class already handled
  for code fences.
- Wired test_check_new_release.py into CI. The earlier deferral was wrong:
  #586 does not touch ci.yml and this PR already edits it, while
  missing_docs/SKILL.md advertises the test as covered.
- suggest_reviewers.py routes resolution diagnostics to stderr under
  --reviewers-only, so a fallback leaves a trace without polluting stdout.
- Removed the duplicated reviewer snippet from missing_docs; create_pr holds
  the canonical copy. The copies had already diverged, and the missing_docs
  one used `[[ -z ... ]] && ...`, which returns 1 and would abort a `set -e`
  scheduled run.
- Backticked the date in the worked example; marked the drafting-only lines
  in the copy-paste heredoc.
- Tests locking in first-content, HTML-comment banners, multi-line comments,
  CRLF bodies, and the stderr diagnostics.

Co-Authored-By: Warp <agent@warp.dev>

* create_pr: stop the fallback reviewer from masking a dropped owner

Review catch on #619. Step 4 appended FALLBACK_REVIEWER to GOT, but GOT
answers "which resolved owners did I actually request". Counting the
fallback there let the verification pass on a run where every real owner
was rejected -- the exact silent failure the section exists to prevent,
two paragraphs after it says "verify against the resolved set, not
against emptiness".

Traced against the documented snippet with a stubbed gh. Resolved owners
alice and bob, both rejected, fallback accepted:

  before:  warning: requested 1/2 resolved reviewers
           Requested reviewers: dannyneira
           exit 0

  after:   ERROR: none of the 2 resolved owners could be requested
           (wanted: alice bob); only the fallback is assigned.
           exit 1

The fallback now stays out of GOT, and the outcomes are reported as four
distinct states rather than one count: all owners requested, a partial
result naming who is missing, owners resolved but none requested (an
error, because the PR has the wrong reviewer), and nothing resolved at
all (a note, because the fallback is the intended pall there). Not even
the fallback landing remains a hard failure.

Verified by extracting the snippet from SKILL.md and executing it against
a stubbed gh across all five cases, so the documented text is what was
tested rather than a paraphrase of it.

Co-Authored-By: Warp <agent@warp.dev>

* create_pr: trust the read-back, and fix comment/fence ordering

Two review catches on #619.

1. Reviewer verification trusted gh's exit status

The section warns that `gh pr edit` can exit 0 while quietly skipping a
reviewer, then verified against GOT -- which is built from those exit
statuses. A silently skipped owner passed.

Verification now compares the read-back against WANT. Step 4's fallback
also keys off the read-back rather than GOT, because when gh exits 0 for
every owner and requests none of them, a GOT-based check skips the
fallback entirely and leaves the PR with no reviewer at all.

Match on the last path segment, lowercased: a team resolves as org/team
but reads back as its bare slug, so a naive compare reported every team
as missing.

Verified by extracting the snippet from SKILL.md and running it against
a stubbed gh across nine cases, including a stub that exits 0 without
recording the reviewer:

  bob silently skipped -> warning names bob   (previously silent)
  all silently skipped -> fall  all silently skipped -> fall  all silently skipped -> fall es its bare slug, no false "missing"

2. Fence detection ran before comment stripping

A ``` line inside an HTML comment opened a phantom code block that ate
the closing --> and every line after it, including the lead heading. A
valid body failed with "missing required lead section", which reads as
an authoring mistake rather than a parser bug.

Precisely: only an *odd* number of fence lines inside a comment breaks
it. A balanced pair opens and closes a phantom block that happens to end
before the -->, so it passed by luck. The tests say which case is the
real regression rather than implying all of them were.

The fix honors fence state first, then strips comments, then looks for a
fence in the visible text. Simply reordering the two would break the
mirror case:mirror case:mirror case:mirror case:mirror case:mirror case:mirror cs a comment would swallow tmirror case:mirror case:mirror cver both directions plus a guard tmirror case:mirror case:mirror case:mirror case:mirror case:mirror case:mirror cs a comment would swallow tmirror caseent@warp.dev>

* create_pr: verify the fallback reviewer by name, not by read-back emptiness

Review catch on #619 (QUALITY-1875 rework). When owner resolution came back
empty and the PR already carried an unrelated reviewer, the prior "is
$REQUESTED non-empty" check treated that unrelated reviewer as proof the
dannyneira fallback had landed, so it skipped verifying/re-requesting the
fallback by name -- and the script still printed "fallback requested" and
exited 0 even when dannyneira was never assigned.

Added a has_reviewer helper that checks the read-back for a specific
reviewer, used it to gate the fallback request/verification when resolution
was empty, and split the final error check so a fallback that truly can't be
assigned is reported as a failure instead of masked by an unrelated
reviewer already on the PR.

Added test_request_reviewers.py, which extracts the documented snippet from
SKILL.md and runs it against a stubbed gh/suggest_reviewers.py across the
normal-resolution, empty-resolution, and pre-existing-unrelated-reviewer
cases. test_unrelated_reviewer_does_not_mask_fallback_failure fails against
the pre-fix snippet and passes after the fix. Wired into ci.yml.

Co-Authored-By: Warp <agent@warp.dev>

* missing_docs: fix the three sandbox footguns validation run #2 hit

The second drift-watch validation run surfaced three ways the skill misleads an
unattended agent. All three are documentation gaps in the skill, not code bugs.

1. Working directory. Every path in the skill is relative to the docs repo root,
   but the skill never says so, and a sandbox commonly starts one level up. The
   failure mode is the problem: python3 exits 2 with "can't open file", which is
   the same exit code audit_docs.py uses to fail loud on a broken environment.
   An agent that reads the code and not the message concludes a sanity guard
   tripped and stops. State the cwd requirement up front, name the collision,
   and repeat it at the release-gate step and in the scheduled-agent prompt --
   the prompt is the only one of the three a cron run is guaranteed to read.

2. npm install. `npm run build` is the only validation this repo has and it
   needs node_modules, which a fresh sandbox does not have. Add `npm ci` as a
   stated precondition in Requirements and at both build sites.

3. Surface-map key edits. A rename sweep run across feature_surface_map.md
   corrupted an    corrupted an    corrupted an    corrupted an    corrupted an    corrupted aon    corrupted an    corrupted an    corrupted an    corrupted an    corrupted an map entry is a literal code identifier that only matches
   because it matches ex   because it matches ex   because it matches ex   beCo-Authored-By: Warp <agent@warp.dev>

---------

Co-authored-by: Warp <agent@warp.dev>
Co-authored-by: warp-agent-staging[bot] <240773466+warp-agent-staging[bot]@users.noreply.github.com>

* missing_docs: keep at most one bookkeeping PR open

The PR strategy said a bookkeeping PR "is independently mergeable in any
order." That is true against feature PRs, which is the case it was written for.
It is false against a second bookkeeping PR: both edit feature_surface_map.md
and surface_snapshot.json, and the snapshot is a wholesale regen, so a conflict
between two of them cannot be resolved by hand at all -- it has to be
regenerated on the merged tree.

#614 and #624 are that collision, sitting open right now. Two drift-watch runs
a day apart independently triaged the same two /factory routes, reached the
same Gate 0 verdict, and each added the same two map lines. Neither looked for
the other's PR, and they used different branch-naming schemes, so there was no
way to find one from the other. Run #2's ledger eway to find one from the other. Run #2's ledger eway to find one from the other. Run #2's ledger eway to find one from the other. Run #2's ledger eway to find one from the other. Run #2's ledgeran
stays rare. Changes:

- Scope the independence claim to feature PRs, and add the rule: check for an
  open bookkeeping PR first, extend that branch, and re-run --commit and
  --update-snapshot there so the marker and snapshot stay one regen covering
  every release the PR carries. Wait for the merge instead when it is already
  approved.
- Standardize the title (missing_docs bookkeeping: <version>) and branch
  (missing-docs/boo  (missing-docs/boo  (mise search  (missing-docs/boo  (missing-docs/boo  (mise search  (missing-docs/boo  (miste their inconsistent
  titles.
- Triage now reads the ledger and map as they stand on any open bookkeeping PR,
  not just on main. A verdict in an unmerged PR is still a verdict.
- Carry both into drift-watch step 8 and the scheduled-agent prompt, which is
  the only copy a cron run is guaranteed to read.

Co-Authored-By: Warp <agent@warp.dev>

* missing_docs: use the repo's existing prefix style for bookkeeping PR titles

The convention I introduced, "missing_docs bookkeeping: <version>", quietly
contradicted create_pr's existing rule that docs PR titles carry a prefix. It
also invented a third naming shape in a change whose whole point is that two
competing shapes are what let #614 and #624 miss each other.

"chore(missing_docs): bookkeeping for <version>" matches the shape #614 already
used, matches the repo's conventional-commit practice, and still carries both
terms the documented search keys on -- verified against #614, whose title has
exactly this form and which the search finds.

Co-Authored-By: Warp <agent@warp.dev>

* missing_docs: restrict bookkeeping-PR search to avoid self-match

The gh pr list --search "missing_docs bookkeeping in:title" query ANDs
the two words anywhere in the title, so it also matches this rule-only
PR's own title ("...keep at most one bookkeeping PR open"). The next
drift-watch run would then check out and extend this PR's branch
instead of a real bookkeeping PR.

Restrict the search to the quoted "bookkeeping for" phrase, which
matches the canonical and legacy bookkeeping-PR titles but not this
PR's title, and add reviewDecision to the output so the already-
approved exception can be applied without a second query. Apply the
same corrected query to the recommended scheduled-agent prompt.

Co-Authored-By: Warp <agent@warp.dev>

---------

Co-authored-by: Warp <agent@warp.dev>
Co-authored-by: warp-agent-staging[bot] <240773466+warp-agent-staging[bot]@users.noreply.github.com>