docs: signpost the hosted MindsHub API from the Cowork docs pages (ENG-1745)

[Dav1dF]

Linear: ENG-1745

Description

docs.mindshub.ai is the address a developer guesses when they are looking for our hosted API, and right now it only shows Cowork content. Its largest page, api.html, is a REST reference for the local Cowork server at http://localhost:26866/api/v1 with no auth header anywhere, so it reads like a cloud API reference when it is not.

This PR only adds a signpost. Nothing moves, nothing is removed, no redirect is introduced.

All four pages (index.html, setup.html, use-cases.html, api.html):

• A banner strip directly under the nav: "These pages document Minds Cowork, the app and local server you run yourself. For the hosted MindsHub API at api.mindshub.ai, with API keys, see the hosted MindsHub API docs."
• A Hosted API ↗ item in the nav row, next to GitHub ↗.

api.html also gets a callout above the first endpoint (above the ERD and the base URL strip) saying the page documents the local Cowork server, that it takes no API key and is not reachable over the internet, and that the hosted MindsHub API at api.mindshub.ai is a different service with its own keys and its own docs.

20 Aug update: the link target changed, and so did the plan around it

The domain decision reversed after Costa's review (ENG-1744). The developer docs go to docs.mindshub.ai/inference, not console.mindshub.ai/docs, and these four pages move to docs.mindshub.ai/cowork so neither product is a lodger in the other's house.

Two consequences for this PR:

• The nine link targets now point at https://docs.mindshub.ai/inference/ (62753a9), the final address, rather than the github.io path they would have had to be corrected off later.
• The /cowork move needs no change in this repo. The nesting happens at the edge, and every internal link on these pages is relative (href="api.html"), so they all resolve correctly one path deeper with no content edit and no change to deploy_docs.yml. There is no window where the live hostname 404s while files are moved around.

Held until the route is live

docs.mindshub.ai/inference does not resolve until the edge route lands, rehearsed on docs-next.mindshub.ai first. Merging before then would ship a banner whose link 404s, which is worse than the dead end it fixes.

Ready to merge the moment that route is live. The alternative was to ship now pointing at github.io and correct it afterwards; that is a link we would knowingly have to come back to, which is the kind of debt this audit keeps finding.

Heads up before merge

