Centralize product docs links and fix broken UI URLs

[enzoames]

Summary

• Add shared docsUrl / Docs helpers in @agent-native/core/shared so product UI and templates stop hardcoding docs URLs.
• Retarget Settings, Team, onboarding, agent tabs, Dispatch, and template help links from broken Builder agent-native-* / relative /docs/... paths to live www.agent-native.com/docs pages.
• Fix soft-broken hashes (error tracking, clips browser logs/rewind/sharing, plan local-files, design docs).

Test plan

• Open Settings → Hosting / Database / File uploads / Authentication and confirm “Set up manually” docs links open the matching live docs pages (no 404).
• Open Team settings org/domain help links and confirm they land on organizations/auth/deployment docs.
• Spot-check Agent resources, Extensions, First-run onboarding, and Dispatch local-app docs links.
• Spot-check Analytics error/session docs, Clips share/browser-logs links, Design tweaks/import docs, Plan local-files docs.
• pnpm --filter @agent-native/core exec vitest run src/shared/docs-url.spec.ts src/client/agent-page/AgentTabsPage.spec.ts
• pnpm --filter @agent-native/dispatch exec vitest run src/components/create-app-popover.spec.tsx

Made with Cursor

[github-actions]

Here's a visual recap of what changed:

Open the full interactive recap

[builder-io-integration]

Builder reviewed your changes and found 1 potential issue 🟡

Review Details

Code Review Summary

PR #2819 centralizes outbound Agent Native documentation links in @agent-native/core/shared via docsUrl and named Docs helpers, then migrates Settings, organization, onboarding, agent, Dispatch, CLI, and template surfaces away from broken relative or legacy Builder URLs. The helper also standardizes absolute origins, fragments, and optional UTM parameters. The overall approach is sound: the shared API is small, exported through the package barrel, covered by focused tests, and the affected package/template consumers remain compatible.

Risk assessment: Standard. The change is primarily link routing and shared utility behavior, with broad user-facing reach but no auth, payment, data mutation, or API-contract changes.

Key Findings

• 🟡 MEDIUM — The Design tweaks help link drops its #tweaks section anchor and now opens the documentation page without the relevant section.
• No high-severity issues were found. A low-severity Clips share-page fragment regression was also identified and included for visibility; server-side review filtering may omit it under standard risk.

Positive notes: the migration removes many hardcoded origins, preserves UTM attribution in Settings, and adds targeted helper tests for slugs, hashes, and UTM parameters.

🧪 Browser testing: Will run after this review (PR touches UI code)

[builder-io-integration]

🟡 Tweaks help link drops its section anchor

The previous link targeted /docs/template-design#tweaks, but Docs.templateDesign() now emits only /docs/template-design. This help link is rendered beside the tweaks controls, so users are taken to the top of the design docs rather than the relevant section. Preserve the intended section destination with the correct hash or a named helper that includes it.

Additional Info

Found by 1 of 2 review agents; confirmed against the prior destination and current consumer context.

[enzoames]

#tweaks does not exist anymore in that docs page

[enzoames]

@builderio-bot why is the "CI / SSR cold-start" check failing and is it related to my changes

[builder-io-integration]

I found the actual cause. The failing check is "SSR cold-start smoke", specifically its plan template sub-test:

[ssr-smoke] plan: FAILED — import took 3225ms (budget 3000ms)
[ssr-smoke] 2 passed, 1 failed, 0 not measured (of 3).

It's not a crash — it's a 225ms timing-budget overrun (3225ms vs the 3000ms limit) importing the plan template's SSR handler. The better-sqlite3 "Could not locate the bindings file" messages you see right before it are pre-existing, non-fatal warnings from [db] Migration failed / Better Auth init — they're logged but caught, and don't cause the failure (this environment has no native module compiled for it, which is expected/handled).

Is it related to your changes? The only file your PR touches in the plan template is templates/plan/app/pages/PlansPage.tsx, where you replaced two hardcoded doc URL strings with calls to a new docsUrl() helper:

-const PLAN_DOCS_URL = "https://www.agent-native.com/docs/template-plan";
-const LOCAL_FILES_DOCS_URL = `${PLAN_DOCS_URL}#local-files`;
+const PLAN_DOCS_URL = docsUrl("template-plan");
+const LOCAL_FILES_DOCS_URL = docsUrl("template-plan-local-and-desktop", {
+  hash: "local-files",
+});

I checked the new docsUrl() helper (packages/core/src/shared/docs-url.ts) — it's a tiny, synchronous string/URL builder with no heavy imports or I/O, so it shouldn't meaningfully add to cold-start import time. A 225ms overrun on a 3-second budget is most consistent with CI runner variance/flakiness rather than a regression from this change — this kind of smoke test is timing-sensitive and can flip based on runner load.

My recommendation: re-run just that job (gh run rerun 31610913972 --job 94161834460) to see if it passes on a retry, which would confirm flakiness. Want me to trigger that rerun?

---

⠀
🟢 Diagnosed the CI failure: a timing-budget overrun in the plan template's SSR smoke test, not a functional break — not clearly caused by your docsUrl() change.

---

  

[steve8708]

awesome

[enzoames]

@builderio-bot can you rebase with main branch and fix any conflicts

[builder-io-integration]

