Point download entry points at artifacts instead of descriptions

[cesartevisual]

Fixes DES-312 — https://linear.app/peridio/issue/DES-312/fix-download-entry-points-that-resolve-to-descriptions-instead-of

The report

The Getting Started with Jetson page does not link to downloads at all, and the Avocado CLI link resolves to a description of what Avocado CLI is rather than to where to get it.

Both halves check out, and the pattern is wider than the one page.

Root cause

a3d4eae retired the docs "Download & Install" page and redirected it to the Desktop overview. From then on a URL literally named download resolved to prose about the app, and the acquisition links in the guides were all written against overview pages.

What was wrong

Where	Link	Landed on
shared/HostPrerequisites.tsx ×2	"install the Avocado CLI"	/avocado-cli/overview — describes the CLI, offers no way to get it, not even an inline link to the install page
shared/HostPrerequisites.tsx	"install Avocado Desktop"	/avocado-desktop/overview
28 generated references/*.mdx	same CLI prerequisite	docs.peridio.com/guides/avocado-cli/overview — 404, the /guides/ prefix was retired
getting-started/index.mdx	CTA "Avocado Desktop"	/avocado-desktop/overview
redirects	/developer-reference/getting-started/download	/avocado-desktop/overview
avocado-desktop/overview.mdx ×2	"Download →" / "macOS release"	peridio.com/avocado-os#downloads, the pre-/downloads anchor

Nothing on the docs site linked to peridio.com/downloads anywhere — grep returned zero hits.

What changed

• HostPrerequisites is the single component all four getting-started surfaces render (Jetson, QEMU, Raspberry Pi, and the Any-Supported-Target selector), so that is where the fix lands rather than in four call sites: both CLI links now resolve to the installation page, "install Avocado Desktop" resolves to the download, and the artifact list is named alongside them.
• The 28 generated reference guides are fixed in sync-references.js, not in the files. They are gitignored build output generated from avocado-linux/references, so editing them does not persist, and we have read-only access upstream. The rewrite sits next to the existing relative-link pass — same class of problem, same seam — so it survives every resync and lapses on its own if upstream is corrected.
• /getting-started/download now redirects to the CLI installation page.
• Desktop acquisition links moved to /downloads#desktop.
• The CLI overview page now says where to get the CLI, so the links that legitimately point at it for description no longer dead-end.
• The MCP prerequisite offers the install page directly instead of routing through the getting-started index.

Left alone deliberately: the tool-choice links in provisioning.md and mcp/installation.md point at overview pages to say what a tool is, which is the right destination for those sentences — and both overviews now route onward to acquisition.

Verification

• npm run build passes, including Docusaurus strict broken-link checking.
• Every prerequisite-style CLI link in the built output resolves to installation; none remain on overview. The avocado-cli/overview hits that remain in the build are menu__link sidebar nav, which is correct.
• All four getting-started surfaces reach /downloads — any-target via the selector, on target selection.
• npm run lint, npm run typecheck, npm run format clean.
• Confirmed the sync rule fires on a real npm run sync-references: 28 × repointed 1 CLI link(s) → installation.

⚠️ Merge order

The peridio.com/downloads links 404 until peridio/apex#120 ships that page. This PR must land after it.

Note on red CI

checks.yml and the CodeQL Analyze jobs fail in 3–5 seconds with zero steps executed, which is a job that never started rather than a check that ran. This is pre-existing and repo-wide: every PR-triggered Checks run in peridio/docs has failed since 2026-08-17 13:43 UTC, including on the unrelated developer-reference/device-tree-overlays branch; the last PR-branch success was 2026-08-15. GitHub status is operational, so it looks like an org-level Actions/permissions/quota change. Not caused by this diff — the equivalent checks all pass locally. Worth a separate issue.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR updates documentation and link-rewrite tooling so “install/download Avocado CLI/Desktop” links resolve to actual acquisition pages (installation/downloads) instead of overview/prose pages, and avoids 404s from the retired /guides/ prefix.

Changes:

• Update various docs/components to link to Avocado CLI installation and peridio.com Downloads anchors.
• Add a sync-time rewrite pass to repoint absolute https://docs.peridio.com/... acquisition links (including retired /guides/ URLs).
• Update a Docusaurus redirect so the old “download” path lands on the CLI installation page.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/src/components/shared/HostPrerequisites.tsx	Updates prereq links to CLI installation and peridio.com download anchors; adds Downloads note.
src/scripts/sync-references.js	Adds rewrite rules for absolute acquisition links during reference sync.
src/docusaurus.config.js	Redirects old download path to CLI installation and clarifies rationale in comments.
src/docs-overview/avocado-desktop/overview.mdx	Updates Desktop download CTA links to peridio.com Downloads.
src/docs-guides/mcp/installation.md	Points MCP prereq to CLI installation + Getting Started.
src/docs-guides/getting-started/index.mdx	Adjusts Desktop CTA label copy.
src/docs-guides/avocado-cli/overview.md	Adds a tip directing readers to installation/downloads.
src/docs-guides/avocado-cli/installation.md	Adds Downloads option + Desktop bundle note.

---

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/scripts/sync-references.js:132

• These rewrites won’t match common URL variants like a trailing slash (e.g. /overview/) or the no-trailing-slash prefix form (e.g. https://docs.peridio.com/guides without the final /). Since the intent is to prevent 404s in generated references, the regexes should tolerate those variants (e.g., make the trailing slash optional and match both prefix forms) so the rewrite is reliably applied.

const ACQUISITION_REWRITES = [
  {
    from: /https:\/\/docs\.peridio\.com\/guides\//g,
    to: 'https://docs.peridio.com/developer-reference/',
  },
  {
    from: /https:\/\/docs\.peridio\.com\/developer-reference\/avocado-cli\/overview/g,
    to: 'https://docs.peridio.com/developer-reference/avocado-cli/installation',
  },
]

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/scripts/sync-references.js:144

• This duplicates the same fenced-code segmentation approach used in rewriteRelativeLinks, and then adds another layer of bespoke capture-group interpolation. Consider extracting a shared helper that applies a list of rewrite rules only to non-fenced segments (so both functions share the same implementation), and represent to as either a native replacement string (letting JS handle $1 etc.) or as a (match, ...groups) => string function to avoid the manual $n interpolation logic.

function rewriteAcquisitionLinks(body) {
  let count = 0
  // Same fenced-code split as rewriteRelativeLinks: a URL shown inside an
  // example is being quoted, not offered as a link to follow.
  const segments = body.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~)/g)

src/scripts/sync-references.js:138

• The first rewrite only matches when the absolute prefix includes a trailing slash (e.g. .../developer-reference/). If any generated content contains https://docs.peridio.com/developer-reference (no trailing slash) before a path delimiter, it won’t be rewritten and may leave a broken absolute link behind. Adjust the regex to also match the no-trailing-slash form (while preserving correct path joining) so the repointing is complete.

const ACQUISITION_REWRITES = [
  {
    from: /https:\/\/docs\.peridio\.com\/(?:guides|developer-reference)\//g,
    to: '/developer-reference/',
  },
  {
    from: /\/developer-reference\/avocado-cli\/overview\/?([?#][^)\s]*)?(?=[)\s]|$)/g,
    to: '/developer-reference/avocado-cli/installation$1',
  },
]

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/scripts/sync-references.js:135

• The overview → installation rewrite only triggers when the URL is followed by ) / whitespace / end-of-string. This misses common terminators like > (Markdown autolinks: <...>) and quotes (HTML: href=\"...\"), so some overview URLs may not be repointed. Consider broadening the lookahead to include > and quote delimiters so the rewrite applies in those contexts too.

    from: /\/developer-reference\/avocado-cli\/overview\/?([?#][^)\s]*)?(?=[)\s]|$)/g,
    to: '/developer-reference/avocado-cli/installation$1',

src/scripts/sync-references.js:174

• acquisitionCount is incremented per regex match across all rules, so a single link can be counted multiple times (e.g., domain-prefix rewrite + overview→installation rewrite). This makes the log message ambiguous. Consider either logging per-rule counts, or adjust the message to clarify it’s counting 'matches/replacements' rather than distinct links.

  const { body: repointed, count: acquisitionCount } = rewriteAcquisitionLinks(rewritten)
  if (acquisitionCount > 0) {
    console.log(`  ${name}: applied ${acquisitionCount} acquisition rewrite(s)`)
  }

src/scripts/sync-references.js:144

• This duplicates the fenced-code segmentation approach used elsewhere (notably rewriteRelativeLinks). To avoid the two functions drifting (e.g., adding support for additional fence styles in one but not the other), consider extracting this segmentation into a shared helper and reuse it in both rewrite passes.

  // Same fenced-code split as rewriteRelativeLinks: a URL shown inside an
  // example is being quoted, not offered as a link to follow.
  const segments = body.split(/(```[\s\S]*?```|~~~[\s\S]*?~~~)/g)