Skip to content

feat(docs): point a lost agent somewhere useful from the 404 - #12599

Open
jd wants to merge 1 commit into
devs/jd/agentic-readiness/describe-site-schema-org-json-ld--dd84bc05from
devs/jd/agentic-readiness/point-lost-agent-somewhere-useful-404--bb77d582
Open

feat(docs): point a lost agent somewhere useful from the 404#12599
jd wants to merge 1 commit into
devs/jd/agentic-readiness/describe-site-schema-org-json-ld--dd84bc05from
devs/jd/agentic-readiness/point-lost-agent-somewhere-useful-404--bb77d582

Conversation

@jd

@jd jd commented Aug 28, 2026

Copy link
Copy Markdown
Member

The 404 offered a search box and a link home. That works for a person; an
agent that followed a dead link gets a page with nothing machine-readable on
it, and a 404 is the one page where it has no other context to work from.

Add a short recovery list: the documentation index, llms.txt, the sitemap,
the API reference and the OpenAPI document — plus a note that appending .md
to any URL, or sending Accept: text/markdown, returns the Markdown source.
Useful to a human who mistyped a URL too.

Depends-On: #12598

@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 28, 2026 13:26 Failure
This was referenced Aug 28, 2026
Open
Open
Open
Open
Open
@jd

jd commented Aug 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

This pull request is part of a Mergify stack:

# Pull Request Link
1 fix(seo): restore the homepage OpenGraph image #12593
2 fix(a11y): stop docset grids skipping a heading level #12594
3 feat(docs): publish the API description where machines look for it #12595
4 feat(docs): serve Markdown to clients that ask for it #12596
5 feat(docs): tell agents what Mergify is for in llms.txt #12597
6 feat(seo): describe the site with schema.org JSON-LD #12598
7 feat(docs): point a lost agent somewhere useful from the 404 #12599 👈

@jd jd mentioned this pull request Aug 28, 2026
Open
@mergify

mergify Bot commented Aug 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Merge Protections

🔴 3 of 7 protections blocking · waiting on 👀 reviews and ⛓️ dependency

Protection Waiting on
🔴 ⛓️ Depends-On Requirements ⛓️ dependency
🔴 👀 Review Requirements 👀 reviews
🔴 🔎 Reviews 👀 reviews
🟢 🤖 Continuous Integration —
🟢 Enforce conventional commit —
🟢 📕 PR description —
🟢 🚦 Auto-queue —

🔴 ⛓️ Depends-On Requirements

Waiting for

This rule is failing.

Requirement based on the presence of Depends-On in the body of the pull request

🔴 👀 Review Requirements

Waiting for

  • #approved-reviews-by >= 2
This rule is failing.
  • any of:
    • #approved-reviews-by >= 2
    • author = dependabot[bot]
    • author = renovate[bot]
    • all of:
      • author = mergify-ci-bot
      • -head ~= ^docs-agent/

🔴 🔎 Reviews

Waiting for

  • #review-requested = 0
This rule is failing.
  • #review-requested = 0
  • #changes-requested-reviews-by = 0
  • #review-threads-unresolved = 0
Show 4 satisfied protections

🟢 🤖 Continuous Integration

  • all of:
    • check-success = build
    • check-success = lint
    • check-success = test
    • any of:
      • check-success = test-broken-links
      • label = ignore-broken-links
    • any of:
      • check-success=Cloudflare Pages
      • -head-repo-full-name~=^Mergifyio/

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

  • title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 📕 PR description

  • body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

@mergify
mergify Bot requested a review from a team August 28, 2026 13:32
Copilot AI lite review requested due to automatic review settings August 28, 2026 13:33
@jd
jd force-pushed the devs/jd/agentic-readiness/point-lost-agent-somewhere-useful-404--bb77d582 branch from 4e0375e to af4b8b8 Compare August 28, 2026 13:33
@jd

jd commented Aug 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Revision history

# Type Changes Reason Date
1 initial 4e0375e 2026-08-28 13:33 UTC
2 rebase 4e0375e → af4b8b8 (rebase only) 2026-08-28 13:33 UTC
3 rebase af4b8b8 → 12b683f (rebase only) No content change: re-pushed to retrigger the Cloudflare Pages preview build, which failed on the previous SHA while the five earlier PRs in the stack deployed fine (suspected build-concurrency limit… 2026-08-28 13:38 UTC
4 content 12b683f → 26f0c28 Reword the 404 Markdown hint per review on #12599 2026-08-28 14:37 UTC
5 rebase 26f0c28 → db22260 (rebase only) 2026-08-28 15:09 UTC

@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 28, 2026 13:34 Failure
Copilot AI reviewed Aug 28, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Improves the 404 page to provide “next steps” for automated agents (and humans) by adding a small, machine-readable recovery navigation section alongside the existing search and home link.

Changes:

  • Add a “Where to look next” recovery <nav> with links to index, llms.txt, sitemap, API reference, and OpenAPI.
  • Add scoped CSS styles for the recovery section on the 404 page.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread src/pages/404.astro
@jd
jd force-pushed the devs/jd/agentic-readiness/point-lost-agent-somewhere-useful-404--bb77d582 branch from af4b8b8 to 12b683f Compare August 28, 2026 13:38
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 28, 2026 13:39 Failure
@jd
jd marked this pull request as ready for review August 28, 2026 14:09
@jd
jd force-pushed the devs/jd/agentic-readiness/point-lost-agent-somewhere-useful-404--bb77d582 branch from 12b683f to 26f0c28 Compare August 28, 2026 14:37
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 28, 2026 14:38 Failure
@jd
feat(docs): point a lost agent somewhere useful from the 404
db22260 
The 404 offered a search box and a link home. That works for a person; an
agent that followed a dead link gets a page with nothing machine-readable on
it, and a 404 is the one page where it has no other context to work from.

Add a short recovery list: the documentation index, `llms.txt`, the sitemap,
the API reference and the OpenAPI document — plus a note that appending `.md`
to any URL, or sending `Accept: text/markdown`, returns the Markdown source.
Useful to a human who mistyped a URL too.

Change-Id: Ibb77d5829360bfb5b6ae4b1768362c860f5670d8
@jd
jd force-pushed the devs/jd/agentic-readiness/point-lost-agent-somewhere-useful-404--bb77d582 branch from 26f0c28 to db22260 Compare August 28, 2026 15:09
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 28, 2026 15:10 Failure
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

At least 0 approving reviews are required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jd