The rebase resolved the conflict — mergeable is now MERGEABLE (BLOCKED just means required checks haven't finished/passed yet, not a conflict).

Rebased enzoames/changes-587 onto main, resolving three successive conflicts in packages/core/src/client/org/TeamPage.tsx (each one was the same WorkspaceUserGroup import from a new main commit colliding with your evolving Docs/docsUrl import across your 3 commits — resolved by keeping both sides each time, then dropping the now-unused Docs import in the final commit), ran oxfmt, verified no type errors, and force-pushed. The PR is conflict-free now; CI will need to re-run on the new commits.

---

⠀
🟢 Rebased onto main, resolved the TeamPage.tsx conflicts, and force-pushed — PR #2819 is now mergeable, pending CI.

---

  

[builder-io-integration]

Builder reviewed your changes and found 1 potential issue 🔴

Review Details

Code Review Summary

This incremental review evaluates PR #2819 at the latest head. The PR centralizes outbound Agent-Native documentation URLs in docsUrl() and updates links across Core, Dispatch, Skills, Analytics, Clips, Design, Plan, onboarding, and settings surfaces. The helper cleanly centralizes the public origin, optional UTM parameters, and section hashes, and the focused tests/builds pass.

Risk: Standard, because this is a shared package contract used by multiple published/runtime consumers and changes many user-facing navigation targets.

Key Findings

• 🔴 HIGH — Dispatch imports the newly added docsUrl named export from Core while its peer dependency still allows older Core versions that do not export it, creating a runtime/module-load compatibility break for valid existing installations.
• 🟡 MEDIUM/LOW — docsUrl() interpolates arbitrary slugs into a URL without encoding or constraining path syntax, allowing reserved characters or dot segments to alter the query/hash or escape /docs; this is not exercised by current tests.

The two independent code-review passes agreed on the Dispatch/Core compatibility issue. The unresolved TweaksPanel #tweaks anchor comment remains present and was intentionally skipped. The dev server was healthy, and source/network checks confirmed affected routes and docs destinations, but visual browser testing was blocked because Chrome automation tools were unavailable in every executor.

🧪 Browser testing: Attempted after review, but all 20 planned checks were blocked by unavailable browser automation tooling; re-run when Chrome tooling is restored.

[builder-io-integration]

🔴 Require the Core version that exports docsUrl

@agent-native/dispatch still declares @agent-native/core as >=0.8.0, but this new named import only exists in the Core release introduced by this PR. An existing consumer can therefore satisfy Dispatch's advertised peer range with an older Core and fail at module instantiation because the export is missing; raise the peer minimum to the compatible Core release or avoid requiring the new export.

Additional Info

Found by both independent code-review agents; the package peer range is packages/dispatch/package.json:113 and the new import is added on this diff line.

[enzoames]

@builderio-bot can you run run the CI builds, they are not passing but don't seem related to my changes

[builder-io-integration]

CI is re-running now on the new commit.

Summary: Confirmed the failures are not related to your changes. Every failing job (Typecheck, Build, Fast tests core/lane-3/lane-5, Security guards, Content DB PostgreSQL locking, Brain evals, Scaffold E2E, Plan E2E tests) died during pnpm install, hitting the same two transient infra issues:

• electron postinstall: TypeError: fetch failed / HTTPError: 503 downloading electron-v41.9.0-linux-x64.zip from GitHub releases
• ffmpeg-static install: Error: Failed to download ffmpeg

None of these touch your docsUrl diff. I couldn't trigger a re-run via the Actions API (token lacks actions:write for reruns), so I pushed an empty commit to kick off a fresh CI run — that will retry the downloads and should pass if the CDN has recovered.

---

⠀
🟢 Confirmed CI failures are unrelated CDN/network flakes in pnpm install, not your code; triggered a fresh CI run to retry.

[enzoames]

@builderio-bot can you run rebase my branch with main so that we can run the builds again. they keep failing for some reason.

[builder-io-integration]

Rebased enzoames/changes-587 onto the current main (no conflicts this time) and force-pushed. PR #2819 is MERGEABLE; CI is now running fresh on the new commits — BLOCKED just reflects checks still in progress.

---

⠀
🟢 Rebased onto latest main with no conflicts and pushed; fresh CI run is now in progress on PR #2819.

[builder-io-integration]

Builder reviewed your changes and has a few items to flag 🟡

Review Details

Code Review Summary

This incremental review covers the latest PR head. The new commits are CI/lint retriggers only; the underlying docsUrl() migration remains unchanged. Two independent balanced reviewers found no new confirmed regressions. One reviewer questioned the Clips Chrome-extension anchor, but I verified the live documentation contains browser-logs-with-the-chrome-extension, so that is not actionable.

Risk: Standard, because the change is a shared cross-package URL contract with broad UI reach. The two existing comments remain applicable and were intentionally skipped: TweaksPanel still omits the #tweaks anchor, and Dispatch still imports docsUrl while its peer range permits older Core versions.

The dev server is healthy and source/live-page checks passed where available. Browser verification was attempted again, but Chrome automation tools remain unavailable across all planner and executor sessions.

🧪 Browser testing: Attempted after review; all 20 planned checks were blocked by missing browser automation tooling and require a rerun when Chrome tools are restored.

[enzoames]

@builderio-bot can you run rebase my branch with main so that we can run the builds again.

[builder-io-integration]

Rebased cleanly onto latest main (no conflicts this time) and force-pushed. PR #2819 is MERGEABLE; CI is now running fresh on the new commits.

---

⠀
🟢 Rebased onto latest main and pushed; fresh CI run in progress on PR #2819.