Skip to content

[twarp upstream] docs-readme - #27

Merged
timomak merged 26 commits into
masterfrom
twarp-upstream-catchup-docs-readme
May 11, 2026
Merged

[twarp upstream] docs-readme#27
timomak merged 26 commits into
masterfrom
twarp-upstream-catchup-docs-readme

Conversation

@timomak

@timomak timomak commented May 10, 2026

Copy link
Copy Markdown
Owner

Summary

Cherry-picks 26 commit(s) from warpdotdev/warp in the docs-readme theme.

SHA Subject
b7c64bc0 Add Build Status section linking to build.warp.dev (warpdotdev#9339)
18497952 Point stable-skill instructions at resources/bundled/skills/ (warpdotdev#9406)
874a2576 Add stakeholders for lsp and languages crates. (warpdotdev#9442)
d1601f54 add vertical tabs, tab configs, worktree, notifications, and rich input stakeholders (warpdotdev#9487)
a8f57a84 Clarify alacritty_terminal origins for some terminal model code. (warpdotdev#9513)
6188ed17 Fix broken Markdown link in languages/grammars README (warpdotdev#9343)
e05c5d23 Fix typos and example reference in crate READMEs (warpdotdev#9408)
33c48601 Update env_vars README to match current file layout (warpdotdev#9407)
b740b82f Update persistence README paths to crates/persistence (warpdotdev#9405)
799e13fe docs: simplify PR template for public contributors (warpdotdev#9270)
6898ac27 docs: surface #oss-contributors Slack channel in README, CONTRIBUTING, and FAQ (warpdotdev#9473)
a12d9e46 Add more UI framework stakeholders. (warpdotdev#9622)
ed0cdaef docs: attribute Alacritty/vte derivative code in two more files (warpdotdev#9522) (warpdotdev#9563)
182c1ac6 chore: assign / route to @warpdotdev/oss-maintainers in STAKEHOLDERS (warpdotdev#9635)
73074bad remove @moirahuang from context chips from stakeholders (warpdotdev#9654)
fc1d2ff0 docs(skills): require screenshots or videos for UI-impacting PRs (warpdotdev#9701)
cabd3292 docs: replace Becoming a Collaborator with Code Review section (warpdotdev#9982)
24a39aac Remove ready-to-implement from bug report template (warpdotdev#10064)
59c6a48e docs: attribute two more Alacritty-derived files (warpdotdev#9522) (warpdotdev#9707)
716603a0 docs: replace warp-external with warp in local agent skills (warpdotdev#9990)
27c838b1 docs: add README badges (warpdotdev#10204)
a8ec49e4 Improve badge formatting in README.md (warpdotdev#10260)
0b728175 Update contributing.md and pr template to include manual testing instructions (warpdotdev#10286)
04069a29 Reference README badges from brand assets (warpdotdev#10281)
606e1653 Fix Markdown ToC anchor navigation in notebooks (warpdotdev#10143)
1fa2fc30 docs: standardize bullet style to hyphens (GH9742) (warpdotdev#9937)

Dropped commits

These would have re-introduced AI code or had unresolvable conflicts:

Conflict resolution

Where conflicts touched files removed by twarp's AI deletion (in crates/ai/, crates/{input_classifier,natural_language_detection,voice_input,mcp}/, app/src/ai*/, ambient_agent/cli_agent_sessions/agent_mode), the conflicting files were dropped from the cherry-pick. Where a conflict in a kept file would have re-introduced AI symbols, the commit was dropped entirely.

Test plan

  • CI build/lint/test

zachlloyd and others added 26 commits May 10, 2026 17:25
## Description
Adds a **Warp Contributions** section to the README right after Installation
and before Licensing, prominently linking to
[build.warp.dev](https://build.warp.dev).

## Testing
README-only change, no code tests needed.

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

_Conversation:
https://staging.warp.dev/conversation/24b02952-f7b1-45c4-9122-dd116c4522ec_
_Run:
https://oz.staging.warp.dev/runs/019dd668-0e7c-7cf8-bcbd-0deee3485a1b_

_This PR was generated with [Oz](https://warp.dev/oz)._

---------

Co-authored-by: Oz <oz-agent@warp.dev>
Co-authored-by: sathvik vang <sathvik@warp.dev>
…dev#9406)

### Description

The channel-gated skills README and the runtime error message in
\`script/copy_conditional_skills\` both pointed contributors at
\`resources/skills/\` for stable-ready skills, but that directory
doesn't exist in the repo — \`script/prepare_bundled_resources\` copies
the always-bundled skills from \`resources/bundled/\`, so the right
destination is \`resources/bundled/skills/\`.

The result: if anyone bumped into the existing \`stable/\` guard
(\`copy_conditional_skills\` line 39), the printed remediation pointed
them at a path that doesn't exist.

Three updates:
- \`resources/channel-gated-skills/README.md\` — \"place them in the
always-bundled \`resources/skills/\`\" → \`resources/bundled/skills/\`
(in the prose blockquote and in the gating table).
- \`script/copy_conditional_skills\` — header comment + the user-facing
error \`echo\`.

No behavior change in the script itself; only the comment and the error
string contents.

### Testing

Doc/script-comment only — nothing to run. The actual copy logic is
unchanged.

### Server API

No server changes.

### Agent Mode

Not applicable.

### Changelog Entries

None.

Co-authored-by: anshul-garg27 <anshul-garg27@users.noreply.github.com>
## Description

Adding @kevinyang372 @bnavetta for `crates/languages` and @kevinyang372
@moirahuang for `crates/lsp`.
…ut stakeholders (warpdotdev#9487)

## Description
Add vertical tabs, tab configs, worktree, notifications, and rich input
stakeholders from the Warp team side

## Testing
N/A

## Server API dependencies
<!-- You may remove this section if your PR does not have any server
dependencies. -->
- [ ] Is this change necessary to make the client compatible with a
desired [server API breaking
change](https://www.notion.so/warpdev/How-to-safely-introduce-server-API-breaking-changes-0aa805ff5d5d41fd8834f3c95caba0b4?pvs=4#d55ecf8aea3449949d3c33b0e67f6800)?
- [ ] Does this change rely on a [new server
API](https://www.notion.so/warpdev/How-to-add-a-new-full-stack-feature-8412cede405a4ec194b32bdd4b951035?pvs=4#04da1e6a493542d68b3e998c7d339640)?
- [ ] If so, is the use of this API restricted to client channels that
rely on the staging server (e.g. WarpDev)?
- [ ] Is this change enabling the use of a server API on client channels
that rely on the production server (e.g. WarpStable)?
- [ ] If so, has the new server API been stable on production for at
least one server release cycle? See
[here](https://www.notion.so/warpdev/How-to-add-a-new-full-stack-feature-8412cede405a4ec194b32bdd4b951035?pvs=4#73b202f939834b97ab1fbdf7fc82cd53)
for more details.

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

## Changelog Entries for Stable
<!--
The entries below will be used when constructing a soft-copy of the
stable release changelog. Leave blank or remove the lines if no entry in
the stable changelog is needed. Entries should be on the same line,
without the `{{` `}}` brackets. You can use multiple lines, even of the
same type. The valid suffixes are:

* NEW-FEATURE: for new, relatively sizable features. Features listed
here will likely have docs / social media posts / marketing launches
associated with them, so use sparingly.
* IMPROVEMENT: for new functionality of existing features.
* BUG-FIX: for fixes related to known bugs or regressions.
* IMAGE: the image specified by the URL (hosted on GCP) will be added to
Dev & Preview releases. For Stable releases, see the pinned doc in the
#release Slack channel.
* OZ: Oz-related updates. Use `CHANGELOG-OZ`. At most 4 Oz updates are
shown in-app per release.
-->

CHANGELOG-NEW-FEATURE: {{text goes here...}}
CHANGELOG-IMPROVEMENT: {{text goes here...}}
CHANGELOG-BUG-FIX: {{text goes here...}}
CHANGELOG-BUG-FIX: {{more text goes here...}}
CHANGELOG-IMAGE: {{GCP-hosted URL goes here...}}
CHANGELOG-OZ: {{text goes here...}}

---------

Co-authored-by: Oz <oz-agent@warp.dev>
…arpdotdev#9513)

## Description

Explicitly identifies, in source files, which ones were inherited from
Alacritty when Warp was initially built, and separately bundles in the
Alacritty license.
## Description

The link to the tree-sitter docs in
`crates/languages/grammars/README.md` is missing the closing `]`, so
GitHub renders it as plain text instead of a link:

```diff
-We need a [TSLanguage(https://tree-sitter.github.io/tree-sitter/using-parsers#the-basic-objects) object to parse a source code file.
+We need a [TSLanguage](https://tree-sitter.github.io/tree-sitter/using-parsers#the-basic-objects) object to parse a source code file.
```

## Testing

Docs-only change. Verified the rendered link is clickable in the GitHub
Markdown preview.

Co-authored-by: anshul-garg27 <anshul-garg27@users.noreply.github.com>
### Description

Two README files in \`crates/\` had typos and one had an ambiguous file
reference:

**\`crates/warpui_core/README.md\`**
- \"to do describe\" → \"To describe\"
- \"appearence\" → \"appearance\"
- \"precicely\" → \"precisely\"
- \"handlign\" → \"handling\"

**\`crates/lsp/README.md\`**
- \"implmentation\" → \"implementation\"
- The README said \"See main.rs for an example implementation\" but
there is no \`main.rs\` in \`crates/lsp/src/\`. The example actually
lives at \`crates/lsp/examples/rust-lsp/main.rs\`, so I made the path
explicit.

Doc-only changes.

### Testing

Markdown only.

### Server API

No server changes.

### Agent Mode

Not applicable.

### Changelog Entries

None.

Co-authored-by: anshul-garg27 <anshul-garg27@users.noreply.github.com>
### Description

The env_vars README ("up-to-date as of 6/26/2024") still references
three filenames that have moved or been renamed in the meantime. The
prose description of each file still matches the actual contents — only
the filenames changed.

| README path | Actual path |
|---|---|
| \`app/src/server/update_manager.rs\` |
\`app/src/server/cloud_objects/update_manager.rs\` |
| \`command_dialog/view.rs\` | \`command_dialog/command_dialog_view.rs\`
|
| \`section_headers_and_footers.rs\` | \`fixed_view_components.rs\`
(still defines \`render_trash_banner\` and \`render_save_button\`) |

I deliberately left the rest of the README alone — the other paths it
points at all still exist (verified locally with \`test -f\`).

### Testing

Markdown only — nothing to run.

### Server API

No server changes.

### Agent Mode

Not applicable.

### Changelog Entries

None.

Co-authored-by: anshul-garg27 <anshul-garg27@users.noreply.github.com>
### Description

Spotted while running another doc audit: `app/src/persistence/README.md`
still describes the migration workflow in terms of the pre-open-source
layout. `schema.rs` and `schema.patch` actually live under
`crates/persistence/` now, and the doc also still tells contributors to
`cd <warp-internal repo>`.

Three small text-only fixes:

- `app/src/persistence/schema.rs` → `crates/persistence/src/schema.rs`
- `app/src/persistence/schema.patch` → `crates/persistence/schema.patch`
- `cd <warp-internal repo>` → `cd <repo root>` (this is the public repo
now; contributors clone it under whatever name they pick)

I deliberately left the `our fork of diesel_cli` paragraph alone —
`script/install_cargo_build_deps` calls `cargo binstall --force -y
diesel_cli` which suggests it currently uses upstream, but I'd rather a
maintainer confirm whether the bundled-SQLite behavior the README claims
is still accurate before rewording that section.

### Testing

Markdown only — nothing to run.

### Server API

No server changes.

### Agent Mode

Not applicable.

### Changelog Entries

None.

---------

Co-authored-by: anshul-garg27 <anshul-garg27@users.noreply.github.com>
## Description
Simplifies the public-facing pull request template by removing
internal-only sections and guiding contributors toward the
issue-readiness workflow.

Changes:
- Removed the `Server API dependencies` section and its internal Notion
links.
- Removed the `Changelog Entries for Stable` section (internal release
process).
- Removed the testing-policy Notion link from the `Testing` section.
- Added a `Linked Issue` section with checkboxes asking authors to
confirm:
  - The linked issue is labeled `ready-to-spec` or `ready-to-implement`.
- Screenshots or a short video of the implementation are included where
appropriate.
- Added a `Screenshots / Videos` section as a place to attach that
media.

## Testing
Documentation-only change; verified the rendered template via `git
diff`.

_Conversation:
https://staging.warp.dev/conversation/7821ed8c-960f-406d-bec1-485a6c540873_
_Run:
https://oz.staging.warp.dev/runs/019dd545-1271-74cb-81ad-2545e30fb1fc_

_This PR was generated with [Oz](https://warp.dev/oz)._

---------

Co-authored-by: Oz <oz-agent@warp.dev>
…, and FAQ (warpdotdev#9473)

## Description

Surface the **`#oss-contributors`** Slack channel
([link](https://warpcommunity.slack.com/archives/C0B0LM8N4DB)) as the
dedicated place for contributors to chat with each other and the Warp
team in the docs new contributors actually read.

- **`README.md`** — adds a `[!TIP]` callout under "Open Source &
Contributing", and updates the "Support and Questions" bullet to point
at `#oss-contributors`.
- **`CONTRIBUTING.md`** — adds a `[!TIP]` callout near the top so
contributors see it as soon as they land, and updates the "Getting Help"
bullet at the bottom.
- **`FAQ.md`** — updates the "Where do I get help?" bullet.

The existing
[`go.warp.dev/join-preview`](https://go.warp.dev/join-preview) link is
preserved as the workspace on-ramp for people who aren't yet in the Warp
Slack.

## Testing

Docs-only change — rendered the markdown locally to confirm the
GitHub-flavored `[!TIP]` callouts and Slack/`go.warp.dev` links render
correctly.

## Server API dependencies

N/A — docs only.

## Agent Mode

- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

## Changelog Entries for Stable

<!-- Docs-only change; no changelog entry. -->

---


[Conversation](https://staging.warp.dev/conversation/1011b077-6ef3-4516-857f-85043490d114)

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

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

Adds more stakeholders for UI framework crates.
…dotdev#9522) (warpdotdev#9563)

## Description

Refs warpdotdev#9522.

After warpdotdev#9513 bundled `LICENSE-ALACRITTY` and added attribution headers to
the original tranche of derivative files, [@chrisduerr (Alacritty
maintainer) followed
up](warpdotdev#9522 (comment))
and named two specific files that were still missing attribution:

> - This is an almost verbatim copy of VTE's ansi.rs module:
>   `crates/warp_terminal/src/model/ansi/control_sequence_parameters.rs`
> - This function (and several others) are also verbatim copies:
>   `app/src/terminal/grid_renderer/cell_type.rs:L160`

This PR adds the same two-line "adapted from … under the Apache license"
comment header that warpdotdev#9513 introduced, pointing to the same bundled
`crates/warp_terminal/src/model/LICENSE-ALACRITTY`:

| File | Attribution |
| ---- | ----------- |
| `crates/warp_terminal/src/model/ansi/control_sequence_parameters.rs` |
"adapted from the vte crate (an Alacritty project)" — file-wide |
| `app/src/terminal/grid_renderer/cell_type.rs` | "color-mapping helpers
(`compute_fg_rgb`, `compute_bg_rgb`, `get_override_color`) below are
adapted from the alacritty_terminal crate" — scoped because `Secret` /
`IsFocused` / `CellType` at the top of the file are Warp-specific |

Both files now point to the existing
`crates/warp_terminal/src/model/LICENSE-ALACRITTY` (Apache-2.0 — the
same license `vte` and `alacritty_terminal` both ship under). No
license-file changes are needed.

This is documentation/attribution only — no functional changes.

## Scope

This PR addresses the **two files explicitly cited** in warpdotdev#9522 by the
Alacritty maintainer. The cited comment also says "this function and
several others" — the "several others" likely includes the
immediately-adjacent `compute_bg_rgb` and `get_override_color` helpers
in the same `cell_type.rs` (they are similar verbatim ports), which is
why this PR's attribution covers all three of them. A broader audit of
files that *might* be derivative beyond what's explicitly cited is best
done by Warp's team or the Alacritty maintainers directly, since it
requires intimate knowledge of upstream history; happy to extend this PR
to cover any additional files that get flagged.

## Testing

Documentation/comments only. `cargo fmt -- --check` clean. No code paths
affected.

## Server API dependencies

- [ ] No server impact.

## Agent Mode

- [ ] Warp Agent Mode

## Changelog Entries for Stable

(None — internal/legal attribution metadata.)
…arpdotdev#9635)

## Description
Update the default fallback owner for the root `/` pattern in
`.github/STAKEHOLDERS` from the list of FA leads to the
`@warpdotdev/oss-maintainers` team.

## Linked Issue
N/A — small ownership update.
- [ ] The linked issue is labeled `ready-to-spec` or
`ready-to-implement`.
- [ ] Where appropriate, screenshots or a short video of the
implementation are included below (especially for user-visible or UI
changes).

## Screenshots / Videos
N/A — no UI changes.

## Testing
No code changes; this only updates the STAKEHOLDERS file used by the
triage workflow.

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

_Conversation:
https://staging.warp.dev/conversation/5d3add1a-47d9-4eb8-9400-a84b51e9f920_
_Run:
https://oz.staging.warp.dev/runs/019ddf7c-4acd-7a1d-8470-5f40af986b2b_

_This PR was generated with [Oz](https://warp.dev/oz)._

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

## Description
WISOTT

## Linked Issue
<!--
Link the GitHub issue this PR addresses. Before opening this PR, please
confirm:
-->
- [ ] The linked issue is labeled `ready-to-spec` or
`ready-to-implement`.
- [ ] Where appropriate, screenshots or a short video of the
implementation are included below (especially for user-visible or UI
changes).

## Screenshots / Videos
<!-- Attach screenshots or a short video demonstrating the change, where
appropriate. Remove this section if it is not relevant to your PR. -->

## Testing
<!--
How did you test this change? What automated tests did you add? If you
didn't add any new tests, what's your justification for not adding any?
-->

## Agent Mode
- [ ] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

<!--
## Changelog Entries for Stable

The entries below will be used when constructing a soft-copy of the
stable release changelog. Leave blank or remove the lines if no entry in
the stable changelog is needed. Entries should be on the same line,
without the `{{` `}}` brackets. You can use multiple lines, even of the
same type. The valid suffixes are:

* NEW-FEATURE: for new, relatively sizable features. Features listed
here will likely have docs / social media posts / marketing launches
associated with them, so use sparingly.
* IMPROVEMENT: for new functionality of existing features.
* BUG-FIX: for fixes related to known bugs or regressions.
* IMAGE: the image specified by the URL (hosted on GCP) will be added to
Dev & Preview releases. For Stable releases, see the pinned doc in the
#release Slack channel.
* OZ: Oz-related updates. Use `CHANGELOG-OZ`. At most 4 Oz updates are
shown in-app per release.

CHANGELOG-NEW-FEATURE: {{text goes here...}}
CHANGELOG-IMPROVEMENT: {{text goes here...}}
CHANGELOG-BUG-FIX: {{text goes here...}}
CHANGELOG-BUG-FIX: {{more text goes here...}}
CHANGELOG-IMAGE: {{GCP-hosted URL goes here...}}
CHANGELOG-OZ: {{text goes here...}}
-->
…pdotdev#9701)

## Description
Updates the `review-pr-local` skill so the PR review agent analyzes the
PR description and comments for screenshots and videos when the change
is UI-impacting. If visual evidence is missing for a user-visible
change, the agent should ask for it (e.g. _"For faster review, please
upload screenshots or a video of the feature working end to end."_) and
treat the review as `Request changes`.

This addresses the Slack thread asking the agent itself to request
visual evidence on UI-impacting PRs and to make it (effectively)
blocking.

This is a new version of warpdotdev#9650, rebased on the current master branch.

## Linked Issue
- [x] N/A — skill-only change.

## Screenshots / Videos
N/A — docs-only change to a skill markdown file.

## Testing
Reviewed the rendered markdown locally; no code changes.

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

_Conversation:
https://staging.warp.dev/conversation/ab81ec4d-60dc-4d12-a95e-51edfe581e0c_
_Run:
https://oz.staging.warp.dev/runs/019de151-a557-712a-ac02-58a8d4fb90ec_

_This PR was generated with [Oz](https://warp.dev/oz)._

Co-authored-by: Oz <oz-agent@warp.dev>
…otdev#9982)

## Description
Remove the "Becoming a Collaborator" section from CONTRIBUTING.md and
replace it with a new "Code Review" section that clearly documents the
two-stage review process:

1. **Oz review** — Oz is automatically assigned and produces the first
review on every PR.
2. **Warp team review** — Only after Oz has approved the PR is it routed
to a Warp team subject-matter expert for final human review. PRs not yet
approved by Oz will not be assigned to a team member.

## Linked Issue
N/A — documentation-only change requested internally.

## Testing
Docs-only change; no code or tests affected.

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

_Conversation:
https://staging.warp.dev/conversation/cd3469da-7b12-46ea-84e4-fd639252308b_
_Run:
https://oz.staging.warp.dev/runs/019deec0-9ca9-701d-8043-05c7027c73ba_

_This PR was generated with [Oz](https://warp.dev/oz)._

Co-authored-by: Oz <oz-agent@warp.dev>
## Description
Removes the `ready-to-implement` default label from the bug report issue template while keeping the `bug` label. Also updates the `triage-issue-local` skill so the triage agent determines whether `ready-to-implement` should be applied based on reproducibility and fix scope.

## Linked Issue
N/A - requested from Slack.
- [ ] The linked issue is labeled `ready-to-spec` or `ready-to-implement`.
- [ ] Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes).

## Screenshots / Videos
N/A - issue template and skill guidance changes only.

## Testing
- `python3` assertion that `.github/ISSUE_TEMPLATE/01_bug_report.yml` now uses only `labels: ["bug"]` and no longer includes `ready-to-implement` in the template metadata.
- `python3` assertion that `.agents/skills/triage-issue-local/SKILL.md` includes the new `ready-to-implement` triage guidance for reproducible, narrow-scope bugs.
- `git diff --check`

## Agent Mode
- [ ] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

_This PR was created by [Oz](https://warp.dev/oz) (running Codex)._
…arpdotdev#9707)

## Description

Refs warpdotdev#9522.

After warpdotdev#9513 and warpdotdev#9563 added attribution headers to the original set of
derivative files, two more files remain unattributed:

| File | Upstream origin |
| --- | --- |
| `app/src/terminal/model/grid/grid_storage/resize.rs` |
`alacritty_terminal/src/grid/resize.rs` — grid resize/reflow logic. The
parent `grid_storage.rs` was attributed in warpdotdev#9513; this child module was
missed. |
| `app/src/terminal/ref_tests/mod.rs` |
`alacritty_terminal/tests/ref.rs` — test harness, including the
`ref_tests!` macro, JSON fixture loading, and the `.alacritty.recording`
data format. |

Both files now carry the same two-line attribution comment that warpdotdev#9513
and warpdotdev#9563 introduced, pointing to the existing
`crates/warp_terminal/src/model/LICENSE-ALACRITTY` (Apache-2.0).

## Linked Issue

- [x] The linked issue is labeled `ready-to-spec` or
`ready-to-implement`.

## Screenshots / Videos

Not applicable — documentation/comments only.

## Testing

No code paths changed. `cargo clippy --workspace --all-targets
--all-features --tests -- -D warnings` clean.

Note: `cargo fmt --check` reports pre-existing import-ordering failures
in both files that are present on `master` before this change (confirmed
by checking `git stash` baseline). These are not introduced by this PR.

## Agent Mode
- [ ] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
## Description
Adds the new Built with Warp and Powered by Oz badge images to the top
badge row in the README.

## Linked Issue
N/A
- [ ] The linked issue is labeled `ready-to-spec` or
`ready-to-implement`.
- [ ] Where appropriate, screenshots or a short video of the
implementation are included below (especially for user-visible or UI
changes).

## Screenshots / Videos
N/A — README-only change.

## Testing
- `cargo fmt -- --check`
- `cargo clippy --workspace --exclude warp_completer --all-targets
--tests -- -D warnings`
- `cargo clippy -p warp_completer --all-targets --tests -- -D warnings`

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

Conversation:
https://staging.warp.dev/conversation/0819cd3b-0dfa-457f-aa38-f0bb1ad01c6d

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

---------

Co-authored-by: Oz <oz-agent@warp.dev>
Co-authored-by: Safia Abdalla <captainsafia@users.noreply.github.com>
Added non-breaking space for better formatting of warp badges
## Description
Fixes rendered Markdown fragment links in notebook editors so links like
`[Goal](#goal)` scroll to the matching Markdown heading instead of being
routed through normal external URL/file link handling.

This adds notebook-local anchor resolution that:
- matches fragments against rendered Markdown headings
- normalizes heading text into GitHub-like slugs
- supports duplicate headings with `-1`, `-2`, etc.
- handles percent-encoded fragments

## Linked Issue
Fixes warpdotdev#10058

- [x] The linked issue is labeled `ready-to-implement`.
- [x] Where appropriate, screenshots or a short video of the
implementation are included below (especially for user-visible or UI
changes).

## Screenshots / Videos
Manual verification of rendered Markdown ToC anchor navigation using
`crates/editor/test_fixtures/toc_anchor_test.md`.

Before navigation, the rendered Markdown viewer shows the table of
contents with fragment links:

![Rendered Markdown ToC before anchor
navigation](https://raw.githubusercontent.com/haikomatt/warp/anchor-demo-artifacts/warp-fix-markdown-toc-1.png)

After clicking ToC links, the viewer scrolls to the corresponding
normalized and duplicate heading targets:

![Rendered Markdown ToC after anchor
navigation](https://raw.githubusercontent.com/haikomatt/warp/anchor-demo-artifacts/warp-fix-markdown-toc-2.png)

## Testing
Added regression coverage for:
- matching a simple Markdown heading anchor
- normalizing heading text before matching
- duplicate heading anchors using numeric suffixes

Validated locally with:

- `cargo fmt -- --check`
- `cargo clippy --workspace --exclude warp_completer --all-targets
--tests -- -D warnings`
- `cargo clippy -p warp_completer --all-targets --tests -- -D warnings`
- `./script/run-clang-format.py -r --extensions 'c,h,cpp,m'
./crates/warpui/src/ ./app/src/`
- `find . -name "*.wgsl" -exec wgslfmt --check {} +`
- `cargo test --manifest-path app/Cargo.toml --lib
test_markdown_anchor_target`
- `cargo test --manifest-path app/Cargo.toml --lib test_inline_markdown`
- `cargo nextest run --no-fail-fast --workspace --exclude
command-signatures-v2 -E 'not test(/_ssh_/)'`
  - Passed locally: `5952 passed`, `106 skipped`
- SSH integration tests were excluded because they require Warp GCP SSH
test infrastructure credentials.
- `cargo nextest run -p warp_completer --features v2`
- `cargo test --doc`

PowerShell lint was skipped locally because `pwsh` is not installed.

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

CHANGELOG-BUG-FIX: Fixed Markdown table-of-contents anchor links in
rendered notebooks.

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

---------

Co-authored-by: Oz <oz-agent@warp.dev>
## Summary                              
Resolves the inconsistent bullet styling called out in warpdotdev#9742. Two files
in the core docs were mixing asterisk (`*`) and hyphen
(`-`) bullets within themselves, while every other top-level Markdown
file in the repo already uses hyphens uniformly:
   
- **`README.md`** — the nine *Open Source Dependencies* entries used `*`
while the rest of the file used `-`.
- **`.github/pull_request_template.md`** — the five `CHANGELOG-*` suffix
descriptions in the commented-out instruction block used
`*` while the visible *Linked Issue* checkboxes used `-`.
Both are now hyphens. After this PR every `.md` file in the seven core
docs (`CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `FAQ.md`,
`README.md`, `SECURITY.md`, `WARP.md`,
`.github/pull_request_template.md`) uses the hyphen style consistently.
The other items mentioned in warpdotdev#9742 (header spacing, section dividers)
were spot-checked and are already consistent across these
files; no further changes were necessary. If a maintainer wants stricter
project-wide enforcement (e.g. a `markdownlint` config or
`prettier --parser markdown` run over the whole tree), that is a tooling
decision that warrants its own discussion and a much
larger diff — happy to follow up on a separate PR if there is interest.
                                         
## Linked Issue
  Closes warpdotdev#9742.                          

- [x] The linked issue is labeled `ready-to-spec` or
`ready-to-implement`.
- [ ] Where appropriate, screenshots or a short video of the
implementation are included below (especially for user-visible or UI
  changes).                                   
                                          
  N/A — docs-only change; no UI or behavior impact.
  ## Screenshots / Videos                     
N/A — docs-only.
  ## Testing
Verified post-edit with `grep -c '^\* \|^ \* \|^ \* '` over the seven
core `.md` files; all return `0` asterisk-bulleted lines.
  No code changes; no test-suite impact.  

## Agent Mode
   
- [ ] Warp Agent Mode - This PR was created via Warp's AI Agent Mode
@timomak
timomak merged commit 8ff2eac into master May 11, 2026
5 of 16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.