Merging this deploys straight to the public docs.mindshub.ai. .github/workflows/deploy_docs.yml publishes docs/ to GitHub Pages on any push to main that touches docs/**. So this wants a look before merge, not after.

One thing to know if you are reviewing after the cutover: ENG-1744 takes docs.mindshub.ai off this repo as a GitHub Pages custom domain, so the site then serves at mindsdb.github.io/mindshub/ and reaches the public hostname through Cloudflare. The deploy workflow is unchanged either way.

Type of change

• 📄 Documentation change (content only, no code paths touched)

Verification

Done locally with headless Chrome over the four files, at 390px (mobile, emulated), 660px and 1280px:

• The banner is above the fold on every page at every width. Its bottom edge sits at 188px at mobile width and 134px at 660px, so no scrolling is needed to see it.
• No horizontal overflow at any width (scrollWidth == clientWidth at 390 and 660). The mobile hamburger still behaves as before, and the banner sits outside it so it is visible without opening the menu.
• HTML tag balance checked on all four files: no unclosed or mismatched tags.
• Diff is insertions only apart from the link retarget. Every existing URL still serves what it served before.
• Link targets re-counted after the retarget: 9 references to docs.mindshub.ai/inference, 0 remaining to mindsdb.github.io/mindshub_inference.

Still owed, and it is why this is not merged yet: the link target returns 200. It cannot until the route exists.

After merge, worth confirming on the live hostname: all four pages still 200 under /cowork/, the banner shows, the four legacy root paths 301 into /cowork/, and the signpost link resolves.

Out of scope

Retiring or redirecting the hostname: not happening, docs.mindshub.ai keeps Cowork's docs under the same ownership and ENG-1747 is cancelled. Also out of scope: re-sorting the local API reference onto the developer docs, restyling onto the Minds design system, and the stale Mintlify docs/docs.json beside these files. The edge route, the Pages custom-domain removal and the legacy-path 301s all belong to ENG-1744.

[Dav1dF]

Costa, review welcome now — please do not merge yet, and this one matters more than usual.

Merging pushes straight to the public docs.mindshub.ai: deploy_docs.yml publishes docs/ to GitHub Pages on any push to main touching docs/**. Until your edge route is live, the banner this adds would link to a 404.

The nine link targets now point at https://docs.mindshub.ai/inference/, the final address, rather than the github.io path they would have had to be corrected off later.

One thing you may not expect, and it is good news for your build: the /cowork move needs no change in this repo at all. Every internal link on these four pages is relative, so they resolve correctly one path deeper once the edge serves them under /cowork/. No workflow change, no content edit, and no window where the live hostname 404s while files move.

The one repo-settings step that is yours: taking docs.mindshub.ai off this repo as a Pages custom domain before Cloudflare fronts the hostname. Skip it and the address loops. Detail on ENG-1744.

[C0staTin]

@Dav1dF
Reviewed. The idea is right and the substance — banner, callout, nav link — is well built and low-risk. Holding until /inference resolves is the correct call; I confirmed that target 404s right now.

Things that check out before I get to the problems: your counts are exact (9 links to /inference/, 0 leftover github.io refs). All eight design tokens the new CSS uses are defined identically in all four :root blocks, so no silent fallbacks on any page. rgba(34,211,238,0.30) is --accent at 30% alpha and no token exists for that value, so hardcoding it is fine. CI is green on all four checks. Retargeting to the final address rather than shipping a known-temporary github.io path was the right instinct.

Four findings, first two worth fixing before merge.

1. The nav visually breaks between 641px and 718px, and it's a new regression

I measured the real nav with this PR's exact markup and CSS injected. The row now needs a 719px minimum viewport: 79px back link + 117px brand + 411px links + 64px of gaps + 48px padding. The hamburger doesn't take over until ≤640px. That leaves a ~78px band where the nav has to squeeze.

At 660px, one of the three widths in the Verification section:

	main today	With this PR
Brand "Minds Cowork"	18px, one line	35px, wrapped to two lines
Every nav link	21px, one line	42px, all wrapped

So "MINDS / COWORK" stacks, and the links wrap inside a bar that's still fixed at 52px tall.

The reason this slipped through is worth naming, because it isn't carelessness: the check used was scrollWidth == clientWidth, and that genuinely passes at 660px — I re-ran it. The failure here is text wrapping vertically inside a fixed-height bar, which a horizontal-overflow assertion structurally cannot detect. The method was sound for the banner, which is why it worked there; it just can't see this class of bug. Anything that changes nav row width needs a per-item height or line-count check instead.

Cheapest fix: raise the collapse breakpoint from 640px to ~760px in all four files.

2. ← All docs points somewhere wrong in two of the three states

It's href="/", and the code comment describes it as the chooser page at the root of the hostname — which doesn't exist yet. Verified all three:

• Today: docs.mindshub.ai/ serves the Cowork index (<title>Minds Cowork — Docs</title>). On index.html that makes it a self-link, sitting immediately left of a Docs link already carrying class="active" for the current page. Two controls, same URL, one of them labelled "back".
• After ENG-1744 drops the Pages custom domain and the origin serves at mindsdb.github.io/mindshub/, / resolves to mindsdb.github.io/ — which 404s. Confirmed with a request.
• Correct only once the edge serves a chooser at the hostname root.

Worth deciding whether this ships now at all, or waits for the chooser it's pointing at.

3. The description and the 22:32 comment are both stale

Both predate f97ac04d and b7f84a26, which landed the back control about 1.5h later. Two consequences:

• The comment says every internal link on these pages is relative, so /cowork needs no change in this repo. True when written; href="/" is absolute, so it no longer holds — that one link does not follow the pages a path deeper.
• The Verification section doesn't mention the back control at all — it only covers the banner. Since it's the section a reviewer leans on, please re-run it across all four files with the back control in place and update it.

4. Smaller things

• Hosted API ↗ opens in a new tab; the genuinely external GitHub ↗ beside it doesn't. Post-cutover the hosted docs are the same hostname, so target="_blank" is the wrong way round on both counts.
• .nav-up:hover sets colour but doesn't reset the global a:hover { opacity: 0.8 }, while .nav-links a:hover explicitly does. The back link hovers dimmer than its neighbours.
• New copy says "Minds Cowork" while the PR title says "MindsHub". Fine to keep matching the existing brand string, but let's make that a decision rather than an inheritance — public docs are the surface where the first-mention convention matters most.

---

Not approving yet on the strength of 1 and 2, both small. Since the merge is already gated on the edge route there's no time pressure — the breakpoint bump and a decision on ← All docs fit comfortably in that window.

[Dav1dF]

Costa — findings 1, 3 and 4 fixed in f1d75e5. Finding 2 has an answer rather than a fix, below.

1. The nav wrapping between 641 and 718

Right, and the diagnosis is worth more than the bug. Breakpoint raised 640 to 760 in all four files; the two other 640px queries are content grids and are untouched.

The verifier has been fixed too, because it would have passed this. I built a cutover verification script tonight (mindshub_inference#442) around exactly the assertion you identified as blind: scrollWidth == clientWidth.

First attempt at fixing it was wrong in a way worth recording: counting getClientRects() detects a wrapped inline box, but nav links are flex items, which are blockified and report one rect however much their text wraps. It passed on a nav that was visibly broken.

What works is differential — record every nav item's height at a 1400px reference width, flag any that grew at a narrower one. Against your files it reproduces your numbers exactly:

FAIL  /cowork/ at 660px  (MINDS COWORK 18->35px; Docs 21->42px; Setup 21->42px; Use Cases 21->42px)

18 to 35 and 21 to 42, the same figures you measured by hand. Clears after the breakpoint change. The width set now includes 640, 660, 700 and 1024, because the old 390/768 pair stepped straight over the band the bug lived in.

And the script was caching its own results, so a re-run after the fix reported the state before it. Network.setCacheDisabled now runs for the session. In a real cutover that would have reported the old site as the new one.

2. Where ← All docs points

Your three states are correct. My answer is that the third one is the only one that ships.

The root becomes a real chooser page under mindshub_inference#442 — the same landing page you asked for on website#113, which existed before your review but which you had no way of knowing about. So href="/" is correct at cutover.

The middle state you describe, / resolving to mindsdb.github.io/ and 404ing, only happens if someone reaches these files at the raw origin. Through the edge, which is the only way a reader gets here after cutover, / is the chooser. That said, your point stands that the origin is briefly reachable and wrong during the window, which is an argument for keeping this PR gated where it already is.

Not shipping it before the chooser. Both are gated on the same route.

3. Stale description

Fair, and I have rewritten it below with the back control included and the verification re-run across all four files.

4. Smaller things

Hosted API no longer opens in a new tab and drops the arrow — after cutover it is the same hostname, so the arrow claimed external and the new tab treated a sibling doc set as a departure. The genuinely external GitHub link keeps both.

.nav-up:hover now resets the global opacity: 0.8, matching .nav-links a:hover.

On the brand string: agreed it should be a decision. These pages document Minds Cowork, the product, so "Minds Cowork" is right in the copy; "MindsHub" in the PR title is the company-level name and is what is wrong. Leaving the page copy as is.