diff --git a/.ai/plans/portal-subpath-hosting.md b/.ai/plans/portal-subpath-hosting.md
new file mode 100644
index 000000000..ffb672f74
--- /dev/null
+++ b/.ai/plans/portal-subpath-hosting.md
@@ -0,0 +1,1071 @@
+# Plan: hosting the portal under a sub-path
+
+Status: designed 2026-09-29 on `saeedjamshaid/portal-subpath-hosting`, cut from `origin/dev` at
+`74ad5d2e`. Tracks apimatic-io#2275, whose design this follows except where section 14 says
+otherwise. Reviewed four times on 2026-09-29; section 15 records what each round changed.
+
+Implemented in steps 1–4 on 2026-09-29 and 30, and opened as apimatic/apimatic-cli#411, which
+supersedes #407. Step 5 (section 7) is the follow-up outside this repository.
+
+## 1. Goal and scope
+
+`portal.site.url` may carry a path, such as `https://acme.github.io/docs` for a GitHub Pages
+project site or a docs prefix behind a reverse proxy. When it does, the portal works when it is
+served at that path: its pages, assets, client navigation, search, downloads, SEO files and
+`portal serve`.
+
+- **In scope:** the path comes from `site.url`, and only from there.
+- **Out of scope** (decided 2026-09-29; section 12 says why):
+  - a path given without `site.url`, as a setting or a flag;
+  - one build that works at whatever path it is deployed to.
+- **Invariant:** a portal whose `site.url` has no path, or that has no `site.url`, emits the same
+  pages, files and addresses as today. The content hashes in chunk names are the only difference,
+  apart from the image fixes of 5.10 and 5.12, which apply at the root too: reference-style images
+  are bundled and checked like inline ones, an image in a description no longer fails its page,
+  and search results show no image from a description.
+
+**Terms:**
+- A **portal-relative path** is a page's path from the portal's own root (`/guides/intro`).
+- The **base path** is where the portal is mounted (`/docs`, or `''` at a host's root).
+- The **site address** is the origin plus the base path (`https://acme.github.io/docs`).
+- The **served path** is the base path plus the portal-relative path.
+
+The comments that say "site-relative" today (`portal-config.ts:29,31`, `portal-types.ts`) are
+changed to "portal-relative". `StaticAsset.siteUrl()`, which returns a portal-relative path, is
+renamed `portalPath()` (4.3).
+
+## 2. Decisions (2026-09-29)
+
+1. **Where the path comes from.** It is the path of `site.url`. Without `site.url` the portal is
+   at the root of its host, as today.
+2. **Vite's `base` is the one switch.** TanStack Start derives the rest from it:
+   - the router basepath (`deriveRouterBasepath`, start-plugin-core `planning.js:14`);
+   - every page's asset URLs (the Start manifest is built from `publicBase`);
+   - the prerender, which fetches `withBase(page)` and writes `withoutBase(file)` (`prerender.js:78,92`).
+
+   Fumadocs' links are TanStack Router links (`fumadocs-core/dist/framework/tanstack.js`), which
+   already carry the basepath. So `docsRoute` stays `/`; a Fumadocs `baseUrl` would double every
+   link (`/docs/docs/guides`). TanStack's maintainer puts the split the same way on #4888: Vite
+   `base` owns assets, and the router basepath owns routes.
+3. **One source for the path: the CLI's `SiteAddress`** (revised 2026-10-08, section 15).
+   - `siteUrl` in `portal.identity.json` becomes the site address.
+   - `portal.config.json` carries `base`, the address's `path()`, and `vite.config.ts` takes it as
+     it is. The CLI writes both files from one `SiteAddress` when it prepares the build.
+   - Not in `portal.identity.json`: the browser imports that file whole, and it already has the
+     base as `import.meta.env.BASE_URL` (decision 4).
+   - Until 2026-10-08 the template worked `base` out of `siteUrl` a second time, in `viteBase`, and
+     a contract test held that to `SiteAddress.path()`.
+4. **Portal-relative strings are prefixed in the template.** The strings the router never sees
+   go through one helper, `withBasePath()`, which reads `import.meta.env.BASE_URL`.
+   - The template is the layer that already adds the base to the router's URLs. Prefixing in the
+     CLI would give the same rule a second home.
+   - `BASE_URL` is the value Vite actually applied. Under `portal serve`, an edit that moves the
+     path rewrites `siteUrl` while Vite keeps its startup base (decision 9), so reading `siteUrl`
+     there would disagree with the assets.
+   - The code that runs in Node passes the base explicitly: the prerender list, the dev
+     downloads middleware and the cache plugin. So the prefix rule has one home.
+5. **`siteUrl` carries the whole site address.** `seo.ts` and `sitemap.server.ts` concatenate
+   `siteUrl + pageUrl`, so these follow with no code change: canonical, `og:url`, the sitemap, and
+   the plugin's Markdown install command.
+6. **A base path that collides with page paths works; nothing is refused.** A collision is a
+   page whose portal-relative path starts with the base, such as `/api` against the API reference,
+   or `/docs` against a `docs/` folder. Two things break on one today, and each gets a fix in the
+   template:
+   - **The prerender.** ufo's `withBase` leaves a path that already starts with the base unchanged
+     (ufo 1.6.4), so `/docs/intro` under `/docs` is fetched as `/intro` and 404s. Fixed by giving
+     TanStack the served paths (5.7): `withBase` then leaves every one alone, and `withoutBase`
+     strips the base exactly once for the filename.
+   - **Search results.** They navigate through `router.navigate({ href })`, whose input rewrite
+     strips a leading base, case-insensitively (`router-core router.js:261-265`, `rewrite.js`).
+     Fixed by handing the dialog served URLs (5.2), so the rewrite strips exactly once. The dialog
+     is the only place in Fumadocs that navigates by `href`.
+
+   Router links (`to`) and direct loads already strip once, correctly. All of this was measured
+   under base `/api`, in the worst case (section 3).
+7. **No `robots.txt` under a path.** Crawlers read it only from the root of a host. The Next
+   Steps note says where the sitemap is instead.
+8. **The static server-function cache URL is rewritten in the client build** by a Vite plugin in
+   the template, until TanStack/router#6152 ships. The rejected alternatives:
+   - a pnpm patch, which never reaches users who install the CLI with npm;
+   - a copy of the middleware, which needs `@tanstack/start-client-core` and `seroval` as direct
+     dependencies pinned to Start's versions;
+   - a wrapper round the global `fetch`, which changes a browser global for every caller.
+
+   TanStack offers no option for this URL (`staticFunctionMiddleware.ts:50` on `main`), and the
+   latest release is 1.167.38.
+9. **`portal serve` runs under the base**, as the build does. The 2026-09-29 dev probe found
+   routing, the `/docs/_serverFn/` page data, HMR and live edits all working there, and it surfaced
+   the same missing prefixes a build shows.
+   - It reports and waits on the address with its trailing slash.
+   - An edit that moves the path is applied, so canonical links follow, but the preview keeps
+     serving the old path until it restarts. The restart list in the Live preview note names it.
+     There is no notice of its own: the path is set once, and a notice would mean reworking the
+     static-directory one into a keyed prompt, which is not worth it for so rare an edit.
+10. **Links in the Markdown copies.**
+    - **In scope:** the links we write into the SDK pages' Markdown copies get the base (5.2).
+    - **Deferred to a follow-up** (decided 2026-09-29): the links authors write keep their
+      spelling in the copies. The reasons:
+      - It is the one part whose mechanism is still open (section 9).
+      - It affects only the copies handed to AI assistants; the HTML already follows the base.
+      - No portal is hosted under a path yet.
+      - It would couple us to another Fumadocs internal.
+11. **The quickstart note stays as #403 left it.** The change is carried by:
+    - the schema description;
+    - the validation messages;
+    - the Next Steps note of `portal generate`;
+    - the README.
+
+## 3. What was verified (2026-09-29)
+
+This covers the installed versions: Vite 8.2.2, @tanstack/react-start 1.168.50, start-plugin-core
+1.171.40, router-core 1.171.28, start-static-server-functions 1.167.33, fumadocs-core/ui 16.15.15,
+fumadocs-mdx 15.4.0. **Measured** means it was built or run; **read** means it was read in the
+installed source.
+
+**Measured: the `default` fixture built with Vite `base: '/docs/'`, served at `/docs`, and driven
+in headless Chrome.** In the fixes column, the `/__tsr/` fix was a hand-written fetch wrapper; the
+planned plugin was verified afterwards (see the next list).
+
+| | `base` only | `base` + search, `/__tsr/` and logo fixes |
+|---|---|---|
+| First page load | works | works |
+| Client navigation | the 404 page: `/__tsr/staticServerFnCache/*.json` 404s | works |
+| Search | no results: `/api/search.json` 404s | works |
+| Logo, favicon | 404 | work |
+| Failed requests | 5 | 0 |
+
+**Measured, with the planned plugin (5.6) in place of the fetch wrapper:**
+- Picking a search result navigates to `/docs/api/…/Calculate`, and its cache fetch answers 200.
+- An unknown deep link served through `404.html` shows the not-found page, with `/docs/` links.
+- Cache files are written to `dist/client/__tsr/`.
+
+**Measured: a colliding base.**
+- `base: '/api/'` as things stand fails the build (`Failed to fetch /api/search.json: Not Found`).
+- With served paths handed to the prerender and served URLs handed to the search dialog, it
+  builds, and the output layout is unchanged: `api/search.json` and
+  `api/<spec>/…/Calculate/index.html` are at the output's root.
+- In the browser, all of these work:
+  - a direct load of `/api/api/…/Calculate`;
+  - a sidebar click to it and back;
+  - clicking a search result;
+  - a deep link through `404.html`.
+
+**Measured with step 3 in place (2026-09-30):** the `subpath` fixture built and served at
+`/api`, with `404.html` for missing paths, and driven in headless Chrome. All of these work:
+- first load, with the logo, the Markdown image and the favicon;
+- a click to a content page and to a colliding `/api/api/…` reference page, and back. Their
+  cached data comes from `/api/__tsr/…`, with status 200;
+- the popover's "View as Markdown" (`http://…/api/authentication.md`, 200), the prompt's page
+  address, and the copy button's fetch;
+- search, and a click on a result landing on the colliding page;
+- the SDK download (200), the plugin page's install command with `/api`, a direct load of a
+  reference page, and a missing page shown as the not-found page with `/api/` links.
+
+The only console output was also there on the root-hosted `default` build, driven the same way:
+- headless Chrome refusing the clipboard to an unfocused document;
+- the not-found page's own failed data lookup.
+
+**Measured with step 4 in place (2026-09-30):** `portal serve` on the `subpath` fixture, run as
+the action runs with only the account check and the artifacts stubbed, and driven in headless
+Chrome. It printed `http://127.0.0.1:<port>/api/`, and the restart list named the path. All of
+these work, with no failed request and no console output:
+- the printed link, with the logo, the Markdown image and the favicon;
+- a click to a content page and to a colliding `/api/api/…` reference page, and back, their data
+  from `/api/_serverFn/…`;
+- search, and a click on a result landing on the colliding page;
+- the SDK download and the plugin's (200, both under `/api/__downloads/`), and the install
+  command's address;
+- a missing page, shown as the not-found page.
+
+Moving the path to `/v2` in the running preview applied the edit (canonical links then carry
+`/v2`), while `/api/` went on being served and `/v2/` answered 404, as the restart list says.
+Stopping it the way CTRL+C does left no project directory behind.
+
+**Measured, other builds and runs:**
+- `base: './'` writes script URLs as `/./assets/…` (the host's root), CSS links relative to the
+  page, and a router basepath of `.`.
+- Vite dev with `base: '/docs/'`:
+  - `/docs/` answers 200, `/docs` answers 404 and `/` answers 302 to `/docs/`;
+  - routing, `/docs/_serverFn/…` page data, the HMR websocket (`ws://…/docs/`) and a live content
+    edit all work;
+  - `/docs/__downloads/plugin.zip` comes back as the SPA's HTML, while a bare `/__downloads/…`
+    answers with the zip, because our middleware runs ahead of Vite's base check.
+- In the `/docs/` build:
+  - pages are written to `dist/client/guides/intro/index.html`, and the host serves that
+    directory at `/docs`;
+  - router links, `<script>` and `<link>` tags, and images in user Markdown (turned into imports
+    by `remarkImage`) all carry `/docs/`;
+  - canonical keeps `https://docs.test/guides/intro` until `siteUrl` carries the path;
+  - `import.meta.env.BASE_URL` is `/docs/` in the SSR and `.server` chunks too.
+- Still root-relative, in the build and in dev:
+  - the logo and favicon;
+  - SDK downloads;
+  - the popover's "View as Markdown" link;
+  - the AI prompts' page URL;
+  - `llms.txt` links, and the SDK pages' Markdown copies;
+  - an author's `[auth](/authentication)` in a page's `.md` copy and in `llms-full.txt`. Its HTML
+    link is `/docs/authentication`.
+
+**Read in source:**
+- `llms()` writes `node.url` and has no base option. It takes a loader and reads only
+  `getPageTree`, `getNodePage`, `getNodeMeta` and `_i18n`; `getNodePage` goes by `$ref`
+  (`dynamic-CSrl9w26.js:756`).
+- `MarkdownCopyButton` prefixes its URL (`page-actions.js:17`). `ViewOptionsPopover` renders plain
+  `<a>` tags and stopped prefixing in ui 16.15.13 (fuma-nama/fumadocs PR #3572), still so in the
+  16.15.15 we install. Fixed in 16.15.17 (fuma-nama/fumadocs#3620, commit `6791d6f`) with the same
+  `withBasePath`, which leaves an address with a scheme as it is (`/^\w+:/`).
+- The search clients default to `join(BASE_PATH, '/api/search')` (core 16.10.6), but our explicit
+  `from` overrides that.
+- The search dialog's results are buttons that call `router.push(item.url)`
+  (`fumadocs-ui/dist/components/dialog/search.js:110`).
+- The static cache writer uses `path.join(TSS_CLIENT_OUTPUT_DIR, url)`. The client reads the cache
+  only when `NODE_ENV === 'production'`.
+- Fumadocs' `Link` renders any `scheme:` or `//` href as a plain `<a target="_blank">`
+  (`fumadocs-core/dist/link.js:5`). No router listens for clicks on plain `<a>` tags.
+
+## 4. CLI changes
+
+### 4.1 `SiteAddress`: `src/types/portal/config/site-address.ts` (new)
+
+- **`SiteAddress`**
+  - Holds the origin and the path.
+  - `static parse(value: unknown, path: string): Parsed<SiteAddress>`, as `Link` and
+    `StaticAsset` do.
+  - `toString()` is the site address with no trailing slash.
+  - `path()` is where the portal is served, in the form Vite's `base` takes: `'/'` at the root,
+    `'/docs/'` under a path. The build takes it from `portal.config.json` as Vite's `base` (5.1).
+  - `hasPath()` says whether it is under a path.
+  - `addressOf(portalPath)` is a portal-relative path's address on the host, so no caller
+    appends to `toString()` itself.
+- **No `BasePath` class.** It was planned for comparing a moved path under `portal serve`. With
+  that notice cut (4.5), Next Steps is the only user, and `SiteAddress` covers it.
+- **What `parse` checks, on the raw text before `new URL` normalises it:**
+  - it starts with `http://` or `https://`, in any case. `new URL` would take `https:x.test` as
+    `https://x.test/`, and the refused list in `portal-config.test.ts` holds that out;
+  - a host before the path, with no whitespace in it. `new URL` reads past the extra slash of
+    `https:///x.test/docs` and drops a tab from a host, both of which the schema refuses;
+  - no `?`, `#` or `\`;
+  - each path segment is one or more of `[A-Za-z0-9._~-]`, and is not `.` or `..`;
+  - no empty segment, except one trailing slash;
+  - the last segment does not end in `.html` or `.htm`, in any case. A home page's address
+    pasted whole would put every asset under `/docs/index.html/`. Only these two: `v1.0` is a path.
+
+  That keeps the same spelling in Vite's `base`, the router's prefix match, a host's folder name
+  and the canonical address, with nothing percent-encoded to disagree on. GitHub repository names
+  use only `[A-Za-z0-9._-]`, so every project site passes.
+- **The refusals.** Each one names what it found. `<path>` is the field's path, as in the other
+  `portal` messages.
+  - Not an `http(s)` address, or no host: "'<path>' must be the address the portal is hosted at,
+    for example 'https://docs.example.com' or 'https://example.com/docs'."
+  - A `?`, `#` or `\`: "'<path>' cannot contain '?'. Give the address the portal is hosted at,
+    for example 'https://example.com/docs'." The message names the character that was found.
+  - A segment outside the rule: "'<path>' has 'my docs' in its path. Each part between '/'s can
+    use only letters, digits, '.', '_', '~' and '-', and cannot be '.' or '..'."
+  - An empty segment: "'<path>' has an empty part ('//') in its path."
+  - A page: "'<path>' ends in 'index.html', which names a page. Give the address the portal is
+    hosted at, for example 'https://example.com/docs'." The message names the last segment.
+
+### 4.2 `SiteConfig` (`src/types/portal/config/site-config.ts`)
+
+- It holds `SiteAddress | null`. `validUrl` and `parseOrigin` go, replaced by
+  `SiteAddress.parse`.
+- `origin()` becomes `siteAddress(): SiteAddress | null`, beside `siteName()` and
+  `siteDescription()`, and `toJSON()` writes the address.
+- The comment above the old check goes. `SiteAddress` owns the rule.
+
+### 4.3 `PortalConfig` (`src/types/portal/portal-config.ts`)
+
+- `identity().siteUrl` is `site.siteAddress()?.toString() ?? null`.
+- New `siteAddress(): SiteAddress | null`, for Next Steps (4.6). `generate.ts` reaches it through
+  the `source` that `onPrepared` already receives (`PortalSource.config`).
+- The comment on `PortalIdentity.siteUrl`, and on the template's `Portal.siteUrl`, becomes "The
+  site address, with no trailing slash."
+- `StaticAsset.siteUrl()` (`static-asset.ts:55`) is renamed `portalPath()`, so `siteUrl` means
+  only the site address. It is called at `portal-config.ts:118-119` and in `portal-config.test.ts`.
+
+### 4.4 `apimatic.schema.json`
+
+- The `site.url` pattern becomes
+  `^\s*[hH][tT][tT][pP][sS]?://[^\s/?#\\]+(?:/(?!\.{1,2}(?:/|\s*$))(?![A-Za-z0-9._~-]*\.[hH][tT][mM][lL]?/?\s*$)[A-Za-z0-9._~-]+)*/?\s*$`.
+  The second lookahead refuses a last segment that names a page (4.1).
+- The description: "The address the portal is hosted at, for example 'https://docs.example.com'
+  or 'https://example.com/docs'."
+- `test/types/apimatic-config/schema.test.ts` runs the pattern and `SiteAddress.parse` over one
+  table. The table includes `docs?`, `docs#`, `docs\guides`, `docs/.`, `docs/..`, `docs//x`, `//docs`,
+  `%20`, a trailing slash and upper case. It also includes `https:///x.test/docs`, a tab in the host,
+  `docs/index.html`, `INDEX.HTM/`, `docs/v1.0` and `docs.htmlx`.
+
+### 4.5 `portal serve`
+
+- **The address keeps its slash.**
+  - `LOCAL_URL_PATTERN` (`portal-dev-server-service.ts:24`) keeps the trailing slash when the
+    address has a path. `http://127.0.0.1:5173/docs/` is then what is printed and what
+    `networkService.answers` waits on; the root case stays `http://127.0.0.1:5173`.
+  - Without this, `answers`, which counts any response, gets Vite's immediate 404 for `/docs`.
+    The #399 wait then ends before the first page compiles, and the printed link opens Vite's
+    "did you mean /docs/" page.
+- **The restart list.** `portalServed`'s list (`prompts/portal/serve.ts:57`) adds "changing the
+  path in `portal.site.url`". That is the whole of the path-edit handling:
+  - `PreviewConfig` and the static-directory notice are unchanged.
+  - A notice of its own for a moved path was planned and cut on 2026-09-29. Doing it without a
+    sibling prompt meant folding `staticDirectoryNotServed` into one keyed prompt, about 100
+    lines for an edit made once. It can come later as its own cleanup.
+- **The help.** The restart sentence of `portal serve --help`, and its copy in the README, name the
+  path edit too.
+
+### 4.6 `portal generate` Next Steps (`src/prompts/portal/generate.ts:90`)
+
+`nextSteps` takes the site address (4.3). When `hasPath()`, the note reads as below, with the
+zipped line in place of the first one when zipped. The sitemap address is
+`addressOf('/sitemap.xml')`, which is how `seo.ts` builds it too.
+
+> Upload the contents of `<dir>` so they are served at `https://acme.github.io/docs/`.
+>
+> (zipped) Unpack `portal.zip` in `<dir>` so its contents are served at
+> `https://acme.github.io/docs/`.
+>
+> To check the portal locally, serve it under `/docs/`: from the root of a local server, its
+> pages load without their styles and scripts.
+>
+> Serve `404.html` for missing pages under `/docs/`, so deep links resolve.
+>
+> Crawlers read `robots.txt` only at the root of a host, so none is generated. If you control
+> the root, add `Sitemap: https://acme.github.io/docs/sitemap.xml` to its `robots.txt`.
+
+At the root, and without an address, the note is unchanged. The note matters most when someone
+previews the output from the root of a local server. The page then loads without its styles and
+scripts, which are requested under the path, and the terminal is where they look next. The
+second line says so outright (added 2026-10-06).
+
+`portal generate --help`, and its copy in the README, said the files can be hosted "anywhere".
+They now say the files are served at a host's root, or at the path of `portal.site.url` when it
+has one.
+
+### 4.7 README
+
+The "Upgrading from 1.x" bullet that lists the `portal` block (`README.md:29`) describes `site`
+as "its name, address and description". It gains: the address may carry a path, such as
+`https://acme.github.io/docs`, and the portal is then built to be served there. The README has
+no other place that describes `site`.
+
+## 5. Template changes
+
+### 5.1 `portal-config.ts` and `vite.config.ts`
+
+- `BuildPaths` (`portal-config.ts`) and the CLI's `PortalBuildPaths` gain `base`, which
+  `PortalProjectService` writes as `siteAddress()?.path() ?? '/'` (decision 3). The `Equal<>`
+  check in `test/portal-template.test.ts` holds the two types to one shape.
+- `vite.config.ts` sets `base: paths.base`. `prerenderPages` reads `config.base` for the served
+  paths and the robots rule (5.7), and keeps its `siteUrl` argument for the sitemap.
+- `remarkImageOptions` leaves `useImport` at its default, which is true under Vite (fumadocs-mdx
+  sets `useImport ?? environment === 'bundler'`). It is what gives a Markdown image the base: the
+  image is bundled, not linked. The e2e image check fails on an upgrade that changes it (section 8).
+  It was written out until 2026-10-08.
+
+### 5.2 `withBasePath`: `src/lib/base-path.ts` (new)
+
+- `withBasePath(path: string, base = BASE)` prefixes a portal-relative path with the base less its
+  trailing slash.
+  - Every caller passes a portal-relative path. The SDK downloads are always
+    `sdkDownloadAddress`'s `/__downloads/…`, and a hosted plugin's absolute address never
+    reaches it (5.3).
+  - So there is no pass-through for absolute URLs. An earlier draft had one, for the plugin.
+- `BASE` is `import.meta.env.BASE_URL`, guarded the way Fumadocs guards it, since tsx leaves it
+  undefined.
+- `/// <reference types="vite/client" />` in the file keeps `pretest`'s `tsc`, which lists only
+  node, mocha, chai and sinon types, from rejecting `import.meta.env`.
+- **Users:**
+  - `components/search.tsx`:
+    - `from: withBasePath('/api/search.json')`;
+    - the results given to `SearchDialogList` carry `url: withBasePath(item.url)`, so the dialog's
+      `router.push` strips the base exactly once, whatever the page's path (decision 6). They are
+      memoised on `query.data`: the list moves its highlight to the top whenever it gets a new
+      array.
+  - `routes/__root.tsx`: the favicon `href`.
+  - `lib/layout.shared.tsx`: the light and dark logos, in its three `<img src>`s (lines 33, 37,
+    38).
+  - `components/sdk-actions.tsx`:
+    - `DownloadLink`'s `href`, which covers the SDK page and cards;
+    - the Markdown branch's `[Download SDK](…)` (line 25).
+  - `components/sdk-cards.tsx`: the Markdown branch's `[${name}](${page})` (line 43). The HTML
+    branch is a router `Link` and is left alone.
+  - `routes/$.tsx`: in the browser, the `pageUrl` the popover gets is a full address, from
+    `fullAddress(path)` beside `withBasePath` in `base-path.ts`:
+    `new URL(withBasePath(path), window.location.origin)`. On the server it stays a path, as
+    `pageUrl` is today; the popover renders it only when it is used.
+    - `pageUrl` (line 133) needs the base because the router's pathname has it stripped.
+    - `markdownUrl` goes to `ViewOptionsPopover` as the page's path. fumadocs-ui 16.15.17 adds the
+      base itself (`withBasePath(markdownUrl)`, `page-actions.js:70`), and
+      `test/portal-template/page-actions.test.ts`, from #413, fails if an upgrade stops doing so.
+      Until 2026-10-08 it was a full address, which Fumadocs leaves alone, so that it was right
+      whether Fumadocs added the base or not: ui 16.15.13 to 16.15.15 did not
+      (fuma-nama/fumadocs#3620).
+    - The copy button is the template's own since #419 (`components/markdown-copy-button.tsx`).
+      It takes the page's path, and `copyMarkdown` adds the base through `withBasePath`. Handed
+      the full address, it would fetch `/apihttp://…`.
+    - An earlier draft prefixed the popover's URL and passed Fumadocs' copy button the bare one.
+      That was right only for that Fumadocs, and an upgrade that fixed the popover would have
+      doubled the path with nothing to catch it.
+  - `lib/llms.server.ts`: the page headings' `(${page.url})`, and the index (5.4).
+  - `components/plugin-install.tsx`: `fullAddress('/')` in the browser's snapshot (5.3).
+  - `components/api-page.tsx`: `oauthRedirectUrl`, where the playground's OAuth sign-in returns
+    (from #424). Fumadocs resolves it against the host's origin, so it is
+    `withBasePath(oauthCallbackPath)`.
+  - `components/authorization-failure.tsx`: the OAuth callback's link to the home page.
+- **Users in Node, which pass the base:**
+  - `prerender-pages.ts`, with `config.base` (5.7). It already imports from `src/lib/`.
+  - `downloads.ts`'s dev keys, with `server.config.base` (5.8).
+  - `static-functions-base.ts`'s literal, with the resolved `config.base` (5.6).
+
+  With `'/'` as the base, the path comes back unchanged, which keeps the root case as it is.
+- **Never through it:**
+  - the page tree the pages render, and every Fumadocs or router link. The `llms.txt` index
+    renders from a prefixed copy (5.4);
+  - canonical, `og:url` and the sitemap (through `siteUrl`);
+  - header links, which are portal-relative router links.
+
+### 5.3 The plugin install command (`components/plugin-install.tsx`)
+
+- **The shape today:** one call, `installCommand(path, origin)`. The `origin` comes from
+  `useSyncExternalStore`: `portal.siteUrl` in the server snapshot, `window.location.origin` in
+  the browser's. The Markdown branch calls `installCommand(path, portal.siteUrl)`.
+- **The change:** the browser's snapshot becomes `fullAddress('/')`, the address the browser
+  sees the portal at, built as the page actions' is (5.2). Nothing else changes:
+  - `path` is not prefixed. The call is shared with the server snapshot, whose `siteUrl` already
+    carries the path, so prefixing it would print `/docs/docs/__downloads/…` in the
+    prerendered page.
+  - The server snapshot and the Markdown branch are right as they are, because `siteUrl` now
+    carries the path.
+  - `install-command.ts` is unchanged. It trims the trailing slash from what it is given.
+- The component's comment changes from "its own origin" to "its own address".
+
+### 5.4 `llms.txt` (`lib/llms.server.ts`)
+
+- The index is rendered by giving `llms()` a loader whose `getPageTree` returns a copy of the tree
+  with prefixed page URLs.
+- `getNodePage` goes by `$ref`, so titles and descriptions survive.
+
+### 5.5 Links authors write, in the Markdown copies: deferred
+
+Not in this PR (decision 10). Section 9 records the limitation and the approach found for the
+follow-up.
+
+### 5.6 The static server-function cache: `static-functions-base.ts` (new, beside `downloads.ts`)
+
+- **What it does:** a Vite plugin with `apply: 'build'`, active in the `client` environment only.
+  In `@tanstack/start-static-server-functions`, it rewrites the literal
+  `` `/__tsr/staticServerFnCache/ `` into
+  `withBasePath('/__tsr/staticServerFnCache/', config.base)`. `config.base` is the resolved base,
+  read in `configResolved`.
+  - As built in step 3, it runs `enforce: 'pre'` and uses a transform hook filter (by package id
+    and by the literal). TanStack builds with `sharedPlugins: true`, so `applyToEnvironment`
+    is what keeps it out of the server build.
+  - The literal is in `dist/esm/staticFunctionMiddleware.js` today. The unit guard scans the
+    package's `dist` for it rather than naming that file.
+- **Why the `ssr` environment is left alone:** its writer joins the same URL onto the client
+  output directory, and a prefixed URL would write `dist/client/docs/__tsr/…`.
+- **Why build-only:** dev never reads the cache.
+- **What makes it fail:** `buildEnd` in the client environment fails the build when no module
+  held the literal. That also covers an upgrade that moves it to another package. The check
+  counts matches, not changes: at the root, the replacement is the literal itself.
+- **The guard:** a unit test reads the installed module and asserts the literal is there, so the
+  guard does not rest on fake input alone.
+- It is applied at the root too, so there is one path through the code. It goes when
+  TanStack/router#6152 ships (section 10).
+
+### 5.7 `prerender-pages.ts`
+
+- **Served paths.** `prerenderPages(config, siteUrl)` returns every path as
+  `withBasePath(url, config.base)` (`/docs/guides/intro`). TanStack's `withBase` then leaves each
+  one alone, and `withoutBase` strips the base once for the filename, which keeps the output
+  layout as it is at the root.
+  - The SPA shell is not in the list: TanStack adds it itself and prefixes it.
+  - That is what makes a colliding base build (decision 6).
+- **`robots.txt`** is listed only when `siteUrl` is set and `config.base` is `'/'`.
+
+### 5.8 `downloads.ts`
+
+- The dev middleware answers only under the base.
+  - `filesByAddress` builds its keys with `withBasePath(…, server.config.base)`
+    (`downloads.ts:39`), giving `/docs/__downloads/…`. The lookup itself is unchanged. The
+    middleware sees the full URL, because it runs ahead of Vite's base handling (measured).
+  - A request without the base finds no key and goes on to Vite, so a link missing its prefix
+    fails in dev as it would once built.
+- The build still copies the downloads to `dist/client/__downloads/`.
+
+### 5.9 The playground's saved values (`components/api-page.tsx`, added 2026-10-06)
+
+- **The problem.** Fumadocs saves what a reader types into the playground in `localStorage`:
+  credentials under `fumadocs-openapi-auth-<scheme id>`, and the chosen server. Portals under
+  paths of one host share an origin, such as two GitHub Pages project sites on
+  `acme.github.io`. Without a change, a key typed into one portal is filled in on the other
+  under a common scheme id like `bearerAuth`, and sent to that API.
+- **The change.** `storageKeyPrefix` is `fumadocs-openapi-` followed by the base path without
+  its leading slash: `fumadocs-openapi-docs/` under `/docs/`.
+  - At the root it stays Fumadocs' own `fumadocs-openapi-`, so values readers saved before are
+    kept, and the root build is unchanged (section 1).
+
+### 5.10 Images Fumadocs leaves out (added 2026-10-06)
+
+- **Images in the specification's descriptions.** Fumadocs renders descriptions with `img`
+  mapped to `undefined`, so one image fails the whole operation page, at the root too, with
+  React error #130. A root-relative image there would also miss the base.
+  - `api-page.tsx` passes `components.Markdown` = `ApiMarkdown` (`components/api-markdown.tsx`).
+    It is built on Fumadocs' own `createMarkdownRenderer` with `remarkGfm`, and its `img` gives a
+    root-relative `src` the base through `withBasePath`. Code blocks go through `DynamicCodeBlock`,
+    with the highlighter and themes of Fumadocs' default.
+  - `languageOf`, which reads a fence's language, lives in `lib/code-titles.ts`. In
+    `rehype-code-titles.ts` it put the highlighter on every page, through the route's chunk.
+    The default e2e build checks that no page preloads `shiki-bundle`.
+  - The e2e fixture's operation has an image and a code block in its description.
+  - Filed as fuma-nama/fumadocs#3661 (section 10). `ApiMarkdown` can go once Fumadocs renders
+    images and gives them the base.
+- **Reference-style images (`![alt][ref]`).** Fumadocs' `remarkImage` sizes and imports inline
+  images only, so a reference kept a root-relative `src` that misses the base.
+  - `remarkImageReferences` (`lib/remark-image-references.ts`) writes each one as an inline image
+    ahead of `remarkImage`. It is registered in the global options (`vite.config.ts`), which the
+    content collection takes. The generated collection replaces them and leaves it out: with no
+    `publicDir`, an SDK page's root-relative image would fail the build once imported (measured).
+  - `src/types/portal/page.ts` checks those images before a build too. A missing one is then
+    reported by the CLI, not by a failed build. A contract test holds the two to the same images.
+  - Like every imported image, it now reads `<img src="__imgN" />` in the Markdown copies (section 9).
+
+### 5.11 The query on load (`lib/search-options.ts`, added 2026-10-07)
+
+- **The problem.** Under a base path, TanStack Router 1.171.28 rewrites the address when a page
+  loads, and the query goes through its JSON parsing on the way. A value that does not survive
+  that changes:
+  - the OAuth `state` Fumadocs sends, 39 digits, came back as `3.3941682453855677e+38`, so
+    Fumadocs skipped the token exchange and sign-in never completed under a path;
+  - `?v=1.0` came back as `?v=1`.
+
+  At the root nothing is rewritten. The `Transitioner` compares the address as loaded with the
+  one `buildLocation` gives. `parseLocation` keeps the raw address only when a rewrite, such as
+  the basepath, is set, so only then do the two differ (TanStack/router#8448).
+- **The change.** `router.tsx` takes `searchOptions`, which keep query values as text:
+  `parseSearchWith((value) => value)` and `stringifySearchWith(JSON.stringify)`. The portal reads
+  no typed search params. `search-options.test.ts` runs both on an OAuth return's query and gets
+  it back as written.
+  - A repeated key (`?a=1&a=2`) still comes back as one JSON value under a path. Nothing in the
+    portal or Fumadocs reads one.
+  - The address is still written anew, so `%20` becomes `+` and a bare `?a` becomes `?a=`. Each
+    value reads back the same.
+  - When TanStack's fix (PR #8450) ships, `searchOptions` can go (section 10).
+
+### 5.12 Images in search results (`routes/api/search[.]json.ts`, added 2026-10-08)
+
+- **The problem** (found in review, 2026-10-08). fumadocs-openapi puts an operation's description
+  in the search index as written (`toStaticData`), and the search dialog renders a result's
+  content as Markdown, images included. A root-relative image then loads from the host's root and
+  404s under a path. Fumadocs' own pages carry none: `remarkStructure`'s stringifier drops images.
+- **The change.** The search route hands `createFromSource` a copy of the loader whose reference
+  pages have their images taken out of the description and of each content entry, by
+  `withoutImages` (`lib/search-content.ts`). It parses without GFM, as the dialog renders a
+  result, and cuts each `image` and `imageReference` out of the text as written, so the rest
+  keeps its spelling.
+  - The description goes through it too. Fumadocs indexes the description again when no content
+    entry equals it.
+  - At the root too: results no longer show the image, and its address is no longer searched.
+  - Rejected: a `renderMarkdown` for the dialog with an `img` that adds the base. It would copy
+    the dialog's renderer, about 70 lines Fumadocs does not export.
+- `remark` joins the template's linked dependencies; the CLI already depends on it.
+- A raw `<img>` in a description is left in. The dialog renders raw HTML, so it would show
+  unprefixed, as raw HTML does elsewhere (section 9; read from the code, not measured).
+
+### 5.13 Unchanged, and why
+
+| File | Why |
+|---|---|
+| `seo.ts`, `sitemap.server.ts` | String concatenation onto `siteUrl` |
+| `routes/spa-shell.tsx`, `404.html` | The shell's assets carry the base; the router reads the served path (measured) |
+| `usage-tabs.tsx` | Resolves the API's server URLs, not the portal's |
+| Content links and Markdown images in the HTML | Router links and bundled imports |
+
+## 6. Tests
+
+**CLI unit tests:**
+- `test/types/portal/config/site-address.test.ts` (new):
+  - accepted: the root, one or several segments, a trailing slash, with `path()` and
+    `hasPath()` for each;
+  - refused: the table of 4.4, each with its message from 4.1.
+- `test/types/portal/portal-config.test.ts`:
+  - `identity().siteUrl` is the site address;
+  - `siteAddress()` is null without a `url`;
+  - the renamed `portalPath()`.
+- `test/types/apimatic-config/schema.test.ts`: the shared table.
+- **Existing tests that refuse a path, changed in step 1:**
+  - `schema.test.ts:125`, "an address with a path", moves to the accepted cases.
+  - `portal-config.test.ts:92` uses `https://x.test/docs` as its invalid address, to reach five
+    errors. It takes `https://x.test/?a=1` instead.
+  - `portal-config.test.ts:141`, "keeps only the origin of the address", becomes "keeps the
+    path, dropping a trailing slash and keeping a port".
+  - `portal-config.test.ts:149-160` drops `https://x.test/docs` from its refused list.
+    `https:x.test` stays there (4.1).
+- `test/infrastructure/portal-dev-server-service.test.ts`: a `/docs/` banner keeps its slash, and
+  the root banner is unchanged.
+- `test/prompts/portal/serve.test.ts`: the restart list names the path.
+- `test/actions/portal/generate.test.ts`, which stubs `nextSteps` today: it receives the site
+  address.
+- `test/prompts/portal/generate.test.ts` (new; the wording has no test today): both branches, at
+  the root and under a path.
+
+**The CLI/template contract:** the `Equal<>` check on `BuildPaths` (`test/portal-template.test.ts`)
+covers `base`, and `test/infrastructure/portal-project-service.test.ts` checks the value written
+under a path and without an address. Until 2026-10-08 a contract test held the template's
+`viteBase` to `SiteAddress.path()` over a list of addresses; it went with `viteBase` (decision 3).
+
+**Template unit tests (`test/portal-template/`):**
+- `base-path.test.ts` (new): the root, a base, an explicit base; `fullAddress` with a window and
+  without one.
+- `search-content.test.ts` (new, 2026-10-08): `withoutImages` drops an inline image, a
+  reference-style one and one inside a link, and leaves Markdown without images as written (5.12).
+- `prerender-pages.test.ts`:
+  - served paths under a base, including one that collides with it;
+  - portal-relative paths at the root;
+  - no `robots.txt` under a base.
+- `downloads.test.ts`:
+  - the dev middleware answers under the base;
+  - it passes a bare `/__downloads/…` on.
+- `static-functions-base.test.ts` (new):
+  - it rewrites in the client environment only;
+  - it leaves other modules alone;
+  - it fails when nothing matched;
+  - the installed module still holds the literal.
+- `search-navigation.test.ts` (new, step 2). Search results under a colliding base rely on how
+  Fumadocs and TanStack navigate, which only a browser would otherwise show. So an upgrade that
+  changes any of it fails here, naming the mapping in `search.tsx` to revisit:
+  - Fumadocs' search dialog navigates with `router.push(item.url)`, read from the installed
+    `fumadocs-ui`;
+  - Fumadocs' TanStack adapter pushes with `router.navigate({ href })`, read from the installed
+    `fumadocs-core`;
+  - the router, created in Node with a memory history and basepath `/api`, takes
+    `href: '/api/api/x'` to the route `/api/x`. It runs in Node (tried 2026-09-29).
+
+**End to end:** `test/e2e/portal-build.test.ts` gets a `subpath` fixture with
+`site.url: 'https://docs.test/api'`. It is a colliding base on purpose: it guards the reliance on
+TanStack's `withBase` (decision 6), and would fail if that ever prefixed an already-prefixed path.
+The fixture lives at `test/resources/portal-inputs/subpath/src`, beside `default` and `branded`.
+It holds:
+- a spec, so the API reference's `/api/…` pages really collide with the base;
+- a content page linking `/authentication`, and that page;
+- a logo in `static/`;
+- the root `nav.json` that `quickstart` scaffolds, naming the three sections in `tabs`. Since #408,
+  a portal with no root `nav.json` has no tab bar, and the API reference is a collapsed folder in
+  Home whose pages the home page does not link to. The tab is the home page's link to a
+  colliding page (added at the merge of `dev`, 2026-10-05);
+- a Markdown image in the content page (step 2), which guards the `useImport` default (5.1). It
+  is over Vite's 4 KiB inline limit, since an inlined `data:` URI would carry no base to check;
+  the logo is 3.9 KB, so the image is a generated 12 KB `diagram.png`.
+
+It is built with `{ plugin: true }` for the bundled plugin. It is the third real build in the
+file, after `default` and `branded`, and `test.yml` runs the e2e suite on
+every platform in the matrix. The three builds took about a minute together locally (step 1,
+2026-09-29), so this adds some 20 s to each job, more on slower runners. It stays on every platform,
+because the cache writer's `path.join` is where Windows would differ. It lands in step 1, and
+each step extends its assertions:
+- **Step 1:**
+  - the pages are at the output's root, `api/search.json` and the operation pages included, and
+    no page is written twice;
+  - asset `src`/`href`, sidebar links and the content page's `/authentication` link start at
+    `/api/`;
+  - canonical, `og:url` and the sitemap `<loc>`s carry `/api`.
+- **Step 2:**
+  - logo, favicon and SDK download links start at `/api/`;
+  - `llms.txt` links start at `/api/`, and there is no `robots.txt`;
+  - the plugin page's Markdown command carries `/api`;
+  - `sdks.md` links carry `/api`;
+  - the Markdown image's `src` starts at `/api/`.
+- **Step 3:**
+  - a client chunk contains `` `/api/__tsr/staticServerFnCache/ ``, and none contains
+    `` `/__tsr/staticServerFnCache/ `` (the literal with its opening backtick);
+  - the cache files sit at `__tsr/staticServerFnCache/` under the output's root.
+- **The 2026-10-08 review:** `api/search.json` holds the operation description's text and not its
+  image (5.12).
+
+**By hand, in a browser** (the 2026-09-29 headless Chrome probes). Each runs with the step that
+completes what it checks, so a bug is fixed in the commit that made it: the build probe with
+step 3, the `portal serve` probe with step 4. Both use the `subpath` fixture. `portal serve`
+under a colliding base was only read (Start's dev middleware takes `req.originalUrl`, so it
+strips the base once) until step 4 ran it (section 3). Some fixes are checked only here, because they exist only in the
+browser and no automated test reaches them:
+- the search results' served URLs, which make a colliding base navigate. What they rely on is
+  guarded by `search-navigation.test.ts`;
+- the page's path for the copy button, whose base `copy-markdown.test.ts` checks;
+- `pageUrl`;
+- the plugin install command's browser snapshot (5.3);
+- the playground's storage keys (5.9);
+- an OAuth sign-in against a mock provider: the redirect URI, the return through the callback,
+  and the token exchange (5.2, 5.11).
+
+The probes:
+- **Build, served at the base:**
+  - first load, client navigation, search, and clicking a search result, each onto a colliding
+    page as well;
+  - logo, SDK download, the plugin page, a deep link through `404.html`;
+  - the popover's "View as Markdown" link and the copy button, which only exist in the browser.
+- **`portal serve` under the base:**
+  - the printed link, client navigation, search, each onto a colliding page as well;
+  - the plugin download;
+  - an edit that moves the path: it is applied, and the old path is served until a restart;
+  - the OAuth sign-in, and a query kept as written on load.
+
+## 7. Implementation steps
+
+Each step is a commit of its own and stops for review. The tree builds and the suite is green
+after each one. In all, roughly 400 lines of source and 500 of tests.
+
+1. **CLI accepts the path, and Vite follows it.**
+   - Changes:
+     - `SiteAddress`, `SiteConfig`, identity `siteUrl`, the schema and its table;
+     - the `portalPath()` rename;
+     - `viteBase`, `vite.config.ts`;
+     - `withBasePath` (5.2), because the served paths of 5.7 use it.
+   - Tests:
+     - the new unit tests, and the existing ones that refused a path (section 6);
+     - `base-path.test.ts` and the contract test;
+     - the `subpath` e2e fixture with step 1's assertions.
+2. **The template's portal-relative strings.** Every other user in 5.2 and 5.3 (search results
+   included), `llms.txt`, the robots rule, and the dev downloads middleware. Also `useImport`
+   (5.1). With unit and e2e assertions, and `search-navigation.test.ts`.
+3. **The static-cache plugin (5.6).** With its tests and e2e assertions, and the build probe:
+   client navigation first works under a path in this step.
+4. **`portal serve`, `portal generate` and the README (4.5–4.7).** With their tests, and the
+   `portal serve` probe.
+5. **Follow-up.**
+   - a comment on apimatic-io#2275 saying what shipped and how it departs from the issue;
+   - a ticket for the deferred Markdown copy links (section 9);
+   - a ticket for the warning about files in `static/` that replace generated ones. It is wrong
+     both ways:
+     - It says `static/404.html` replaces the generated one, but the CLI copies the shell over
+       the user's.
+     - It names `robots.txt` (and `sitemap.xml`) even where none is generated: without
+       `site.url`, and now under a path. `GENERATED_ROOT_FILES` lists them unconditionally.
+     - Pre-existing, so not fixed here.
+   - a ticket for the `<img src="__img0">` placeholders in the Markdown copies (section 9),
+     found while checking the links there;
+   - the optional TanStack reaction or comment of section 10, if the user wants one. The
+     Fumadocs issue was filed by the user as fuma-nama/fumadocs#3620 and fixed in fumadocs-ui
+     16.15.17 (section 10).
+
+## 8. Risks
+
+- **TanStack's prerender stops treating an already-prefixed path as prefixed.** Every page would
+  then be fetched with the base twice and 404, failing the build. The colliding `subpath` fixture
+  would catch that on the upgrade that brings it.
+- **Dependency upgrades.** Nothing here pins a version or edits an installed package. Two pieces
+  stand in for upstream code until it is fixed: `static-functions-base.ts` rewrites one address in
+  TanStack's browser bundle (5.6), and `ApiMarkdown` renders descriptions as Fumadocs does, with
+  images (5.10). Every behaviour the path relies on fails CI on an upgrade that changes it:
+
+  | Relied on | On an upgrade that changes it |
+  |---|---|
+  | The popover adds the base to its Markdown URL | `page-actions.test.ts` fails (5.2) |
+  | Content pages' Markdown images are bundled | The e2e fails (the bundled image's `src`) (5.1) |
+  | The index takes a reference page's description and contents as the loader gives them | The e2e fails (the index names the image) (5.12) |
+  | Query values on load under a base | `search-options.test.ts` fails: it runs TanStack's own helpers (5.11) |
+  | Fumadocs links are router links | The e2e fails (step 1's link assertions) |
+  | `llms()` reads the loader methods we wrap | The e2e fails (`llms.txt` links) |
+  | Search navigates by `href`, stripped once | `search-navigation.test.ts` fails |
+  | TanStack prefixes only an unprefixed listed path | The colliding e2e fixture fails |
+  | TanStack's cache literal | The build fails, and the unit guard (5.6) |
+
+  A failure is a stop on that upgrade, not a broken portal, and it names what to change.
+
+  `ApiMarkdown` is the exception. If Fumadocs changes how it renders descriptions, ours keeps the
+  old way without failing. The e2e checks only that an image and a code block render (5.10).
+- **A base of `/spa-shell` exactly.** TanStack's own prefixing of the shell path would leave it
+  alone, and the shell would be prerendered from the home page. Deep links would briefly show the
+  home page before hydrating. Not refused, since no one names a docs path after an internal route.
+- **Hosts differ on `/docs` versus `/docs/`.** Canonical and the sitemap give the home page as
+  `…/docs/`, the form that works everywhere.
+- **Header links are portal-relative.** A user who writes `/docs/guides` for a portal at `/docs`
+  gets `/docs/docs/guides`. No schema change is needed: the `link.url` description already reads
+  "A page of the portal starting with '/'". The hosting guide says so as well.
+
+## 9. Known limitations
+
+**Links authors write stay unprefixed in the Markdown copies** (deferred, decision 10).
+- A portal-relative link such as `[auth](/authentication)` is `/docs/authentication` in the page's
+  HTML. It stays `/authentication` in the page's `.md` copy and in `llms-full.txt`, so an assistant
+  reading the copy resolves it against the host's root.
+- `llms.txt` is the same for an operation's description, which it lists as written: a
+  root-relative image or link there keeps its spelling (found in review, 2026-10-08).
+- **The workaround:** write the full site address (`https://acme.github.io/docs/authentication`).
+  It is right in both, at a cost. Fumadocs renders it as a plain `<a target="_blank">`, so in the
+  HTML the link:
+  - opens in a new tab and loads the whole page from scratch, with no client navigation or
+    prefetch;
+  - leads to the production site from `portal serve` or a staging host;
+  - breaks if the portal moves.
+- **Also not prefixed:** raw HTML and JSX URLs in MDX (an `<img src>` or `<a href>`), which are
+  neither routed nor rewritten, in the HTML or in the copy. The docs say to use Markdown links and
+  images.
+- **For the follow-up**, two approaches were found:
+  - **Preferred: an MDX `a` override.** A link whose href starts with `portal.siteUrl` has that
+    prefix stripped and is handed to the router as a portal-relative path.
+    - Authors write the full site address, which is right in the copies as it stands.
+    - In the HTML it becomes a same-tab client navigation, under `portal serve` too.
+    - It is one component compared at runtime, with no compile-time base and no Fumadocs
+      Markdown internals.
+    - The cost is that content hard-codes the portal's address.
+  - **Alternative: rewrite the copies' links.**
+    - Fumadocs' `remarkLLMs` takes mdast-to-markdown `handlers` through a collection's
+      `includeProcessedMarkdown` options. Handlers for `link`, `image` and `definition` would
+      prefix root-relative URLs in the copy alone.
+    - Open: how the handlers learn the base, given that `source.ts` goes through
+      `fumadocs-mdx/macro`.
+
+**Images in the Markdown copies are broken on every portal** (measured 2026-09-30, root and
+path alike). `remarkImage` swaps the image for an import, and the copy and `llms-full.txt` carry
+`<img alt="…" src="__img0" />`, which leads nowhere. This predates the path: `useImport` is the
+default. It gets a ticket of its own. Since 5.10, reference-style images read the same way.
+- It is Fumadocs' bug, filed as fuma-nama/fumadocs#3662 (section 10).
+- A workaround is possible: plugins on either side of `remarkImage`, plus the `stringify` hook
+  that `includeProcessedMarkdown` passes on. It is held back, because it would rest on
+  `remarkImage`'s internal `__img${n}` names.
+
+**API reference pages' Markdown copies keep the spec's own text:** its description and the YAML.
+A root-relative link inside a spec description is prefixed in the page's HTML, which renders it
+with the MDX components, but not in its copy.
+
+## 10. Upstream
+
+| Item | State (2026-09-29) | What it means for us |
+|---|---|---|
+| TanStack/router#6152, PR #5970 | Both open (checked 2026-09-30). A maintainer (2026-07-17): the cache URL "should follow Start's public asset base"; the PR builds the URL with `path.join` and needs an e2e served from a sub-path. SimYunSup (2026-08-12, on the PR): a repro, `path.join` throwing in the browser, a string join returning 200, `import.meta.env.BASE_URL` working, and an offer of the e2e fixture. | When it ships, delete 5.6. |
+| fuma-nama/fumadocs#3620, from PR #3572 (ui 16.15.13) | Fixed 2026-09-29 in fumadocs-ui 16.15.17 (commit `6791d6f`): the popover prefixes `markdownUrl` with `withBasePath` again, in both `radix-ui` and `base-ui` | Since 2026-10-08 we pass the page's path and rely on that `withBasePath`; `page-actions.test.ts` fails if an upgrade drops it again (5.2) |
+| TanStack/router#4888, docs PR #7882 | Docs only | None |
+| TanStack/router#8448, PR #8450 | Both open (checked 2026-10-07); the PR has no review yet. The issue reports a second loader run; we saw the address rewritten too | When it ships, `searchOptions` can go (5.11) |
+| fuma-nama/fumadocs#3661 | Filed 2026-10-07: an image in an operation's description crashes the page | When it ships with the base, `ApiMarkdown` can go (5.10) |
+| fuma-nama/fumadocs#3662 | Filed 2026-10-07: processed Markdown prints images as `__img0` | When it ships, ticket 5 is fixed by the upgrade (section 9) |
+
+**The fixes:**
+- **Fumadocs:** filed by the user as fuma-nama/fumadocs#3620, from a draft made here, and fixed
+  as it proposed. The two image bugs of 5.10 and section 9 were filed as #3661 and #3662.
+  Reference-style images are not filed.
+- **TanStack:** the planned comment on #6152 would have given a repro and a fix that prefixes only
+  the client fetch in `fetchItem`, `fetch(import.meta.env.BASE_URL.replace(/\/$/, '') + url)`,
+  leaving `getStaticCacheUrl` alone. SimYunSup's comments on PR #5970 (2026-08-12) already say all
+  of that. So what is left is optional: a reaction on #6152, or a short comment confirming the
+  current release and the Vite base the maintainer asked for.
+  - A PR, with the e2e case served from a sub-path that the maintainer asked for, follows only if
+    a maintainer answers. That e2e case lives in their monorepo and costs more than the fix, and
+    5.6 already covers us until then.
+
+## 11. Hosting notes, for the docs
+
+These are for the portal's hosting documentation, not the CLI. The CLI emits nothing
+host-specific. A host's own files are the user's to put in `static/`, whose files are copied to
+the output's root, dotfiles included (measured with `.nojekyll`, 2026-09-29).
+
+| Host | Note |
+|---|---|
+| GitHub Pages | **Publishing from a branch runs Jekyll.** Jekyll drops every file and folder starting with `_`: `__tsr/` (every client navigation then shows the 404 page), `__downloads/`, `_shell.html`, and `assets/_-<hash>.js`, the route chunk every page preloads, without which the app never starts: every link reloads the page, and search and the page actions do nothing (reviewer's measurement, 2026-10-08, with a local server hiding those names). Its optional-front-matter plugin, which cannot be disabled, renders the `.md` copies as HTML. Add an empty `static/.nojekyll`, beside the `static/CNAME` a custom domain needs, or deploy through GitHub Actions, which skips Jekyll. A project site serves its own `404.html` at any depth, with status 404, and redirects `/docs` to `/docs/`. |
+| nginx | `location /docs/ { alias …; }` plus `location = /docs { return 301 /docs/; }` and `error_page 404 /docs/404.html`. Add `text/markdown md;` to `mime.types`, or the `.md` copies download. |
+| Netlify | Nest the output under `docs/` in the publish directory or proxy it. `_redirects` is read only at the publish root. |
+| Cloudflare Pages | 25 MiB per file (SDK zips, `llms-full.txt`). With no top-level `404.html` it assumes an SPA. |
+| Vercel, S3 + CloudFront, Azure SWA | Nest the output under the path. Their error documents are set for the whole site, not per path. |
+
+**Out of scope, pre-existing:** canonical links use the form without a trailing slash, which
+GitHub Pages answers with a 301 to the slashed one.
+
+## 12. Not done, and why
+
+**A path without `site.url`.** This was decided against on 2026-09-29, to keep one source for
+the path.
+
+**One build for any path.** Neither framework supports it, and neither plans to:
+- TanStack Start turns `base: './'` into `/./assets/…` and a basepath of `.`, and `''` into the
+  root.
+  - TanStack/router#5966 has no maintainer reply.
+  - PR #7572 would still break nested pages.
+  - Discussion #8496 (2026-09-25) has no replies.
+- Fumadocs' `BASE_PATH` is a compile-time `import.meta.env.BASE_URL`, and its maintainer declined
+  deriving `baseUrl` from it (fumadocs#2545).
+
+A home-grown version would need all of these, and prerendered links would still point at the
+host's root until JavaScript runs:
+- per-page relative asset URLs through Start's experimental `transformAssets`, which breaks
+  preloads after client navigation;
+- a router `rewrite` computed at runtime (Start overwrites a `basepath` set in `getRouter`);
+- a runtime value in place of every `BASE_URL`, Fumadocs' included.
+
+## 13. Delivery
+
+- **This plan:** one PR to `dev` from this branch, after step 5. The README line (4.7) goes in it.
+- **The hosting guide (section 11):** a docs item, outside this repository.
+  - It needs an owner on the docs side, named before the PR merges, so that the release notes can
+    point at it.
+  - Section 11 is written so the guide can reuse it. The guide also says to use Markdown links
+    and images rather than raw HTML (section 9), and that header links are portal-relative
+    (section 8).
+  - Its GitHub Pages section matters for today's root-hosted portals too, since Jekyll breaks
+    them just the same.
+  - **Why the CLI doesn't write `.nojekyll`:** a CLI change that wrote it into every portal was
+    drafted and dropped on 2026-09-29, to keep the CLI free of host-specific files. Nitro and
+    Sphinx write it only when opted in (a `github-pages` preset, a `githubpages` extension), and
+    Docusaurus tells users to add it to `static/`.
+
+## 14. Where this departs from #2275
+
+- **The base path is in the build config only.** The issue put `basePath` in `PortalIdentity`
+  and `BuildIdentity`. Here only `portal.config.json` carries it, as `base`, and the browser never
+  imports that file (decision 3).
+- **`portal serve` needs changes after all:** the address's slash and the restart list. The
+  issue said none (4.5).
+- **`prerenderPages` does not stay portal-relative.** The issue said it could. It hands TanStack
+  served paths, so a colliding base builds (decision 6).
+- **The quickstart note is unchanged** (decision 11).
+- **Not in the issue:**
+  - the static server-function cache (5.6);
+  - colliding base paths (decision 6);
+  - `llms.txt` links (5.4);
+  - the SDK pages' Markdown copy links (5.2);
+  - the popover's `pageUrl` as a full address (5.2);
+  - search results, and the images in them (5.2, 5.12);
+  - `robots.txt` and the sitemap note (decision 7, 4.6);
+  - the README line (4.7);
+  - the address's character rule (4.1);
+  - the dev middleware answering only under the base (5.8).
+
+## 15. History
+
+All on 2026-09-29. Where a later round reversed an earlier one, the later note says so.
+
+**After an adversarial review:**
+- The base path reaches the template through `siteUrl` alone.
+- A path edit under `portal serve` is applied with a notice. (Replaced by the restart list after
+  the cost review.)
+- `SiteAddress` composes the origin and `BasePath`. (`BasePath` was folded into it after the
+  review against the code.)
+- The static-cache plugin is build-only.
+
+**Deferring author links:** rewriting the links authors write in the Markdown copies is
+deferred to a follow-up (decision 10, section 9).
+
+**After a second round of research:**
+- A base path that collides with page paths is made to work instead of refused. The CLI
+  collision check is gone (decision 6, measured with base `/api`).
+- The dev downloads middleware answers only under the base.
+- Hosting notes are added (section 11).
+- The upstream fixes are drafted (section 10).
+- GitHub Pages' Jekyll problem is recorded (section 11).
+
+**`.nojekyll`:** the CLI does not write it. A PR that wrote it into every portal was drafted and
+dropped. Adding it is the user's, through `static/`, the way Docusaurus documents it, so the
+CLI stays host-neutral (section 11).
+
+**After reviewing the plan and its cost:**
+- The prerender's served paths, the dev downloads keys and the cache literal go through
+  `withBasePath` too, so the prefix rule has one home. The helper moves into step 1.
+- `StaticAsset.siteUrl()` becomes `portalPath()`, so `siteUrl` names only the site address.
+- The refusal messages are specified (4.1).
+- A path edit under `portal serve` gets no notice of its own. The restart list names it, and the
+  static-directory notice is left as it is (decision 9, 4.5).
+- The README says `site.url` may carry a path (4.7).
+- TanStack gets a comment on #6152 first, not a PR (section 10).
+- The size and the CI cost are recorded (sections 6 and 7), and so is the fact that some fixes
+  are checked only in a browser.
+
+**After a full review against the code:**
+- `BasePath` is folded into `SiteAddress` (4.1): with no notice to compare paths, Next Steps
+  was its only user.
+- The plugin install command changes only the browser's address (5.3). The earlier wording
+  would have doubled the path in the prerendered page.
+- `withBasePath` has no pass-through for absolute URLs, since no caller passes one (5.2).
+- A test holds the template's Vite base to the CLI's path (section 6).
+- The existing tests that refuse a path are listed (section 6).
+- The browser checks move to steps 3 and 4 (section 7), and the dev one uses the colliding
+  fixture.
+- Also specified: the Next Steps wording (4.6), the cache plugin's failure check (5.6), the
+  fixture's location (section 6) and the `://` check (4.1).
+
+**After checking the dependency upgrade path** (before step 2): three Fumadocs behaviours the
+path relied on would have broken silently on an upgrade, and a fourth was untested.
+- The page actions get a full address, right whether Fumadocs adds the base or not (5.2). This
+  replaces the popover prefix and the bare URL for the copy button.
+- `search-navigation.test.ts` guards how search navigates (section 6).
+- `useImport` is written out, and the fixture gains a Markdown image (5.1, section 6).
+- Section 8 lists every behaviour relied on, and what happens on an upgrade that changes it.
+
+**After reviewing steps 1 and 2** (before step 2's commit):
+- The search results are memoised (5.2). A new array each render moved the highlight to the
+  top, on root portals too.
+- `fullAddress` moves into `base-path.ts`, and the plugin install command's snapshot uses it
+  (5.2, 5.3), so the browser's address of a path is built in one place.
+- The e2e check that nothing points outside the path also covers a content page and an API
+  reference page (it passed).
+- The contract test's wording says it has its own list of addresses (section 6).
+
+**Step 3** (2026-09-30): the plugin as built runs `enforce: 'pre'` with a transform hook filter,
+and its unit guard scans the package's `dist` for the literal (5.6). The build probe passed under
+`/api` and at the root (section 3).
+
+**Step 4** (2026-09-30): as specified in 4.5–4.7. The `portal serve` probe passed under `/api`,
+path edit included (section 3).
+
+**After reviewing all four steps** (2026-09-30), against #374's principles and the reviewer's bar:
+- `SiteAddress.addressOf()` builds the addresses Next Steps names (4.1, 4.6).
+- `SiteConfig`'s getter is `siteAddress()` (4.2).
+- The Next Steps note at the root says its 404 sentence once.
+- The plugin's comment is one line, and `llms.server.ts` has no single-use helper.
+
+**The PR** (2026-09-30): opened as apimatic/apimatic-cli#411, superseding #407. It passed CI on
+Linux, macOS and Windows under Node 24 and 26, the sub-path e2e build included. The planned
+TanStack comment became optional: SimYunSup's comments on PR #5970 already say what it would have
+said (section 10).
+
+**After a completeness audit** (2026-10-06). The audit built a richer fixture under `/api`, under
+`/Dev/v1.0` and at the root. It checked every URL in the output, and loaded and clicked through
+every page, both built and under `portal serve`. Under a path, the only failures a root build does
+not also show were raw HTML and JSX URLs (section 9). Three gaps were fixed in this PR:
+- The playground's saved values are kept per portal (5.9).
+- `SiteAddress.parse` refuses an address that names a page, has no host, or has a tab in its
+  host, and so does the schema (4.1, 4.4).
+- `portal serve --help` names the path edit. `portal generate --help` no longer says "anywhere".
+  Next Steps says to check a portal locally under its path (4.5, 4.6).
+
+Images that Fumadocs leaves out were fixed in this PR too (5.10): images in the specification's
+descriptions, which crashed the page at the root too, and reference-style images.
+
+The open PRs #419 and #424 each add a URL that needs the base. They merge first, and this PR
+adds the base to each once it is on `dev`.
+
+The audit's other findings are left to follow-ups:
+- raw `<img>` in SDK docs;
+- links in the Markdown copies;
+- crashes and links that also break at the root.
+
+**After #419 merged** (2026-10-06). `dev` was merged in. #419 replaced Fumadocs' copy button with
+the template's own, which added `import.meta.env.BASE_URL` by hand, and the merge's conflict was
+over which address it gets. It now takes the page's path and adds the base through
+`withBasePath` (5.2). Headless Chrome copied a page loaded directly and one reached by a link,
+under `/api`, under `/Dev/v1.0` and at the root.
+
+**After #424 merged** (2026-10-07). `dev` was merged in. #424 added the OAuth callback page and
+one redirect URI for the playground's sign-in, and left the base to this PR. The redirect URI and
+the callback's home link now get it (5.2), and the callback is prerendered under it with the
+other pages (5.7). A sign-in against a mock provider then found the router rewriting the query
+on load under a path, which kept sign-in from completing (5.11). After that fix, the sign-in
+completed under `/api`, under `/Dev/v1.0` and at the root, and under `portal serve` at `/api`.
+
+**After a full review** (2026-10-07). An independent review of the whole PR found no blocker. Two
+regressions from 5.10 are fixed, each measured against `dev` and the PR's head:
+- every page preloaded the highlighter, at the root too, through `languageOf`. It moved to
+  `code-titles.ts`, and the e2e checks it;
+- a reference-style image in SDK docs failed the build. The generated collection leaves the
+  plugin out.
+
+It also corrected the invariant (section 1), the 4.4 pattern, section 8's claim about upstream
+code, and 5.11's note on the address.
+
+**After mehnoorsiddiqui's review** (2026-10-08):
+- Search results showed a description's image unprefixed under a path. The index now takes
+  reference pages without their images (5.12).
+- Decision 3 is revised. The CLI writes `base` into `portal.config.json`, and the template's
+  `viteBase` and its contract test are gone. The rule that reads the path out of the address now
+  has one home, `SiteAddress.path()`, where it had two held together by a test.
+- The popover gets the page's path again, since the pinned fumadocs-ui adds the base and #413's
+  test guards it (5.2). `useImport` is left at its default, which the e2e guards (5.1).
+- `llms.txt` joins the known limitation on links authors write (section 9). Jekyll also drops
+  the route chunk `assets/_-<hash>.js` (section 11).
diff --git a/.ai/skills/action.md b/.ai/skills/action.md
index 185ff7bee..d815cfa12 100644
--- a/.ai/skills/action.md
+++ b/.ai/skills/action.md
@@ -171,17 +171,16 @@ export class {PascalName}Action {
     // 3. Business logic wrapped in withDirPath for temp directory
     return await withDirPath(async (tempDirectory) => {
       // 4. Resolve resources / prepare context
-      //    const resourceContext = new ResourceContext(tempDirectory);
-      //    const specFileDirResult = await resourceContext.resolveTo(resourcePath);
-      //    if (specFileDirResult.isErr()) {
-      //      this.prompts.networkError(specFileDirResult.error);
+      //    const spec = await ResourceContext.resolveTo(resourcePath, tempDirectory);
+      //    if (spec.isErr()) {
+      //      this.prompts.specUnavailable(spec.error);
       //      return ActionResult.failed();
       //    }
 
       // 5. Service call via prompts spinner
       //    const response = await this.prompts.spinnerMethod(
       //      this.someService.doSomething({
-      //        file: specFileDirResult.value,
+      //        file: spec.value.file(),
       //        commandMetadata: this.commandMetadata,
       //        authKey: this.authKey
       //      })
diff --git a/.github/workflows/portal_tests.yml b/.github/workflows/portal_tests.yml
index 84bc2cebf..a88a5e28f 100644
--- a/.github/workflows/portal_tests.yml
+++ b/.github/workflows/portal_tests.yml
@@ -82,6 +82,7 @@ jobs:
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with:
           repository: apimatic/v4-test-automation
+          ref: feat/functional-tests
           path: tests
 
       - name: install test dependencies
@@ -166,10 +167,25 @@ jobs:
           PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}\.playwright-browsers
         run: pnpm test:visual
 
+      # Functional runs against the suite's auth build, whose playground calls
+      # the API Tester (tests/api-tester/) on localhost:3000.
+      # Playwright starts the API Tester itself (webServer in playwright.config.ts),
+      # because a server started in its own step doesn't outlive that step.
+
+      - name: generate the auth portal
+        id: generate-auth
+        if: ${{ !cancelled() }}
+        working-directory: tests
+        env:
+          PORTAL: auth
+        run: pnpm portal:generate
+
       - name: functional
-        if: ${{ !cancelled() && steps.generate.outcome == 'success' }}
+        if: ${{ !cancelled() && steps.generate-auth.outcome == 'success' }}
         working-directory: tests
+        shell: bash
         env:
+          PORTAL: auth
           PORTAL_PREBUILT: '1'
           PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}\.playwright-browsers
         run: pnpm test:functional
@@ -189,6 +205,7 @@ jobs:
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: test-results
-          path: tests/test-results/
+          path: |
+            tests/test-results/
           retention-days: 30
           if-no-files-found: ignore
diff --git a/CONTEXT.md b/CONTEXT.md
index 8e17632ca..09ad52aa5 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -22,6 +22,10 @@ _Avoid_: Build directory, build project, build tree
 One API description in `spec/`, in any format APIMatic can transform (OpenAPI 3.x, Swagger, Postman Collections, RAML, API Blueprint, etc.), which becomes one section of reference pages in the portal.
 _Avoid_: Specification file, API definition
 
+**Spec directory**:
+The `spec/` directory in the source directory: every spec, the files they reference, and anything else kept beside them.
+_Avoid_: Specs folder, spec folder
+
 **Endpoint**:
 An operation addressed by its HTTP method and path template, exactly as the spec writes them.
 _Avoid_: Operation ID, route
diff --git a/README.md b/README.md
index fade86dca..d2b246749 100644
--- a/README.md
+++ b/README.md
@@ -21,63 +21,6 @@ To get started with APIMatic's CLI using a step by step wizard, run the followin
 $ apimatic quickstart
 ```
 
-# Upgrading from 1.x
-
-Documentation portals are now built on your machine from a `src/` directory, and
-`APIMATIC-BUILD.json` no longer configures them:
-
-- Describe the portal in the `portal` block of `src/apimatic.json`: `site` (its name, address
-  and description), `brand` (logo, favicon, primary colour and colour mode), `navigation`
-  (header links) and `ai` (the page actions). Running `apimatic quickstart` scaffolds the block
-  with every default spelled out, and the file's `$schema` lets your editor complete and check it.
-- A portal also needs the project's SDK languages, at least one, in the same file's
-  `languages` block, for example `"languages": { "typescript": {} }`; `csharp`, `python` and
-  `typescript` are available for now. `plugin generate` and `sdk publish` both write to it, and
-  the context plugin reads it too, so name only the languages you ship. The same file carries
-  the plugin's identity in `plugin`; `src/plugin-config.json` is no longer read, so run
-  `plugin generate` and `sdk publish` again after upgrading and delete the old file.
-- Put OpenAPI documents in `src/spec/`, Markdown pages in `src/content/` and images and other
-  files in `src/static/`.
-- Every page starts with front matter giving its `title`, which names it in the sidebar.
-  Pages written for 1.x had none; the CLI lists each page that needs one before it builds.
-  ```md
-  ---
-  title: Getting started
-  ---
-  ```
-- Page order comes from a `nav.json` beside your pages, listing them by file name, and a
-  `title` there names the folder it sits in. A folder links to its `index.md`; without one it
-  is only a heading.
-- The top level of the portal is shown as tabs, which `src/content/nav.json` decides with two
-  lists. `tabs` names the tabs after Home, in order, and nothing else is one: a folder directly
-  under `src/content/`, and the sections the CLI makes, placed with `apimatic:sdks`,
-  `apimatic:plugin` and `apimatic:api`. Home comes first, opens on `index.md`, and holds
-  everything `tabs` does not name: every page at the top level, every other folder, and every
-  section not named as a tab, each at the address it always has. Its `pages` orders that sidebar
-  as any other `nav.json` orders its folder, a token standing for its section, and the file's
-  `title` names it; what `pages` does not name follows in alphabetical order, pages before
-  folders. A file with no `tabs`, or no file at all, makes no tab, so Home stands alone and
-  there is no tab bar; the build says so once, with the line that makes tabs of the sections
-  and the reference `pages` does not place. A new portal starts with the three sections as
-  tabs.
-  ```json
-  {
-    "title": "Overview",
-    "tabs": ["tutorials", "apimatic:sdks", "apimatic:api"],
-    "pages": ["index", "authentication", "guides", "apimatic:plugin", "..."]
-  }
-  ```
-- The SDKs tab lists a card per language in the `languages` block, offering its download and,
-  once `sdk publish` records a release, its install command, source repository and package, and
-  gives each language a page carrying its SDK's getting-started docs. The Context Plugin tab,
-  with the plugin's install command, appears when there is a `plugin` block, or a `pluginUrl` in
-  the `portal` block for a plugin hosted elsewhere. Their addresses, `/sdks` and
-  `/context-plugin`, are kept for them, so a page in `src/content/` that would be served there
-  is refused.
-- `portal toc new`, `portal recipe new` and `portal copilot` are gone, and `portal serve` no
-  longer takes `--destination` or `--no-reload`. Run `apimatic autocomplete --refresh-cache`
-  to drop the removed commands from shell completion.
-
 # Usage
 <!-- usage -->
 ```sh-session
@@ -151,9 +94,11 @@ Validate API specification for syntactic and semantic correctness
 
 ```
 USAGE
-  $ apimatic api validate [--file <value>] [--url <value>] [-k <value>]
+  $ apimatic api validate [--file <value> | --url <value> | -i <value>] [-k <value>]
 
 FLAGS
+  -i, --input=<value>     [default: ./] path to the parent directory containing the 'src' directory, which includes API
+                          specifications and configuration files.
   -k, --auth-key=<value>  override current authentication state with an authentication key.
       --file=<value>      Path to the API specification file to validate
       --url=<value>       URL to the API specification file to validate (publicly accessible)
@@ -161,9 +106,14 @@ FLAGS
 DESCRIPTION
   Validate API specification for syntactic and semantic correctness
 
-  Validate your API specification to ensure it adheres to syntactic and semantic standards.
+  Validate the API specification in your 'src/spec' directory, or the one --file or --url points to, to ensure it
+  adheres to syntactic and semantic standards.
 
 EXAMPLES
+  apimatic api validate
+
+  apimatic api validate --input=./
+
   apimatic api validate --file=./specs/sample.json
 
   apimatic api validate --url="https://petstore.swagger.io/v2/swagger.json"
@@ -361,9 +311,10 @@ DESCRIPTION
 
   Builds a documentation portal from the OpenAPI documents and Markdown pages in your 'src' directory.
 
-  The portal is built on your machine and written as static files you can host anywhere. Configure it with
-  'src/apimatic.json', whose 'languages' block gives the portal a page for each SDK language, and whose 'plugin' block,
-  or a 'pluginUrl' in its 'portal' block for a plugin hosted elsewhere, a page for the context plugin.
+  The portal is built on your machine and written as static files for any static host, served at its root or, when
+  'portal.site.url' has a path such as 'https://example.com/docs', at that path. Configure it with 'src/apimatic.json',
+  whose 'languages' block gives the portal a page for each SDK language, and whose 'plugin' block, or a 'pluginUrl' in
+  its 'portal' block for a plugin hosted elsewhere, a page for the context plugin.
 
 EXAMPLES
   apimatic portal generate
@@ -397,8 +348,8 @@ DESCRIPTION
   pages in 'src/content', reorder them in a 'nav.json', or change the 'portal', 'languages' or 'plugin' block of
   'apimatic.json'.
 
-  Adding a language or a 'plugin' block, adding or removing a page in 'src/content', creating 'src/static', or changing
-  which documents are in 'src/spec', needs the preview restarted.
+  Adding a language or a 'plugin' block, adding or removing a page in 'src/content', creating 'src/static', changing
+  which documents are in 'src/spec', or changing the path in 'portal.site.url', needs the preview restarted.
 
   Nothing is written to disk; run 'apimatic portal generate' to produce the static files.
 
diff --git a/apimatic.schema.json b/apimatic.schema.json
index f5f666e43..e305cf119 100644
--- a/apimatic.schema.json
+++ b/apimatic.schema.json
@@ -77,8 +77,8 @@
             },
             "url": {
               "type": "string",
-              "description": "The address the portal is hosted at, without a path, for example 'https://docs.example.com'.",
-              "pattern": "^\\s*[hH][tT][tT][pP][sS]?://[^\\s/?#]+/?\\s*$"
+              "description": "The address the portal is hosted at, for example 'https://docs.example.com' or 'https://example.com/docs'.",
+              "pattern": "^\\s*[hH][tT][tT][pP][sS]?://[^\\s/?#\\\\]+(?:/(?!\\.{1,2}(?:/|\\s*$))(?![A-Za-z0-9._~-]*\\.[hH][tT][mM][lL]?/?\\s*$)[A-Za-z0-9._~-]+)*/?\\s*$"
             },
             "description": {
               "type": "string",
diff --git a/portal-template/dependency-directories.ts b/portal-template/dependency-directories.ts
index a86245be3..2c05a482e 100644
--- a/portal-template/dependency-directories.ts
+++ b/portal-template/dependency-directories.ts
@@ -1,54 +1,45 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-/**
- * The installations the project's dependencies resolve to. Vite serves a file from outside
- * its allow list only once the module importing it has been transformed, an order a browser
- * cache skips: Safari, holding the importer from an earlier preview on the same port, asked
- * for the TanStack dev entry first and was refused, leaving a blank page. Naming where the
- * links really lead keeps every dependency served whatever the browser asks for first.
- */
-export function dependencyDirectories(projectDirectory: string): string[] {
-  const directories = new Set<string>();
-  for (const packagePath of packagePaths(path.join(projectDirectory, 'node_modules'))) {
-    const installed = realPath(packagePath);
-    if (installed !== undefined) {
-      directories.add(outermostNodeModules(installed));
+// Safari runs a cached entry before its importer is transformed (apimatic-io#2287).
+export function dependencyDirectories(portalProjectDirectory: string): string[] {
+  const modules = path.join(portalProjectDirectory, 'node_modules');
+  return narrowest(
+    packageNames(modules)
+      .filter((name) => fs.lstatSync(path.join(modules, name)).isSymbolicLink())
+      .map((name) => holdingDirectory(fs.realpathSync.native(path.join(modules, name)), name))
+  );
+}
+
+/** The one directory holding them all: the CLI's `node_modules` under npm, the store under pnpm. Each alone when only the disk's root would. */
+function narrowest(directories: string[]): string[] {
+  let common: string | undefined = directories[0];
+  for (const directory of directories.slice(1)) {
+    while (common !== undefined && !isWithin(common, directory)) {
+      common = isRoot(path.dirname(common)) ? undefined : path.dirname(common);
     }
   }
-  return [...directories];
+  return common === undefined ? directories : [common];
 }
 
-function packagePaths(modules: string): string[] {
-  return entries(modules).flatMap((name) => {
-    const packagePath = path.join(modules, name);
-    return name.startsWith('@') ? entries(packagePath).map((scoped) => path.join(packagePath, scoped)) : [packagePath];
-  });
+function packageNames(modules: string): string[] {
+  return fs
+    .readdirSync(modules)
+    .flatMap((name) =>
+      name.startsWith('@') ? fs.readdirSync(path.join(modules, name)).map((scoped) => `${name}/${scoped}`) : [name]
+    );
 }
 
-function entries(directory: string): string[] {
-  try {
-    return fs.readdirSync(directory).filter((name) => !name.startsWith('.'));
-  } catch {
-    return [];
-  }
+/** Where a package and the dependencies installed beside it sit, its scope included. */
+function holdingDirectory(packageDirectory: string, name: string): string {
+  return path.resolve(packageDirectory, ...name.split('/').map(() => '..'));
 }
 
-function realPath(target: string): string | undefined {
-  try {
-    return fs.realpathSync(target);
-  } catch {
-    return undefined;
-  }
+function isRoot(directory: string): boolean {
+  return path.dirname(directory) === directory;
 }
 
-/** The widest installation around a package: under pnpm the whole store sits inside one `node_modules` too. */
-function outermostNodeModules(packageDirectory: string): string {
-  let found = packageDirectory;
-  for (let parent = path.dirname(packageDirectory); parent !== path.dirname(parent); parent = path.dirname(parent)) {
-    if (path.basename(parent) === 'node_modules') {
-      found = parent;
-    }
-  }
-  return found;
+function isWithin(directory: string, target: string): boolean {
+  const relative = path.relative(directory, target);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
diff --git a/portal-template/downloads.ts b/portal-template/downloads.ts
index e0e4bbbad..61e9c32cf 100644
--- a/portal-template/downloads.ts
+++ b/portal-template/downloads.ts
@@ -2,6 +2,7 @@ import { createReadStream } from 'node:fs';
 import { cp, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import type { Plugin } from 'vite';
+import { withBasePath } from './src/lib/base-path';
 
 /** Where the site offers the downloads: a name the user's static directory is not expected to use. */
 export const DOWNLOADS_ADDRESS = '__downloads';
@@ -15,7 +16,8 @@ export function downloads(directory: string | null): Plugin {
     name: 'apimatic:downloads',
     async configureServer(server) {
       if (directory === null) return;
-      const files = await filesByAddress(directory);
+      // Under the base only, as once built: this runs ahead of Vite's own base handling.
+      const files = await filesByAddress(directory, server.config.base);
       server.middlewares.use((request, response, next) => {
         const file = files.get(decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname));
         if (file === undefined) return next();
@@ -30,12 +32,13 @@ export function downloads(directory: string | null): Plugin {
   };
 }
 
-async function filesByAddress(directory: string): Promise<Map<string, string>> {
+async function filesByAddress(directory: string, base: string): Promise<Map<string, string>> {
   const entries = await readdir(directory, { recursive: true, withFileTypes: true });
   const files = new Map<string, string>();
   for (const entry of entries.filter((candidate) => candidate.isFile())) {
     const file = path.join(entry.parentPath, entry.name);
-    files.set(`/${DOWNLOADS_ADDRESS}/${path.relative(directory, file).split(path.sep).join('/')}`, file);
+    const address = `/${DOWNLOADS_ADDRESS}/${path.relative(directory, file).split(path.sep).join('/')}`;
+    files.set(withBasePath(address, base), file);
   }
   return files;
 }
diff --git a/portal-template/portal-config.ts b/portal-template/portal-config.ts
index a171c23d2..0127eadc0 100644
--- a/portal-template/portal-config.ts
+++ b/portal-template/portal-config.ts
@@ -3,6 +3,8 @@ import type { Portal } from './src/lib/portal-types';
 
 /** Written by the CLI next to this file before every build or dev-server start. */
 export interface BuildPaths {
+  /** Vite's `base`, the path of the site address that every page and asset is served under: `/`, or `/docs/`. */
+  base: string;
   /** Section slug -> absolute path of an OpenAPI document. */
   specs: Record<string, string>;
   /** Absolute path of the code samples, keyed by path then method; null when there are none. */
diff --git a/portal-template/prerender-pages.ts b/portal-template/prerender-pages.ts
index 395a4b3ff..0560ef52f 100644
--- a/portal-template/prerender-pages.ts
+++ b/portal-template/prerender-pages.ts
@@ -2,6 +2,8 @@ import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { getSlugs, loader } from 'fumadocs-core/source';
 import type { BuildPaths } from './portal-config.ts';
+import { withBasePath } from './src/lib/base-path';
+import { oauthCallbackPath } from './src/lib/oauth-callback';
 import { openApiSection } from './src/lib/openapi-section.server';
 
 const CONTENT_EXTENSIONS = new Set(['.md', '.mdx']);
@@ -19,7 +21,8 @@ export async function prerenderPages(config: BuildPaths, siteUrl: string | null)
   // Both need absolute URLs, so they are only emitted for a portal that declares its address.
   if (siteUrl) {
     urls.add('/sitemap.xml');
-    urls.add('/robots.txt');
+    // Crawlers read it only at the root of a host.
+    if (config.base === '/') urls.add('/robots.txt');
   }
 
   for (const url of await contentUrls(config.contentDir)) urls.add(url);
@@ -35,8 +38,11 @@ export async function prerenderPages(config: BuildPaths, siteUrl: string | null)
     if (url === '/') urls.add('/index.md');
     else if (!/\.(txt|xml|json)$/.test(url)) urls.add(`${url}.md`);
   }
+  // After the twins, since it is no page of the portal's and has none.
+  urls.add(oauthCallbackPath);
 
-  return [...urls].map((url) => ({ path: url }));
+  // Served paths, or TanStack takes a page starting like the base (`/api/…` under `/api`) as already under it.
+  return [...urls].map((url) => ({ path: withBasePath(url, config.base) }));
 }
 
 async function contentUrls(contentDir: string): Promise<string[]> {
diff --git a/portal-template/src/components/api-markdown.tsx b/portal-template/src/components/api-markdown.tsx
new file mode 100644
index 000000000..884582c22
--- /dev/null
+++ b/portal-template/src/components/api-markdown.tsx
@@ -0,0 +1,32 @@
+import { createMarkdownRenderer } from 'fumadocs-core/content/md';
+import { remarkGfm } from 'fumadocs-core/mdx-plugins/remark-gfm';
+import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { Children, type ComponentProps, type ReactElement } from 'react';
+import { withBasePath } from '@/lib/base-path';
+import { languageOf } from '@/lib/code-titles';
+
+const { Markdown } = createMarkdownRenderer({ remarkPlugins: [remarkGfm] });
+
+const components = {
+  ...defaultMdxComponents,
+  // A root-relative address names a file in the static directory, which the host serves under the base.
+  img: ({ src, ...props }: ComponentProps<'img'>) => (
+    <img {...props} src={typeof src === 'string' && /^\/(?!\/)/.test(src) ? withBasePath(src) : src} />
+  ),
+  pre: CodeBlock
+};
+
+/** The specification's descriptions as Fumadocs renders them, but for its `img: undefined`, which fails the page. */
+export function ApiMarkdown({ md }: { md: string }) {
+  return <Markdown components={components}>{md}</Markdown>;
+}
+
+/** A fenced block, highlighted as Fumadocs highlights one in a description. */
+function CodeBlock({ children }: ComponentProps<'pre'>) {
+  const code = Children.only(children) as ReactElement<{ className?: string; children?: unknown }>;
+  const text = code.props.children;
+  if (typeof text !== 'string') return null;
+  const language = languageOf(code.props.className?.split(' ') ?? []) ?? 'text';
+  return <DynamicCodeBlock lang={language} code={text.trimEnd()} />;
+}
diff --git a/portal-template/src/components/api-page.tsx b/portal-template/src/components/api-page.tsx
index 0d9881936..219e28517 100644
--- a/portal-template/src/components/api-page.tsx
+++ b/portal-template/src/components/api-page.tsx
@@ -1,5 +1,8 @@
 import { createOpenAPIPage } from 'fumadocs-openapi/ui';
+import { withBasePath } from '@/lib/base-path';
 import { mediaAdapters } from '@/lib/media-adapters';
+import { oauthCallbackPath } from '@/lib/oauth-callback';
+import { ApiMarkdown } from './api-markdown';
 import { renderExampleLayout } from './example-layout';
 import { codeUsages, renderUsageTabs } from './usage-tabs';
 
@@ -7,5 +10,9 @@ export const OpenAPIPage = createOpenAPIPage({
   codeUsages,
   generateTypeScriptDefinitions: false,
   content: { renderAPIExampleLayout: renderExampleLayout, renderAPIExampleUsageTabs: renderUsageTabs },
-  mediaAdapters
+  components: { Markdown: ApiMarkdown },
+  mediaAdapters,
+  oauthRedirectUrl: withBasePath(oauthCallbackPath),
+  // Portals under paths of one host keep their playground's saved values apart; at the root the keys stay Fumadocs' own.
+  storageKeyPrefix: `fumadocs-openapi-${withBasePath('/').slice(1)}`
 });
diff --git a/portal-template/src/components/authorization-failure.tsx b/portal-template/src/components/authorization-failure.tsx
new file mode 100644
index 000000000..e77fcd9ad
--- /dev/null
+++ b/portal-template/src/components/authorization-failure.tsx
@@ -0,0 +1,63 @@
+import { buttonVariants } from 'fumadocs-ui/components/ui/button';
+import type { ReactNode } from 'react';
+import { withBasePath } from '@/lib/base-path';
+import type { OAuthCallbackFailure } from '@/lib/oauth-callback';
+
+/** What the OAuth callback says when it stays, instead of sending the browser back to the endpoint. */
+export function AuthorizationFailure({ failure }: { failure: OAuthCallbackFailure }) {
+  switch (failure.kind) {
+    case 'providerError':
+      // Ended, not refused: `server_error` and `temporarily_unavailable` arrive here too.
+      return (
+        <>
+          <Explanation>
+            The provider ended the authorization with <code>{failure.error}</code>
+            {failure.description === null ? '.' : `: ${failure.description}`}
+          </Explanation>
+          <Action href={failure.page}>Back to the endpoint</Action>
+        </>
+      );
+    case 'notStarted':
+      return (
+        <>
+          <Explanation>
+            This page completes an authorization started from an endpoint's playground, and none was started in this
+            browser. Open the endpoint's page and authorize from there.
+          </Explanation>
+          <HomeAction />
+        </>
+      );
+    case 'unknownPage':
+      return (
+        <>
+          <Explanation>
+            The authorization was not started from a page of this site, so it cannot be completed here. Open the
+            endpoint's page and authorize from there.
+          </Explanation>
+          <HomeAction />
+        </>
+      );
+  }
+}
+
+function Explanation({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <h1 className="text-2xl font-semibold">Authorization could not be completed</h1>
+      <p className="text-fd-muted-foreground max-w-md">{children}</p>
+    </>
+  );
+}
+
+// The page that started the authorization is unknown here, so the home page is the one way back.
+function HomeAction() {
+  return <Action href={withBasePath('/')}>Go to the home page</Action>;
+}
+
+function Action({ href, children }: { href: string; children: ReactNode }) {
+  return (
+    <a href={href} className={buttonVariants({ color: 'primary', className: 'mt-4' })}>
+      {children}
+    </a>
+  );
+}
diff --git a/portal-template/src/components/markdown-copy-button.tsx b/portal-template/src/components/markdown-copy-button.tsx
index d7c4f495a..ed4ea43eb 100644
--- a/portal-template/src/components/markdown-copy-button.tsx
+++ b/portal-template/src/components/markdown-copy-button.tsx
@@ -12,7 +12,7 @@ const LABELS: Record<CopyState, string> = {
   failed: 'Copy failed'
 };
 
-export function MarkdownCopyButton({ markdownUrl, base }: Readonly<{ markdownUrl: string; base: string }>) {
+export function MarkdownCopyButton({ markdownUrl }: Readonly<{ markdownUrl: string }>) {
   const [state, setState] = useState<CopyState>('idle');
 
   useEffect(() => {
@@ -23,7 +23,7 @@ export function MarkdownCopyButton({ markdownUrl, base }: Readonly<{ markdownUrl
 
   const copy = () => {
     setState('copying');
-    copyMarkdown(markdownUrl, base).then(
+    copyMarkdown(markdownUrl).then(
       () => setState('copied'),
       (error: unknown) => {
         console.error(error);
diff --git a/portal-template/src/components/plugin-install.tsx b/portal-template/src/components/plugin-install.tsx
index 4ada2f432..9c810b52f 100644
--- a/portal-template/src/components/plugin-install.tsx
+++ b/portal-template/src/components/plugin-install.tsx
@@ -1,22 +1,23 @@
 import { useSyncExternalStore } from 'react';
 import { asMarkdown } from 'fumadocs-core/server';
 import { CommandBlock } from './command-block';
+import { fullAddress } from '@/lib/base-path';
 import { installCommand } from '@/lib/install-command';
 import { portal } from '@/lib/portal';
 
-// The origin never changes while the page is open, so there is nothing to subscribe to.
+// The address never changes while the page is open, so there is nothing to subscribe to.
 const noSubscribe = () => () => {};
 
-/** The prerender cannot know where the portal is hosted, so the browser swaps in its own origin. */
+/** The prerender cannot know where the portal is hosted, so the browser swaps in its own address. */
 export function PluginInstall({ path }: Readonly<{ path: string }>) {
   // Ahead of the hook, which only React may call; either branch is taken in every render of one environment.
   if (asMarkdown()) {
     return <CommandBlock command={installCommand(path, portal.siteUrl)} />;
   }
-  const origin = useSyncExternalStore(
+  const site = useSyncExternalStore(
     noSubscribe,
-    () => window.location.origin,
+    () => fullAddress('/'),
     () => portal.siteUrl
   );
-  return <CommandBlock command={installCommand(path, origin)} />;
+  return <CommandBlock command={installCommand(path, site)} />;
 }
diff --git a/portal-template/src/components/sdk-actions.tsx b/portal-template/src/components/sdk-actions.tsx
index 18c9aa0d0..4c90cfb18 100644
--- a/portal-template/src/components/sdk-actions.tsx
+++ b/portal-template/src/components/sdk-actions.tsx
@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 import { asMarkdown } from 'fumadocs-core/server';
 import { buttonVariants } from 'fumadocs-ui/components/ui/button';
 import { Code, Download, Package } from 'lucide-react';
+import { withBasePath } from '@/lib/base-path';
 
 export interface SdkActionsProps {
   download: string;
@@ -22,7 +23,7 @@ export function SdkActions({ download, source, packageUrl, registry }: Readonly<
   // The page's Markdown twin, which the page actions and llms-full.txt hand to an AI assistant.
   if (asMarkdown()) {
     const links = [
-      `[Download SDK](${download})`,
+      `[Download SDK](${withBasePath(download)})`,
       source ? `[View source](${source})` : null,
       packageUrl ? `[View on ${registry}](${packageUrl})` : null
     ];
@@ -64,7 +65,7 @@ interface LinkProps {
 /** A plain link, not a route: the zip is a file the site serves beside its pages. */
 export function DownloadLink({ href, className, children }: Readonly<LinkProps>) {
   return (
-    <a href={href} download className={className}>
+    <a href={withBasePath(href)} download className={className}>
       {children}
     </a>
   );
diff --git a/portal-template/src/components/sdk-cards.tsx b/portal-template/src/components/sdk-cards.tsx
index 0012fdf74..fda88b91e 100644
--- a/portal-template/src/components/sdk-cards.tsx
+++ b/portal-template/src/components/sdk-cards.tsx
@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 import Link from 'fumadocs-core/link';
 import { asMarkdown } from 'fumadocs-core/server';
 import { ArrowDownToLine, ArrowRight, ExternalLink as ExternalLinkIcon } from 'lucide-react';
+import { withBasePath } from '@/lib/base-path';
 import { CommandBlock } from './command-block';
 import { LanguageLogo, LogoTile } from './logos';
 import { DownloadLink, ExternalLink, LINK, QUIET_LINK, SdkActions, type SdkActionsProps } from './sdk-actions';
@@ -40,7 +41,7 @@ function LinkContext({ name }: Readonly<{ name: string }>) {
 export function SdkCard({ language, name, page, install, ...actions }: Readonly<SdkCardProps>) {
   if (asMarkdown()) {
     const command = install ? `\`${install}\` · ` : '';
-    return [`- [${name}](${page}): ${command}`, <SdkActions key="actions" {...actions} />];
+    return [`- [${name}](${withBasePath(page)}): ${command}`, <SdkActions key="actions" {...actions} />];
   }
   const { download, source, packageUrl, registry } = actions;
   return (
diff --git a/portal-template/src/components/search.tsx b/portal-template/src/components/search.tsx
index 439ca12e9..8180d4108 100644
--- a/portal-template/src/components/search.tsx
+++ b/portal-template/src/components/search.tsx
@@ -13,6 +13,8 @@ import {
 import { useDocsSearch } from 'fumadocs-core/search/client';
 import { staticClient } from 'fumadocs-core/search/client/orama-static';
 import { useI18n } from 'fumadocs-ui/contexts/i18n';
+import { useMemo } from 'react';
+import { withBasePath } from '@/lib/base-path';
 
 export default function DefaultSearchDialog(props: SharedProps) {
   const { locale } = useI18n();
@@ -20,10 +22,15 @@ export default function DefaultSearchDialog(props: SharedProps) {
     // Served with an extension so hosts and CDNs give it a JSON content type; without one
     // it went out as application/octet-stream, which some of them attach or refuse.
     client: staticClient({
-      from: '/api/search.json',
+      from: withBasePath('/api/search.json'),
       locale
     })
   });
+  // Served URLs, since the dialog navigates by href (search-navigation.test.ts), memoised so its highlight stays put.
+  const results = useMemo(
+    () => (query.data === 'empty' ? null : query.data?.map((item) => ({ ...item, url: withBasePath(item.url) }))),
+    [query.data]
+  );
 
   return (
     <SearchDialog search={search} onSearchChange={setSearch} isLoading={query.isLoading} {...props}>
@@ -34,7 +41,7 @@ export default function DefaultSearchDialog(props: SharedProps) {
           <SearchDialogInput />
           <SearchDialogClose />
         </SearchDialogHeader>
-        <SearchDialogList items={query.data !== 'empty' ? query.data : null} />
+        <SearchDialogList items={results} />
       </SearchDialogContent>
     </SearchDialog>
   );
diff --git a/portal-template/src/lib/base-path.ts b/portal-template/src/lib/base-path.ts
new file mode 100644
index 000000000..a009ff0b6
--- /dev/null
+++ b/portal-template/src/lib/base-path.ts
@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+// Undefined outside Vite, as under the template's unit tests; Fumadocs guards it the same way.
+const BASE = typeof import.meta.env === 'undefined' ? '/' : import.meta.env.BASE_URL;
+
+/** A portal-relative path as the host serves it, under `base`: Vite's own unless one is given. */
+export function withBasePath(path: string, base: string = BASE): string {
+  return `${base.replace(/\/$/, '')}${path}`;
+}
+
+/** A portal-relative path's full address as the browser sees it; the path itself where there is no window. */
+export function fullAddress(path: string): string {
+  return typeof window === 'undefined' ? path : new URL(withBasePath(path), window.location.origin).toString();
+}
diff --git a/portal-template/src/lib/code-titles.ts b/portal-template/src/lib/code-titles.ts
index 1447c2e15..6d6cdbca6 100644
--- a/portal-template/src/lib/code-titles.ts
+++ b/portal-template/src/lib/code-titles.ts
@@ -27,3 +27,11 @@ export const CODE_BLOCK_TITLES: Readonly<Record<BundledLanguage, string>> = {
   sql: 'SQL',
   tsx: 'TSX'
 };
+
+const LANGUAGE_CLASS = 'language-';
+
+/** The language a fence names, from the class `remark-rehype` gives its `code`. */
+export function languageOf(classes: unknown[]): string | undefined {
+  const languageClass = classes.find((name) => typeof name === 'string' && name.startsWith(LANGUAGE_CLASS));
+  return typeof languageClass === 'string' ? languageClass.slice(LANGUAGE_CLASS.length) : undefined;
+}
diff --git a/portal-template/src/lib/copy-markdown.ts b/portal-template/src/lib/copy-markdown.ts
index 41d8c4098..52ac051a0 100644
--- a/portal-template/src/lib/copy-markdown.ts
+++ b/portal-template/src/lib/copy-markdown.ts
@@ -1,5 +1,7 @@
-export async function copyMarkdown(rootRelativeUrl: string, base: string): Promise<void> {
-  const url = `${base.replace(/\/$/, '')}${rootRelativeUrl}`;
+import { withBasePath } from './base-path';
+
+export async function copyMarkdown(rootRelativeUrl: string, base?: string): Promise<void> {
+  const url = withBasePath(rootRelativeUrl, base);
   // Handed over unresolved, so Safari still counts the write as part of the click.
   const markdown = fetchMarkdown(url);
   await Promise.all([navigator.clipboard.write([new ClipboardItem({ 'text/plain': markdown })]), markdown]);
diff --git a/portal-template/src/lib/install-command.ts b/portal-template/src/lib/install-command.ts
index df9502633..1bd7b3669 100644
--- a/portal-template/src/lib/install-command.ts
+++ b/portal-template/src/lib/install-command.ts
@@ -1,13 +1,13 @@
 const ABSOLUTE = /^https?:\/\//i;
 
 // Quoted, so a `&` or a space in the address stays one argument in any shell a reader pastes it into.
-export function installCommand(path: string, origin: string | null): string {
-  return `npx context-plugins install "${installAddress(path, origin)}"`;
+export function installCommand(path: string, site: string | null): string {
+  return `npx context-plugins install "${installAddress(path, site)}"`;
 }
 
-function installAddress(path: string, origin: string | null): string {
-  if (ABSOLUTE.test(path) || origin === null) {
+function installAddress(path: string, site: string | null): string {
+  if (ABSOLUTE.test(path) || site === null) {
     return path;
   }
-  return `${origin.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+  return `${site.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
 }
diff --git a/portal-template/src/lib/layout.shared.tsx b/portal-template/src/lib/layout.shared.tsx
index cf0e6aaac..d7a4c685f 100644
--- a/portal-template/src/lib/layout.shared.tsx
+++ b/portal-template/src/lib/layout.shared.tsx
@@ -1,4 +1,5 @@
 import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+import { withBasePath } from './base-path';
 import { portal } from './portal';
 
 export function baseOptions(): BaseLayoutProps {
@@ -30,12 +31,13 @@ const LOGO_SIZE = 'h-6 w-auto max-w-none';
 function Logo() {
   const { logo } = portal;
   if (!logo) return null;
-  if (logo.light === logo.dark) return <img src={logo.light} alt="" className={LOGO_SIZE} />;
+  const [light, dark] = [withBasePath(logo.light), withBasePath(logo.dark)];
+  if (light === dark) return <img src={light} alt="" className={LOGO_SIZE} />;
   // Both are in the page and CSS shows one, so the right one is there before any script runs.
   return (
     <>
-      <img src={logo.light} alt="" className={`${LOGO_SIZE} dark:hidden`} />
-      <img src={logo.dark} alt="" className={`hidden ${LOGO_SIZE} dark:block`} />
+      <img src={light} alt="" className={`${LOGO_SIZE} dark:hidden`} />
+      <img src={dark} alt="" className={`hidden ${LOGO_SIZE} dark:block`} />
     </>
   );
 }
diff --git a/portal-template/src/lib/llms.server.ts b/portal-template/src/lib/llms.server.ts
index 0963e0c35..ce82f503b 100644
--- a/portal-template/src/lib/llms.server.ts
+++ b/portal-template/src/lib/llms.server.ts
@@ -1,15 +1,35 @@
+import type * as PageTree from 'fumadocs-core/page-tree';
 import { llms } from 'fumadocs-core/source';
 import { stringify } from 'yaml';
 import { getMDXComponents } from '@/components/mdx';
+import { withBasePath } from './base-path';
 import { operationLabels } from './openapi-labels';
 import { slimOpenAPIPageProps } from './openapi-slim';
-import { source } from './source.server';
+import { type PortalPage, source } from './source.server';
 import { portal } from './portal';
 
-type PortalPage = ReturnType<typeof source.getPages>[number];
 type ReferencePage = Extract<PortalPage, { type: 'openapi' }>;
 
-const index = llms(source);
+// `llms()` links each page by its tree node's URL and has no base of its own; titles are found by `$ref`.
+const index = llms({
+  ...source,
+  getPageTree: (locale?: string) => {
+    const root = source.getPageTree(locale);
+    return { ...root, children: root.children.map(servedNode) };
+  }
+});
+
+function servedNode(node: PageTree.Node): PageTree.Node {
+  if (node.type === 'page') return { ...node, url: withBasePath(node.url) };
+  if (node.type === 'folder') {
+    return {
+      ...node,
+      index: node.index && { ...node.index, url: withBasePath(node.index.url) },
+      children: node.children.map(servedNode)
+    };
+  }
+  return node;
+}
 
 export async function renderPage(page: PortalPage): Promise<string> {
   return await render(page, true);
@@ -34,14 +54,18 @@ export function renderHome(): string {
 }
 
 async function renderContent(page: Exclude<PortalPage, ReferencePage>): Promise<string> {
-  return `# ${page.data.title} (${page.url})\n\n${await page.data.getText('processed', { components: getMDXComponents() })}`;
+  return `# ${page.data.title} (${withBasePath(page.url)})\n\n${await page.data.getText('processed', { components: getMDXComponents() })}`;
 }
 
 /** An operation's page, with the part of its specification that page renders: what an assistant reads best. */
 function renderReference(page: ReferencePage, withSpecification: boolean): string {
   const props = slimOpenAPIPageProps(page.data.getOpenAPIPageProps());
   const endpoints = operationLabels(props, (signature) => `\`${signature}\``);
-  const sections = [`# ${page.data.title} (${page.url})`, endpoints.join('\n'), page.data.description ?? ''];
+  const sections = [
+    `# ${page.data.title} (${withBasePath(page.url)})`,
+    endpoints.join('\n'),
+    page.data.description ?? ''
+  ];
   if (withSpecification) {
     // Its tags and the document's description are the portal's to show, and would come with every operation.
     const { info, tags: _tags, ...document } = props.payload.bundled as Record<string, unknown> & {
diff --git a/portal-template/src/lib/oauth-callback.ts b/portal-template/src/lib/oauth-callback.ts
new file mode 100644
index 000000000..a592192bb
--- /dev/null
+++ b/portal-template/src/lib/oauth-callback.ts
@@ -0,0 +1,63 @@
+/**
+ * The one redirect URI a portal owner registers with their OAuth provider, instead of the
+ * address of every endpoint page that can start an authorization. The CLI keeps the user's
+ * pages off it, in `src/types/portal/content-tree.ts`.
+ */
+export const oauthCallbackPath = '/oauth/callback';
+
+/** The cookie the playground writes before it leaves, naming the page that started the flow. */
+const PAGE_COOKIE_NAME = 'fumadocs-openapi-oauth';
+const PAGE_COOKIE = new RegExp(`(?:^|;\\s*)${PAGE_COOKIE_NAME}=([^;]+)`);
+
+/** What the callback does with the browser that lands on it. */
+export type OAuthCallback =
+  /** Sends it back to the page that started the flow, with the provider's answer still attached. */
+  | { kind: 'return'; url: string }
+  /** Stays, to show the error the provider ended the authorization with, and a link back to that page. */
+  | { kind: 'providerError'; error: string; description: string | null; page: string }
+  /** Stays, since the cookie names no page: no authorization was started in this browser. */
+  | { kind: 'notStarted' }
+  /** Stays, since the cookie names a page on another site, or one that cannot be read. */
+  | { kind: 'unknownPage' };
+
+/** Every outcome but sending the browser on, which leaves the callback before it renders again. */
+export type OAuthCallbackFailure = Exclude<OAuthCallback, { kind: 'return' }>;
+
+/**
+ * The provider answers in the query for the authorization code flow and in the fragment for the
+ * implicit one, an error included. Only an authorization this browser started is answered with
+ * the provider's error: anyone can link here with an `error_description` of their own.
+ */
+export function oauthCallback(cookie: string, location: Pick<Location, 'origin' | 'search' | 'hash'>): OAuthCallback {
+  const value = PAGE_COOKIE.exec(cookie)?.[1];
+  if (value === undefined) return { kind: 'notStarted' };
+
+  let page: URL;
+  try {
+    page = new URL(decodeURIComponent(value), location.origin);
+  } catch {
+    return { kind: 'unknownPage' };
+  }
+  // Anything else is an open redirect, carrying the authorization code to another site.
+  if (page.origin !== location.origin) return { kind: 'unknownPage' };
+
+  const query = new URLSearchParams(location.search);
+  const answer = query.has('error') ? query : new URLSearchParams(location.hash.slice(1));
+  const error = answer.get('error');
+  if (error !== null) {
+    return { kind: 'providerError', error, description: answer.get('error_description'), page: page.href };
+  }
+
+  // Whole, not as a path: a path of `//evil.test/x` would be read as another site's address.
+  page.search = location.search;
+  page.hash = location.hash;
+  return { kind: 'return', url: page.href };
+}
+
+/**
+ * The playground leaves the cookie for the session, so a later visit would be sent back to the
+ * last page that started an authorization. Forgotten once read, it names only the flow just started.
+ */
+export function forgetStartingPage(): void {
+  document.cookie = `${PAGE_COOKIE_NAME}=; path=/; max-age=0`;
+}
diff --git a/portal-template/src/lib/portal-types.ts b/portal-template/src/lib/portal-types.ts
index c9b24fe7e..8762b2eb2 100644
--- a/portal-template/src/lib/portal-types.ts
+++ b/portal-template/src/lib/portal-types.ts
@@ -10,14 +10,14 @@ export interface PortalLink {
   external: boolean;
 }
 
-/** Site-relative, one per colour mode; the same URL twice when one image serves both. */
+/** Portal-relative, one per colour mode; the same URL twice when one image serves both. */
 export interface PortalLogo {
   light: string;
   dark: string;
 }
 
 export interface PortalFavicon {
-  /** Site-relative, and inside the static directory. */
+  /** Portal-relative, and inside the static directory. */
   url: string;
   type: string | null;
 }
@@ -25,7 +25,7 @@ export interface PortalFavicon {
 export interface Portal {
   name: string;
   description: string | null;
-  /** Origin only, with no trailing slash. */
+  /** The site address, with no trailing slash. */
   siteUrl: string | null;
   logo: PortalLogo | null;
   favicon: PortalFavicon | null;
diff --git a/portal-template/src/lib/rehype-code-titles.ts b/portal-template/src/lib/rehype-code-titles.ts
index 862b6dff8..e563fe269 100644
--- a/portal-template/src/lib/rehype-code-titles.ts
+++ b/portal-template/src/lib/rehype-code-titles.ts
@@ -1,5 +1,5 @@
 import { parseCodeBlockAttributes } from 'fumadocs-core/mdx-plugins/codeblock-utils';
-import { CODE_BLOCK_TITLES } from './code-titles';
+import { CODE_BLOCK_TITLES, languageOf } from './code-titles';
 import { bundledLanguage } from './shiki-bundle';
 
 interface HastNode {
@@ -11,8 +11,6 @@ interface HastNode {
   children?: HastNode[];
 }
 
-const LANGUAGE_CLASS = 'language-';
-
 /** Where `remarkCodeTab` puts a tabbed block, by its own tabs or an MDX `<Tabs>`: the tab already names it. */
 const CODE_TABS = new Set(['CodeBlockTab', 'Tab', 'TabsContent']);
 
@@ -40,8 +38,8 @@ export function rehypeCodeTitles() {
       return;
     }
     const classes = Array.isArray(code.properties?.className) ? code.properties.className : [];
-    const languageClass = classes.find((name) => typeof name === 'string' && name.startsWith(LANGUAGE_CLASS));
-    const language = typeof languageClass === 'string' ? bundledLanguage(languageClass.slice(LANGUAGE_CLASS.length)) : null;
+    const name = languageOf(classes);
+    const language = name === undefined ? null : bundledLanguage(name);
     const meta = typeof code.properties?.metastring === 'string' ? code.properties.metastring : '';
     // Read as `rehypeCode` reads it, which shows no title for a bare or unquoted one.
     const { title } = parseCodeBlockAttributes(meta, ['title']).attributes;
diff --git a/portal-template/src/lib/remark-image-references.ts b/portal-template/src/lib/remark-image-references.ts
new file mode 100644
index 000000000..127b9a258
--- /dev/null
+++ b/portal-template/src/lib/remark-image-references.ts
@@ -0,0 +1,35 @@
+/** An mdast node, as far as images and the definitions they refer to go. */
+interface MarkdownNode {
+  type: string;
+  identifier?: string;
+  url?: string;
+  title?: string | null;
+  alt?: string | null;
+  position?: unknown;
+  children?: MarkdownNode[];
+}
+
+/** Writes `![alt][ref]` as `![alt](url)`, the only form Fumadocs' `remarkImage` imports. page.ts checks the same. */
+export function remarkImageReferences() {
+  return (tree: MarkdownNode) => {
+    const definitions = new Map<string, MarkdownNode>();
+    const define = (node: MarkdownNode) => {
+      // The first definition of a label wins, as CommonMark reads them.
+      if (node.type === 'definition' && node.identifier !== undefined && !definitions.has(node.identifier)) {
+        definitions.set(node.identifier, node);
+      }
+      node.children?.forEach(define);
+    };
+    define(tree);
+
+    const inline = (node: MarkdownNode): MarkdownNode => {
+      const definition = node.type === 'imageReference' ? definitions.get(node.identifier ?? '') : undefined;
+      if (definition !== undefined) {
+        return { type: 'image', url: definition.url, title: definition.title, alt: node.alt, position: node.position };
+      }
+      if (node.children !== undefined) node.children = node.children.map(inline);
+      return node;
+    };
+    inline(tree);
+  };
+}
diff --git a/portal-template/src/lib/search-content.ts b/portal-template/src/lib/search-content.ts
new file mode 100644
index 000000000..f49359ced
--- /dev/null
+++ b/portal-template/src/lib/search-content.ts
@@ -0,0 +1,28 @@
+import { remark } from 'remark';
+
+/** An mdast node, as far as finding images goes. */
+interface MarkdownNode {
+  type: string;
+  position?: { start: { offset?: number }; end: { offset?: number } };
+  children?: MarkdownNode[];
+}
+
+const IMAGES = new Set(['image', 'imageReference']);
+
+// Without GFM, as the search dialog renders a result.
+const markdown = remark();
+
+/** Markdown without its images, as Fumadocs indexes a page of its own, and otherwise as written. */
+export function withoutImages(text: string): string {
+  let kept = '';
+  let from = 0;
+  for (const { position } of imagesIn(markdown.parse(text))) {
+    kept += text.slice(from, position?.start.offset ?? from);
+    from = position?.end.offset ?? from;
+  }
+  return kept + text.slice(from);
+}
+
+function imagesIn(node: MarkdownNode): MarkdownNode[] {
+  return IMAGES.has(node.type) ? [node] : (node.children ?? []).flatMap(imagesIn);
+}
diff --git a/portal-template/src/lib/search-options.ts b/portal-template/src/lib/search-options.ts
new file mode 100644
index 000000000..665fdd554
--- /dev/null
+++ b/portal-template/src/lib/search-options.ts
@@ -0,0 +1,7 @@
+import { parseSearchWith, stringifySearchWith } from '@tanstack/react-router';
+
+/** Query values as text: under a base path the router rewrites the address through these, and JSON loses some. */
+export const searchOptions = {
+  parseSearch: parseSearchWith((value) => value),
+  stringifySearch: stringifySearchWith(JSON.stringify)
+};
diff --git a/portal-template/src/lib/source.server.ts b/portal-template/src/lib/source.server.ts
index 98367ff4d..58d1d0e4d 100644
--- a/portal-template/src/lib/source.server.ts
+++ b/portal-template/src/lib/source.server.ts
@@ -25,3 +25,5 @@ export const source = loader(
     pageTree: { transformers: [navigationTransformer(), tabsTransformer()], generateFallback: false }
   }
 );
+
+export type PortalPage = ReturnType<typeof source.getPages>[number];
diff --git a/portal-template/src/router.tsx b/portal-template/src/router.tsx
index 7815ed845..07b88abb4 100644
--- a/portal-template/src/router.tsx
+++ b/portal-template/src/router.tsx
@@ -1,12 +1,14 @@
 import { createRouter as createTanStackRouter } from '@tanstack/react-router';
 import { routeTree } from './routeTree.gen';
 import { NotFound } from '@/components/not-found';
+import { searchOptions } from '@/lib/search-options';
 
 export function getRouter() {
   return createTanStackRouter({
     routeTree,
     defaultPreload: 'intent',
     scrollRestoration: true,
-    defaultNotFoundComponent: NotFound
+    defaultNotFoundComponent: NotFound,
+    ...searchOptions
   });
 }
diff --git a/portal-template/src/routes/$.tsx b/portal-template/src/routes/$.tsx
index 19b6521e1..16c6686a6 100644
--- a/portal-template/src/routes/$.tsx
+++ b/portal-template/src/routes/$.tsx
@@ -3,6 +3,7 @@ import { createServerFn } from '@tanstack/react-start';
 import { docs, generated } from '@/lib/source';
 import { source } from '@/lib/source.server';
 import { PortalLayout } from '@/lib/layout';
+import { fullAddress } from '@/lib/base-path';
 import { getPageMarkdownUrl, slugsFromSplat } from '@/lib/shared';
 import { portal } from '@/lib/portal';
 import { absoluteUrl, canonicalLink } from '@/lib/seo';
@@ -129,7 +130,7 @@ function Content({
   const PageBody = page.body;
   const pathname = usePathname();
   // Named, or the popover reads `window.location.href` and sends the reader's query and hash on.
-  const pageUrl = typeof window === 'undefined' ? pathname : new URL(pathname, window.location.origin).toString();
+  const pageUrl = fullAddress(pathname);
 
   return (
     <DocsPage toc={toc} full={page.full}>
@@ -137,7 +138,7 @@ function Content({
       <DocsDescription>{page.description}</DocsDescription>
       <div className="flex flex-row gap-2 items-center border-b -mt-4 pb-6">
         {/* Keyed so a new page starts at "Copy Markdown", not at the last page's result. */}
-        <MarkdownCopyButton key={markdownUrl} markdownUrl={markdownUrl} base={import.meta.env.BASE_URL} />
+        <MarkdownCopyButton key={markdownUrl} markdownUrl={markdownUrl} />
         {/* Sends the reader to an external AI vendor, so a portal published under someone
             else's brand can turn it off. */}
         {portal.pageActions ? <ViewOptionsPopover markdownUrl={markdownUrl} pageUrl={pageUrl} /> : null}
diff --git a/portal-template/src/routes/__root.tsx b/portal-template/src/routes/__root.tsx
index 2bd185bfd..ba8d973df 100644
--- a/portal-template/src/routes/__root.tsx
+++ b/portal-template/src/routes/__root.tsx
@@ -5,6 +5,7 @@ import { source } from '@/lib/source.server';
 import appCss from '@/styles/app.css?url';
 import { RootProvider } from 'fumadocs-ui/provider/tanstack';
 import SearchDialog from '@/components/search';
+import { withBasePath } from '@/lib/base-path';
 import { portal } from '@/lib/portal';
 
 // The sidebar tree is the same on every page. Loaded here, once, it is written to a single
@@ -15,7 +16,13 @@ const loadPageTree = createServerFn({ method: 'GET' })
 
 // Without one the browser tab shows the blank-document icon on every page.
 const iconLinks = portal.favicon
-  ? [{ rel: 'icon', href: portal.favicon.url, ...(portal.favicon.type ? { type: portal.favicon.type } : {}) }]
+  ? [
+      {
+        rel: 'icon',
+        href: withBasePath(portal.favicon.url),
+        ...(portal.favicon.type ? { type: portal.favicon.type } : {})
+      }
+    ]
   : [];
 
 // A portal fixed to one mode keeps to it whatever the visitor's system prefers, and offers no
diff --git a/portal-template/src/routes/api/search[.]json.ts b/portal-template/src/routes/api/search[.]json.ts
index b1851d3b4..661d8dc4a 100644
--- a/portal-template/src/routes/api/search[.]json.ts
+++ b/portal-template/src/routes/api/search[.]json.ts
@@ -1,9 +1,30 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { source } from '@/lib/source.server';
+import { withoutImages } from '@/lib/search-content';
+import { type PortalPage, source } from '@/lib/source.server';
 import { createFromSource } from 'fumadocs-core/search/server';
 
-const server = createFromSource(source, { language: 'english' });
+// Fumadocs indexes a reference page's description as written, so results show its images, without the path.
+const server = createFromSource(
+  { ...source, getPages: (language?: string) => source.getPages(language).map(searchable) },
+  { language: 'english' }
+);
 
 export const Route = createFileRoute('/api/search.json')({
   server: { handlers: { GET: () => server.staticGET() } }
 });
+
+/** A reference page as Fumadocs indexes a page of its own: without images. */
+function searchable(page: PortalPage): PortalPage {
+  if (page.type !== 'openapi') return page;
+  const { description, structuredData } = page.data;
+  const contents = structuredData.contents.map((item) => ({ ...item, content: withoutImages(item.content) }));
+  // Both alike, or Fumadocs no longer finds the description among the contents and indexes it a second time.
+  return {
+    ...page,
+    data: {
+      ...page.data,
+      description: description && withoutImages(description),
+      structuredData: { ...structuredData, contents }
+    }
+  };
+}
diff --git a/portal-template/src/routes/oauth.callback.tsx b/portal-template/src/routes/oauth.callback.tsx
new file mode 100644
index 000000000..4ced996a4
--- /dev/null
+++ b/portal-template/src/routes/oauth.callback.tsx
@@ -0,0 +1,54 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { useEffect, useState } from 'react';
+import { AuthorizationFailure } from '@/components/authorization-failure';
+import { baseOptions } from '@/lib/layout.shared';
+import { forgetStartingPage, oauthCallback, type OAuthCallback, type OAuthCallbackFailure } from '@/lib/oauth-callback';
+import { portal } from '@/lib/portal';
+
+// Published portals are static, so this page does in the browser what Fumadocs'
+// `createOAuthHandler()` route does on a server.
+export const Route = createFileRoute('/oauth/callback')({
+  head: () => ({ meta: [{ title: `Authorization | ${portal.name}` }, { name: 'robots', content: 'noindex' }] }),
+  component: OAuthCallbackPage
+});
+
+let completion: OAuthCallback | undefined;
+
+/**
+ * Reading the cookie and sending the browser on can each happen only once per page load, not
+ * once per mount: the StrictMode `portal serve` runs under mounts the page twice, and the second
+ * mount would find the cookie gone. The answer is kept, so a later mount in the same load, such
+ * as Back after leaving through the header, shows the same outcome. Every arrival from a provider
+ * is a new load.
+ */
+function completeAuthorization(): OAuthCallback {
+  if (completion === undefined) {
+    completion = oauthCallback(document.cookie, window.location);
+    forgetStartingPage();
+    if (completion.kind === 'return') window.location.replace(completion.url);
+  }
+  return completion;
+}
+
+function OAuthCallbackPage() {
+  // Null until the effect has read the cookie, which the prerendered page cannot.
+  const [failure, setFailure] = useState<OAuthCallbackFailure | null>(null);
+
+  useEffect(() => {
+    const callback = completeAuthorization();
+    if (callback.kind !== 'return') setFailure(callback);
+  }, []);
+
+  return (
+    <HomeLayout {...baseOptions()}>
+      <div className="flex flex-col px-8 justify-center flex-1 text-center items-center gap-4">
+        {failure === null ? (
+          <p className="text-fd-muted-foreground">Completing authorization…</p>
+        ) : (
+          <AuthorizationFailure failure={failure} />
+        )}
+      </div>
+    </HomeLayout>
+  );
+}
diff --git a/portal-template/static-functions-base.ts b/portal-template/static-functions-base.ts
new file mode 100644
index 000000000..dba8d9c0e
--- /dev/null
+++ b/portal-template/static-functions-base.ts
@@ -0,0 +1,41 @@
+import type { Plugin } from 'vite';
+import { withBasePath } from './src/lib/base-path';
+
+/** The package whose browser half fetches a prerendered server function's result. */
+const PACKAGE = /[\\/]@tanstack[\\/]start-static-server-functions[\\/]/;
+
+/** Where it fetches that result from, opening backtick included so nothing else naming the folder matches. */
+export const CACHE_ADDRESS = '`/__tsr/staticServerFnCache/';
+
+/** Puts the browser's fetch of prerendered page data under the base, until TanStack/router#6152 does it itself. */
+export function staticFunctionsBase(): Plugin {
+  let base = '/';
+  let found = false;
+  return {
+    name: 'apimatic:static-functions-base',
+    apply: 'build',
+    enforce: 'pre',
+    // The server writes the files under the output directory, which the host already serves at the base.
+    applyToEnvironment: (environment) => environment.name === 'client',
+    configResolved(config) {
+      base = config.base;
+    },
+    transform: {
+      filter: { id: PACKAGE, code: CACHE_ADDRESS },
+      handler(code) {
+        // Found at the root too, where the replacement is the address itself.
+        found = true;
+        return code.replaceAll(CACHE_ADDRESS, '`' + withBasePath(CACHE_ADDRESS.slice(1), base));
+      }
+    },
+    // An upgrade that moves the address fails the build, rather than every link in the portal.
+    buildEnd(error) {
+      if (error === undefined && !found) {
+        this.error(
+          `No module of @tanstack/start-static-server-functions holds ${CACHE_ADDRESS}, so a portal ` +
+            'served under a path could not load the pages its links lead to. See portal-template/static-functions-base.ts.'
+        );
+      }
+    }
+  };
+}
diff --git a/portal-template/vite.config.ts b/portal-template/vite.config.ts
index 38b846862..53a0947ae 100644
--- a/portal-template/vite.config.ts
+++ b/portal-template/vite.config.ts
@@ -1,7 +1,7 @@
 import { fileURLToPath } from 'node:url';
 import react from '@vitejs/plugin-react';
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
-import { defineConfig } from 'vite';
+import { defineConfig, searchForWorkspaceRoot } from 'vite';
 import tailwindcss from '@tailwindcss/vite';
 import { fumadocsMdx } from 'fumadocs-mdx/vite';
 import { dependencyDirectories } from './dependency-directories.ts';
@@ -10,22 +10,31 @@ import { generatedPagesReload } from './generated-pages-reload.ts';
 import { readBuildPaths, readPortalIdentity } from './portal-config.ts';
 import { prerenderPages } from './prerender-pages.ts';
 import { specReload } from './spec-reload.ts';
+import { remarkImageReferences } from './src/lib/remark-image-references.ts';
+import { staticFunctionsBase } from './static-functions-base.ts';
 
 export default defineConfig(async () => {
   const [paths, identity] = await Promise.all([readBuildPaths(), readPortalIdentity()]);
   const pages = await prerenderPages(paths, identity.siteUrl);
   const publicDir: string | false = paths.staticDir ?? false;
-  const projectDirectory = fileURLToPath(new URL('.', import.meta.url));
+  const portalProjectDirectory = fileURLToPath(new URL('.', import.meta.url));
 
   return {
+    // TanStack Start derives the router's basepath and every asset URL from it.
+    base: paths.base,
     publicDir,
     plugins: [
       generatedPagesReload(),
       downloads(paths.downloadsDir),
+      staticFunctionsBase(),
       // `/images/logo.png` is read from the static directory, and a remote image is never fetched for its size.
       fumadocsMdx({
         globalOptions: {
-          mdxOptions: { remarkImageOptions: { publicDir: publicDir || undefined, external: false } }
+          mdxOptions: {
+            remarkImageOptions: { publicDir: publicDir || undefined, external: false },
+            // A function, so it runs ahead of the preset's own plugins, `remarkImage` among them.
+            remarkPlugins: (plugins) => [remarkImageReferences, ...plugins]
+          }
         }
       }),
       specReload(paths.specs),
@@ -57,13 +66,11 @@ export default defineConfig(async () => {
     // listens on `::1` alone, a connect that stalls under load falls back to 127.0.0.1 and is
     // refused, failing the build; binding IPv4 leaves the fetch a single address to reach.
     preview: { host: '127.0.0.1' },
-    // Spelled out because the default, the project alone, misses the CLI installation the
-    // dependencies are linked from, and the static directory pages import images from.
     server: {
       fs: {
         allow: [
-          projectDirectory,
-          ...dependencyDirectories(projectDirectory),
+          searchForWorkspaceRoot(portalProjectDirectory),
+          ...dependencyDirectories(portalProjectDirectory),
           ...(paths.staticDir === null ? [] : [paths.staticDir])
         ]
       }
diff --git a/src/actions/action-result.ts b/src/actions/action-result.ts
index 6765d56d4..6cb6cfd6d 100644
--- a/src/actions/action-result.ts
+++ b/src/actions/action-result.ts
@@ -4,23 +4,25 @@ enum ResultType {
   Failure = 1,
 }
 
-export class ActionResult<T = void> {
+export class ActionResult<T = void, E = never> {
   private readonly message: string;
   private readonly resultType: ResultType;
   private readonly value?: T;
+  private readonly error?: E;
 
-  private constructor(resultType: ResultType, message: string, value?: T) {
+  private constructor(resultType: ResultType, message: string, value?: T, error?: E) {
     this.resultType = resultType;
     this.message = message;
     this.value = value;
+    this.error = error;
   }
 
   static success<T>(value?: T): ActionResult<T> {
     return new ActionResult<T>(ResultType.Success, "Succeeded", value);
   }
 
-  static failed<T = never>(message = "Failed"): ActionResult<T> {
-    return new ActionResult(ResultType.Failure, message);
+  static failed<T = never, E = never>(message = "Failed", error?: E): ActionResult<T, E> {
+    return new ActionResult<T, E>(ResultType.Failure, message, undefined, error);
   }
 
   static cancelled<T = never>(message = "Cancelled"): ActionResult<T> {
@@ -77,6 +79,10 @@ export class ActionResult<T = void> {
     return this.isSuccess() ? this.value! : defaultValue;
   }
 
+  public getError(): E | undefined {
+    return this.error;
+  }
+
   public discardValue(): ActionResult {
     return new ActionResult(this.resultType, this.message);
   }
diff --git a/src/actions/api/transform.ts b/src/actions/api/transform.ts
index 4efbeb9b8..399409772 100644
--- a/src/actions/api/transform.ts
+++ b/src/actions/api/transform.ts
@@ -1,14 +1,15 @@
-import { DirectoryPath } from "../../types/file/directoryPath.js";
-import { ActionResult } from "../action-result.js";
-import { ApiTransformPrompts } from "../../prompts/api/transform.js";
-import { withDirPath } from "../../infrastructure/tmp-extensions.js";
-import { TransformationService } from "../../infrastructure/services/transformation-service.js";
-import { ExportFormats } from "@apimatic/sdk";
-import { ApiValidatePrompts } from "../../prompts/api/validate.js";
-import { CommandMetadata } from "../../types/common/command-metadata.js";
-import { TransformContext } from "../../types/transform-context.js";
-import { ResourceInput } from "../../types/file/resource-input.js";
-import { ResourceContext } from "../../types/resource-context.js";
+import { DirectoryPath } from '../../types/file/directoryPath.js';
+import { ActionResult } from '../action-result.js';
+import { ApiTransformPrompts } from '../../prompts/api/transform.js';
+import { withDirPath } from '../../infrastructure/tmp-extensions.js';
+import { TransformationService } from '../../infrastructure/services/transformation-service.js';
+import { ExportFormats } from '@apimatic/sdk';
+import { ApiValidatePrompts } from '../../prompts/api/validate.js';
+import { CommandMetadata } from '../../types/common/command-metadata.js';
+import { TransformContext } from '../../types/transform-context.js';
+import { FilePath } from '../../types/file/filePath.js';
+import { UrlPath } from '../../types/file/urlPath.js';
+import { ResourceContext } from '../../types/resource-context.js';
 
 export class TransformAction {
   private readonly prompts: ApiTransformPrompts = new ApiTransformPrompts();
@@ -25,19 +26,18 @@ export class TransformAction {
   }
 
   public readonly execute = async (
-    resourcePath: ResourceInput,
+    resourcePath: FilePath | UrlPath,
     format: ExportFormats,
     destination: DirectoryPath,
     force: boolean
   ): Promise<ActionResult> => {
     return await withDirPath(async (tempDirectory) => {
-      const resourceContext = new ResourceContext(tempDirectory);
-      const specFileDirResult = await resourceContext.resolveTo(resourcePath);
-      if (specFileDirResult.isErr()) {
-        this.prompts.networkError(specFileDirResult.error);
+      const spec = await ResourceContext.resolveTo(resourcePath, tempDirectory);
+      if (spec.isErr()) {
+        this.validatePrompts.specUnavailable(spec.error);
         return ActionResult.failed();
       }
-      const transformContext = new TransformContext(specFileDirResult.value, format, destination);
+      const transformContext = new TransformContext(spec.value.file(), format, destination);
       if (!force && (await transformContext.exists()) && !(await this.prompts.overwriteApi(destination))) {
         this.prompts.transformedApiAlreadyExists();
         return ActionResult.cancelled();
@@ -45,7 +45,7 @@ export class TransformAction {
 
       const result = await this.prompts.transformApi(
         this.transformationService.transformViaFile({
-          file: specFileDirResult.value,
+          file: spec.value.file(),
           format: format,
           configDir: this.configDir,
           commandMetadata: this.commandMetadata,
diff --git a/src/actions/api/validate.ts b/src/actions/api/validate.ts
index 4f6820acc..b79fb57b8 100644
--- a/src/actions/api/validate.ts
+++ b/src/actions/api/validate.ts
@@ -8,8 +8,8 @@ import { withDirPath } from '../../infrastructure/tmp-extensions.js';
 import { ResourceContext } from '../../types/resource-context.js';
 import { ValidationSummary } from '@apimatic/sdk';
 
-/** `unchecked`: the spec could not be fetched or the validation service did not answer, so nothing is known of it. */
-export type SpecCheck = 'valid' | 'invalid' | 'unchecked';
+/** `unchecked`: the spec never reached the validation service, or the service did not answer, so nothing is known of it. */
+export type ValidateActionFailure = 'invalid' | 'unchecked';
 
 export class ValidateAction {
   private readonly prompts: ApiValidatePrompts = new ApiValidatePrompts();
@@ -23,51 +23,47 @@ export class ValidateAction {
     this.commandMetadata = commandMetadata;
   }
 
-  /** `onChecked` hears what the validation found, which the `ActionResult` alone cannot tell apart. */
   public readonly execute = async (
-    resourcePath: ResourceInput,
-    displayValidationSummary = true,
-    onChecked?: (check: SpecCheck) => void
-  ): Promise<ActionResult> => {
-    const check = await this.check(resourcePath, displayValidationSummary);
-    onChecked?.(check);
-    return check === 'valid' ? ActionResult.success() : ActionResult.failed();
-  };
+    spec: ResourceInput | ResourceContext,
+    displayValidationSummary = true
+  ): Promise<ActionResult<void, ValidateActionFailure>> => {
+    if (!(spec instanceof ResourceContext)) {
+      return await withDirPath(async (tempDirectory) => {
+        const resolved = await ResourceContext.resolveTo(spec, tempDirectory);
+        if (resolved.isErr()) {
+          this.prompts.specUnavailable(resolved.error);
+          return ActionResult.failed(undefined, 'unchecked');
+        }
+        return await this.execute(resolved.value, displayValidationSummary);
+      });
+    }
+    const validationSummaryResult = await this.prompts.validateApi(
+      this.validationService.validateViaFile({
+        file: spec.file(),
+        commandMetadata: this.commandMetadata,
+        authKey: this.authKey
+      })
+    );
 
-  private readonly check = async (
-    resourcePath: ResourceInput,
-    displayValidationSummary: boolean
-  ): Promise<SpecCheck> => {
-    return await withDirPath(async (tempDirectory) => {
-      const resourceContext = new ResourceContext(tempDirectory);
-      const specFileDirResult = await resourceContext.resolveTo(resourcePath);
-      if (specFileDirResult.isErr()) {
-        this.prompts.networkError(specFileDirResult.error);
-        return 'unchecked';
-      }
-      const validationSummaryResult = await this.prompts.validateApi(
-        this.validationService.validateViaFile({
-          file: specFileDirResult.value,
-          commandMetadata: this.commandMetadata,
-          authKey: this.authKey
-        })
+    if (validationSummaryResult.isErr()) {
+      this.prompts.logValidationError(validationSummaryResult.error.message);
+      return ActionResult.failed(
+        undefined,
+        validationSummaryResult.error.kind === 'rejected' ? 'invalid' : 'unchecked'
       );
-
-      if (validationSummaryResult.isErr()) {
-        this.prompts.logValidationError(validationSummaryResult.error.message);
-        return validationSummaryResult.error.kind === 'rejected' ? 'invalid' : 'unchecked';
+    }
+    const { validation, linting } = validationSummaryResult.value;
+    if (displayValidationSummary) {
+      if (this.hasValidationIssues(validation)) {
+        this.prompts.displayValidationSummary(validation);
       }
-      const { validation, linting } = validationSummaryResult.value;
-      if (displayValidationSummary) {
-        if (this.hasValidationIssues(validation)) {
-          this.prompts.displayValidationSummary(validation);
-        }
-        if (this.hasValidationIssues(linting)) {
-          this.prompts.displayValidationSummary(linting);
-        }
+      if (this.hasValidationIssues(linting)) {
+        this.prompts.displayValidationSummary(linting);
       }
-      return validation.isSuccess && linting.isSuccess ? 'valid' : 'invalid';
-    });
+    }
+    return validation.isSuccess && linting.isSuccess
+      ? ActionResult.success()
+      : ActionResult.failed(undefined, 'invalid');
   };
 
   private hasValidationIssues(summary: ValidationSummary): boolean {
diff --git a/src/actions/portal/generate.ts b/src/actions/portal/generate.ts
index 8f716507f..2a1f42b3b 100644
--- a/src/actions/portal/generate.ts
+++ b/src/actions/portal/generate.ts
@@ -4,6 +4,7 @@ import { PortalGeneratePrompts } from '../../prompts/portal/generate.js';
 import { CommandMetadata } from '../../types/common/command-metadata.js';
 import { DirectoryPath } from '../../types/file/directoryPath.js';
 import { PortalContext } from '../../types/portal-context.js';
+import { SiteAddress } from '../../types/portal/config/site-address.js';
 import { ProjectContext } from '../../types/project-context.js';
 import { ActionResult } from '../action-result.js';
 import { PreparePortalProjectAction } from './prepare-project.js';
@@ -42,7 +43,8 @@ export class GenerateAction {
     const portalContext = new PortalContext(portalDirectory);
     return await new PreparePortalProjectAction(this.configDir, this.commandMetadata, this.authKey).execute(project, {
       confirm: () => this.confirmOverwrite(portalContext, portalDirectory, force),
-      onPrepared: (portalProject) => this.build(portalProject, portalContext, portalDirectory, zipPortal)
+      onPrepared: (portalProject, source) =>
+        this.build(portalProject, source.config.siteAddress(), portalContext, portalDirectory, zipPortal)
     });
   };
 
@@ -60,6 +62,7 @@ export class GenerateAction {
 
   private async build(
     portalProject: PortalProjectPaths,
+    site: SiteAddress | null,
     portalContext: PortalContext,
     portalDirectory: DirectoryPath,
     zipPortal: boolean
@@ -79,7 +82,7 @@ export class GenerateAction {
     }
 
     this.prompts.portalGenerated(portalDirectory);
-    this.prompts.nextSteps(portalDirectory, zipPortal);
+    this.prompts.nextSteps(portalDirectory, zipPortal, site);
 
     return ActionResult.success();
   }
diff --git a/src/actions/quickstart.ts b/src/actions/quickstart.ts
index f02c80970..b82511175 100644
--- a/src/actions/quickstart.ts
+++ b/src/actions/quickstart.ts
@@ -1,4 +1,3 @@
-import { err, ok, Result } from 'neverthrow';
 import { getAuthInfo } from '../client-utils/auth-manager.js';
 import { FileService } from '../infrastructure/file-service.js';
 import { withDirPath } from '../infrastructure/tmp-extensions.js';
@@ -6,29 +5,23 @@ import { QuickstartPrompts } from '../prompts/quickstart.js';
 import { DirectoryPath } from '../types/file/directoryPath.js';
 import { FilePath } from '../types/file/filePath.js';
 import { UrlPath } from '../types/file/urlPath.js';
-import { ResourceInput } from '../types/file/resource-input.js';
 import { LoginAction } from './auth/login.js';
 import { ActionResult } from './action-result.js';
 import { CommandMetadata } from '../types/common/command-metadata.js';
-import { SpecCheck, ValidateAction } from './api/validate.js';
-import { SpecContext } from '../types/spec-context.js';
+import { ValidateAction, ValidateActionFailure } from './api/validate.js';
 import { OpenApiDocument, SpecFormat } from '../types/portal/openapi-document.js';
-import { PortalScaffoldProblem } from '../types/portal/portal-source.js';
+import { ResourceInput } from '../types/file/resource-input.js';
 import { PortalAuthorizationService } from '../infrastructure/services/portal-authorization-service.js';
-import { FileDownloadService } from '../infrastructure/services/file-download-service.js';
 import { PortalProjectService } from '../infrastructure/portal-project-service.js';
 import { APIMATIC_SCHEMA_URL } from '../types/apimatic-config/document.js';
 import { PLACEHOLDER_METADATA } from '../types/plugin/plugin-config.js';
 import { ProjectContext } from '../types/project-context.js';
+import { ResourceContext } from '../types/resource-context.js';
 import { DEFAULT_PORTAL_PORT, PortalServeAction } from './portal/serve.js';
 
-/** A URL's `file` is a download in a temporary directory, so only `source` says what the user gave. */
-type ImportedSpec = { file: FilePath; source: ResourceInput };
-
 export class QuickstartAction {
   private readonly prompts: QuickstartPrompts = new QuickstartPrompts();
   private readonly fileService: FileService = new FileService();
-  private readonly fileDownloadService = new FileDownloadService();
   private readonly authorizationService = new PortalAuthorizationService();
   private readonly projectService = new PortalProjectService();
   private readonly configDir: DirectoryPath;
@@ -70,46 +63,136 @@ export class QuickstartAction {
       return ActionResult.failed();
     }
 
-    return await withDirPath<ActionResult>((tempDirectory: DirectoryPath) =>
-      this.runWizard(workingDirectory, tempDirectory)
-    );
+    return await withDirPath<ActionResult>(async (tempDirectory: DirectoryPath) => {
+      const here = ProjectContext.in(workingDirectory);
+      return (await here.specsExist())
+        ? await this.adoptProject(here, workingDirectory)
+        : await this.startProject(tempDirectory);
+    });
   };
 
-  private async runWizard(workingDirectory: DirectoryPath, tempDirectory: DirectoryPath): Promise<ActionResult> {
-    const here = ProjectContext.in(workingDirectory);
-    const adoptedSpec = await here.portalSource().primarySpec();
-    return adoptedSpec === null
-      ? await this.startProject(tempDirectory)
-      : await this.adoptProject(here, workingDirectory, adoptedSpec, tempDirectory);
-  }
-
   // A build downloaded from the platform arrives with its specification in `src/spec/`, so it is not asked for again.
-  private async adoptProject(
-    project: ProjectContext,
-    projectDirectory: DirectoryPath,
-    specPath: FilePath,
-    tempDirectory: DirectoryPath
-  ): Promise<ActionResult> {
-    this.prompts.importSpecStepAdopted(project.sourceDirectory());
-    const validated = await this.validate({ file: specPath, source: specPath }, tempDirectory, true);
-    if (validated.isErr()) {
-      return validated.error;
+  private async adoptProject(project: ProjectContext, projectDirectory: DirectoryPath): Promise<ActionResult> {
+    const sourceDirectory = project.sourceDirectory();
+    const config = await project.config().read();
+    if (config.state === 'missing') {
+      this.prompts.configMissing(sourceDirectory);
+      return ActionResult.failed();
+    }
+    const unsupported = config.state === 'parsed' ? config.document.findingsFor('root') : config.findings;
+    if (unsupported.length > 0) {
+      this.prompts.configUnsupported(unsupported, sourceDirectory);
+      return ActionResult.failed();
+    }
+
+    this.prompts.importSpecStepAdopted(sourceDirectory);
+    this.prompts.validateSpecStep();
+    const failure = await this.validationFailure(project);
+    if (failure === 'unchecked') {
+      return ActionResult.failed();
+    }
+    // No sample is offered: nothing here moves it into a `spec/` the project already fills.
+    if (failure === 'invalid') {
+      this.prompts.specValidationFailed('project');
+      this.prompts.fixYourSpec();
+      return ActionResult.cancelled();
+    }
+
+    const portalSource = project.portalSource();
+    const specs = await portalSource.resolveSpecs();
+    if (specs.isErr()) {
+      this.prompts.specsUnsupported(specs.error, sourceDirectory);
+      return ActionResult.failed();
     }
 
     this.prompts.createPortalStep();
-    const scaffolded = await project.portalSource().adopt(validated.value, APIMATIC_SCHEMA_URL);
-    return await this.completeProject(project, projectDirectory, scaffolded);
+    const [namedAfter] = specs.value;
+    const adopted = await portalSource.adopt(namedAfter);
+    if (adopted.isErr()) {
+      this.prompts.scaffoldFailed(adopted.error, sourceDirectory);
+      return ActionResult.failed();
+    }
+    const pluginConfig = project.pluginConfig();
+    const pluginAdded = await pluginConfig.addMetadataIfMissing(PLACEHOLDER_METADATA);
+    if (pluginAdded.isErr()) {
+      this.prompts.configNotWritten(pluginAdded.error, sourceDirectory);
+      return ActionResult.failed();
+    }
+
+    if (await pluginConfig.languagesMissing()) {
+      const languages = await this.prompts.selectLanguages();
+      if (!languages?.length) {
+        this.prompts.noLanguagesSelected();
+        return ActionResult.cancelled();
+      }
+      const languagesAdded = await pluginConfig.addLanguagesIfMissing(languages);
+      if (languagesAdded.isErr()) {
+        this.prompts.configNotWritten(languagesAdded.error, sourceDirectory);
+        return ActionResult.failed();
+      }
+    }
+
+    return await this.completeProject(project, projectDirectory, adopted.value);
   }
 
   private async startProject(tempDirectory: DirectoryPath): Promise<ActionResult> {
     this.prompts.importSpecStep();
-    const imported = await this.importSpec(tempDirectory);
-    if (imported === undefined) {
-      return ActionResult.cancelled();
+    // Dropped once the CLI's own sample has failed: re-offering the address the user just
+    // watched fail, pre-filled, is the one suggestion that cannot work.
+    let sampleUrl: UrlPath | null = this.defaultSpecUrl;
+    let spec: ResourceContext;
+    for (;;) {
+      const input = await this.prompts.specPathPrompt(sampleUrl);
+      if (!input) {
+        this.prompts.noSpecSpecified();
+        return ActionResult.cancelled();
+      }
+      const resolving = ResourceContext.resolveTo(input, tempDirectory.join('user-spec'));
+      const resolved = input instanceof UrlPath ? await this.prompts.downloadSpecFile(resolving) : await resolving;
+      if (resolved.isOk()) {
+        spec = resolved.value;
+        break;
+      }
+      this.prompts.specUnavailable(resolved.error);
+      if (resolved.error.kind === 'downloadFailed' && sampleUrl?.isEqual(resolved.error.url)) {
+        sampleUrl = null;
+      }
     }
-    const validated = await this.validate(imported, tempDirectory, false);
-    if (validated.isErr()) {
-      return validated.error;
+
+    this.prompts.validateSpecStep();
+    const failure = await this.validationFailure(spec);
+    // The service's own error is already on screen; the spec may be valid, so there is nothing to fix.
+    if (failure === 'unchecked') {
+      return ActionResult.failed();
+    }
+    if (failure === 'invalid') {
+      this.prompts.specValidationFailed(spec.kind());
+      if (!(await this.prompts.useDefaultSpecPrompt())) {
+        this.prompts.fixYourSpec();
+        return ActionResult.cancelled();
+      }
+      const sample = await this.prompts.downloadSpecFile(
+        ResourceContext.resolveTo(this.defaultSpecUrl, tempDirectory.join('sample'))
+      );
+      if (sample.isErr()) {
+        this.prompts.specUnavailable(sample.error);
+        return ActionResult.failed();
+      }
+      spec = sample.value;
+    }
+    const specFile = spec.file();
+
+    // The validation above accepts Swagger 2.0, which a portal cannot be built from. Asked
+    // here rather than left to `portal serve`, which refuses only once the project is
+    // written -- and running the wizard again then rejects the non-empty tree it created.
+    const format = await this.specFormat(specFile);
+    if (!format.supported) {
+      if (format.format === null) {
+        this.prompts.specNotRecognised(specFile);
+      } else {
+        this.prompts.specFormatUnsupported(specFile, format.format);
+      }
+      return ActionResult.failed();
     }
 
     this.prompts.createPortalStep();
@@ -118,16 +201,8 @@ export class QuickstartAction {
       return ActionResult.cancelled();
     }
     const project = ProjectContext.in(projectDirectory);
-    const scaffolded = await project.portalSource().scaffold(validated.value, APIMATIC_SCHEMA_URL);
-    return await this.completeProject(project, projectDirectory, scaffolded);
-  }
-
-  private async completeProject(
-    project: ProjectContext,
-    projectDirectory: DirectoryPath,
-    scaffolded: Result<FilePath, PortalScaffoldProblem>
-  ): Promise<ActionResult> {
     const sourceDirectory = project.sourceDirectory();
+    const scaffolded = await project.portalSource().scaffold(specFile, APIMATIC_SCHEMA_URL);
     if (scaffolded.isErr()) {
       this.prompts.scaffoldFailed(scaffolded.error, sourceDirectory);
       return ActionResult.failed();
@@ -148,107 +223,36 @@ export class QuickstartAction {
       this.prompts.configNotWritten(pluginConfigRecorded.error, sourceDirectory);
       return ActionResult.failed();
     }
+    return await this.completeProject(project, projectDirectory, scaffolded.value);
+  }
 
+  private async completeProject(
+    project: ProjectContext,
+    projectDirectory: DirectoryPath,
+    configFile: FilePath
+  ): Promise<ActionResult> {
     // Reported rather than fatal: what Git tracks does not decide whether a portal can be built.
     const ignored = await project.upsertGitignore();
     if (ignored.isErr()) {
       this.prompts.gitignoreNotUpdated(ignored.error, projectDirectory);
     }
 
-    const structure = await this.fileService.getDirectory(sourceDirectory);
+    const structure = await this.fileService.getDirectory(project.sourceDirectory());
     this.prompts.printDirectoryStructure(projectDirectory, structure);
 
     const result = await new PortalServeAction(this.configDir, this.commandMetadata, null).execute(
       project,
       DEFAULT_PORTAL_PORT,
       true,
-      () => this.prompts.nextSteps(scaffolded.value)
+      () => this.prompts.nextSteps(configFile)
     );
 
     return result.isFailed() ? ActionResult.failed() : ActionResult.success();
   }
 
-  private async importSpec(tempDirectory: DirectoryPath): Promise<ImportedSpec | undefined> {
-    // Dropped once the CLI's own sample has failed: re-offering the address the user just
-    // watched fail, pre-filled, is the one suggestion that cannot work.
-    let sampleUrl: UrlPath | null = this.defaultSpecUrl;
-    for (;;) {
-      const inputPath = await this.prompts.specPathPrompt(sampleUrl);
-      if (!inputPath) {
-        this.prompts.noSpecSpecified();
-        return undefined;
-      }
-
-      if (inputPath instanceof UrlPath) {
-        const downloaded = await this.prompts.downloadSpecFile(this.fileDownloadService.downloadFile(inputPath));
-        if (downloaded.isErr()) {
-          this.prompts.specDownloadFailed(inputPath, downloaded.error);
-          if (sampleUrl !== null && inputPath.isEqual(sampleUrl)) {
-            sampleUrl = null;
-          }
-          continue;
-        }
-        const file = await new SpecContext(tempDirectory).save(downloaded.value.stream, downloaded.value.filename);
-        return { file, source: inputPath };
-      }
-
-      if (await this.fileService.fileExists(inputPath)) {
-        return { file: inputPath, source: inputPath };
-      }
-      this.prompts.specFileDoesNotExist();
-    }
-  }
-
-  /**
-   * `adopted` decides what a failure offers. The sample can replace a specification the user
-   * named, but not one their project carries: an adopted `spec/` already holds the document the
-   * portal would be built from, and nothing here moves the sample into it.
-   */
-  private async validate(
-    spec: ImportedSpec,
-    tempDirectory: DirectoryPath,
-    adopted: boolean
-  ): Promise<Result<FilePath, ActionResult>> {
-    this.prompts.validateSpecStep();
-    let validation = 'unchecked' as SpecCheck;
-    await new ValidateAction(this.configDir, this.commandMetadata).execute(spec.file, false, (check) => {
-      validation = check;
-    });
-    // The service's own error is already on screen; the spec may be valid, so there is nothing to fix.
-    if (validation === 'unchecked') {
-      return err(ActionResult.failed());
-    }
-
-    let checked = spec.file;
-    if (validation === 'invalid') {
-      this.prompts.specValidationFailed(spec.source);
-      if (adopted || !(await this.prompts.useDefaultSpecPrompt())) {
-        this.prompts.fixYourSpec();
-        return err(ActionResult.cancelled());
-      }
-      const downloaded = await this.prompts.downloadSpecFile(
-        this.fileDownloadService.downloadFile(this.defaultSpecUrl)
-      );
-      if (downloaded.isErr()) {
-        this.prompts.serviceError(downloaded.error);
-        return err(ActionResult.failed());
-      }
-      checked = await new SpecContext(tempDirectory).save(downloaded.value.stream, downloaded.value.filename);
-    }
-
-    // The validation above accepts Swagger 2.0, which a portal cannot be built from. Asked
-    // here rather than left to `portal serve`, which refuses only once the project is
-    // written -- and running the wizard again then rejects the non-empty tree it created.
-    const format = await this.specFormat(checked);
-    if (!format.supported) {
-      if (format.format === null) {
-        this.prompts.specNotRecognised(checked);
-      } else {
-        this.prompts.specFormatUnsupported(checked, format.format);
-      }
-      return err(ActionResult.failed());
-    }
-    return ok(checked);
+  private async validationFailure(spec: ResourceInput | ResourceContext): Promise<ValidateActionFailure | undefined> {
+    const validated = await new ValidateAction(this.configDir, this.commandMetadata).execute(spec, false);
+    return validated.isFailed() ? validated.getError() ?? 'unchecked' : undefined;
   }
 
   private async chooseProjectDirectory(): Promise<DirectoryPath | undefined> {
diff --git a/src/commands/api/transform.ts b/src/commands/api/transform.ts
index 409c952f2..6f078feaa 100644
--- a/src/commands/api/transform.ts
+++ b/src/commands/api/transform.ts
@@ -4,7 +4,7 @@ import { FlagsProvider } from '../../types/flags-provider.js';
 import { TransformAction } from '../../actions/api/transform.js';
 import { CommandMetadata } from '../../types/common/command-metadata.js';
 import { format, intro, outro } from '../../prompts/format.js';
-import { createResourceInput } from '../../types/file/resource-input.js';
+import { createFileOrUrlInput } from '../../types/file/resource-input.js';
 import { TransformationFormats } from '../../types/api/transform.js';
 import { TRANSFORMATIONS_DIRECTORY_NAME } from '../../types/transform-context.js';
 import { ExportFormats } from '@apimatic/sdk';
@@ -56,7 +56,7 @@ Supports multiple formats including OpenAPI/Swagger, RAML, WSDL, and Postman Col
 
     const workingDirectory = DirectoryPath.createInput(destination);
     const transformedApiDirectory = workingDirectory.join(TRANSFORMATIONS_DIRECTORY_NAME);
-    const specFile = createResourceInput(file, url);
+    const specFile = createFileOrUrlInput(file, url);
     // Directly map the format flag to ExportFormats using TransformationFormats
     const key = format as keyof typeof TransformationFormats;
     const transformationFormat = TransformationFormats[key] as keyof typeof ExportFormats;
diff --git a/src/commands/api/validate.ts b/src/commands/api/validate.ts
index d07a70f46..53328abe7 100644
--- a/src/commands/api/validate.ts
+++ b/src/commands/api/validate.ts
@@ -1,44 +1,56 @@
-import { Command, Flags } from "@oclif/core";
-import { DirectoryPath } from "../../types/file/directoryPath.js";
-import { FlagsProvider } from "../../types/flags-provider.js";
-import { ValidateAction } from "../../actions/api/validate.js";
-import { CommandMetadata } from "../../types/common/command-metadata.js";
-import { format, intro, outro } from "../../prompts/format.js";
-import { createResourceInput } from "../../types/file/resource-input.js";
+import { Command, Flags } from '@oclif/core';
+import { DirectoryPath } from '../../types/file/directoryPath.js';
+import { FlagsProvider } from '../../types/flags-provider.js';
+import { ValidateAction } from '../../actions/api/validate.js';
+import { CommandMetadata } from '../../types/common/command-metadata.js';
+import { format, intro, outro } from '../../prompts/format.js';
+import { createResourceInput } from '../../types/file/resource-input.js';
 
 export default class Validate extends Command {
-  static readonly summary = "Validate API specification for syntactic and semantic correctness";
+  static readonly summary = 'Validate API specification for syntactic and semantic correctness';
 
-  static readonly description = `Validate your API specification to ensure it adheres to syntactic and semantic standards.`;
+  static readonly description = `Validate the API specification in your 'src/spec' directory, or the one --file or --url points to, to ensure it adheres to syntactic and semantic standards.`;
 
-  static readonly cmdTxt = format.cmd("apimatic", "api", "validate");
+  static readonly cmdTxt = format.cmd('apimatic', 'api', 'validate');
 
   static examples = [
-    `${Validate.cmdTxt} ${format.flag("file", "./specs/sample.json")}`,
-    `${Validate.cmdTxt} ${format.flag("url", '"https://petstore.swagger.io/v2/swagger.json"')}`
+    Validate.cmdTxt,
+    `${Validate.cmdTxt} ${format.flag('input', './')}`,
+    `${Validate.cmdTxt} ${format.flag('file', './specs/sample.json')}`,
+    `${Validate.cmdTxt} ${format.flag('url', '"https://petstore.swagger.io/v2/swagger.json"')}`
   ];
 
   static flags = {
-    file: Flags.string({ description: "Path to the API specification file to validate" }),
-    url: Flags.string({ description: "URL to the API specification file to validate (publicly accessible)" }),
+    file: Flags.string({
+      description: 'Path to the API specification file to validate',
+      exclusive: ['url', 'input'],
+      parse: FlagsProvider.nonEmpty
+    }),
+    url: Flags.string({
+      description: 'URL to the API specification file to validate (publicly accessible)',
+      exclusive: ['file', 'input'],
+      parse: FlagsProvider.nonEmpty
+    }),
+    ...FlagsProvider.nonEmptyInput,
     ...FlagsProvider.authKey
   };
 
   async run() {
     const {
-      flags: { file, url, "auth-key": authKey }
+      flags: { file, url, input, 'auth-key': authKey }
     } = await this.parse(Validate);
 
+    const spec = createResourceInput(file, url, input);
+
     const commandMetadata: CommandMetadata = {
       commandName: Validate.id,
       shell: this.config.shell
     };
 
     const action = new ValidateAction(this.getConfigDir(), commandMetadata, authKey);
-    const resourceInput = createResourceInput(file, url);
 
-    intro("Validate API");
-    const result = await action.execute(resourceInput);
+    intro('Validate API');
+    const result = await action.execute(spec);
     outro(result);
   }
 
diff --git a/src/commands/portal/generate.ts b/src/commands/portal/generate.ts
index d70dc4f9a..4d6ea91e3 100644
--- a/src/commands/portal/generate.ts
+++ b/src/commands/portal/generate.ts
@@ -11,7 +11,7 @@ export default class PortalGenerate extends Command {
 
   static readonly description = `Builds a documentation portal from the OpenAPI documents and Markdown pages in your 'src' directory.
 
-The portal is built on your machine and written as static files you can host anywhere. Configure it with 'src/apimatic.json', whose 'languages' block gives the portal a page for each SDK language, and whose 'plugin' block, or a 'pluginUrl' in its 'portal' block for a plugin hosted elsewhere, a page for the context plugin.`;
+The portal is built on your machine and written as static files for any static host, served at its root or, when 'portal.site.url' has a path such as 'https://example.com/docs', at that path. Configure it with 'src/apimatic.json', whose 'languages' block gives the portal a page for each SDK language, and whose 'plugin' block, or a 'pluginUrl' in its 'portal' block for a plugin hosted elsewhere, a page for the context plugin.`;
 
   static readonly cmdTxt = format.cmd('apimatic', 'portal', 'generate');
 
diff --git a/src/commands/portal/serve.ts b/src/commands/portal/serve.ts
index a3e580561..edc13b150 100644
--- a/src/commands/portal/serve.ts
+++ b/src/commands/portal/serve.ts
@@ -13,7 +13,7 @@ export default class PortalServe extends Command {
 
   static readonly description = `Serves the portal described by 'src/apimatic.json' from your machine, reloading the browser as you edit the Markdown pages in 'src/content', reorder them in a 'nav.json', or change the 'portal', 'languages' or 'plugin' block of 'apimatic.json'.
 
-Adding a language or a 'plugin' block, adding or removing a page in 'src/content', creating 'src/static', or changing which documents are in 'src/spec', needs the preview restarted.
+Adding a language or a 'plugin' block, adding or removing a page in 'src/content', creating 'src/static', changing which documents are in 'src/spec', or changing the path in 'portal.site.url', needs the preview restarted.
 
 Nothing is written to disk; run 'apimatic portal generate' to produce the static files.`;
 
diff --git a/src/infrastructure/file-service.ts b/src/infrastructure/file-service.ts
index 9b523b9a9..5120a9e96 100644
--- a/src/infrastructure/file-service.ts
+++ b/src/infrastructure/file-service.ts
@@ -4,11 +4,13 @@ import fsExtra from 'fs-extra';
 import * as path from 'node:path';
 import { pipeline } from 'node:stream';
 import { promisify } from 'node:util';
+import { err, ok, Result } from 'neverthrow';
 import { FilePath } from '../types/file/filePath.js';
 import { DirectoryPath } from '../types/file/directoryPath.js';
 import { Directory, DirectoryItem } from '../types/file/directory.js';
 import { FileName } from '../types/file/fileName.js';
 import { sleep } from './timer-extensions.js';
+import { errorMessage } from '../utils/error-utils.js';
 
 /** `stat` follows a link, so a link to nothing fails as though the entry were not there. */
 function isDanglingLink(error: unknown): boolean {
@@ -73,6 +75,28 @@ export class FileService {
     }
   }
 
+  public async findSymlinks(dir: DirectoryPath): Promise<Result<FilePath[], string>> {
+    try {
+      return ok(await this.symlinksUnder(dir));
+    } catch (error) {
+      return err(errorMessage(error));
+    }
+  }
+
+  private async symlinksUnder(dir: DirectoryPath): Promise<FilePath[]> {
+    const symlinks: FilePath[] = [];
+    for (const name of await fsExtra.readdir(dir.toString())) {
+      const entry = new FilePath(dir, new FileName(name));
+      const stat = await fsExtra.lstat(entry.toString());
+      if (stat.isSymbolicLink()) {
+        symlinks.push(entry);
+      } else if (stat.isDirectory()) {
+        symlinks.push(...(await this.symlinksUnder(dir.join(name))));
+      }
+    }
+    return symlinks;
+  }
+
   public async cleanDirectory(dir: DirectoryPath): Promise<void> {
     await fsExtra.ensureDir(dir.toString());
     await fsExtra.emptyDir(dir.toString()); // removes everything inside, keeps the dir
diff --git a/src/infrastructure/portal-dev-server-service.ts b/src/infrastructure/portal-dev-server-service.ts
index 356adc91f..8c2e97abc 100644
--- a/src/infrastructure/portal-dev-server-service.ts
+++ b/src/infrastructure/portal-dev-server-service.ts
@@ -21,7 +21,8 @@ const OUTPUT_TAIL_BYTES = 64 * 1024;
 const DRAIN_TIMEOUT_MS = 2000;
 
 // Read after Vite's colour codes are stripped but not the line end, which proves the URL arrived whole.
-const LOCAL_URL_PATTERN = /Local:\s*(https?:\/\/\S+?)\/?[ \t]*[\r\n]/i;
+// A path keeps its trailing slash, since Vite answers `/docs` with a 404.
+const LOCAL_URL_PATTERN = /Local:\s*(https?:\/\/[^\s/]+(?:\/\S+\/)?)\/?[ \t]*[\r\n]/i;
 
 export interface PortalDevServer {
   url: UrlPath;
diff --git a/src/infrastructure/portal-project-service.ts b/src/infrastructure/portal-project-service.ts
index cb8698809..6a53f3b0f 100644
--- a/src/infrastructure/portal-project-service.ts
+++ b/src/infrastructure/portal-project-service.ts
@@ -18,6 +18,7 @@ import { errorMessage } from '../utils/error-utils.js';
 import { envInfo } from './env-info.js';
 import { FileService } from './file-service.js';
 import { PortalPagesService } from './portal-pages-service.js';
+import { canonical } from './tmp-extensions.js';
 
 // Copied, not linked: Tailwind rebases their `url()`s onto the project, and no relative path crosses drives.
 export const COPIED_DEPENDENCIES = ['@fontsource-variable/geist', '@fontsource-variable/geist-mono'];
@@ -41,6 +42,7 @@ export const LINKED_DEPENDENCIES = [
   'react',
   'react-dom',
   'rehype-raw',
+  'remark',
   'shiki',
   'tailwindcss',
   'tslib',
@@ -72,6 +74,7 @@ export interface PortalProjectPaths {
 
 /** `portal.config.json`, which the template reads as `BuildPaths`; a test holds the two to one shape. */
 export interface PortalBuildPaths {
+  base: string;
   specs: Record<string, string>;
   codeSamples: string | null;
   contentDir: string;
@@ -273,9 +276,10 @@ export class PortalProjectService {
       specs[spec.slug] = spec.file.toPosix();
     }
 
-    // Everything here addresses this machine, so it stays behind `portal.server.ts` and the
-    // build's own config files.
+    // Everything here but `base` addresses this machine, so it stays behind `portal.server.ts`
+    // and the build's own config files.
     const configuration: PortalBuildPaths = {
+      base: source.config.siteAddress()?.path() ?? '/',
       specs,
       codeSamples: codeSamples === null ? null : codeSamples.toPosix(),
       contentDir: contentDirectory.toPosix(),
@@ -393,8 +397,9 @@ export class PortalProjectService {
   private packageDirectory(name: string): DirectoryPath | undefined {
     for (const candidate of this.require.resolve.paths(name) ?? []) {
       const manifest = path.join(candidate, name, 'package.json');
+      // Vite refuses a Windows 8.3 short name, and resolves symlinks before comparing against its allow list.
       if (fsExtra.existsSync(manifest)) {
-        return new DirectoryPath(path.dirname(manifest));
+        return new DirectoryPath(canonical(path.dirname(manifest)));
       }
     }
     return undefined;
diff --git a/src/infrastructure/services/file-download-service.ts b/src/infrastructure/services/file-download-service.ts
index c121c23bd..15e44adce 100644
--- a/src/infrastructure/services/file-download-service.ts
+++ b/src/infrastructure/services/file-download-service.ts
@@ -1,8 +1,8 @@
-import axios from "axios";
-import { UrlPath } from "../../types/file/urlPath.js";
-import { err, ok, Result } from "neverthrow";
-import { handleServiceError, ServiceError } from "../service-error.js";
-import { FileName } from "../../types/file/fileName.js";
+import axios from 'axios';
+import { UrlPath } from '../../types/file/urlPath.js';
+import { err, ok, Result } from 'neverthrow';
+import { handleServiceError, ServiceError } from '../service-error.js';
+import { FileName } from '../../types/file/fileName.js';
 
 export type FileDownloadResponse = {
   stream: NodeJS.ReadableStream;
@@ -13,10 +13,10 @@ export class FileDownloadService {
   public async downloadFile(url: UrlPath): Promise<Result<FileDownloadResponse, ServiceError>> {
     try {
       const response = await axios.get(url.toString(), {
-        responseType: "stream"
+        responseType: 'stream'
       });
 
-      const contentDisposition = response.headers["content-disposition"];
+      const contentDisposition = response.headers['content-disposition'];
       let filename: FileName | undefined;
 
       // Try to parse filename from Content-Disposition (supports filename* as per RFC 5987 and plain filename)
@@ -34,13 +34,13 @@ export class FileDownloadService {
         if (fromUrl) {
           filename = new FileName(fromUrl);
         } else {
-          filename = new FileName("file");
+          filename = new FileName('file');
         }
       }
 
       // Basic guard — responseType: "stream" should always yield a stream
       const data = response.data as unknown;
-      const isReadableStream = data && typeof (data as NodeJS.ReadableStream).pipe === "function";
+      const isReadableStream = data && typeof (data as NodeJS.ReadableStream).pipe === 'function';
 
       if (!isReadableStream) {
         return err(ServiceError.InvalidResponse);
@@ -80,7 +80,7 @@ export class FileDownloadService {
   private getFilenameFromUrl(rawUrl: string): string | null {
     try {
       const u = new URL(rawUrl);
-      const last = u.pathname.split("/").filter(Boolean).pop();
+      const last = u.pathname.split('/').filter(Boolean).pop();
       if (!last) return null;
 
       // Remove any spurious trailing spaces and decode
@@ -88,7 +88,7 @@ export class FileDownloadService {
       return this.sanitizeFilename(decoded);
     } catch {
       // Fallback for non-URL-safe strings
-      const parts = rawUrl.split("/").filter(Boolean);
+      const parts = rawUrl.split('/').filter(Boolean);
       const last = parts.pop();
       if (!last) return null;
       return this.sanitizeFilename(this.safeDecodeURIComponent(last));
@@ -106,11 +106,11 @@ export class FileDownloadService {
   private sanitizeFilename(name: string): string {
     // Replace characters not allowed in common filesystems and trim dots/spaces
     const sanitized = name
-      .replace('/[<>:"/\\|?*\x00-\x1F]/g', "_")
-      .replace(/\s+/g, " ")
+      .replace(/[<>:"/\\|?*\p{Cc}]/gu, '_')
+      .replace(/\s+/g, ' ')
       .trim();
     // Avoid names that are empty or only dots/spaces
-    const safe = sanitized.replace(/^[. ]+|[. ]+$/g, ""); // NOSONAR - safe regex for CLI use
-    return safe.length > 0 ? safe : "file";
+    const safe = sanitized.replace(/^[. ]+|[. ]+$/g, ''); // NOSONAR - safe regex for CLI use
+    return safe.length > 0 ? safe : 'file';
   }
 }
diff --git a/src/prompts/api/transform.ts b/src/prompts/api/transform.ts
index 5682afc82..24eff00a3 100644
--- a/src/prompts/api/transform.ts
+++ b/src/prompts/api/transform.ts
@@ -3,7 +3,6 @@ import { DirectoryPath } from "../../types/file/directoryPath.js";
 import { format as f } from "../format.js";
 import { Result } from "neverthrow";
 import { TransformationResultData } from "../../infrastructure/services/transformation-service.js";
-import { ServiceError } from "../../infrastructure/service-error.js";
 import { withSpinner } from "../prompt.js";
 
 export class ApiTransformPrompts {
@@ -32,8 +31,4 @@ export class ApiTransformPrompts {
   logTransformationError(error: string): void {
     log.error(error);
   }
-
-  public networkError(serviceError: ServiceError): void {
-    log.error(serviceError.errorMessage);
-  }
 }
diff --git a/src/prompts/api/validate.ts b/src/prompts/api/validate.ts
index f27ddef0c..8b611832b 100644
--- a/src/prompts/api/validate.ts
+++ b/src/prompts/api/validate.ts
@@ -1,10 +1,11 @@
 import { log } from '@clack/prompts';
 import { replaceHTML } from '../../utils/utils.js';
+import { listedInProse } from '../../utils/string-utils.js';
 import { ValidationMessages } from '../../types/utils.js';
 import { Result } from 'neverthrow';
 import { ValidateApiResult, ValidationEntry, ValidationSummary } from '@apimatic/sdk';
-import { ServiceError } from '../../infrastructure/service-error.js';
 import { FilePath } from '../../types/file/filePath.js';
+import { ResolveProblem } from '../../types/resource-context.js';
 import { format as f } from '../format.js';
 import { withSpinner } from '../prompt.js';
 
@@ -82,9 +83,44 @@ export class ApiValidatePrompts {
     log.error(error);
   }
 
-  public networkError(serviceError: ServiceError): void {
-    const message = serviceError.errorMessage;
-    log.error(message);
+  public specUnavailable(problem: ResolveProblem): void {
+    switch (problem.kind) {
+      case 'downloadFailed': {
+        log.error(problem.error.errorMessage);
+        return;
+      }
+      case 'fileUnreadable': {
+        log.error(`${f.path(problem.file)} does not exist or could not be read.`);
+        return;
+      }
+      case 'noSpec': {
+        const message =
+          `No API specification found in ${f.path(problem.specDirectory)}. Add yours there, point ` +
+          `${f.flag('input')} at the directory that holds ${f.var('src')}, or give a spec with ` +
+          `${f.flag('file')} or ${f.flag('url')}.`;
+        log.error(message);
+        return;
+      }
+      case 'unreadable': {
+        log.error(`${f.path(problem.specDirectory)} could not be read: ${problem.reason}`);
+        return;
+      }
+      case 'zipFailed': {
+        log.error(`${f.path(problem.specDirectory)} could not be zipped for upload: ${problem.reason}`);
+        return;
+      }
+      case 'symlinks': {
+        const names = listedInProse(
+          problem.symlinks.map((symlink) => f.var(symlink.relativeTo(problem.specDirectory)))
+        );
+        const one = problem.symlinks.length === 1;
+        const message =
+          `${names} in ${f.path(problem.specDirectory)} ${one ? 'is a symlink' : 'are symlinks'}, which cannot ` +
+          `be uploaded for validation. Replace ${one ? 'it' : 'each'} with a copy of the files it points to.`;
+        log.error(message);
+        return;
+      }
+    }
   }
 
   public transformedApiSaved(filePath: FilePath): void {
diff --git a/src/prompts/format.ts b/src/prompts/format.ts
index 12f0da246..3cde32ba2 100644
--- a/src/prompts/format.ts
+++ b/src/prompts/format.ts
@@ -41,7 +41,7 @@ export const format = {
 export function intro(text: string) {
   i(format.intro(` ${text} `));
 }
-export function outro<T>(result: ActionResult<T>) {
+export function outro<T, E>(result: ActionResult<T, E>) {
   const exitCode = result.getExitCode();
   const message = result.getMessage();
 
diff --git a/src/prompts/portal/generate.ts b/src/prompts/portal/generate.ts
index d01dcf18d..58f4d49e6 100644
--- a/src/prompts/portal/generate.ts
+++ b/src/prompts/portal/generate.ts
@@ -3,6 +3,7 @@ import { DirectoryPath } from '../../types/file/directoryPath.js';
 import { FilePath } from '../../types/file/filePath.js';
 import { PortalBuildFailure, PortalBuildResult } from '../../infrastructure/portal-build-service.js';
 import { NOT_FOUND_FILE_NAME, PortalSaveProblem, ZIP_FILE_NAME } from '../../types/portal-context.js';
+import { SiteAddress } from '../../types/portal/config/site-address.js';
 import { Result } from 'neverthrow';
 import { format as f } from '../format.js';
 import { logTail, noteWrapped, withSpinner } from '../prompt.js';
@@ -87,12 +88,29 @@ export class PortalGeneratePrompts {
     log.info(`Portal artifacts can be found at ${f.path(portal)}.`);
   }
 
-  public nextSteps(portal: DirectoryPath, zipped: boolean) {
-    const message = zipped
-      ? `Unpack ${f.var(ZIP_FILE_NAME)} in ${f.path(portal)} onto any static host.\n` +
-        `Configure ${f.var(NOT_FOUND_FILE_NAME)} as the error document so deep links resolve.`
-      : `Upload the contents of ${f.path(portal)} to any static host.\n` +
-        `Configure ${f.var(NOT_FOUND_FILE_NAME)} as the error document so deep links resolve.`;
+  public nextSteps(portal: DirectoryPath, zipped: boolean, site: SiteAddress | null) {
+    if (site === null || !site.hasPath()) {
+      const upload = zipped
+        ? `Unpack ${f.var(ZIP_FILE_NAME)} in ${f.path(portal)} onto any static host.`
+        : `Upload the contents of ${f.path(portal)} to any static host.`;
+      const message = `${upload}\nConfigure ${f.var(NOT_FOUND_FILE_NAME)} as the error document so deep links resolve.`;
+      noteWrapped(message, 'Next steps');
+      return;
+    }
+
+    const served = f.link(site.addressOf('/'));
+    const upload = zipped
+      ? `Unpack ${f.var(ZIP_FILE_NAME)} in ${f.path(portal)} so its contents are served at ${served}.`
+      : `Upload the contents of ${f.path(portal)} so they are served at ${served}.`;
+    const sitemapLine = `Sitemap: ${site.addressOf('/sitemap.xml')}`;
+    const message = [
+      upload,
+      `To check the portal locally, serve it under ${f.var(site.path())}: from the root of a local server, its ` +
+        'pages load without their styles and scripts.',
+      `Serve ${f.var(NOT_FOUND_FILE_NAME)} for missing pages under ${f.var(site.path())}, so deep links resolve.`,
+      `Crawlers read ${f.var('robots.txt')} only at the root of a host, so none is generated. If you control the ` +
+        `root, add ${f.var(sitemapLine)} to its ${f.var('robots.txt')}.`
+    ].join('\n');
     noteWrapped(message, 'Next steps');
   }
 }
diff --git a/src/prompts/portal/prepare-project.ts b/src/prompts/portal/prepare-project.ts
index 7aa856059..0da362c21 100644
--- a/src/prompts/portal/prepare-project.ts
+++ b/src/prompts/portal/prepare-project.ts
@@ -30,6 +30,14 @@ export class PreparePortalProjectPrompts {
 
   public sourceProblem(problem: PortalSourceProblem, sourceDirectory: DirectoryPath) {
     reportSourceProblem(problem, sourceDirectory);
+    const noPortalBlock =
+      problem.kind === 'missingConfig' || (problem.kind === 'invalidConfig' && problem.missingPortal);
+    if (noPortalBlock) {
+      log.message(
+        `Run ${f.cmdAlt('apimatic', 'quickstart')} in an empty directory with a sample spec to see an example of ` +
+          `a valid portal.`
+      );
+    }
   }
 
   public filesShadowedByStatic(shadowed: FileName[]) {
diff --git a/src/prompts/portal/serve.ts b/src/prompts/portal/serve.ts
index b610fe4a4..183532f8f 100644
--- a/src/prompts/portal/serve.ts
+++ b/src/prompts/portal/serve.ts
@@ -55,8 +55,9 @@ export class PortalServePrompts {
         'Mistakes in these files are reported on save, and the preview keeps what it last accepted.',
         '',
         `Restart the preview after adding a language or a ${f.var('plugin')} block (its SDK or plugin is ` +
-          `fetched at startup), adding or removing a page, creating ${staticPath(sourceDirectory)}, or ` +
-          `changing which documents are in ${specPath(sourceDirectory)}.`,
+          `fetched at startup), adding or removing a page, creating ${staticPath(sourceDirectory)}, ` +
+          `changing which documents are in ${specPath(sourceDirectory)}, or changing the path in ` +
+          `${f.var('portal.site.url')}.`,
         '',
         'Press CTRL+C to stop the server.'
       ].join('\n'),
@@ -70,7 +71,7 @@ export class PortalServePrompts {
 
   /** Explained as `portal generate` would explain it, since the same rules refused it. */
   public configRejected(problem: PortalSourceProblem, sourceDirectory: DirectoryPath) {
-    reportSourceProblem(problem, sourceDirectory, { offerQuickstart: false });
+    reportSourceProblem(problem, sourceDirectory);
     log.message('The preview keeps showing what it last accepted until the file is fixed.');
   }
 
diff --git a/src/prompts/portal/source.ts b/src/prompts/portal/source.ts
index 35f68edee..f0b83043e 100644
--- a/src/prompts/portal/source.ts
+++ b/src/prompts/portal/source.ts
@@ -76,30 +76,17 @@ function reportSpecConversion({ file, format, converted, others }: SpecConversio
 
 /**
  * Shared by `portal generate` and `portal serve`: both read the same source directory, so
- * a broken one has to be explained the same way in both. `offerQuickstart` is false once a
- * preview of the directory is running: quickstart refuses a directory that is not empty.
+ * a broken one has to be explained the same way in both.
  */
-export function reportSourceProblem(
-  problem: PortalSourceProblem,
-  sourceDirectory: DirectoryPath,
-  { offerQuickstart = true }: { offerQuickstart?: boolean } = {}
-): void {
-  const quickstart = `Run ${f.cmdAlt('apimatic', 'quickstart')} to set up a portal.`;
+export function reportSourceProblem(problem: PortalSourceProblem, sourceDirectory: DirectoryPath): void {
   switch (problem.kind) {
     case 'missingConfig': {
       log.error(`No ${f.var(APIMATIC_CONFIG_FILE_NAME)} found in ${f.path(sourceDirectory)}.`);
-      if (offerQuickstart) {
-        log.message(quickstart);
-      }
       return;
     }
     case 'invalidConfig': {
       log.error(`The ${f.var(APIMATIC_CONFIG_FILE_NAME)} in ${f.path(sourceDirectory)} is not valid:`);
       log.message(problem.errors.map((error) => `  • ${error}`).join('\n'));
-      // A file without the block is no worse off than no file: the same command sets it up.
-      if (problem.missingPortal && offerQuickstart) {
-        log.message(quickstart);
-      }
       return;
     }
     case 'invalidContent': {
@@ -225,17 +212,16 @@ function reportMissingImages(images: MissingImage[], sourceDirectory: DirectoryP
 
 function reportReservedAddresses(pages: ReservedAddressPage[], sourceDirectory: DirectoryPath): void {
   const one = pages.length === 1;
-  const lines = pages.map(({ file, address, section }) => {
-    const kept = `/${section.folder}`;
-    const within = address === kept ? '' : `, under ${f.var(kept)}`;
+  const lines = pages.map(({ file, address, keptFor }) => {
+    const within = address === keptFor.address ? '' : `, under ${f.var(keptFor.address)}`;
     return `  • ${relative(file, sourceDirectory)}, at ${f.var(address)}${within}, which is kept for ${
-      section.description
+      keptFor.description
     }`;
   });
   log.error(
     one
-      ? `A page in ${f.path(sourceDirectory)} would be served where the portal puts the pages it generates:`
-      : `Pages in ${f.path(sourceDirectory)} would be served where the portal puts the pages it generates:`
+      ? `A page in ${f.path(sourceDirectory)} would be served where the portal puts pages of its own:`
+      : `Pages in ${f.path(sourceDirectory)} would be served where the portal puts pages of its own:`
   );
   log.message(lines.join('\n'));
   log.message(one ? 'Rename or move the page.' : 'Rename or move each page.');
diff --git a/src/prompts/quickstart.ts b/src/prompts/quickstart.ts
index 218c181b6..5684204fe 100644
--- a/src/prompts/quickstart.ts
+++ b/src/prompts/quickstart.ts
@@ -4,19 +4,18 @@ import { UrlPath } from '../types/file/urlPath.js';
 import { format as f, getTree } from './format.js';
 import { DirectoryPath } from '../types/file/directoryPath.js';
 import { FilePath } from '../types/file/filePath.js';
-import { ServiceError } from '../infrastructure/service-error.js';
 import { Directory } from '../types/file/directory.js';
-import { createResourceInputFromInput, ResourceInput } from '../types/file/resource-input.js';
-import { FileDownloadResponse } from '../infrastructure/services/file-download-service.js';
+import { createFileOrUrlFromInput } from '../types/file/resource-input.js';
 import { PortalAuthorizationFailure } from '../infrastructure/services/portal-authorization-service.js';
-import { APIMATIC_CONFIG_FILE_NAME } from '../types/apimatic-config/document.js';
+import { APIMATIC_CONFIG_FILE_NAME, ConfigFinding, findingClause } from '../types/apimatic-config/document.js';
 import { PluginConfigWriteFailure } from '../types/plugin-config-context.js';
-import { PortalScaffoldProblem } from '../types/portal/portal-source.js';
+import { PortalScaffoldProblem, PortalSourceProblem } from '../types/portal/portal-source.js';
 import { GENERATED, GITIGNORE, GitignoreFailure } from '../types/project-context.js';
+import { DownloadProblem, FileReadProblem, ResourceKind } from '../types/resource-context.js';
 import { AVAILABLE_LANGUAGES, Language, languageLabel, UPCOMING_LANGUAGES } from '../types/sdk/generate.js';
 import { noteWrapped, withSpinner } from './prompt.js';
 import { reportAuthorizationFailure } from './portal/authorization.js';
-import { convertToOpenApi3 } from './portal/source.js';
+import { convertToOpenApi3, reportSourceProblem, specPath } from './portal/source.js';
 
 const vscodeExtensionUrl =
   'https://marketplace.visualstudio.com/items?itemName=apimatic-developers.apimatic-for-vscode';
@@ -38,7 +37,7 @@ Let's get started!`);
   }
 
   /** `defaultSpecUrl` is null once the sample has failed to download; it is not offered again. */
-  public async specPathPrompt(defaultSpecUrl: UrlPath | null): Promise<ResourceInput | undefined> {
+  public async specPathPrompt(defaultSpecUrl: UrlPath | null): Promise<FilePath | UrlPath | undefined> {
     const spec = await text({
       message: `Provide a local path or a public URL for your OpenAPI Definition file:`,
       placeholder: defaultSpecUrl
@@ -50,7 +49,7 @@ Let's get started!`);
         if (!value && defaultSpecUrl === null) {
           return 'Please enter a file path or URL.';
         }
-        if (value && !createResourceInputFromInput(value)) {
+        if (value && !createFileOrUrlFromInput(value)) {
           return 'Please enter a valid file path or URL.';
         }
       }
@@ -58,26 +57,50 @@ Let's get started!`);
     if (isCancel(spec)) {
       return undefined;
     }
-    return createResourceInputFromInput(spec);
+    return createFileOrUrlFromInput(spec);
   }
 
-  public specFormatUnsupported(specPath: FilePath, format: string) {
-    const message = `${f.path(specPath)} is ${format}, not OpenAPI 3.x. ` + convertToOpenApi3();
+  // Named rather than shown by path: the file checked is the wizard's own copy in a temporary directory.
+  public specFormatUnsupported(spec: FilePath, format: string) {
+    const message = `${f.var(spec.name().toString())} is ${format}, not OpenAPI 3.x. ` + convertToOpenApi3();
     log.error(message);
   }
 
   /** For a document that names no format at all: a Postman collection, a RAML file, arbitrary JSON. */
-  public specNotRecognised(specPath: FilePath) {
-    const message = `${f.path(specPath)} is not an OpenAPI 3.x document. ` + convertToOpenApi3();
+  public specNotRecognised(spec: FilePath) {
+    const message = `${f.var(spec.name().toString())} is not an OpenAPI 3.x document. ` + convertToOpenApi3();
     log.error(message);
   }
 
+  public specsUnsupported(problem: PortalSourceProblem, sourceDirectory: DirectoryPath) {
+    reportSourceProblem(problem, sourceDirectory);
+  }
+
+  public configMissing(sourceDirectory: DirectoryPath) {
+    const configFile = f.var(APIMATIC_CONFIG_FILE_NAME);
+    log.error(`${specPath(sourceDirectory)} already holds files, but ${f.path(sourceDirectory)} has no ${configFile}.`);
+    log.message(
+      `Add the project's ${configFile} there, or run ${f.cmdAlt('apimatic', 'quickstart')} from a directory ` +
+        `with no ${f.var('src')} to start a new portal.`
+    );
+  }
+
+  public configUnsupported(findings: readonly ConfigFinding[], sourceDirectory: DirectoryPath) {
+    const configFile = f.var(APIMATIC_CONFIG_FILE_NAME);
+    log.error(`The ${configFile} in ${f.path(sourceDirectory)} cannot be used: ${findingClause(findings)}.`);
+  }
+
   public runtimeUnsupported(reason: string) {
     log.error(reason);
   }
 
-  public specFileDoesNotExist() {
-    log.error('The specified file does not exist or is not a valid file. Please enter a valid file path.');
+  /** Names the address that failed: without it the same message repeats for every retry. */
+  public specUnavailable(problem: DownloadProblem | FileReadProblem) {
+    if (problem.kind === 'fileUnreadable') {
+      log.error('The specified file does not exist or is not a valid file. Please enter a valid file path.');
+      return;
+    }
+    log.error(`${problem.error.errorMessage} Could not download ${f.link(problem.url.toString())}.`);
   }
 
   public noSpecSpecified() {
@@ -109,14 +132,10 @@ Let's get started!`);
     log.info(`Step 2 of 3: Validate and Lint your OpenAPI Definition`);
   }
 
-  public specValidationFailed(spec: ResourceInput) {
+  public specValidationFailed(kind: ResourceKind) {
     log.error(`Oops, it looks like there are some errors in your API Definition`);
-    // A placeholder rather than the user's own path or URL, which no quoting survives every shell with.
-    const specFlag = spec instanceof UrlPath ? f.flag('url', '<url>') : f.flag('file', '<path>');
-    const validateCommand = `${f.cmdAlt('apimatic', 'api', 'validate')} ${specFlag}`;
     const message = [
-      `Ask an AI coding agent to run this command and fix what it reports:`,
-      validateCommand,
+      ...this.validateWithAgent(kind),
       '',
       `Or use APIMatic's interactive VS Code Extension:`,
       f.link(vscodeExtensionUrl)
@@ -124,6 +143,16 @@ Let's get started!`);
     noteWrapped(message, 'How to fix');
   }
 
+  // A placeholder rather than the user's own path or URL, which no quoting survives every shell with.
+  private validateWithAgent(kind: ResourceKind): string[] {
+    const validate = f.cmdAlt('apimatic', 'api', 'validate');
+    if (kind === 'project') {
+      return [`Ask an AI coding agent to run ${validate} and fix what it reports.`];
+    }
+    const specFlag = kind === 'url' ? f.flag('url', '<url>') : f.flag('file', '<path>');
+    return [`Ask an AI coding agent to run this command and fix what it reports:`, `${validate} ${specFlag}`];
+  }
+
   public createPortalStep() {
     log.info(`Step 3 of 3: Create your portal`);
   }
@@ -182,7 +211,7 @@ Let's get started!`);
     }
   }
 
-  public downloadSpecFile(fn: Promise<Result<FileDownloadResponse, ServiceError>>) {
+  public downloadSpecFile<T, E>(fn: Promise<Result<T, E>>) {
     return withSpinner(
       'Downloading API Definition',
       `API Definition downloaded`,
@@ -202,15 +231,6 @@ Let's get started!`);
     noteWrapped(message, 'Next Steps');
   }
 
-  public serviceError(serviceError: ServiceError) {
-    log.error(serviceError.errorMessage);
-  }
-
-  /** Names the address that failed: without it the same message repeats for every retry. */
-  public specDownloadFailed(url: UrlPath, serviceError: ServiceError) {
-    log.error(`${serviceError.errorMessage} Could not download ${f.link(url.toString())}.`);
-  }
-
   public printDirectoryStructure(projectDirectory: DirectoryPath, structure: Directory) {
     const heading = `${f.var('src')} directory containing source files created at ${f.path(projectDirectory)}\n`;
     const message = getTree(structure.toTreeNode());
@@ -242,8 +262,8 @@ Let's get started!`);
   public configNotWritten(failure: PluginConfigWriteFailure, sourceDirectory: DirectoryPath) {
     const problem = failure === 'unreadable' ? 'read' : 'written';
     const message =
-      `${f.var(APIMATIC_CONFIG_FILE_NAME)} in ${f.path(sourceDirectory)} could not be ${problem}, ` +
-      `so the languages you chose were not recorded. Check that it can be ${problem} and try again.`;
+      `${f.var(APIMATIC_CONFIG_FILE_NAME)} in ${f.path(sourceDirectory)} could not be ${problem}. ` +
+      `Check that it can be ${problem} and try again.`;
     log.error(message);
   }
 
diff --git a/src/types/apimatic-config/document.ts b/src/types/apimatic-config/document.ts
index 74f80c900..44d683d0b 100644
--- a/src/types/apimatic-config/document.ts
+++ b/src/types/apimatic-config/document.ts
@@ -158,6 +158,11 @@ export class ApimaticConfigDocument {
     return isJsonObject(this.root.languages) ? this.root.languages : undefined;
   }
 
+  /** Whether the file holds the block at all, in whatever shape. */
+  public has(block: ConfigBlockName): boolean {
+    return this.root[block] !== undefined;
+  }
+
   public findingsFor(...blocks: ConfigBlock[]): ConfigFinding[] {
     return this.findings.filter((finding) => blocks.includes(finding.block));
   }
diff --git a/src/types/file/resource-input.ts b/src/types/file/resource-input.ts
index 2096c3ab4..8c6b332dd 100644
--- a/src/types/file/resource-input.ts
+++ b/src/types/file/resource-input.ts
@@ -1,38 +1,44 @@
-import path from "path";
-import { DirectoryPath } from "./directoryPath.js";
-import { FileName } from "./fileName.js";
-import { FilePath } from "./filePath.js";
-import { UrlPath } from "./urlPath.js";
-import { removeQuotes } from "../../utils/string-utils.js";
+import path from 'path';
+import { DirectoryPath } from './directoryPath.js';
+import { FileName } from './fileName.js';
+import { FilePath } from './filePath.js';
+import { UrlPath } from './urlPath.js';
+import { removeQuotes } from '../../utils/string-utils.js';
+import { ProjectContext } from '../project-context.js';
 
-export type ResourceInput = FilePath | UrlPath;
+export type ResourceInput = FilePath | UrlPath | ProjectContext;
 
-// Factory function to create the discriminated union
-export const createResourceInput = (file?: string, url?: string): ResourceInput => {
+export const createResourceInput = (
+  file: string | undefined,
+  url: string | undefined,
+  input: string | undefined
+): ResourceInput => (file || url ? createFileOrUrlInput(file, url) : ProjectContext.at(input));
+
+export const createFileOrUrlInput = (file?: string, url?: string): FilePath | UrlPath => {
   if (file && url) {
-    throw new Error("Cannot specify both file and url. Please provide only one.");
+    throw new Error('Cannot specify both file and url. Please provide only one.');
   }
   if (!file && !url) {
-    throw new Error("Must specify either file or url.");
+    throw new Error('Must specify either file or url.');
   }
 
   if (file) {
     if (!file.trim()) {
-      throw new Error("Invalid file path provided.");
+      throw new Error('Invalid file path provided.');
     }
     return new FilePath(new DirectoryPath(path.dirname(file)), new FileName(path.basename(file)));
   }
   if (url) {
     if (!url.trim()) {
-      throw new Error("Invalid URL provided.");
+      throw new Error('Invalid URL provided.');
     }
     return new UrlPath(url);
   }
-  throw new Error("Must specify either file or url.");
+  throw new Error('Must specify either file or url.');
 };
 
-export function createResourceInputFromInput(path: string): ResourceInput | undefined {
-  const sanitizedPath = removeQuotes(path.trim() ?? "")
+export function createFileOrUrlFromInput(path: string): FilePath | UrlPath | undefined {
+  const sanitizedPath = removeQuotes(path.trim() ?? '');
   const urlPath = UrlPath.create(sanitizedPath);
   if (urlPath) {
     return urlPath;
diff --git a/src/types/flags-provider.ts b/src/types/flags-provider.ts
index 82c92f6f3..05b6e444b 100644
--- a/src/types/flags-provider.ts
+++ b/src/types/flags-provider.ts
@@ -1,20 +1,33 @@
-import { Flags } from "@oclif/core";
+import { Flags } from '@oclif/core';
 
 export class FlagsProvider {
-  private static readonly inputFlagName: string = "input" as const;
+  private static readonly inputFlagName: string = 'input' as const;
+  private static readonly inputFlagOptions = {
+    char: 'i',
+    description:
+      "[default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files."
+  } as const;
+
+  public static readonly nonEmpty = async (value: string): Promise<string> => {
+    if (value.trim() === '') {
+      throw new Error('The value is empty. Give a value, or leave the flag out.');
+    }
+    return value;
+  };
+
   // Common folder flag group
   public static input = {
-    [FlagsProvider.inputFlagName]: Flags.string({
-      char: "i",
-      description:
-        "[default: ./] path to the parent directory containing the 'src' directory, which includes API specifications and configuration files."
-    })
+    [FlagsProvider.inputFlagName]: Flags.string(FlagsProvider.inputFlagOptions)
+  };
+
+  public static nonEmptyInput = {
+    [FlagsProvider.inputFlagName]: Flags.string({ ...FlagsProvider.inputFlagOptions, parse: FlagsProvider.nonEmpty })
   };
 
   public static destination(artifact: string, artifactName: string) {
     return {
       destination: Flags.string({
-        char: "d",
+        char: 'd',
         description: `[default: <${FlagsProvider.inputFlagName}>/${artifact}] path where the ${artifactName} will be generated.`
       })
     };
@@ -22,17 +35,17 @@ export class FlagsProvider {
 
   // Auth key group
   public static authKey = {
-    "auth-key": Flags.string({
-      char: "k",
-      description: "override current authentication state with an authentication key."
+    'auth-key': Flags.string({
+      char: 'k',
+      description: 'override current authentication state with an authentication key.'
     })
   };
 
   public static force = {
     force: Flags.boolean({
-      char: "f",
+      char: 'f',
       default: false,
-      description: "overwrite changes without asking for user consent."
+      description: 'overwrite changes without asking for user consent.'
     })
   };
 }
diff --git a/src/types/plugin-config-context.ts b/src/types/plugin-config-context.ts
index d8b36348d..2956e98ac 100644
--- a/src/types/plugin-config-context.ts
+++ b/src/types/plugin-config-context.ts
@@ -1,4 +1,4 @@
-import { Result, ResultAsync } from 'neverthrow';
+import { ok, Result, ResultAsync } from 'neverthrow';
 import { FileService } from '../infrastructure/file-service.js';
 import { ApimaticConfigContext, ApimaticConfigWriteFailure } from './apimatic-config-context.js';
 import { ApimaticConfigDocument, ConfigBlockName, findingClause } from './apimatic-config/document.js';
@@ -12,6 +12,7 @@ import {
   PluginIdentityData,
   PluginMetadata
 } from './plugin/plugin-config.js';
+import { PortalLanguages } from './portal/portal-languages.js';
 import { SOURCE_DIRECTORY_NAME } from './project-layout.js';
 import { SemVersion } from './publish/version.js';
 import { isAvailableLanguage, Language } from './sdk/generate.js';
@@ -125,6 +126,25 @@ const keepsRecord = (language: string, entry: PluginLanguageEntry<Language> | un
 
 const isUnavailableLanguage = (language: string): boolean => !isAvailableLanguage(language);
 
+const namesNoLanguage = (document: ApimaticConfigDocument): boolean =>
+  PortalLanguages.namesNone(document.languages(), document.findingsFor('languages'));
+
+const withMetadata = (
+  document: ApimaticConfigDocument,
+  metadata: PluginMetadata,
+  author?: PluginAuthor
+): ApimaticConfigDocument => {
+  const plugin = (document.plugin() ?? {}) as PluginIdentityData;
+  return document.with('plugin', {
+    ...plugin,
+    pluginId: metadata.pluginId,
+    pluginName: metadata.pluginName,
+    pluginVersion: metadata.pluginVersion,
+    ...(!plugin.author && author && { author }),
+    license: plugin.license ?? DEFAULT_PLUGIN_LICENSE
+  });
+};
+
 export class PluginConfigContext {
   private readonly configContext: ApimaticConfigContext;
   private readonly fileService = new FileService();
@@ -153,17 +173,30 @@ export class PluginConfigContext {
     metadata: PluginMetadata,
     author?: PluginAuthor
   ): Promise<Result<PluginConfig, PluginConfigWriteFailure>> {
-    return await this.merge((document) => {
-      const plugin = (document.plugin() ?? {}) as PluginIdentityData;
-      return document.with('plugin', {
-        ...plugin,
-        pluginId: metadata.pluginId,
-        pluginName: metadata.pluginName,
-        pluginVersion: metadata.pluginVersion,
-        ...(!plugin.author && author && { author }),
-        license: plugin.license ?? DEFAULT_PLUGIN_LICENSE
-      });
-    });
+    return await this.merge((document) => withMetadata(document, metadata, author));
+  }
+
+  // Merged against `plugin` alone: a file's `languages` is not what this write could spread or break.
+  public async addMetadataIfMissing(metadata: PluginMetadata): Promise<Result<void, PluginConfigWriteFailure>> {
+    const state = await this.configContext.read();
+    if (state.state === 'parsed' && state.document.has('plugin')) {
+      return ok(undefined);
+    }
+    const merged = await this.configContext.merge(['plugin'], (document) => withMetadata(document, metadata));
+    return merged.map(() => undefined);
+  }
+
+  public async languagesMissing(): Promise<boolean> {
+    const state = await this.configContext.read();
+    return state.state === 'parsed' && namesNoLanguage(state.document);
+  }
+
+  // Merged against `languages` alone, as `addMetadataIfMissing` is against `plugin`.
+  public async addLanguagesIfMissing(languages: readonly Language[]): Promise<Result<void, PluginConfigWriteFailure>> {
+    const merged = await this.configContext.merge(['languages'], (document) =>
+      namesNoLanguage(document) ? document.with('languages', recorded(document, languages, keepsRecord)) : document
+    );
+    return merged.map(() => undefined);
   }
 
   // A published entry survives a cleared checkbox: only `sdk publish` can write that record.
diff --git a/src/types/portal-source-context.ts b/src/types/portal-source-context.ts
index 6e1cd702a..16bd26e7e 100644
--- a/src/types/portal-source-context.ts
+++ b/src/types/portal-source-context.ts
@@ -2,6 +2,7 @@ import { ExportFormats } from '@apimatic/sdk';
 import { err, ok, Result } from 'neverthrow';
 import { FileService } from '../infrastructure/file-service.js';
 import { errorMessage } from '../utils/error-utils.js';
+import { isJsonObject } from '../utils/json-utils.js';
 import { ApimaticConfigContext } from './apimatic-config-context.js';
 import { APIMATIC_CONFIG_FILE_NAME, ApimaticConfigDocument, findingSentences } from './apimatic-config/document.js';
 import { Directory } from './file/directory.js';
@@ -10,7 +11,7 @@ import { FileName } from './file/fileName.js';
 import { FilePath } from './file/filePath.js';
 import { NOT_FOUND_FILE_NAME, SHELL_FILE_NAME } from './portal-context.js';
 import { CONTENT_DIRECTORY_NAME, SPEC_DIRECTORY_NAME, STATIC_DIRECTORY_NAME } from './project-layout.js';
-import { PLACEHOLDER_SITE, SuggestedSite } from './portal/config/site-config.js';
+import { PLACEHOLDER_SITE, SiteConfig, SuggestedSite } from './portal/config/site-config.js';
 import { AcceptedContent, ContentFile, ContentTree, ReadPage } from './portal/content-tree.js';
 import { Endpoint } from './portal/endpoint.js';
 import { GeneratedPages, PluginSource } from './portal/generated-pages.js';
@@ -74,6 +75,10 @@ export class PortalSourceContext {
     return this.sourceDirectory.join(STATIC_DIRECTORY_NAME);
   }
 
+  private get configFile(): FilePath {
+    return new FilePath(this.sourceDirectory, new FileName(APIMATIC_CONFIG_FILE_NAME));
+  }
+
   /** Reads and validates the whole source directory, or reports the first problem found. */
   public async resolve(): Promise<Result<PortalSource, PortalSourceProblem>> {
     const document = await this.readConfigDocument();
@@ -115,6 +120,11 @@ export class PortalSourceContext {
     });
   }
 
+  /** The `spec/` half of `resolve`, for quickstart to refuse a project the build would refuse before writing into it. */
+  public async resolveSpecs(): Promise<Result<PortalSpec[], PortalSourceProblem>> {
+    return (await this.specs()).map(({ specs }) => specs);
+  }
+
   /**
    * The `content/` half of `resolve`, for `portal serve` to run on each save, against the `specs`
    * it found and the generated pages the preview shows.
@@ -312,50 +322,64 @@ export class PortalSourceContext {
       if (installed.isErr()) {
         return err({ kind: 'sourceUnwritable', reason: installed.error.reason });
       }
+      const config = PortalConfig.scaffolded(await this.suggestedSite(specPath));
+      // Every default is spelled out, so the block shows what can be set, and the schema lets an
+      // editor complete and check the rest.
+      const written = await this.mergeConfig((document) =>
+        document.referencingSchema(schemaUrl).with('portal', config.toJSON())
+      );
+      if (written.isErr()) {
+        return err(written.error);
+      }
+      await this.writeContent(config.siteTitle());
+      return ok(this.configFile);
     } catch (error) {
       return err({ kind: 'sourceUnwritable', reason: errorMessage(error) });
     }
-    return await this.adopt(specPath, schemaUrl);
   }
 
-  /** The same tree around a specification the project already carries, which is left where it is. */
-  public async adopt(specPath: FilePath, schemaUrl: string): Promise<Result<FilePath, PortalScaffoldProblem>> {
+  /** Names the site after the spec and writes a starter content/, each only where the project has none. */
+  public async adopt(namedAfter: PortalSpec): Promise<Result<FilePath, PortalScaffoldProblem>> {
     try {
-      return await this.writeSourceTree(specPath, schemaUrl);
+      const site = await this.suggestedSite(namedAfter.file);
+      // A block or a site that is not an object is left for the build to report.
+      const written = await this.mergeConfig((document) => {
+        const portal = document.portal() ?? {};
+        if (!isJsonObject(portal)) {
+          return document;
+        }
+        if (portal.site === undefined) {
+          return document.with('portal', { site: SiteConfig.suggested(site).toJSON(), ...portal });
+        }
+        return isJsonObject(portal.site) && portal.site.name === undefined
+          ? document.with('portal', { ...portal, site: { name: site.name, ...portal.site } })
+          : document;
+      });
+      if (written.isErr()) {
+        return err(written.error);
+      }
+      if (!(await this.fileService.directoryExists(this.contentDirectory))) {
+        const config = PortalConfig.fromBlock(written.value.portal(), site);
+        await this.writeContent(config.isOk() ? config.value.siteTitle() : site.name);
+      }
+      return ok(this.configFile);
     } catch (error) {
       return err({ kind: 'sourceUnwritable', reason: errorMessage(error) });
     }
   }
 
-  /**
-   * The document the portal speaks for, and the one quickstart validates when it adopts a
-   * project someone downloaded rather than asking for a specification the project has.
-   */
-  public async primarySpec(): Promise<FilePath | null> {
-    const fileName = (await this.specDirectoryListing()).fileNames.find((name) =>
-      SPEC_EXTENSIONS.some((extension) => name.hasExtension(extension))
-    );
-    return fileName === undefined ? null : new FilePath(this.specDirectory, fileName);
-  }
-
-  private async writeSourceTree(
-    specPath: FilePath,
-    schemaUrl: string
-  ): Promise<Result<FilePath, PortalScaffoldProblem>> {
-    const site = await this.suggestedSite(specPath);
-    const config = PortalConfig.scaffolded(site);
-    // A downloaded build carries `spec/` and no config, so the merge creates the file on both
-    // paths. Every default is spelled out, so the block shows what can be set, and the schema
-    // lets an editor complete and check the rest.
-    const written = await this.configContext.merge(['portal'], (document) =>
-      document.referencingSchema(schemaUrl).with('portal', config.toJSON())
-    );
-    if (written.isErr()) {
-      return err({ kind: written.error === 'unreadable' ? 'configUnreadable' : 'configUnwritable' });
-    }
+  private async mergeConfig(
+    apply: (document: ApimaticConfigDocument) => ApimaticConfigDocument
+  ): Promise<Result<ApimaticConfigDocument, PortalScaffoldProblem>> {
+    const written = await this.configContext.merge(['portal'], apply);
+    return written.mapErr((failure) => ({
+      kind: failure === 'unreadable' ? ('configUnreadable' as const) : ('configUnwritable' as const)
+    }));
+  }
 
+  private async writeContent(siteTitle: string): Promise<void> {
     await this.fileService.createDirectoryIfNotExists(this.contentDirectory);
-    const summary = `Getting started with ${config.siteTitle()}`;
+    const summary = `Getting started with ${siteTitle}`;
     await this.fileService.writeContents(
       new FilePath(this.contentDirectory, new FileName('index.md')),
       [
@@ -366,7 +390,7 @@ export class PortalSourceContext {
         `description: ${JSON.stringify(summary)}`,
         '---',
         '',
-        `Welcome to the ${config.siteTitle()} documentation.`,
+        `Welcome to the ${siteTitle} documentation.`,
         '',
         'Replace this page with your own introduction, and add more Markdown pages beside it.',
         ''
@@ -377,7 +401,6 @@ export class PortalSourceContext {
       new FilePath(this.contentDirectory, new FileName(NAVIGATION_FILE_NAME)),
       JSON.stringify({ tabs: TOKENS, pages: ['index', '...'] }, null, 2) + '\n'
     );
-    return ok(new FilePath(this.sourceDirectory, new FileName(APIMATIC_CONFIG_FILE_NAME)));
   }
 
   // A split specification arrives as an archive, whose parts are left to the build to read.
diff --git a/src/types/portal/config/site-address.ts b/src/types/portal/config/site-address.ts
new file mode 100644
index 000000000..ae74127c8
--- /dev/null
+++ b/src/types/portal/config/site-address.ts
@@ -0,0 +1,72 @@
+import { err, ok } from 'neverthrow';
+import { isWebAddress, Parsed } from './fields.js';
+
+/** One spelling of the path everywhere: Vite's base, the router's prefix, the host's folder and canonical links. */
+const SEGMENT = /^[A-Za-z0-9._~-]+$/;
+
+/** The last part of a page's address, such as a home page's `index.html`, which the portal cannot be served under. */
+const PAGE = /\.html?$/i;
+
+const GIVE_THE_ADDRESS = "Give the address the portal is hosted at, for example 'https://example.com/docs'.";
+
+/** Where the portal is hosted: an origin, and the path it is served under there. */
+export class SiteAddress {
+  private constructor(
+    private readonly origin: string,
+    /** `''` at the root of the host, otherwise `/docs` or deeper, with no trailing slash. */
+    private readonly basePath: string
+  ) {}
+
+  public static parse(value: unknown, path: string): Parsed<SiteAddress> {
+    const text = typeof value === 'string' ? value.trim() : '';
+    const hostStart = text.indexOf('//') + 2;
+    const pathStart = text.indexOf('/', hostStart);
+    // Checked as written: the URL parser drops a tab from the host and reads past extra slashes before it.
+    const host = text.slice(hostStart, pathStart === -1 ? undefined : pathStart);
+    if (!isWebAddress(text) || !/^\S+$/.test(host)) {
+      return err([
+        `'${path}' must be the address the portal is hosted at, for example 'https://docs.example.com' or 'https://example.com/docs'.`
+      ]);
+    }
+    // Checked as written: the URL parser reads `\` as `/` and drops an empty query or fragment.
+    const character = ['?', '#', '\\'].find((candidate) => text.includes(candidate));
+    if (character !== undefined) {
+      return err([`'${path}' cannot contain '${character}'. ${GIVE_THE_ADDRESS}`]);
+    }
+    const basePath = pathStart === -1 ? '' : text.slice(pathStart).replace(/\/$/, '');
+    const segments = basePath.split('/').slice(1);
+    if (segments.includes('')) {
+      return err([`'${path}' has an empty part ('//') in its path.`]);
+    }
+    const invalid = segments.find((segment) => !SEGMENT.test(segment) || segment === '.' || segment === '..');
+    if (invalid !== undefined) {
+      return err([
+        `'${path}' has '${invalid}' in its path. Each part between '/'s can use only letters, digits, '.', '_', '~' and '-', and cannot be '.' or '..'.`
+      ]);
+    }
+    const page = segments.at(-1);
+    if (page !== undefined && PAGE.test(page)) {
+      return err([`'${path}' ends in '${page}', which names a page. ${GIVE_THE_ADDRESS}`]);
+    }
+    return ok(new SiteAddress(new URL(text).origin, basePath));
+  }
+
+  /** Where the portal is served, in the form Vite's `base` takes: `/`, or `/docs/`. */
+  public path(): string {
+    return `${this.basePath}/`;
+  }
+
+  public hasPath(): boolean {
+    return this.basePath !== '';
+  }
+
+  /** A portal-relative path's address on the host: `/sitemap.xml` is `https://example.com/docs/sitemap.xml`. */
+  public addressOf(portalPath: string): string {
+    return `${this.origin}${this.basePath}${portalPath}`;
+  }
+
+  /** The site address, with no trailing slash. */
+  public toString(): string {
+    return `${this.origin}${this.basePath}`;
+  }
+}
diff --git a/src/types/portal/config/site-config.ts b/src/types/portal/config/site-config.ts
index d92446dd8..e68168010 100644
--- a/src/types/portal/config/site-config.ts
+++ b/src/types/portal/config/site-config.ts
@@ -1,6 +1,6 @@
 import { err, ok, Result } from 'neverthrow';
-import { UrlPath } from '../../file/urlPath.js';
-import { allOf, isWebAddress, namespace, nonEmptyString, Parsed, unknownKeys } from './fields.js';
+import { allOf, namespace, nonEmptyString, optional, Parsed, unknownKeys } from './fields.js';
+import { SiteAddress } from './site-address.js';
 
 /** What a specification says about itself, which is what a portal is called until the block says otherwise. */
 export interface SuggestedSite {
@@ -15,7 +15,7 @@ const KNOWN = ['name', 'url', 'description'];
 export class SiteConfig {
   private constructor(
     private readonly name: string,
-    private readonly url: UrlPath | null,
+    private readonly address: SiteAddress | null,
     private readonly description: string | null
   ) {}
 
@@ -29,10 +29,10 @@ export class SiteConfig {
         unknownKeys(data, KNOWN, path),
         Result.combineWithAllErrors([
           SiteConfig.validName(data.name, `${path}.name`, suggested),
-          SiteConfig.validUrl(data.url, `${path}.url`),
+          optional(data.url, (url) => SiteAddress.parse(url, `${path}.url`)),
           SiteConfig.validDescription(data.description, `${path}.description`, suggested)
         ])
-      ).map(([name, url, description]) => new SiteConfig(name, url, description))
+      ).map(([name, address, description]) => new SiteConfig(name, address, description))
     );
   }
 
@@ -48,14 +48,14 @@ export class SiteConfig {
     return this.description;
   }
 
-  public origin(): UrlPath | null {
-    return this.url;
+  public siteAddress(): SiteAddress | null {
+    return this.address;
   }
 
   public toJSON(): { name: string; url?: string; description?: string } {
     return {
       name: this.name,
-      ...(this.url === null ? {} : { url: this.url.toString() }),
+      ...(this.address === null ? {} : { url: this.address.toString() }),
       ...(this.description === null ? {} : { description: this.description })
     };
   }
@@ -84,29 +84,4 @@ export class SiteConfig {
     const trimmed = description.trim();
     return ok(trimmed.length > 0 ? trimmed : null);
   }
-
-  // Only the origin is accepted: the portal is hosted at the root of its host, so a path,
-  // query or fragment would produce canonical links that do not resolve.
-  private static validUrl(url: unknown, path: string): Parsed<UrlPath | null> {
-    if (url === undefined) {
-      return ok(null);
-    }
-    const origin = typeof url === 'string' ? SiteConfig.parseOrigin(url.trim()) : null;
-    return origin === null
-      ? err([
-          `'${path}' must be the address the portal is hosted at, without a path, for example 'https://docs.example.com'.`
-        ])
-      : ok(origin);
-  }
-
-  private static parseOrigin(value: string): UrlPath | null {
-    if (!isWebAddress(value)) {
-      return null;
-    }
-    const parsed = new URL(value);
-    if (parsed.pathname !== '/' || parsed.search !== '' || parsed.hash !== '') {
-      return null;
-    }
-    return new UrlPath(parsed.origin);
-  }
 }
diff --git a/src/types/portal/config/static-asset.ts b/src/types/portal/config/static-asset.ts
index 6a6d25bd5..e84d8762d 100644
--- a/src/types/portal/config/static-asset.ts
+++ b/src/types/portal/config/static-asset.ts
@@ -49,10 +49,10 @@ export class StaticAsset {
   }
 
   /**
-   * The `static/` prefix is the site root. Each name is escaped, since a `#`, `?` or `%` in it
+   * The `static/` prefix is the portal's root. Each name is escaped, since a `#`, `?` or `%` in it
    * would otherwise end or alter the path.
    */
-  public siteUrl(): string {
+  public portalPath(): string {
     return `/${this.relativePath.slice(STATIC_PREFIX.length).split('/').map(encodeURIComponent).join('/')}`;
   }
 
diff --git a/src/types/portal/content-tree.ts b/src/types/portal/content-tree.ts
index 419bc1bcc..0b545b549 100644
--- a/src/types/portal/content-tree.ts
+++ b/src/types/portal/content-tree.ts
@@ -18,11 +18,30 @@ import {
   PortalNavigation,
   TabEntry
 } from './portal-navigation.js';
-import { ContentProblem, MissingImage, PortalSpec, ReservedAddressPage, SharedAddress } from './portal-source.js';
+import {
+  ContentProblem,
+  MissingImage,
+  PortalSpec,
+  ReservedAddress,
+  ReservedAddressPage,
+  SharedAddress
+} from './portal-source.js';
 import { PortalTab, sharedTabNames, TabOwner, untitledTabName } from './portal-tabs.js';
 
 const NAVIGATION_FILE = new FileName(NAVIGATION_FILE_NAME);
 
+/**
+ * The page the API playground's OAuth authorization returns through, which the template serves
+ * from a route of its own (`portal-template/src/lib/oauth-callback.ts`). That route wins over a
+ * content page at the address, so such a page would build and never be shown.
+ */
+export const OAUTH_CALLBACK_ADDRESS = '/oauth/callback';
+
+export const OAUTH_CALLBACK: ReservedAddress = {
+  address: OAUTH_CALLBACK_ADDRESS,
+  description: "the API playground's OAuth authorization"
+};
+
 /** Extensions the docs collection compiles, and so the ones an entry can address. */
 const PAGE_EXTENSIONS = ['.md', '.mdx'];
 
@@ -302,15 +321,19 @@ export class ContentTree {
 
   /**
    * Pages served at a generated section's address or below it, whether or not `apimatic.json`
-   * calls for the section. Judged by the address, as the content source computes it, rather
-   * than by the directories as written: a page in a `(group)` folder is served as if the folder
-   * were not there, and a folder's index page at the folder's own address.
+   * calls for the section, and at the OAuth callback's. Judged by the address, as the content
+   * source computes it, rather than by the directories as written: a page in a `(group)` folder
+   * is served as if the folder were not there, and a folder's index page at the folder's own address.
    */
   private static reservedAddressPages(pages: ContentPage[]): ReservedAddressPage[] {
     return pages.flatMap(({ file, segments }) => {
       const slugs = getSlugs(segments.join('/'));
+      const address = `/${slugs.join('/')}`;
+      if (address === OAUTH_CALLBACK.address) return [{ file, address, keptFor: OAUTH_CALLBACK }];
       const section = GENERATED_SECTIONS.find((candidate) => candidate.folder === slugs[0]);
-      return section === undefined ? [] : [{ file, address: `/${slugs.join('/')}`, section }];
+      return section === undefined
+        ? []
+        : [{ file, address, keptFor: { address: `/${section.folder}`, description: section.description } }];
     });
   }
 
diff --git a/src/types/portal/page.ts b/src/types/portal/page.ts
index 65daa3085..7e423b4b3 100644
--- a/src/types/portal/page.ts
+++ b/src/types/portal/page.ts
@@ -35,6 +35,7 @@ const EXPECTED: Partial<Record<string, string>> = { string: 'text', boolean: 'tr
 interface MarkdownNode {
   type: string;
   url?: string;
+  identifier?: string;
   position?: { start: { line: number } };
   children?: MarkdownNode[];
 }
@@ -114,9 +115,26 @@ async function imagesIn(body: string, isMdx: boolean): Promise<PageImage[]> {
     return [];
   }
 
+  // The template writes `![a][ref]` as `![a](url)` before the build imports it (remark-image-references.ts).
+  const definitions = new Map<string, string>();
+  const define = (node: MarkdownNode) => {
+    // The first definition of a label wins, as CommonMark reads them.
+    if (node.type === 'definition' && node.identifier !== undefined && !definitions.has(node.identifier)) {
+      definitions.set(node.identifier, node.url ?? '');
+    }
+    node.children?.forEach(define);
+  };
+  define(tree);
+
   const images: PageImage[] = [];
   const visit = (node: MarkdownNode) => {
-    const image = node.type === 'image' && node.url !== undefined ? located(node.url) : null;
+    const url =
+      node.type === 'image'
+        ? node.url
+        : node.type === 'imageReference'
+        ? definitions.get(node.identifier ?? '')
+        : undefined;
+    const image = url !== undefined ? located(url) : null;
     if (image !== null) {
       images.push({ ...image, line: node.position?.start.line ?? 0 });
     }
diff --git a/src/types/portal/portal-config.ts b/src/types/portal/portal-config.ts
index 538c198b6..56cf2ce4b 100644
--- a/src/types/portal/portal-config.ts
+++ b/src/types/portal/portal-config.ts
@@ -6,6 +6,7 @@ import { BrandConfig, ColorMode } from './config/brand-config.js';
 import { allOf, optional, Parsed, unknownKeys } from './config/fields.js';
 import { Link } from './config/link.js';
 import { NavigationConfig } from './config/navigation-config.js';
+import { SiteAddress } from './config/site-address.js';
 import { SiteConfig, SuggestedSite } from './config/site-config.js';
 import { StaticAsset } from './config/static-asset.js';
 
@@ -24,11 +25,11 @@ export interface PortalLink {
 export interface PortalIdentity {
   name: string;
   description: string | null;
-  /** Origin only, with no trailing slash. */
+  /** The site address, with no trailing slash. */
   siteUrl: string | null;
-  /** Site-relative, one per colour mode; the same URL twice when one image serves both. */
+  /** Portal-relative, one per colour mode; the same URL twice when one image serves both. */
   logo: { light: string; dark: string } | null;
-  /** Site-relative, with the image type its extension names, when it names one. */
+  /** Portal-relative, with the image type its extension names, when it names one. */
   favicon: { url: string; type: string | null } | null;
   colorMode: ColorMode;
   links: PortalLink[];
@@ -94,6 +95,11 @@ export class PortalConfig {
     return this.site.siteName();
   }
 
+  /** Where the portal is hosted, or null when `site.url` is left out. */
+  public siteAddress(): SiteAddress | null {
+    return this.site.siteAddress();
+  }
+
   /** Where the context plugin is hosted when it is not bundled into the portal, or null when it is. */
   public pluginUrl(): UrlPath | null {
     return this.pluginAddress;
@@ -108,15 +114,15 @@ export class PortalConfig {
   }
 
   public identity(): PortalIdentity {
-    const origin = this.site.origin();
+    const address = this.site.siteAddress();
     const logo = this.brand.logoImages();
     const favicon = this.brand.faviconImage();
     return {
       name: this.site.siteName(),
       description: this.site.siteDescription(),
-      siteUrl: origin === null ? null : origin.toString(),
-      logo: logo === null ? null : { light: logo.light().siteUrl(), dark: logo.dark().siteUrl() },
-      favicon: favicon === null ? null : { url: favicon.siteUrl(), type: favicon.imageType() },
+      siteUrl: address === null ? null : address.toString(),
+      logo: logo === null ? null : { light: logo.light().portalPath(), dark: logo.dark().portalPath() },
+      favicon: favicon === null ? null : { url: favicon.portalPath(), type: favicon.imageType() },
       colorMode: this.brand.mode(),
       links: this.navigation.headerLinks().map(portalLink),
       pageActions: this.ai.offersPageActions()
diff --git a/src/types/portal/portal-languages.ts b/src/types/portal/portal-languages.ts
index ee3e6d900..ae4da5671 100644
--- a/src/types/portal/portal-languages.ts
+++ b/src/types/portal/portal-languages.ts
@@ -30,7 +30,7 @@ export class PortalLanguages {
   ): Result<PortalLanguages, string[]> {
     const errors = findingSentences(findings);
     const entries = Object.entries(block ?? {});
-    if (entries.length === 0 && findings.length === 0) {
+    if (PortalLanguages.namesNone(block, findings)) {
       errors.push(REQUIRED);
     }
     for (const [key] of entries.filter(([key]) => !SUPPORTED_LANGUAGES.includes(key))) {
@@ -46,6 +46,11 @@ export class PortalLanguages {
     return ok(new PortalLanguages(entries.map(([key, entry]) => PortalSdk.fromEntry(key as Language, entry))));
   }
 
+  /** False for a block of the wrong shape, which `findings` reports instead. */
+  public static namesNone(block: Record<string, unknown> | undefined, findings: readonly ConfigFinding[]): boolean {
+    return Object.keys(block ?? {}).length === 0 && findings.length === 0;
+  }
+
   /** In the order the block lists them. */
   public listed(): PortalSdk[] {
     return [...this.sdks];
diff --git a/src/types/portal/portal-source.ts b/src/types/portal/portal-source.ts
index 7929e5cc8..94813dd27 100644
--- a/src/types/portal/portal-source.ts
+++ b/src/types/portal/portal-source.ts
@@ -4,7 +4,7 @@ import { FilePath } from '../file/filePath.js';
 import { Endpoint } from './endpoint.js';
 import { SuggestedSite } from './config/site-config.js';
 import { ContentNotices } from './content-notices.js';
-import { GeneratedPages, GeneratedSection } from './generated-pages.js';
+import { GeneratedPages } from './generated-pages.js';
 import { PortalConfig } from './portal-config.js';
 
 /** An OpenAPI document found in `src/spec/`, with the slug its section is mounted at. */
@@ -57,12 +57,19 @@ export interface MissingStaticFile extends MissingFile {
   setting: string;
 }
 
-/** A page of the user's served at an address the CLI keeps for the pages it generates. */
+/** An address the portal serves a page of its own at: a generated section's, and every one below it, or a single page's. */
+export interface ReservedAddress {
+  address: string;
+  /** What a message says the address is kept for. */
+  description: string;
+}
+
+/** A page of the user's served at an address the portal keeps for a page of its own. */
 export interface ReservedAddressPage {
   file: FilePath;
   /** Where the page would be served, which a `(group)` folder makes differ from its path. */
   address: string;
-  section: GeneratedSection;
+  keptFor: ReservedAddress;
 }
 
 /** Pages of the user's that would be served at one address, which only one of them can have. */
diff --git a/src/types/project-context.ts b/src/types/project-context.ts
index 902ac21ab..9c6b25021 100644
--- a/src/types/project-context.ts
+++ b/src/types/project-context.ts
@@ -24,6 +24,12 @@ export type GitignoreFailure = 'unreadable' | 'unwritable';
 
 export type VersionProblem = 'noVersions' | 'versionNotFound';
 
+export type SpecZipProblem =
+  | { kind: 'noSpec'; specDirectory: DirectoryPath }
+  | { kind: 'unreadable'; specDirectory: DirectoryPath; reason: string }
+  | { kind: 'symlinks'; specDirectory: DirectoryPath; symlinks: FilePath[] }
+  | { kind: 'zipFailed'; specDirectory: DirectoryPath; reason: string };
+
 export class ProjectContext {
   private readonly fileService = new FileService();
 
@@ -49,6 +55,10 @@ export class ProjectContext {
     return new FilePath(this.projectDirectory, new FileName(GITIGNORE));
   }
 
+  private get specDirectory(): DirectoryPath {
+    return this.source.join(SPEC_DIRECTORY_NAME);
+  }
+
   public sourceDirectory(): DirectoryPath {
     return this.source;
   }
@@ -83,7 +93,24 @@ export class ProjectContext {
   }
 
   public async specsExist(): Promise<boolean> {
-    return await new SpecContext(this.source.join(SPEC_DIRECTORY_NAME)).validate();
+    return await new SpecContext(this.specDirectory).validate();
+  }
+
+  public async specZip(tempDirectory: DirectoryPath): Promise<Result<FilePath, SpecZipProblem>> {
+    if (!(await this.specsExist())) {
+      return err({ kind: 'noSpec', specDirectory: this.specDirectory });
+    }
+    const symlinks = await this.fileService.findSymlinks(this.specDirectory);
+    if (symlinks.isErr()) {
+      return err({ kind: 'unreadable', specDirectory: this.specDirectory, reason: symlinks.error });
+    }
+    if (symlinks.value.length > 0) {
+      return err({ kind: 'symlinks', specDirectory: this.specDirectory, symlinks: symlinks.value });
+    }
+    const zipped = await new TempContext(tempDirectory).zip(this.specDirectory);
+    return zipped.mapErr(
+      ({ reason }): SpecZipProblem => ({ kind: 'zipFailed', specDirectory: this.specDirectory, reason })
+    );
   }
 
   public async srcDirZip(
diff --git a/src/types/resource-context.ts b/src/types/resource-context.ts
index 15bf6fe19..3ebcba0be 100644
--- a/src/types/resource-context.ts
+++ b/src/types/resource-context.ts
@@ -1,34 +1,67 @@
-import * as path from "path";
-import { err, ok, Result } from "neverthrow";
-import { UrlPath } from "./file/urlPath.js";
-import { FilePath } from "./file/filePath.js";
-import { DirectoryPath } from "./file/directoryPath.js";
-import { FileName } from "./file/fileName.js";
-import { FileDownloadService } from "../infrastructure/services/file-download-service.js";
-import { FileService } from "../infrastructure/file-service.js";
-import { ResourceInput } from "./file/resource-input.js";
-import { ServiceError } from "../infrastructure/service-error.js";
+import { err, ok, Result } from 'neverthrow';
+import { UrlPath } from './file/urlPath.js';
+import { FilePath } from './file/filePath.js';
+import { DirectoryPath } from './file/directoryPath.js';
+import { FileDownloadService } from '../infrastructure/services/file-download-service.js';
+import { FileService } from '../infrastructure/file-service.js';
+import { ResourceInput } from './file/resource-input.js';
+import { ServiceError } from '../infrastructure/service-error.js';
+import { ProjectContext, SpecZipProblem } from './project-context.js';
 
-export class ResourceContext {
-  private readonly fileDownloadService = new FileDownloadService();
-  private readonly fileService = new FileService();
+export type ResourceKind = 'file' | 'url' | 'project';
+
+export type DownloadProblem = { kind: 'downloadFailed'; url: UrlPath; error: ServiceError };
 
-  constructor(private readonly tempDirectory: DirectoryPath) {}
+export type FileReadProblem = { kind: 'fileUnreadable'; file: FilePath };
 
-  public async resolveTo(resourcePath: ResourceInput): Promise<Result<FilePath, ServiceError>> {
-    const fileName = new FileName(path.basename(resourcePath.toString()));
-    const destinationFilePath = new FilePath(this.tempDirectory, fileName);
+export type ResolveProblem = SpecZipProblem | DownloadProblem | FileReadProblem;
 
-    if (resourcePath instanceof UrlPath) {
-      const downloadFileResult = await this.fileDownloadService.downloadFile(resourcePath);
-      if (downloadFileResult.isErr()) {
-        return err(downloadFileResult.error);
+export class ResourceContext {
+  private constructor(private readonly input: ResourceInput, private readonly resolvedFile: FilePath) {}
+
+  public static resolveTo(
+    input: FilePath | UrlPath,
+    tempDirectory: DirectoryPath
+  ): Promise<Result<ResourceContext, DownloadProblem | FileReadProblem>>;
+  public static resolveTo(
+    input: ResourceInput,
+    tempDirectory: DirectoryPath
+  ): Promise<Result<ResourceContext, ResolveProblem>>;
+  public static async resolveTo(
+    input: ResourceInput,
+    tempDirectory: DirectoryPath
+  ): Promise<Result<ResourceContext, ResolveProblem>> {
+    if (input instanceof ProjectContext) {
+      return (await input.specZip(tempDirectory)).map((zip) => new ResourceContext(input, zip));
+    }
+    const fileService = new FileService();
+    await fileService.createDirectoryIfNotExists(tempDirectory);
+    if (input instanceof UrlPath) {
+      const downloaded = await new FileDownloadService().downloadFile(input);
+      if (downloaded.isErr()) {
+        return err({ kind: 'downloadFailed', url: input, error: downloaded.error });
       }
-      await this.fileService.writeFile(destinationFilePath, downloadFileResult.value.stream);
+      const file = new FilePath(tempDirectory, downloaded.value.filename);
+      await fileService.writeFile(file, downloaded.value.stream);
+      return ok(new ResourceContext(input, file));
     }
-    if (resourcePath instanceof FilePath) {
-      await this.fileService.copy(resourcePath, destinationFilePath);
+    const copy = input.replaceDirectory(tempDirectory);
+    try {
+      await fileService.copy(input, copy);
+    } catch {
+      return err({ kind: 'fileUnreadable', file: input });
     }
-    return ok(destinationFilePath);
+    return ok(new ResourceContext(input, copy));
+  }
+
+  public kind(): ResourceKind {
+    if (this.input instanceof ProjectContext) {
+      return 'project';
+    }
+    return this.input instanceof UrlPath ? 'url' : 'file';
+  }
+
+  public file(): FilePath {
+    return this.resolvedFile;
   }
 }
diff --git a/test/actions/action-result.test.ts b/test/actions/action-result.test.ts
new file mode 100644
index 000000000..87e025fc9
--- /dev/null
+++ b/test/actions/action-result.test.ts
@@ -0,0 +1,33 @@
+import { expect } from 'chai';
+import { ActionResult } from '../../src/actions/action-result';
+
+describe('ActionResult', () => {
+  it('carries the error a failure was given, beside its message', () => {
+    const result = ActionResult.failed('Validation failed', 'invalid');
+
+    expect(result.isFailed()).to.be.true;
+    expect(result.getError()).to.equal('invalid');
+    expect(result.getMessage()).to.equal('Validation failed');
+    expect(result.getExitCode()).to.equal(1);
+  });
+
+  it('keeps the default message on a failure given only an error', () => {
+    const result = ActionResult.failed(undefined, 'unchecked');
+
+    expect(result.getMessage()).to.equal('Failed');
+    expect(result.getError()).to.equal('unchecked');
+  });
+
+  it('has no error on a failure given none, a success or a cancellation', () => {
+    expect(ActionResult.failed().getError()).to.be.undefined;
+    expect(ActionResult.success().getError()).to.be.undefined;
+    expect(ActionResult.cancelled().getError()).to.be.undefined;
+  });
+
+  it('drops the error along with the value', () => {
+    const result = ActionResult.failed(undefined, 'invalid').discardValue();
+
+    expect(result.isFailed()).to.be.true;
+    expect(result.getError()).to.be.undefined;
+  });
+});
diff --git a/test/actions/api/validate.test.ts b/test/actions/api/validate.test.ts
new file mode 100644
index 000000000..58dbefaa2
--- /dev/null
+++ b/test/actions/api/validate.test.ts
@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import { Readable } from 'node:stream';
+import os from 'node:os';
+import path from 'node:path';
+import sinon from 'sinon';
+import { expect } from 'chai';
+import { err, ok } from 'neverthrow';
+import { ValidateAction } from '../../../src/actions/api/validate.js';
+import { ApiValidatePrompts } from '../../../src/prompts/api/validate.js';
+import { ValidateViaFileParams, ValidationService } from '../../../src/infrastructure/services/validation-service.js';
+import { FileDownloadService } from '../../../src/infrastructure/services/file-download-service.js';
+import { ServiceError } from '../../../src/infrastructure/service-error.js';
+import { CommandMetadata } from '../../../src/types/common/command-metadata.js';
+import { DirectoryPath } from '../../../src/types/file/directoryPath.js';
+import { FileName } from '../../../src/types/file/fileName.js';
+import { FilePath } from '../../../src/types/file/filePath.js';
+import { ResourceInput } from '../../../src/types/file/resource-input.js';
+import { UrlPath } from '../../../src/types/file/urlPath.js';
+import { ProjectContext, SpecZipProblem } from '../../../src/types/project-context.js';
+import { ResolveProblem, ResourceContext } from '../../../src/types/resource-context.js';
+
+const COMMAND_METADATA: CommandMetadata = { commandName: 'api validate', shell: 'test' };
+const PASSED = { isSuccess: true, blocking: [], errors: [], warnings: [], information: [] };
+const FAILED = { isSuccess: false, blocking: [], errors: ['bad'], warnings: [], information: [] };
+
+describe('ValidateAction', () => {
+  let workingDirectory: DirectoryPath;
+  let prompts: sinon.SinonStubbedInstance<ApiValidatePrompts>;
+  let validateViaFile: sinon.SinonStub;
+
+  const project = () => ProjectContext.in(workingDirectory);
+
+  const validate = (spec: ResourceInput | ResourceContext) =>
+    new ValidateAction(workingDirectory, COMMAND_METADATA).execute(spec);
+
+  const expectUnchecked = async (spec: ResourceInput, problem: ResolveProblem) => {
+    const result = await validate(spec);
+
+    expect(result.isFailed()).to.be.true;
+    expect(result.getError()).to.equal('unchecked');
+    expect(prompts.specUnavailable.calledOnceWithExactly(problem)).to.be.true;
+    expect(validateViaFile.called).to.be.false;
+  };
+
+  beforeEach(() => {
+    workingDirectory = new DirectoryPath(fs.mkdtempSync(path.join(os.tmpdir(), 'api-validate-')));
+    prompts = sinon.stub(ApiValidatePrompts.prototype);
+    prompts.validateApi.callsFake((fn) => fn);
+    validateViaFile = sinon
+      .stub(ValidationService.prototype, 'validateViaFile')
+      .resolves(ok({ validation: PASSED, linting: PASSED } as never));
+  });
+
+  afterEach(() => {
+    sinon.restore();
+    fs.rmSync(workingDirectory.toString(), { recursive: true, force: true });
+  });
+
+  it('uploads the archive a project makes of its spec/', async () => {
+    const zip = new FilePath(workingDirectory, new FileName('spec.zip'));
+    sinon.stub(ProjectContext.prototype, 'specZip').resolves(ok(zip));
+
+    expect((await validate(project())).isSuccess()).to.be.true;
+    expect((validateViaFile.firstCall.args[0] as ValidateViaFileParams).file).to.equal(zip);
+  });
+
+  it("reports why a project's spec/ could not be zipped, and asks nothing of the service", async () => {
+    const problem: SpecZipProblem = { kind: 'noSpec', specDirectory: workingDirectory.join('src', 'spec') };
+    sinon.stub(ProjectContext.prototype, 'specZip').resolves(err(problem));
+
+    await expectUnchecked(project(), problem);
+  });
+
+  it('uploads a copy of a local file, under its own name', async () => {
+    const spec = new FilePath(workingDirectory, new FileName('openapi.yaml'));
+    fs.writeFileSync(spec.toString(), 'openapi: 3.0.3');
+    let uploaded: { file: FilePath; contents: string } | undefined;
+    // Read during the call: the copy is in a temporary directory the run removes.
+    validateViaFile.callsFake(async ({ file }: ValidateViaFileParams) => {
+      uploaded = { file, contents: fs.readFileSync(file.toString(), 'utf8') };
+      return ok({ validation: PASSED, linting: PASSED } as never);
+    });
+
+    expect((await validate(spec)).isSuccess()).to.be.true;
+    expect(uploaded?.file.isEqual(spec)).to.be.false;
+    expect(uploaded?.file.name().toString()).to.equal('openapi.yaml');
+    expect(uploaded?.contents).to.equal('openapi: 3.0.3');
+  });
+
+  it('reports a URL it could not download, and asks nothing of the service', async () => {
+    sinon.stub(FileDownloadService.prototype, 'downloadFile').resolves(err(ServiceError.NetworkError));
+    const url = new UrlPath('https://example.org/openapi.json');
+
+    await expectUnchecked(url, { kind: 'downloadFailed', url, error: ServiceError.NetworkError });
+  });
+
+  it('reports a local file that does not exist, and asks nothing of the service', async () => {
+    const missing = new FilePath(workingDirectory, new FileName('missing.json'));
+
+    await expectUnchecked(missing, { kind: 'fileUnreadable', file: missing });
+  });
+
+  it('calls a spec the service finds errors in invalid', async () => {
+    validateViaFile.resolves(ok({ validation: FAILED, linting: PASSED } as never));
+    const spec = new FilePath(workingDirectory, new FileName('openapi.yaml'));
+    fs.writeFileSync(spec.toString(), 'openapi: 3.0.3');
+
+    const result = await validate(spec);
+
+    expect(result.isFailed()).to.be.true;
+    expect(result.getError()).to.equal('invalid');
+  });
+
+  it('calls a spec the service refuses outright invalid, and one it never answered for unchecked', async () => {
+    const spec = new FilePath(workingDirectory, new FileName('openapi.yaml'));
+    fs.writeFileSync(spec.toString(), 'openapi: 3.0.3');
+
+    validateViaFile.resolves(err({ kind: 'rejected', message: 'Your API Definition is invalid.' }));
+    expect((await validate(spec)).getError()).to.equal('invalid');
+
+    validateViaFile.resolves(err({ kind: 'unavailable', message: 'Service unavailable' }));
+    expect((await validate(spec)).getError()).to.equal('unchecked');
+  });
+
+  // Quickstart hands over a spec it has resolved already, and needs the file it resolved to afterwards.
+  it('validates the file a context it is given resolved to, without resolving it again', async () => {
+    const download = sinon
+      .stub(FileDownloadService.prototype, 'downloadFile')
+      .resolves(ok({ stream: Readable.from(['openapi: 3.0.3']), filename: new FileName('openapi.yaml') }));
+    const spec = (
+      await ResourceContext.resolveTo(new UrlPath('https://example.org/openapi.yaml'), workingDirectory.join('temp'))
+    )._unsafeUnwrap();
+
+    expect((await validate(spec)).isSuccess()).to.be.true;
+    expect(download.calledOnce).to.be.true;
+    expect((validateViaFile.firstCall.args[0] as ValidateViaFileParams).file).to.equal(spec.file());
+    expect(fs.existsSync(spec.file().toString()), 'the file outlives the validation').to.be.true;
+  });
+});
diff --git a/test/actions/portal/generate.test.ts b/test/actions/portal/generate.test.ts
index aac217ee9..66e347500 100644
--- a/test/actions/portal/generate.test.ts
+++ b/test/actions/portal/generate.test.ts
@@ -20,6 +20,7 @@ import { completeArtifacts, stubPreparePortalProject } from './prepare-project-s
 const COMMAND_METADATA: CommandMetadata = { commandName: 'portal generate', shell: 'test' };
 const FIXTURE = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default');
 const CODE_SAMPLES_FIXTURE = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/code-samples');
+const SUBPATH_FIXTURE = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/subpath');
 
 /** The catalogs the merged fixture expects, read the way the service reads them. */
 const samplesFromFixture = (): CodeSampleCatalogs => {
@@ -249,6 +250,14 @@ describe('GenerateAction', () => {
     expect(prompts.nextSteps.calledOnceWith(portalDirectory, true)).to.be.true;
   });
 
+  it('tells the next steps where the portal is hosted, path included', async () => {
+    const result = await execute(SUBPATH_FIXTURE);
+
+    expect(result.isSuccess()).to.be.true;
+    const [, , site] = prompts.nextSteps.firstCall.args;
+    expect(site?.toString()).to.equal('https://docs.test/api');
+  });
+
   it('keeps the previous portal when the new one cannot be written', async () => {
     writeOldPortal();
     sinon.stub(FileService.prototype, 'copyDirectoryContents').rejects(new Error('ENOSPC: no space left on device'));
diff --git a/test/actions/quickstart.test.ts b/test/actions/quickstart.test.ts
index 13a3f4a85..66d4cc314 100644
--- a/test/actions/quickstart.test.ts
+++ b/test/actions/quickstart.test.ts
@@ -4,8 +4,10 @@ import path from 'path';
 import sinon from 'sinon';
 import { expect } from 'chai';
 import { err, ok } from 'neverthrow';
+import { ActionResult } from '../../src/actions/action-result';
 import { QuickstartAction } from '../../src/actions/quickstart';
 import { QuickstartPrompts } from '../../src/prompts/quickstart';
+import { PreparePortalProjectPrompts } from '../../src/prompts/portal/prepare-project';
 import { ApiValidatePrompts } from '../../src/prompts/api/validate';
 import { PortalAuthorizationService } from '../../src/infrastructure/services/portal-authorization-service';
 import { PortalProjectService } from '../../src/infrastructure/portal-project-service';
@@ -17,7 +19,9 @@ import { CommandMetadata } from '../../src/types/common/command-metadata';
 import { Language } from '../../src/types/sdk/generate';
 import { PortalArtifactsService } from '../../src/infrastructure/services/portal-artifacts-service';
 import { FileDownloadService } from '../../src/infrastructure/services/file-download-service';
+import { ServiceError } from '../../src/infrastructure/service-error';
 import { UrlPath } from '../../src/types/file/urlPath';
+import { ProjectContext } from '../../src/types/project-context';
 import { completeArtifacts } from './portal/prepare-project-stubs';
 
 const COMMAND_METADATA: CommandMetadata = { commandName: 'portal quickstart', shell: 'test' };
@@ -25,8 +29,15 @@ const SPEC = new FilePath(
   new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default/src/spec'),
   new FileName('Apimatic-Calculator.json')
 );
+const SAMPLE_URL = new UrlPath(
+  'https://raw.githubusercontent.com/apimatic/sample-docs-as-code-portal/refs/heads/v2/src/spec/openapi.json'
+);
 
 const PASSED = { isSuccess: true, blocking: [], errors: [], warnings: [], information: [] };
+const FAILED = { isSuccess: false, blocking: [], errors: ['bad'], warnings: [], information: [] };
+
+const downloadOf = (filename: string) =>
+  ok({ stream: fs.createReadStream(SPEC.toString()), filename: new FileName(filename) });
 
 describe('QuickstartAction', () => {
   let root: string;
@@ -34,11 +45,14 @@ describe('QuickstartAction', () => {
   let prompts: sinon.SinonStubbedInstance<QuickstartPrompts>;
   let runtimeProblem: sinon.SinonStub;
   let authorize: sinon.SinonStub;
+  let validateViaFile: sinon.SinonStub;
 
   // `root` holds no `src/`, so every test but the adopting ones takes the importing path.
   const execute = (workingDirectory: DirectoryPath = new DirectoryPath(root)) =>
     new QuickstartAction(new DirectoryPath(root), COMMAND_METADATA).execute(workingDirectory);
 
+  const failValidation = () => validateViaFile.resolves(ok({ validation: FAILED, linting: PASSED } as never));
+
   beforeEach(() => {
     root = fs.mkdtempSync(path.join(os.tmpdir(), 'portal-quickstart-'));
     // Signed in already, so the wizard goes straight to its questions.
@@ -49,9 +63,10 @@ describe('QuickstartAction', () => {
     prompts = sinon.stub(QuickstartPrompts.prototype);
     prompts.specPathPrompt.resolves(SPEC);
     prompts.projectDirectoryPrompt.resolves(projectDirectory);
+    prompts.downloadSpecFile.callsFake((fn) => fn);
 
     sinon.stub(ApiValidatePrompts.prototype, 'validateApi').callsFake((fn) => fn);
-    sinon
+    validateViaFile = sinon
       .stub(ValidationService.prototype, 'validateViaFile')
       .resolves(ok({ validation: PASSED, linting: PASSED } as never));
     runtimeProblem = sinon.stub(PortalProjectService.prototype, 'runtimeProblem').returns(null);
@@ -121,45 +136,189 @@ describe('QuickstartAction', () => {
     expect(prompts.noLanguagesSelected.calledOnce).to.be.true;
   });
 
-  // A build downloaded from the platform arrives with `src/spec/` already filled. Asking such a
-  // user for the specification their project carries, and then for where to put it, is the pair
-  // of questions this adoption exists to skip.
+  // A build downloaded from the platform arrives with `src/spec/` filled, beside its own
+  // `apimatic.json`. Asking such a user for the specification their project carries, and then
+  // for where to put it, is the pair of questions this adoption exists to skip.
   describe('a project that already carries a source directory', () => {
     let downloaded: DirectoryPath;
+    const inSource = (...parts: string[]) => path.join(downloaded.toString(), 'src', ...parts);
 
     beforeEach(() => {
       downloaded = new DirectoryPath(root).join('downloaded');
-      fs.mkdirSync(path.join(downloaded.toString(), 'src', 'spec'), { recursive: true });
-      fs.copyFileSync(SPEC.toString(), path.join(downloaded.toString(), 'src', 'spec', 'Apimatic-Calculator.json'));
+      fs.mkdirSync(inSource('spec'), { recursive: true });
+      fs.copyFileSync(SPEC.toString(), inSource('spec', 'Apimatic-Calculator.json'));
+      fs.writeFileSync(inSource('apimatic.json'), '{}');
     });
 
-    it('validates the specification it finds instead of asking for one', async () => {
-      prompts.selectLanguages.resolves([Language.TYPESCRIPT]);
+    it('validates the specification it finds instead of asking for one, or for its languages', async () => {
+      fs.writeFileSync(inSource('apimatic.json'), JSON.stringify({ languages: { typescript: {} } }));
       sinon.stub(PortalArtifactsService.prototype, 'generate').resolves(ok(completeArtifacts([Language.TYPESCRIPT])));
-      sinon.stub(PortalProjectService.prototype, 'prepare').resolves(err('stopped here'));
+      const prepare = sinon.stub(PortalProjectService.prototype, 'prepare').resolves(err('stopped here'));
 
       await execute(downloaded);
 
       expect(prompts.specPathPrompt.called, 'asked for a specification the project has').to.be.false;
       expect(prompts.projectDirectoryPrompt.called, 'asked where to put a project that exists').to.be.false;
+      expect(prompts.selectLanguages.called, 'asked for languages the project records itself').to.be.false;
 
-      const sourceDirectory = path.join(downloaded.toString(), 'src');
-      const written = JSON.parse(fs.readFileSync(path.join(sourceDirectory, 'apimatic.json'), 'utf8'));
+      const written = JSON.parse(fs.readFileSync(inSource('apimatic.json'), 'utf8'));
       expect(written.languages).to.deep.equal({ typescript: {} });
-      expect(written.portal, 'the portal block is scaffolded into the project it adopted').to.not.be.undefined;
+      expect(written.portal.site, 'a site is added to the project it adopted').to.not.be.undefined;
+      expect(written.plugin).to.deep.equal({
+        pluginId: 'my-api-plugin',
+        pluginName: 'My API Plugin',
+        pluginVersion: '0.1.0',
+        license: 'MIT'
+      });
+      expect(prepare.called, 'the wizard reached the preview').to.be.true;
 
       // The one that was there, and no copy of it beside itself.
-      expect(fs.readdirSync(path.join(sourceDirectory, 'spec'))).to.deep.equal(['Apimatic-Calculator.json']);
+      expect(fs.readdirSync(inSource('spec'))).to.deep.equal(['Apimatic-Calculator.json']);
+    });
+
+    const namingNoLanguage: [string, string][] = [
+      ['has no languages block', '{}'],
+      ['names no language', JSON.stringify({ languages: {} })]
+    ];
+
+    namingNoLanguage.forEach(([file, config]) => {
+      it(`asks for languages when the apimatic.json it adopts ${file}, and records the choice`, async () => {
+        fs.writeFileSync(inSource('apimatic.json'), config);
+        prompts.selectLanguages.resolves([Language.TYPESCRIPT]);
+        sinon.stub(PortalArtifactsService.prototype, 'generate').resolves(ok(completeArtifacts([Language.TYPESCRIPT])));
+        const prepare = sinon.stub(PortalProjectService.prototype, 'prepare').resolves(err('stopped here'));
+
+        await execute(downloaded);
+
+        expect(prompts.selectLanguages.calledOnce).to.be.true;
+        const written = JSON.parse(fs.readFileSync(inSource('apimatic.json'), 'utf8'));
+        expect(written.languages).to.deep.equal({ typescript: {} });
+        expect(prepare.called, 'the wizard reached the preview').to.be.true;
+      });
+    });
+
+    it('records no language, and stops, when none is chosen for the project it adopts', async () => {
+      prompts.selectLanguages.resolves([]);
+
+      expect((await execute(downloaded)).isCancelled()).to.be.true;
+      expect(prompts.noLanguagesSelected.calledOnce).to.be.true;
+      expect(JSON.parse(fs.readFileSync(inSource('apimatic.json'), 'utf8')).languages).to.be.undefined;
+    });
+
+    it('leaves a languages block of the wrong shape for the preview to report, writing nothing to it', async () => {
+      fs.writeFileSync(inSource('apimatic.json'), JSON.stringify({ languages: { typescript: true } }));
+      const sourceProblem = sinon.stub(PreparePortalProjectPrompts.prototype, 'sourceProblem');
+
+      await execute(downloaded);
+
+      expect(prompts.selectLanguages.called, 'asked for languages the project names').to.be.false;
+      expect(prompts.configNotWritten.called, 'blamed a file it had no languages to write to').to.be.false;
+      expect(JSON.parse(fs.readFileSync(inSource('apimatic.json'), 'utf8')).languages).to.deep.equal({
+        typescript: true
+      });
+      expect(sourceProblem.calledOnce, 'the preview reported the block').to.be.true;
+    });
+
+    it('refuses an apimatic.json of a schema version it does not read by that version, before validating', async () => {
+      const config = JSON.stringify({ schemaVersion: 2 });
+      fs.writeFileSync(inSource('apimatic.json'), config);
+
+      expect((await execute(downloaded)).isFailed()).to.be.true;
+      expect(prompts.configUnsupported.calledOnce).to.be.true;
+      expect(prompts.configUnsupported.firstCall.args[0].map((finding) => finding.field)).to.deep.equal([
+        'schemaVersion'
+      ]);
+      expect(validateViaFile.called).to.be.false;
+      expect(fs.readFileSync(inSource('apimatic.json'), 'utf8')).to.equal(config);
+      expect(fs.existsSync(inSource('content'))).to.be.false;
+    });
+
+    it('refuses an apimatic.json that is not valid JSON, before validating', async () => {
+      const config = '{ "portal": ';
+      fs.writeFileSync(inSource('apimatic.json'), config);
+
+      expect((await execute(downloaded)).isFailed()).to.be.true;
+      expect(prompts.configUnsupported.calledOnce).to.be.true;
+      expect(prompts.configUnsupported.firstCall.args[0].map((finding) => finding.problem)).to.deep.equal([
+        'is not valid JSON'
+      ]);
+      expect(validateViaFile.called).to.be.false;
+      expect(prompts.scaffoldFailed.called).to.be.false;
+      expect(fs.readFileSync(inSource('apimatic.json'), 'utf8')).to.equal(config);
+      expect(fs.existsSync(inSource('content'))).to.be.false;
+    });
+
+    it('leaves the plugin block an adopted project carries as it is', async () => {
+      const config = JSON.stringify({
+        portal: { site: { name: 'Our Docs' } },
+        languages: { typescript: {} },
+        plugin: { pluginName: 'Ours' }
+      });
+      fs.writeFileSync(inSource('apimatic.json'), config);
+      sinon.stub(PortalArtifactsService.prototype, 'generate').resolves(ok(completeArtifacts([Language.TYPESCRIPT])));
+      sinon.stub(PortalProjectService.prototype, 'prepare').resolves(err('stopped here'));
+
+      await execute(downloaded);
+
+      expect(fs.readFileSync(inSource('apimatic.json'), 'utf8')).to.equal(config);
+    });
+
+    it('refuses a project without apimatic.json before validating, and writes nothing', async () => {
+      fs.rmSync(inSource('apimatic.json'));
+
+      expect((await execute(downloaded)).isFailed()).to.be.true;
+      expect(prompts.configMissing.calledOnce).to.be.true;
+      expect(validateViaFile.called).to.be.false;
+      expect(fs.readdirSync(inSource())).to.deep.equal(['spec']);
+    });
+
+    // Whatever `spec/` holds is the user's, so it is adopted, and fails as `api validate` would fail it.
+    it('adopts a spec/ that holds no document rather than asking for one', async () => {
+      fs.rmSync(inSource('spec', 'Apimatic-Calculator.json'));
+      fs.writeFileSync(inSource('spec', 'README.md'), '# Specs');
+      failValidation();
+
+      expect((await execute(downloaded)).isCancelled()).to.be.true;
+      expect(prompts.specPathPrompt.called).to.be.false;
+      expect(prompts.specValidationFailed.calledOnceWith('project')).to.be.true;
+    });
+
+    // The validation service accepts Swagger 2.0, and the portal build does not.
+    it('refuses a spec/ the portal cannot be built from, as the build does, before writing into it', async () => {
+      fs.rmSync(inSource('spec', 'Apimatic-Calculator.json'));
+      fs.writeFileSync(inSource('spec', 'petstore.json'), JSON.stringify({ swagger: '2.0', info: {}, paths: {} }));
+
+      expect((await execute(downloaded)).isFailed()).to.be.true;
+      expect(prompts.specsUnsupported.calledOnce).to.be.true;
+      expect(prompts.specsUnsupported.firstCall.args[0].kind).to.equal('noOpenApiSpec');
+      expect(fs.readFileSync(inSource('apimatic.json'), 'utf8')).to.equal('{}');
+      expect(fs.existsSync(inSource('content'))).to.be.false;
+    });
+
+    it('validates all of spec/, not only the document the portal is built from', async () => {
+      const zip = new FilePath(new DirectoryPath(root), new FileName('spec.zip'));
+      const specZip = sinon.stub(ProjectContext.prototype, 'specZip').resolves(ok(zip));
+
+      await execute(downloaded);
+
+      expect(specZip.calledOnce).to.be.true;
+      expect(specZip.firstCall.thisValue.isSourceDirectory(downloaded.join('src'))).to.be.true;
+      expect(validateViaFile.firstCall.args[0].file).to.equal(zip);
+    });
+
+    it('names the project in the failure, so the fix it suggests validates all of spec/', async () => {
+      failValidation();
+
+      await execute(downloaded);
+
+      expect(prompts.specValidationFailed.calledOnceWith('project')).to.be.true;
     });
 
     // The sample is written where the wizard is told to write, and an adopted `spec/` already
     // holds the document the portal would be built from. Offering it would promise a swap the
     // wizard cannot make.
     it('does not offer the sample when the specification it found fails validation', async () => {
-      const failed = { isSuccess: false, blocking: [], errors: ['bad'], warnings: [], information: [] };
-      (ValidationService.prototype.validateViaFile as sinon.SinonStub).resolves(
-        ok({ validation: failed, linting: PASSED } as never)
-      );
+      failValidation();
 
       expect((await execute(downloaded)).isCancelled()).to.be.true;
       expect(prompts.useDefaultSpecPrompt.called, 'offered to replace a specification it cannot replace').to.be.false;
@@ -168,50 +327,114 @@ describe('QuickstartAction', () => {
   });
 
   // Shown with the failure, so it is in view while the user decides how to proceed.
-  it('names the specification the user gave in the failure, before asking how to proceed', async () => {
-    const failed = { isSuccess: false, blocking: [], errors: ['bad'], warnings: [], information: [] };
-    (ValidationService.prototype.validateViaFile as sinon.SinonStub).resolves(
-      ok({ validation: failed, linting: PASSED } as never)
-    );
+  it('suggests validating the file the user gave in the failure, before asking how to proceed', async () => {
+    failValidation();
     prompts.useDefaultSpecPrompt.resolves(false);
 
     expect((await execute()).isCancelled()).to.be.true;
-    expect(prompts.specValidationFailed.calledOnceWith(SPEC)).to.be.true;
+    expect(prompts.specValidationFailed.calledOnceWith('file')).to.be.true;
     expect(prompts.specValidationFailed.calledBefore(prompts.useDefaultSpecPrompt)).to.be.true;
   });
 
-  it('names a specification from a URL by that URL, not by its download', async () => {
-    const url = new UrlPath('https://example.com/openapi.json');
-    prompts.specPathPrompt.resolves(url);
-    sinon.stub(FileDownloadService.prototype, 'downloadFile').resolves(ok(undefined as never));
-    prompts.downloadSpecFile.resolves(
-      ok({ stream: fs.createReadStream(SPEC.toString()), filename: 'openapi.json' } as never)
-    );
-    const failed = { isSuccess: false, blocking: [], errors: ['bad'], warnings: [], information: [] };
-    (ValidationService.prototype.validateViaFile as sinon.SinonStub).resolves(
-      ok({ validation: failed, linting: PASSED } as never)
-    );
+  it('suggests validating a specification from a URL by its URL, not by its download', async () => {
+    prompts.specPathPrompt.resolves(new UrlPath('https://example.com/openapi.json'));
+    sinon.stub(FileDownloadService.prototype, 'downloadFile').resolves(downloadOf('openapi.json'));
+    failValidation();
     prompts.useDefaultSpecPrompt.resolves(false);
 
     expect((await execute()).isCancelled()).to.be.true;
-    expect(prompts.specValidationFailed.calledOnceWith(url)).to.be.true;
+    expect(prompts.downloadSpecFile.calledOnce, 'downloaded under the spinner').to.be.true;
+    expect(prompts.specValidationFailed.calledOnceWith('url')).to.be.true;
+  });
+
+  it('reads a local file without the download spinner', async () => {
+    prompts.selectLanguages.resolves([]);
+
+    await execute();
+
+    expect(prompts.downloadSpecFile.called).to.be.false;
+  });
+
+  it('asks again for a file that does not exist, before validating anything', async () => {
+    const missing = new FilePath(new DirectoryPath(root), new FileName('missing.json'));
+    prompts.specPathPrompt.onFirstCall().resolves(missing);
+    prompts.selectLanguages.resolves([]);
+
+    await execute();
+
+    expect(prompts.specUnavailable.calledOnceWith({ kind: 'fileUnreadable', file: missing })).to.be.true;
+    expect(prompts.specPathPrompt.calledTwice).to.be.true;
+    expect(validateViaFile.calledOnce).to.be.true;
+  });
+
+  it('asks again after a download fails, and stops offering the sample once it has failed', async () => {
+    prompts.specPathPrompt.onFirstCall().callsFake(async (sample) => sample ?? undefined);
+    sinon.stub(FileDownloadService.prototype, 'downloadFile').resolves(err(ServiceError.NetworkError));
+    prompts.selectLanguages.resolves([]);
+
+    await execute();
+
+    const failed = prompts.specUnavailable.firstCall.args[0];
+    expect(failed.kind === 'downloadFailed' && failed.url.isEqual(SAMPLE_URL)).to.be.true;
+    expect(prompts.specPathPrompt.firstCall.args[0]?.isEqual(SAMPLE_URL)).to.be.true;
+    expect(prompts.specPathPrompt.secondCall.args[0]).to.be.null;
+  });
+
+  it("keeps offering the sample after the user's own address fails", async () => {
+    prompts.specPathPrompt.onFirstCall().resolves(new UrlPath('https://example.com/openapi.json'));
+    sinon.stub(FileDownloadService.prototype, 'downloadFile').resolves(err(ServiceError.NetworkError));
+    prompts.selectLanguages.resolves([]);
+
+    await execute();
+
+    expect(prompts.specPathPrompt.secondCall.args[0]?.isEqual(SAMPLE_URL)).to.be.true;
+  });
+
+  it('swaps in the sample, downloaded under the spinner, when the user asks for it', async () => {
+    failValidation();
+    prompts.useDefaultSpecPrompt.resolves(true);
+    const download = sinon.stub(FileDownloadService.prototype, 'downloadFile').resolves(downloadOf('openapi.json'));
+    prompts.selectLanguages.resolves([]);
+
+    await execute();
+
+    expect(download.calledOnce).to.be.true;
+    expect(download.firstCall.args[0].isEqual(SAMPLE_URL)).to.be.true;
+    expect(prompts.downloadSpecFile.calledOnce).to.be.true;
+    expect(fs.readdirSync(path.join(projectDirectory.toString(), 'src', 'spec'))).to.deep.equal(['openapi.json']);
+  });
+
+  it('ends the wizard when the sample cannot be downloaded', async () => {
+    failValidation();
+    prompts.useDefaultSpecPrompt.resolves(true);
+    sinon.stub(FileDownloadService.prototype, 'downloadFile').resolves(err(ServiceError.NetworkError));
+
+    expect((await execute()).isFailed()).to.be.true;
+    expect(prompts.specUnavailable.calledOnce).to.be.true;
+    expect(prompts.projectDirectoryPrompt.called).to.be.false;
   });
 
   it('treats a document the validation service refuses outright as an invalid specification', async () => {
-    (ValidationService.prototype.validateViaFile as sinon.SinonStub).resolves(
-      err({ kind: 'rejected', message: 'Your API Definition is invalid.' })
-    );
+    validateViaFile.resolves(err({ kind: 'rejected', message: 'Your API Definition is invalid.' }));
     prompts.useDefaultSpecPrompt.resolves(false);
 
     expect((await execute()).isCancelled()).to.be.true;
-    expect(prompts.specValidationFailed.calledOnceWith(SPEC)).to.be.true;
+    expect(prompts.specValidationFailed.calledOnceWith('file')).to.be.true;
+  });
+
+  it('treats a failed validation that carries no error as unchecked, never as a pass', async () => {
+    failValidation();
+    const failed = ActionResult.failed;
+    sinon.stub(ActionResult, 'failed').callsFake((message?: string) => failed(message));
+
+    expect((await execute()).isFailed()).to.be.true;
+    expect(prompts.specValidationFailed.called).to.be.false;
+    expect(prompts.projectDirectoryPrompt.called, 'went on to scaffold an unvalidated spec').to.be.false;
   });
 
   // The service's error is already shown, and the specification may be valid: there is nothing to fix.
   it('stops without calling the specification invalid when the validation service fails', async () => {
-    (ValidationService.prototype.validateViaFile as sinon.SinonStub).resolves(
-      err({ kind: 'unavailable', message: 'Service unavailable' })
-    );
+    validateViaFile.resolves(err({ kind: 'unavailable', message: 'Service unavailable' }));
 
     expect((await execute()).isFailed()).to.be.true;
     expect(prompts.specValidationFailed.called).to.be.false;
diff --git a/test/commands/api/validate-flags.test.ts b/test/commands/api/validate-flags.test.ts
new file mode 100644
index 000000000..276408f24
--- /dev/null
+++ b/test/commands/api/validate-flags.test.ts
@@ -0,0 +1,25 @@
+import { expect } from 'chai';
+import ApiValidate from '../../../src/commands/api/validate.js';
+import { flagParser } from '../flag-parser.js';
+
+const { rejects } = flagParser(ApiValidate);
+
+describe('api validate flags', () => {
+  it('takes the specification from one place only: a file, a URL, or a project directory', async () => {
+    expect((await rejects(['--file', 'openapi.json', '--input', './'])).message).to.contain('--input');
+    expect((await rejects(['--url', 'https://example.org/openapi.json', '--input', './'])).message).to.contain(
+      '--input'
+    );
+    expect((await rejects(['--file', 'openapi.json', '--url', 'https://example.org/openapi.json'])).message).to.contain(
+      '--url'
+    );
+  });
+
+  it('refuses a flag given empty, as an unset shell variable gives it, rather than reading it as left out', async () => {
+    for (const flag of ['--file', '--url', '--input', '-i']) {
+      expect((await rejects([flag, ''])).message).to.contain('The value is empty');
+    }
+    expect((await rejects(['--file', ' '])).message).to.contain('The value is empty');
+    expect((await rejects(['--file', '', '--input', './project'])).message).to.contain('Parsing --file');
+  });
+});
diff --git a/test/commands/flag-parser.ts b/test/commands/flag-parser.ts
new file mode 100644
index 000000000..1ff85798a
--- /dev/null
+++ b/test/commands/flag-parser.ts
@@ -0,0 +1,19 @@
+import { expect } from 'chai';
+import { Parser } from '@oclif/core';
+
+export function flagParser(command: { flags: unknown }) {
+  const parse = (argv: string[]) => Parser.parse(argv, { flags: command.flags as never, strict: true } as never);
+
+  const rejects = async (argv: string[]): Promise<Error> => {
+    let thrown: unknown;
+    try {
+      await parse(argv);
+    } catch (error) {
+      thrown = error;
+    }
+    expect(thrown, `expected ${argv.join(' ')} to be rejected`).to.be.an('error');
+    return thrown as Error;
+  };
+
+  return { parse, rejects };
+}
diff --git a/test/commands/sdk/publish-flags.test.ts b/test/commands/sdk/publish-flags.test.ts
index 23cc24145..d08ca9e96 100644
--- a/test/commands/sdk/publish-flags.test.ts
+++ b/test/commands/sdk/publish-flags.test.ts
@@ -1,20 +1,9 @@
 import { expect } from 'chai';
-import { Parser } from '@oclif/core';
 import SdkPublish from '../../../src/commands/sdk/publish.js';
 import { CodeGenerationVersion, Stability } from '../../../src/types/sdk/generate.js';
+import { flagParser } from '../flag-parser.js';
 
-const parse = (argv: string[]) => Parser.parse(argv, { flags: SdkPublish.flags as never, strict: true } as never);
-
-const rejects = async (argv: string[]): Promise<Error> => {
-  let thrown: unknown;
-  try {
-    await parse(argv);
-  } catch (error) {
-    thrown = error;
-  }
-  expect(thrown, `expected ${argv.join(' ')} to be rejected`).to.be.an('error');
-  return thrown as Error;
-};
+const { parse, rejects } = flagParser(SdkPublish);
 
 // Recording a publish is bookkeeping, not a decision, so the flag that asked is gone. A run that
 // still passes it is told it is unknown rather than having it quietly ignored — this pins that it
diff --git a/test/e2e/portal-build.test.ts b/test/e2e/portal-build.test.ts
index 4a41cda1b..ac8011e92 100644
--- a/test/e2e/portal-build.test.ts
+++ b/test/e2e/portal-build.test.ts
@@ -228,6 +228,13 @@ const stylesheetOf = (output: DirectoryPath) => {
     expect(read('index.md')).to.contain('Hello from the fixture.');
   });
 
+  it('writes the one OAuth redirect URI every endpoint page authorizes through, kept out of search', () => {
+    expect(read('oauth/callback/index.html')).to.contain('<meta name="robots" content="noindex"');
+    // The cookie it reads is the browser's, so the page is built to wait for it.
+    expect(read('oauth/callback/index.html')).to.contain('Completing authorization…');
+    expect(read('sitemap.xml')).to.not.contain('/oauth/callback');
+  });
+
   it('writes a search index and the llms files', () => {
     expect(exists('api/search.json')).to.be.true;
     expect(read('llms.txt')).to.contain('Welcome');
@@ -341,6 +348,11 @@ const stylesheetOf = (output: DirectoryPath) => {
     expect(assets.length, 'asset count').to.be.below(150);
   });
 
+  // Highlighting loads on demand; page code importing `shiki-bundle` would preload it on every page.
+  it('leaves the highlighter out of what a page preloads', () => {
+    expect(read('index.html')).to.not.contain('shiki-bundle');
+  });
+
   it('carries the code samples placed on the operation into its page data', () => {
     const page = read('api/apimatic-calculator/simple-calculator/Calculate/index.html');
 
@@ -717,3 +729,158 @@ const stylesheetOf = (output: DirectoryPath) => {
     ).to.deep.equal([-1, -1, -1, -1]);
   });
 });
+
+/**
+ * A portal whose address carries a path, `/api`, that its API reference's own pages start with:
+ * the case where a page could be taken for one already under the path and written without it.
+ */
+(enabled ? describe : describe.skip)('portal build, under a path (end to end)', function () {
+  this.timeout(10 * 60 * 1000);
+
+  let built: BuiltPortal | undefined;
+  let output: DirectoryPath;
+
+  before(async () => {
+    built = await buildFixture('subpath', { plugin: true });
+    ({ output } = built);
+  });
+
+  after(async () => {
+    await removeBuilt(built);
+  });
+
+  const read = (relative: string) => fs.readFileSync(path.join(output.toString(), relative), 'utf8');
+  const exists = (relative: string) => fs.existsSync(path.join(output.toString(), relative));
+
+  // The host serves the output's root at the path, so the path itself is no folder in it.
+  it('writes each page once, laid out as it would be at the root', () => {
+    for (const page of [
+      'index.html',
+      'index.md',
+      'authentication/index.html',
+      'api/search.json',
+      'api/apimatic-calculator/simple-calculator/Calculate/index.html'
+    ]) {
+      expect(exists(page), page).to.be.true;
+    }
+    expect(exists('api/api')).to.be.false;
+    expect(exists('api/authentication')).to.be.false;
+  });
+
+  it('points the page at its scripts, styles and the other pages under the path', () => {
+    const page = read('index.html');
+    const assets = [...page.matchAll(/\s(?:src|href)="([^"]*\/assets\/[^"]*)"/g)].map((match) => match[1]);
+
+    expect(assets).to.not.be.empty;
+    expect(assets.filter((asset) => !asset.startsWith('/api/assets/'))).to.deep.equal([]);
+    expect(page).to.contain('href="/api/authentication"');
+    expect(page).to.contain('href="/api/api/apimatic-calculator/');
+    expect(page).to.not.contain('href="/authentication"');
+  });
+
+  // Everything the page itself names on this host, the logo and favicon among them.
+  it('names nothing on its host outside the path', () => {
+    for (const page of [
+      'index.html',
+      'authentication/index.html',
+      'api/apimatic-calculator/simple-calculator/Calculate/index.html',
+      'sdks/index.html',
+      'sdks/typescript/index.html',
+      'context-plugin/index.html',
+      'oauth/callback/index.html'
+    ]) {
+      const addresses = [...read(page).matchAll(/\s(?:src|href)="(\/[^"]*)"/g)].map((match) => match[1]);
+
+      expect(addresses, page).to.not.be.empty;
+      expect(
+        addresses.filter((address) => !address.startsWith('/api/')),
+        page
+      ).to.deep.equal([]);
+    }
+    expect(read('index.html')).to.match(/<img src="\/api\/images\/logo\.png"/);
+    expect(read('index.html')).to.match(/<link rel="icon" href="\/api\/images\/logo\.png"/);
+    expect(read('sdks/index.html')).to.contain('href="/api/__downloads/sdk/typescript.zip"');
+  });
+
+  // Bundled, so it carries the base; a linked `/images/diagram.png` would be fetched from the host's
+  // root. The image is over Vite's 4 KiB inline limit, or it would be a data: URI and prove nothing.
+  it('bundles a Markdown image, under the path', () => {
+    expect(read('index.html')).to.match(/<img[^>]* src="\/api\/assets\/diagram[^"]*\.png"/);
+  });
+
+  // Fumadocs' `remarkImage` bundles inline images alone; the template writes this one inline first.
+  it('bundles a reference-style image too', () => {
+    expect(read('authentication/index.html')).to.match(/<img[^>]* src="\/api\/assets\/diagram[^"]*\.png"/);
+  });
+
+  // Fumadocs' own renderer fails the whole page over an image in a description; `ApiMarkdown` stands in for it.
+  it('renders an image and a code block in a description, the image under the path', () => {
+    const page = read('api/apimatic-calculator/simple-calculator/Calculate/index.html');
+
+    expect(page).to.match(/<img[^>]* src="\/api\/images\/diagram\.png"/);
+    expect(page).to.match(/<pre[^>]*><code><span class="line">\{ &quot;calculated&quot;: 9 \}<\/span><\/code><\/pre>/);
+  });
+
+  // The dialog would load a result's image from the host's root, as Fumadocs prefixes none.
+  it("searches a description's text without its image", () => {
+    const index = read('api/search.json');
+
+    expect(index).to.contain('Calculates the expression using the specified operation.');
+    expect(index).to.not.contain('diagram.png');
+  });
+
+  // The pages' own links: a description after one is the author's Markdown, which keeps its spelling.
+  it('links the pages under the path in llms.txt and llms-full.txt', () => {
+    const links = [...read('llms.txt').matchAll(/^\s*- \[[^\]]*\]\(([^)]*)\)/gm)].map((match) => match[1]);
+
+    expect(links).to.include.members(['/api/authentication']);
+    expect(links.some((link) => link.startsWith('/api/api/apimatic-calculator/'))).to.be.true;
+    expect(links.filter((link) => !link.startsWith('/api/'))).to.deep.equal([]);
+    expect(read('llms-full.txt')).to.contain('# Authentication (/api/authentication)');
+  });
+
+  it('writes no robots file, which crawlers read only at the root of a host', () => {
+    expect(exists('robots.txt')).to.be.false;
+    expect(exists('sitemap.xml')).to.be.true;
+  });
+
+  it('writes the path into the links and install command the Markdown twins carry', () => {
+    const sdks = read('sdks.md');
+
+    expect(sdks).to.contain('[TypeScript](/api/sdks/typescript)');
+    expect(sdks).to.contain('[Download SDK](/api/__downloads/sdk/typescript.zip)');
+    expect(read('context-plugin.md')).to.contain(
+      'npx context-plugins install "https://docs.test/api/__downloads/plugin.zip"'
+    );
+  });
+
+  // The prerender knows the configured address, which carries the path; the browser swaps in its own.
+  it('installs the bundled plugin from under the path', () => {
+    expect(read('context-plugin/index.html')).to.match(
+      /npx context-plugins install (&quot;|")https:\/\/docs\.test\/api\/__downloads\/plugin\.zip(&quot;|")/
+    );
+  });
+
+  // Without it every page reached by a link is the not-found page: the browser looks for the
+  // page's data at the host's root, while the build writes it where the host serves the path.
+  it('fetches the pages’ prerendered data from under the path, where the build writes it', () => {
+    const scripts = scriptsOf(output);
+    const fetchingFrom = (address: RegExp) =>
+      scripts.filter((script) => address.test(script.text)).map((script) => script.name);
+
+    expect(fetchingFrom(/[`'"]\/api\/__tsr\/staticServerFnCache\//)).to.not.be.empty;
+    expect(fetchingFrom(/[`'"]\/__tsr\/staticServerFnCache\//)).to.deep.equal([]);
+    expect(fs.readdirSync(path.join(output.toString(), '__tsr/staticServerFnCache'))).to.not.be.empty;
+    expect(exists('api/__tsr')).to.be.false;
+  });
+
+  it('gives the path in canonical links, og:url and the sitemap', () => {
+    const page = read('index.html');
+    const locations = [...read('sitemap.xml').matchAll(/<loc>([^<]*)<\/loc>/g)].map((match) => match[1]);
+
+    expect(page).to.contain('<link rel="canonical" href="https://docs.test/api/"');
+    expect(page).to.contain('<meta property="og:url" content="https://docs.test/api/"');
+    expect(locations).to.include('https://docs.test/api/api/apimatic-calculator/simple-calculator/Calculate');
+    expect(locations.filter((location) => !location.startsWith('https://docs.test/api/'))).to.deep.equal([]);
+  });
+});
diff --git a/test/e2e/portal-serve.test.ts b/test/e2e/portal-serve.test.ts
index 565355a5c..b02122dde 100644
--- a/test/e2e/portal-serve.test.ts
+++ b/test/e2e/portal-serve.test.ts
@@ -14,16 +14,15 @@ import {
   removePortalProjectDirectoryBase
 } from '../../src/infrastructure/tmp-extensions';
 
-// A real Vite dev server takes a minute to compile the portal and needs every runtime
-// dependency installed, so it stays out of the default run, as the build test does.
+// Opt-in: a real dev server needs a minute and every runtime dependency.
 const enabled = process.env.APIMATIC_E2E === '1';
 
 (enabled ? describe : describe.skip)('portal serve (end to end)', function () {
   this.timeout(10 * 60 * 1000);
 
   const fixture = new DirectoryPath(process.cwd()).join('test/resources/portal-inputs/default/src');
-  let base: string;
-  let root: string;
+  let base: string | undefined;
+  let root: string | undefined;
   let server: PortalDevServer | undefined;
 
   before(async () => {
@@ -55,27 +54,22 @@ const enabled = process.env.APIMATIC_E2E === '1';
 
   after(async () => {
     await server?.stop();
-    fs.rmSync(root, { recursive: true, force: true });
-    await removePortalProjectDirectoryBase(base);
+    if (root !== undefined) fs.rmSync(root, { recursive: true, force: true });
+    if (base !== undefined) await removePortalProjectDirectoryBase(base);
   });
 
-  /**
-   * Safari keeps the entry module cached across previews on the fixed port and executes it
-   * without asking the fresh server, so its first request is the file the entry imports from
-   * the CLI's installation. Served only through its importer's transform, that first request
-   * is refused as outside the allow list, and the page stays blank (apimatic-io#2287).
-   */
-  it('serves the TanStack dev entry to a browser that asks for it before anything else', async () => {
-    const installed = fs.realpathSync(path.join(root, 'build', 'node_modules', '@tanstack', 'react-start'));
+  // A missing file answers 200 too, with the fallback page, so the type says what came back.
+  it('serves a dependency file asked for before its importer (apimatic-io#2287)', async () => {
+    const installed = fs.realpathSync(path.join(root!, 'build', 'node_modules', '@tanstack', 'react-start'));
     const entry = path.join(installed, 'dist', 'plugin', 'default-entry', 'client.tsx').split(path.sep).join('/');
 
     const response = await globalThis.fetch(`${server?.url.toString()}/@fs/${entry}`);
 
-    expect(response.status, await response.text()).to.equal(200);
+    expect(response.status, await response.clone().text()).to.equal(200);
+    expect(response.headers.get('content-type')).to.contain('javascript');
   });
 
-  // A page imports its images from the static directory, outside the project, by the same kind of address.
-  it('serves an image from the static directory to a browser that asks for it before the page', async () => {
+  it('serves an image from the static directory asked for before the page importing it', async () => {
     const image = fs
       .realpathSync(path.join(fixture.toString(), 'static', 'images', 'logo.png'))
       .split(path.sep)
@@ -84,5 +78,6 @@ const enabled = process.env.APIMATIC_E2E === '1';
     const response = await globalThis.fetch(`${server?.url.toString()}/@fs/${image}`);
 
     expect(response.status).to.equal(200);
+    expect(response.headers.get('content-type')).to.equal('image/png');
   });
 });
diff --git a/test/infrastructure/file-service.test.ts b/test/infrastructure/file-service.test.ts
index a24584802..da7f2cbc2 100644
--- a/test/infrastructure/file-service.test.ts
+++ b/test/infrastructure/file-service.test.ts
@@ -142,4 +142,49 @@ describe('FileService', () => {
       expect(await fileService.spelledOnDisk(root, fileAt('static', 'images'))).to.be.null;
     });
   });
+
+  describe('findSymlinks', () => {
+    const fileService = new FileService();
+    let root: DirectoryPath;
+    const symlink = (target: string, ...at: string[]) =>
+      fs.symlinkSync(
+        root.join(target).toString(),
+        root.join(...at).toString(),
+        process.platform === 'win32' ? 'junction' : 'dir'
+      );
+
+    beforeEach(() => {
+      root = new DirectoryPath(fs.mkdtempSync(path.join(os.tmpdir(), 'file-service-')));
+      fs.mkdirSync(root.join('spec', 'schemas').toString(), { recursive: true });
+      fs.writeFileSync(path.join(root.toString(), 'spec', 'openapi.yaml'), '');
+    });
+
+    afterEach(() => {
+      fs.rmSync(root.toString(), { recursive: true, force: true });
+    });
+
+    it('answers every symlink at any depth, without following one', async () => {
+      fs.mkdirSync(root.join('shared').toString());
+      symlink('shared', 'shared', 'back');
+      symlink('shared', 'spec', 'common');
+      symlink('shared', 'spec', 'schemas', 'shared');
+
+      const found = (await fileService.findSymlinks(root.join('spec')))._unsafeUnwrap();
+
+      expect(found.map((file) => file.toString())).to.have.members([
+        root.join('spec', 'common').toString(),
+        root.join('spec', 'schemas', 'shared').toString()
+      ]);
+    });
+
+    it('answers an empty list when there is none', async () => {
+      expect((await fileService.findSymlinks(root.join('spec')))._unsafeUnwrap()).to.deep.equal([]);
+    });
+
+    it('answers why, rather than throwing, when the directory cannot be read', async () => {
+      const missing = await fileService.findSymlinks(root.join('missing'));
+
+      expect(missing._unsafeUnwrapErr()).to.contain('ENOENT');
+    });
+  });
 });
diff --git a/test/infrastructure/portal-dev-server-service.test.ts b/test/infrastructure/portal-dev-server-service.test.ts
index 8fd7f8a6c..0fd7cd6bf 100644
--- a/test/infrastructure/portal-dev-server-service.test.ts
+++ b/test/infrastructure/portal-dev-server-service.test.ts
@@ -58,6 +58,16 @@ describe('PortalDevServerService', () => {
     await server.stop();
   });
 
+  // Vite answers the path without its slash with a 404, which would end the first page's wait early.
+  it('keeps the trailing slash of an address under a path', async () => {
+    const binary = script(serving(`response.end('page');`, `  Local:   http://127.0.0.1:${port}/docs/guides/`));
+
+    const server = (await start(binary))._unsafeUnwrap();
+    await server.stop();
+
+    expect(server.url.toString()).to.equal(`http://127.0.0.1:${port}/docs/guides/`);
+  });
+
   it('reports the server started only once it has answered its first page', async () => {
     const binary = script(serving(`require('fs').writeFileSync('answered', ''); response.end('page');`));
 
diff --git a/test/infrastructure/portal-project-service.test.ts b/test/infrastructure/portal-project-service.test.ts
index a1972d4c8..085e49644 100644
--- a/test/infrastructure/portal-project-service.test.ts
+++ b/test/infrastructure/portal-project-service.test.ts
@@ -7,6 +7,7 @@ import sinon from 'sinon';
 import { FileService } from '../../src/infrastructure/file-service';
 import {
   COPIED_DEPENDENCIES,
+  LINKED_DEPENDENCIES,
   PortalProjectService,
   TEMPLATE_DEPENDENCIES
 } from '../../src/infrastructure/portal-project-service';
@@ -129,6 +130,18 @@ describe('PortalProjectService', () => {
       }
     });
 
+    // Vite refuses an 8.3 short name outright, and compares the real path against its allow list.
+    it('links each dependency, and names the Vite binary, by its real path', async () => {
+      const prepared = (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap();
+
+      for (const name of LINKED_DEPENDENCIES) {
+        const link = path.join(project.toString(), 'node_modules', name);
+        expect(path.resolve(fs.readlinkSync(link)), name).to.equal(fs.realpathSync.native(link));
+      }
+      const binary = prepared.viteBinary.toString();
+      expect(binary).to.equal(fs.realpathSync.native(binary));
+    });
+
     // Linked, their `url()`s would resolve from the CLI's install, which may be on another drive.
     it('copies the font packages into the project instead of linking them', async () => {
       (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap();
@@ -152,6 +165,7 @@ describe('PortalProjectService', () => {
 
       const config = readConfig();
       expect(Object.keys(config).sort()).to.deep.equal([
+        'base',
         'codeSamples',
         'contentDir',
         'downloadsDir',
@@ -163,6 +177,20 @@ describe('PortalProjectService', () => {
       expect(config.specs.calculator).to.contain('api.json');
     });
 
+    it('builds the portal under the path of its address', async () => {
+      const config = configFor({ site: { name: 'My API', url: 'https://example.com/Docs/v2.1/' } });
+
+      (await service.prepare(project, sourceFor({ config }), NO_ARTIFACTS))._unsafeUnwrap();
+
+      expect(readConfig().base).to.equal('/Docs/v2.1/');
+    });
+
+    it('builds the portal at the root when it has no address', async () => {
+      (await service.prepare(project, sourceFor(), NO_ARTIFACTS))._unsafeUnwrap();
+
+      expect(readConfig().base).to.equal('/');
+    });
+
     it('writes the generated pages into the project, and names their directory in the build-only config', async () => {
       (
         await service.prepare(project, sourceFor({ generatedPages: pagesFor({ typescript: {} }, true) }), NO_ARTIFACTS)
diff --git a/test/portal-template.test.ts b/test/portal-template.test.ts
index d3cab763f..a7b5b286f 100644
--- a/test/portal-template.test.ts
+++ b/test/portal-template.test.ts
@@ -156,9 +156,11 @@ describe('portal template packaging', () => {
   // — tracking and preview parameters among them — reach the AI vendors it links out to.
   it('sends the AI vendors the page address and nothing the reader carried with them', () => {
     const route = fs.readFileSync(path.join(templateRoot, 'src/routes/$.tsx'), 'utf8');
+    const basePath = fs.readFileSync(path.join(templateRoot, 'src/lib/base-path.ts'), 'utf8');
 
     expect(route).to.match(/<ViewOptionsPopover [^>]*pageUrl=/);
-    expect(route).to.contain('new URL(pathname, window.location.origin)');
+    expect(route).to.contain('const pageUrl = fullAddress(pathname);');
+    expect(basePath).to.contain('new URL(withBasePath(path), window.location.origin)');
   });
 
   it('registers the plugin that reloads the generated pages under portal serve', () => {
diff --git a/test/portal-template/authorization-failure.test.ts b/test/portal-template/authorization-failure.test.ts
new file mode 100644
index 000000000..f54128a72
--- /dev/null
+++ b/test/portal-template/authorization-failure.test.ts
@@ -0,0 +1,115 @@
+import { expect } from 'chai';
+import { createServer, type Plugin, type ViteDevServer } from 'vite';
+import type { OAuthCallbackFailure } from '../../portal-template/src/lib/oauth-callback';
+
+const ENTRY = 'virtual:authorization-failure-fixture';
+
+const fixture = `
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { AuthorizationFailure } from '/portal-template/src/components/authorization-failure.tsx';
+
+export function render(failure) {
+  return renderToStaticMarkup(createElement(AuthorizationFailure, { failure }));
+}
+`;
+
+function authorizationFailureFixture(): Plugin {
+  return {
+    name: 'authorization-failure-fixture',
+    enforce: 'pre',
+    resolveId: (id) => (id === ENTRY ? `\0${ENTRY}` : null),
+    load: (id) => (id === `\0${ENTRY}` ? fixture : null)
+  };
+}
+
+/** What the reader is told, as text, and where its one link goes. */
+interface Shown {
+  text: string;
+  link: { label: string; href: string };
+}
+
+describe('the OAuth callback when it cannot complete the authorization', function () {
+  this.timeout(60 * 1000);
+
+  let server: ViteDevServer;
+  let render: (failure: OAuthCallbackFailure) => string;
+
+  before(async () => {
+    server = await createServer({
+      configFile: false,
+      root: process.cwd(),
+      // Under a path, which the home link has to carry.
+      base: '/docs/',
+      resolve: { tsconfigPaths: true },
+      logLevel: 'silent',
+      appType: 'custom',
+      server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+      optimizeDeps: { noDiscovery: true, include: [] },
+      plugins: [authorizationFailureFixture()]
+    });
+    ({ render } = (await server.ssrLoadModule(ENTRY)) as { render: typeof render });
+  });
+
+  after(() => server.close());
+
+  const shown = (failure: OAuthCallbackFailure): Shown => {
+    const markup = render(failure);
+    const link = /<a [^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/s.exec(markup);
+    expect(link, 'the page offers a way on').to.not.be.null;
+    return { text: readable(markup), link: { label: readable(link![2]), href: link![1] } };
+  };
+
+  it("names the provider's error and its description, with a link back to the starting page", () => {
+    const page = 'https://docs.test/api/pets/pets/listPets';
+
+    expect(
+      shown({ kind: 'providerError', error: 'access_denied', description: 'The user said no.', page })
+    ).to.deep.equal({
+      text: 'Authorization could not be completed The provider ended the authorization with access_denied: The user said no. Back to the endpoint',
+      link: { label: 'Back to the endpoint', href: page }
+    });
+  });
+
+  // `server_error` is no refusal, so the wording fits every code the provider can send.
+  it("names the provider's error alone when the provider gives no description", () => {
+    const { text } = shown({
+      kind: 'providerError',
+      error: 'server_error',
+      description: null,
+      page: 'https://docs.test/'
+    });
+
+    expect(text).to.contain('The provider ended the authorization with server_error.');
+  });
+
+  it('says no authorization was started in this browser, and leads to the home page', () => {
+    expect(shown({ kind: 'notStarted' })).to.deep.equal({
+      text:
+        "Authorization could not be completed This page completes an authorization started from an endpoint's playground, and none " +
+        "was started in this browser. Open the endpoint's page and authorize from there. Go to the home page",
+      link: { label: 'Go to the home page', href: '/docs/' }
+    });
+  });
+
+  it('says the authorization was not started from a page of this site, and leads to the home page', () => {
+    expect(shown({ kind: 'unknownPage' })).to.deep.equal({
+      text:
+        'Authorization could not be completed The authorization was not started from a page of this site, so it cannot be ' +
+        "completed here. Open the endpoint's page and authorize from there. Go to the home page",
+      link: { label: 'Go to the home page', href: '/docs/' }
+    });
+  });
+});
+
+/** Markup as the reader sees it: tags dropped, each block apart, entities spelled out. */
+function readable(markup: string): string {
+  return markup
+    .replace(/<\/(h1|p)>/g, ' ')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&#x27;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
diff --git a/test/portal-template/base-path.test.ts b/test/portal-template/base-path.test.ts
new file mode 100644
index 000000000..5e4c13bd7
--- /dev/null
+++ b/test/portal-template/base-path.test.ts
@@ -0,0 +1,35 @@
+import { expect } from 'chai';
+import { fullAddress, withBasePath } from '../../portal-template/src/lib/base-path';
+
+describe('withBasePath', () => {
+  // Outside Vite there is no `import.meta.env`, so the portal is taken to be at the root.
+  it('leaves a path alone at the root', () => {
+    expect(withBasePath('/guides/intro')).to.equal('/guides/intro');
+    expect(withBasePath('/guides/intro', '/')).to.equal('/guides/intro');
+  });
+
+  it('puts a path under the base it is given', () => {
+    expect(withBasePath('/guides/intro', '/docs/')).to.equal('/docs/guides/intro');
+    expect(withBasePath('/', '/docs/')).to.equal('/docs/');
+    expect(withBasePath('/api/search.json', '/api/')).to.equal('/api/api/search.json');
+  });
+});
+
+describe('fullAddress', () => {
+  const global = globalThis as { window?: unknown };
+
+  afterEach(() => {
+    delete global.window;
+  });
+
+  it('is the path itself where there is no window, as in the prerender', () => {
+    expect(fullAddress('/guides/intro.md')).to.equal('/guides/intro.md');
+  });
+
+  it('is the address the browser loaded the portal from, in the browser', () => {
+    global.window = { location: { origin: 'https://docs.test' } };
+
+    expect(fullAddress('/guides/intro.md')).to.equal('https://docs.test/guides/intro.md');
+    expect(fullAddress('/')).to.equal('https://docs.test/');
+  });
+});
diff --git a/test/portal-template/dependency-directories.test.ts b/test/portal-template/dependency-directories.test.ts
index 13ee77ea7..1bdd24ba1 100644
--- a/test/portal-template/dependency-directories.test.ts
+++ b/test/portal-template/dependency-directories.test.ts
@@ -2,29 +2,27 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { expect } from 'chai';
+import sinon from 'sinon';
 import { dependencyDirectories } from '../../portal-template/dependency-directories';
 
-/**
- * The directories `server.fs.allow` names so the dev server serves a linked dependency even
- * when the browser, from its cache, asks for it before the module importing it.
- */
 describe('dependencyDirectories', () => {
   let root: string;
 
-  const install = (relative: string): string => {
-    const directory = path.join(root, relative);
+  const install = (...segments: string[]): string => {
+    const directory = path.join(root, ...segments);
     fs.mkdirSync(directory, { recursive: true });
     return directory;
   };
 
   const link = (name: string, target: string) => {
-    const linkPath = path.join(root, 'project', 'node_modules', name);
+    const linkPath = path.join(root, 'project', 'node_modules', ...name.split('/'));
     fs.mkdirSync(path.dirname(linkPath), { recursive: true });
     // A junction is the only link type Windows grants without elevation.
     fs.symlinkSync(target, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
   };
 
   const project = () => path.join(root, 'project');
+  const real = (...segments: string[]) => fs.realpathSync.native(path.join(root, ...segments));
 
   beforeEach(() => {
     root = fs.mkdtempSync(path.join(os.tmpdir(), 'dependency-directories-'));
@@ -32,44 +30,81 @@ describe('dependencyDirectories', () => {
   });
 
   afterEach(() => {
+    sinon.restore();
     fs.rmSync(root, { recursive: true, force: true });
   });
 
-  it('answers the installation a linked dependency resolves to', () => {
-    link('vite', install(path.join('cli', 'node_modules', 'vite')));
+  it('answers the node_modules the linked dependencies are installed in, scoped ones included', () => {
+    link('vite', install('cli', 'node_modules', 'vite'));
+    link('@tanstack/react-start', install('cli', 'node_modules', '@tanstack', 'react-start'));
 
-    expect(dependencyDirectories(project())).to.deep.equal([fs.realpathSync(path.join(root, 'cli', 'node_modules'))]);
+    expect(dependencyDirectories(project())).to.deep.equal([real('cli', 'node_modules')]);
   });
 
-  it('answers one directory for dependencies installed side by side, scoped ones included', () => {
-    link('vite', install(path.join('cli', 'node_modules', 'vite')));
-    link(path.join('@tanstack', 'react-start'), install(path.join('cli', 'node_modules', '@tanstack', 'react-start')));
+  it("answers the CLI's own node_modules in an npm global install, not every global package around it", () => {
+    const cli = ['lib', 'node_modules', '@apimatic', 'cli', 'node_modules'];
+    install('lib', 'node_modules', 'some-other-global-package');
+    link('vite', install(...cli, 'vite'));
+    link('@tanstack/react-start', install(...cli, '@tanstack', 'react-start'));
 
-    expect(dependencyDirectories(project())).to.deep.equal([fs.realpathSync(path.join(root, 'cli', 'node_modules'))]);
+    expect(dependencyDirectories(project())).to.deep.equal([real(...cli)]);
   });
 
-  it('answers the store around a pnpm installation, not the one package inside it', () => {
-    link('vite', install(path.join('cli', 'node_modules', '.pnpm', 'vite@8.2.2', 'node_modules', 'vite')));
+  it('answers the whole pnpm store, where each dependency sits in a directory of its own', () => {
+    const store = ['global', 'node_modules', '.pnpm'];
+    link('vite', install(...store, 'vite@8.2.2', 'node_modules', 'vite'));
+    link(
+      '@tanstack/react-start',
+      install(...store, '@tanstack+react-start@1.168.50', 'node_modules', '@tanstack', 'react-start')
+    );
 
-    expect(dependencyDirectories(project())).to.deep.equal([fs.realpathSync(path.join(root, 'cli', 'node_modules'))]);
+    expect(dependencyDirectories(project())).to.deep.equal([real(...store)]);
   });
 
-  it('keeps a copied dependency where it is', () => {
-    install(path.join('project', 'node_modules', '@fontsource-variable', 'geist'));
+  it("answers the pnpm 11 global store's links directory, where each dependency sits under a hash of its own", () => {
+    const links = ['store', 'links'];
+    link('vite', install(...links, 'vite', '8.2.2', 'a1b2', 'node_modules', 'vite'));
+    link(
+      '@tanstack/react-start',
+      install(...links, '@tanstack', 'react-start', '1.168.50', 'c3d4', 'node_modules', '@tanstack', 'react-start')
+    );
 
-    expect(dependencyDirectories(project())).to.deep.equal([
-      fs.realpathSync(path.join(root, 'project', 'node_modules'))
-    ]);
+    expect(dependencyDirectories(project())).to.deep.equal([real(...links)]);
   });
 
-  it('leaves out a link leading nowhere rather than failing the server over it', () => {
-    link('vite', install(path.join('cli', 'node_modules', 'vite')));
+  it('leaves a copied dependency to the workspace root, which already holds it', () => {
+    install('project', 'node_modules', '@fontsource-variable', 'geist');
+    link('vite', install('cli', 'node_modules', 'vite'));
+
+    expect(dependencyDirectories(project())).to.deep.equal([real('cli', 'node_modules')]);
+  });
+
+  it('reports a link leading nowhere rather than leaving it out', () => {
+    link('vite', install('cli', 'node_modules', 'vite'));
     fs.rmdirSync(path.join(root, 'cli', 'node_modules', 'vite'));
 
-    expect(dependencyDirectories(project())).to.deep.equal([]);
+    expect(() => dependencyDirectories(project())).to.throw(/ENOENT/);
   });
 
-  it('answers nothing for a project without dependencies', () => {
-    expect(dependencyDirectories(path.join(root, 'nowhere'))).to.deep.equal([]);
+  it('lists installations one by one rather than the whole disk, when only its root holds them all', () => {
+    const disk = path.parse(root).root;
+    const installations: Record<string, string> = {
+      vite: path.join(disk, 'usr', 'lib', 'node_modules', '@apimatic', 'cli', 'node_modules'),
+      react: path.join(disk, 'home', 'me', 'src', 'node_modules')
+    };
+    link('vite', install('cli', 'node_modules', 'vite'));
+    link('react', install('elsewhere', 'node_modules', 'react'));
+    const installed = (target: string) => path.join(installations[path.basename(target)], path.basename(target));
+    // Only the disk's root holds both, and a test cannot install there.
+    sinon.stub(fs.realpathSync, 'native').callsFake(installed as typeof fs.realpathSync.native);
+
+    expect(dependencyDirectories(project())).to.have.members(Object.values(installations));
+  });
+
+  it('reports a node_modules it cannot read, rather than serving less than the page needs', () => {
+    fs.rmdirSync(path.join(root, 'project', 'node_modules'));
+    fs.writeFileSync(path.join(root, 'project', 'node_modules'), '');
+
+    expect(() => dependencyDirectories(project())).to.throw(/ENOTDIR/);
   });
 });
diff --git a/test/portal-template/downloads.test.ts b/test/portal-template/downloads.test.ts
index bce28a544..5eca0c3e2 100644
--- a/test/portal-template/downloads.test.ts
+++ b/test/portal-template/downloads.test.ts
@@ -36,17 +36,17 @@ describe('downloads', () => {
   });
 
   describe('in the preview', () => {
-    const middlewareFor = async (downloadsDirectory: string | null): Promise<Middleware | undefined> => {
+    const middlewareFor = async (downloadsDirectory: string | null, base = '/'): Promise<Middleware | undefined> => {
       let middleware: Middleware | undefined;
-      const server = { middlewares: { use: (handler: Middleware) => (middleware = handler) } };
+      const server = { config: { base }, middlewares: { use: (handler: Middleware) => (middleware = handler) } };
       const configureServer = downloads(downloadsDirectory).configureServer as (server: ViteDevServer) => Promise<void>;
       await configureServer(server as unknown as ViteDevServer);
       return middleware;
     };
 
     /** The body served for `url`, or `undefined` when the request is passed on. */
-    const request = async (url: string): Promise<string | undefined> => {
-      const middleware = (await middlewareFor(directory))!;
+    const request = async (url: string, base = '/'): Promise<string | undefined> => {
+      const middleware = (await middlewareFor(directory, base))!;
       const response = Object.assign(new PassThrough(), { setHeader: () => {} });
       let passedOn = false;
       middleware({ url }, response, () => (passedOn = true));
@@ -74,6 +74,13 @@ describe('downloads', () => {
       expect(await request('/__downloads/../plugin.zip')).to.be.undefined;
     });
 
+    // A link that forgot the base would 404 once built, so the preview does not answer it either.
+    it('serves each under the base when the portal has one, and passes on the address without it', async () => {
+      expect(await request('/docs/__downloads/sdk/python.zip', '/docs/')).to.equal('PK python');
+      expect(await request('/docs/__downloads/plugin.zip', '/docs/')).to.equal('PK plugin');
+      expect(await request('/__downloads/plugin.zip', '/docs/')).to.be.undefined;
+    });
+
     it('adds nothing when the run carried no downloads', async () => {
       expect(await middlewareFor(null)).to.be.undefined;
     });
diff --git a/test/portal-template/install-command.test.ts b/test/portal-template/install-command.test.ts
index 4e9257d8d..b1ddd7c52 100644
--- a/test/portal-template/install-command.test.ts
+++ b/test/portal-template/install-command.test.ts
@@ -2,7 +2,7 @@ import { expect } from 'chai';
 import { installCommand } from '../../portal-template/src/lib/install-command';
 
 describe('installCommand', () => {
-  it('prefixes a path on the portal with the origin it is served at', () => {
+  it('prefixes a path on the portal with the address the portal is served at', () => {
     expect(installCommand('/__downloads/plugin.zip', 'https://docs.acme.test')).to.equal(
       'npx context-plugins install "https://docs.acme.test/__downloads/plugin.zip"'
     );
@@ -14,14 +14,23 @@ describe('installCommand', () => {
     );
   });
 
+  // The browser's own address ends in a slash, and a configured one does not.
+  it('keeps the path a portal is served under, either way it is written', () => {
+    for (const site of ['https://acme.github.io/docs', 'https://acme.github.io/docs/']) {
+      expect(installCommand('/__downloads/plugin.zip', site), site).to.equal(
+        'npx context-plugins install "https://acme.github.io/docs/__downloads/plugin.zip"'
+      );
+    }
+  });
+
   it('leaves an address elsewhere as it is', () => {
     expect(installCommand('https://plugins.acme.test/calc.zip', 'https://docs.acme.test')).to.equal(
       'npx context-plugins install "https://plugins.acme.test/calc.zip"'
     );
   });
 
-  // Prerendered with no configured address: the browser supplies the origin once the page loads.
-  it('leaves the path as it is when the origin is not known', () => {
+  // Prerendered with no configured address: the browser supplies its address once the page loads.
+  it('leaves the path as it is when the address is not known', () => {
     expect(installCommand('/__downloads/plugin.zip', null)).to.equal(
       'npx context-plugins install "/__downloads/plugin.zip"'
     );
diff --git a/test/portal-template/oauth-callback.test.ts b/test/portal-template/oauth-callback.test.ts
new file mode 100644
index 000000000..35ff8ff12
--- /dev/null
+++ b/test/portal-template/oauth-callback.test.ts
@@ -0,0 +1,101 @@
+import { expect } from 'chai';
+import { oauthCallback, oauthCallbackPath } from '../../portal-template/src/lib/oauth-callback';
+import { OAUTH_CALLBACK_ADDRESS } from '../../src/types/portal/content-tree';
+
+// The CLI refuses a page of the user's at the address the template serves the callback at.
+describe('oauthCallbackPath', () => {
+  it('is the address the CLI keeps the content pages off', () => {
+    expect(oauthCallbackPath).to.equal(OAUTH_CALLBACK_ADDRESS);
+  });
+});
+
+describe('oauthCallback', () => {
+  const origin = 'https://docs.test';
+  const pageCookie = (path: string) => `theme=dark; fumadocs-openapi-oauth=${encodeURIComponent(path)}`;
+  const answered = (search: string, hash = '') => ({ origin, search, hash });
+
+  it("sends the authorization code back to the page that started the flow, in the provider's query", () => {
+    const callback = oauthCallback(pageCookie('/api/pets/pets/listPets'), answered('?code=abc&state=123'));
+
+    expect(callback).to.deep.equal({
+      kind: 'return',
+      url: 'https://docs.test/api/pets/pets/listPets?code=abc&state=123'
+    });
+  });
+
+  // The implicit flow answers in the fragment, which a browser never sends to a server either.
+  it("sends the implicit flow's token back in the provider's fragment", () => {
+    const callback = oauthCallback(pageCookie('/api/pets/pets/listPets'), answered('', '#access_token=xyz&state=123'));
+
+    expect(callback).to.deep.equal({
+      kind: 'return',
+      url: 'https://docs.test/api/pets/pets/listPets#access_token=xyz&state=123'
+    });
+  });
+
+  it('keeps an encoded page address as the page wrote it', () => {
+    const callback = oauthCallback(pageCookie('/api/pets/Get%20Pets'), answered('?code=abc'));
+
+    expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test/api/pets/Get%20Pets?code=abc' });
+  });
+
+  // As a bare path, `//evil.test/x?code=abc` would send the code to evil.test.
+  it('keeps the code on this site for a page whose path reads as another site', () => {
+    const callback = oauthCallback(
+      pageCookie('https://docs.test//evil.test/x'),
+      answered('?code=abc', '#access_token=xyz')
+    );
+
+    expect(callback).to.deep.equal({ kind: 'return', url: 'https://docs.test//evil.test/x?code=abc#access_token=xyz' });
+  });
+
+  // The playground's own return handling finds no code or token in it, and says nothing.
+  it("stays to show the provider's error, in the query, with a way back to the page", () => {
+    const callback = oauthCallback(
+      pageCookie('/api/pets/listPets'),
+      answered('?error=access_denied&error_description=The+user+said+no&state=123')
+    );
+
+    expect(callback).to.deep.equal({
+      kind: 'providerError',
+      error: 'access_denied',
+      description: 'The user said no',
+      page: 'https://docs.test/api/pets/listPets'
+    });
+  });
+
+  it("stays to show the implicit flow's error, in the fragment, without a description it was not given", () => {
+    const callback = oauthCallback(pageCookie('/api/pets/listPets'), answered('', '#error=access_denied&state=123'));
+
+    expect(callback).to.deep.equal({
+      kind: 'providerError',
+      error: 'access_denied',
+      description: null,
+      page: 'https://docs.test/api/pets/listPets'
+    });
+  });
+
+  it('says no authorization was started without the cookie', () => {
+    expect(oauthCallback('theme=dark', answered('?code=abc'))).to.deep.equal({ kind: 'notStarted' });
+    expect(oauthCallback('', answered('?code=abc'))).to.deep.equal({ kind: 'notStarted' });
+  });
+
+  // Anyone can link here, so an error and its description are only shown for an authorization this browser started.
+  it("shows no provider's error for an authorization this browser did not start", () => {
+    const callback = oauthCallback('', answered('?error=access_denied&error_description=Call+this+number'));
+
+    expect(callback).to.deep.equal({ kind: 'notStarted' });
+  });
+
+  it('refuses to send the code to another site', () => {
+    for (const page of ['https://evil.test/steal', '//evil.test/steal']) {
+      expect(oauthCallback(pageCookie(page), answered('?code=abc')), page).to.deep.equal({ kind: 'unknownPage' });
+    }
+  });
+
+  it('refuses a cookie that is not encoded the way the playground writes it', () => {
+    const callback = oauthCallback('fumadocs-openapi-oauth=%E0%A4%A', answered('?code=abc'));
+
+    expect(callback).to.deep.equal({ kind: 'unknownPage' });
+  });
+});
diff --git a/test/portal-template/prerender-pages.test.ts b/test/portal-template/prerender-pages.test.ts
index f8b3ab40d..1032d0781 100644
--- a/test/portal-template/prerender-pages.test.ts
+++ b/test/portal-template/prerender-pages.test.ts
@@ -17,9 +17,9 @@ describe('prerenderPages', () => {
   };
   const write = (relative: string, body = '# page\n') => writeIn(contentDir, relative, body);
 
-  const urlsFor = async (siteUrl: string | null = null, specs: Record<string, string> = {}) => {
+  const urlsFor = async (siteUrl: string | null = null, base = '/', specs: Record<string, string> = {}) => {
     const pages = await prerenderPages(
-      { specs, codeSamples: null, contentDir, generatedDir, staticDir: null, downloadsDir: null },
+      { base, specs, codeSamples: null, contentDir, generatedDir, staticDir: null, downloadsDir: null },
       siteUrl
     );
     return pages.map((page) => page.path);
@@ -106,6 +106,15 @@ describe('prerenderPages', () => {
     expect(await urlsFor('https://docs.test')).to.include('/robots.txt');
   });
 
+  it('lists the OAuth callback, without a Markdown twin', async () => {
+    write('index.md');
+
+    const urls = await urlsFor();
+
+    expect(urls).to.include('/oauth/callback');
+    expect(urls).to.not.include('/oauth/callback.md');
+  });
+
   it('does not ask for a Markdown twin of the generated files', async () => {
     write('index.md');
 
@@ -142,7 +151,7 @@ describe('prerenderPages', () => {
         }
       })
     );
-    const reference = (await urlsFor(null, { pets: spec })).filter((url) => url.startsWith('/api/pets/')).sort();
+    const reference = (await urlsFor(null, '/', { pets: spec })).filter((url) => url.startsWith('/api/pets/')).sort();
 
     expect(reference).to.deep.equal([
       '/api/pets/pets/createPet',
@@ -152,6 +161,46 @@ describe('prerenderPages', () => {
     ]);
   });
 
+  it('lists portal-relative paths for a portal at the root of its host', async () => {
+    write('index.md');
+    write('guides.md');
+
+    expect(await urlsFor('https://docs.test')).to.include.members(['/', '/guides', '/api/search.json']);
+  });
+
+  // TanStack prefixes a listed path with the base only when it does not already start with it,
+  // so `/api/search.json` under `/api` would otherwise be fetched as `/search.json`.
+  it('lists served paths for a portal under a path, the colliding ones included', async () => {
+    write('index.md');
+    write('guides.md');
+    write('api/overview.md');
+
+    const urls = await urlsFor('https://docs.test/api', '/api/');
+
+    expect(urls).to.include.members([
+      '/api/',
+      '/api/guides',
+      '/api/guides.md',
+      '/api/index.md',
+      '/api/api/search.json',
+      '/api/api/overview',
+      '/api/llms.txt',
+      '/api/sitemap.xml',
+      '/api/oauth/callback'
+    ]);
+    expect(urls.filter((url) => !url.startsWith('/api/'))).to.be.empty;
+  });
+
+  // A robots.txt anywhere but the root of a host is never read.
+  it('emits no robots file for a portal under a path', async () => {
+    write('index.md');
+
+    const urls = await urlsFor('https://docs.test/api', '/api/');
+
+    expect(urls).to.include('/api/sitemap.xml');
+    expect(urls.filter((url) => url.endsWith('robots.txt'))).to.be.empty;
+  });
+
   it('suffixes each page once, however many pages there are', async () => {
     write('index.md');
     write('guides.md');
diff --git a/test/portal-template/remark-image-references.test.ts b/test/portal-template/remark-image-references.test.ts
new file mode 100644
index 000000000..18feb57bb
--- /dev/null
+++ b/test/portal-template/remark-image-references.test.ts
@@ -0,0 +1,60 @@
+import { expect } from 'chai';
+import { remark } from 'remark';
+import { FileName } from '../../src/types/file/fileName';
+import { parsePage } from '../../src/types/portal/page';
+import { remarkImageReferences } from '../../portal-template/src/lib/remark-image-references';
+
+describe('the reference-style images of the content pages', () => {
+  interface Node {
+    type: string;
+    url?: string;
+    title?: string | null;
+    alt?: string | null;
+    children?: Node[];
+  }
+
+  /** A page's tree once the step has run, as `remarkImage` receives it. */
+  const transformed = (markdown: string): Node => {
+    const tree = remark().parse(markdown) as Node;
+    remarkImageReferences()(tree);
+    return tree;
+  };
+
+  const all = (node: Node, type: string): Node[] => [
+    ...(node.type === type ? [node] : []),
+    ...(node.children ?? []).flatMap((child) => all(child, type))
+  ];
+
+  it('writes a reference as an inline image, its address and title from the definition, its text from the reference', () => {
+    const tree = transformed('- ![A diagram][Flow]\n\n[flow]: /images/flow.png "The flow"\n');
+
+    expect(all(tree, 'image').map(({ url, title, alt }) => ({ url, title, alt }))).to.deep.equal([
+      { url: '/images/flow.png', title: 'The flow', alt: 'A diagram' }
+    ]);
+    expect(all(tree, 'imageReference')).to.deep.equal([]);
+  });
+
+  it('takes the first definition of a label, as CommonMark does', () => {
+    const tree = transformed('![a][x]\n\n[x]: /first.png\n[x]: /second.png\n');
+
+    expect(all(tree, 'image').map(({ url }) => url)).to.deep.equal(['/first.png']);
+  });
+
+  // A label with no definition is text to the parser already; a link to a defined label stays a link.
+  it('leaves an undefined label as text, and a link to a label as a link', () => {
+    const tree = transformed('![a][nowhere]\n\n[a link][x]\n\n[x]: /page\n');
+
+    expect(all(tree, 'image')).to.deep.equal([]);
+    expect(all(tree, 'text').map((node) => (node as { value?: string }).value)).to.include('![a][nowhere]');
+    expect(all(tree, 'linkReference')).to.have.length(1);
+  });
+
+  // The CLI reports a missing image before a build that would otherwise fail over it, naming no page.
+  it('hands the build exactly the images the CLI checks', async () => {
+    const markdown =
+      '---\ntitle: Images\n---\n\n![a](/images/a.png)\n\n> ![b][b]\n\n![c][missing]\n\n![d](./d.png)\n\n[b]: /images/b.png\n';
+    const checked = (await parsePage(markdown, new FileName('page.md'), 'content/page.md')).images;
+
+    expect(all(transformed(markdown), 'image').map(({ url }) => url)).to.deep.equal(checked.map(({ url }) => url));
+  });
+});
diff --git a/test/portal-template/search-content.test.ts b/test/portal-template/search-content.test.ts
new file mode 100644
index 000000000..2973fa328
--- /dev/null
+++ b/test/portal-template/search-content.test.ts
@@ -0,0 +1,23 @@
+import { expect } from 'chai';
+import { withoutImages } from '../../portal-template/src/lib/search-content';
+
+describe('withoutImages', () => {
+  it('drops an image and keeps the text and code around it as written', () => {
+    const description = 'Calculates it.\n\n![How a calculation flows](/images/diagram.png)\n\n```json\n{ "a": 9 }\n```';
+
+    expect(withoutImages(description)).to.equal('Calculates it.\n\n\n\n```json\n{ "a": 9 }\n```');
+  });
+
+  it('drops a reference-style image and an image inside a link', () => {
+    expect(withoutImages('See ![flow][f] here.\n\n[f]: /images/diagram.png')).to.equal(
+      'See  here.\n\n[f]: /images/diagram.png'
+    );
+    expect(withoutImages('A [![badge](/b.png)](https://x.test) link.')).to.equal('A [](https://x.test) link.');
+  });
+
+  it('leaves Markdown without images as written', () => {
+    const description = '- Some *text*, a [link](/x)\n- a table:\n\n| a | b |\n| - | - |\n| 1 | 2 |';
+
+    expect(withoutImages(description)).to.equal(description);
+  });
+});
diff --git a/test/portal-template/search-navigation.test.ts b/test/portal-template/search-navigation.test.ts
new file mode 100644
index 000000000..c8e74e964
--- /dev/null
+++ b/test/portal-template/search-navigation.test.ts
@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { expect } from 'chai';
+
+/** An installed module's code, as the portal's build bundles it. */
+const installed = (specifier: string) => fs.readFileSync(createRequire(import.meta.url).resolve(specifier), 'utf8');
+
+// `search.tsx` hands the dialog served URLs, right only while it navigates by href and the router strips
+// the base once: a failure here is an upgrade that changed one of them, which only a browser would show.
+describe('search navigation under a base', () => {
+  it("has Fumadocs' search dialog navigate to a result by its URL", () => {
+    expect(installed('fumadocs-ui/components/dialog/search')).to.contain('router.push(item.url)');
+  });
+
+  it("has Fumadocs' TanStack adapter push by href", () => {
+    expect(installed('fumadocs-core/framework/tanstack')).to.contain('router.navigate({ href: url })');
+  });
+
+  it('has the router strip the base from an href once, from a page starting like the base too', async () => {
+    // Its ES module build: the CommonJS one warns of a circular require when loaded.
+    const { createMemoryHistory, createRootRoute, createRoute, createRouter } = await import('@tanstack/react-router');
+    const root = createRootRoute();
+    const router = createRouter({
+      routeTree: root.addChildren([createRoute({ getParentRoute: () => root, path: '$' })]),
+      basepath: '/api',
+      history: createMemoryHistory({ initialEntries: ['/api/'] })
+    });
+    await router.load();
+
+    await router.navigate({ href: '/api/api/calc/Calculate' });
+
+    expect(router.state.location.pathname).to.equal('/api/calc/Calculate');
+    expect(router.history.location.pathname).to.equal('/api/api/calc/Calculate');
+  });
+});
diff --git a/test/portal-template/search-options.test.ts b/test/portal-template/search-options.test.ts
new file mode 100644
index 000000000..849ca0218
--- /dev/null
+++ b/test/portal-template/search-options.test.ts
@@ -0,0 +1,12 @@
+import { expect } from 'chai';
+
+describe('the query the router reads and writes', () => {
+  // Under a base path the router puts back on load what these give it; TanStack's JSON default made the state a float.
+  it('gives back the query an OAuth provider returns, as it was written', async () => {
+    const { searchOptions } = await import('../../portal-template/src/lib/search-options');
+    const query = '?code=probe-code&state=339416824538556760932965154722860613397&v=1.0&page=2&debug=true';
+
+    expect(searchOptions.parseSearch(query)).to.include({ state: '339416824538556760932965154722860613397', v: '1.0' });
+    expect(searchOptions.stringifySearch(searchOptions.parseSearch(query))).to.equal(query);
+  });
+});
diff --git a/test/portal-template/static-functions-base.test.ts b/test/portal-template/static-functions-base.test.ts
new file mode 100644
index 000000000..930b9822a
--- /dev/null
+++ b/test/portal-template/static-functions-base.test.ts
@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { expect } from 'chai';
+import type { Plugin } from 'vite';
+import { CACHE_ADDRESS, staticFunctionsBase } from '../../portal-template/static-functions-base';
+
+interface Transform {
+  filter: { id: RegExp; code: string };
+  handler: (code: string) => string;
+}
+
+const MODULE =
+  '/p/node_modules/.pnpm/x/node_modules/@tanstack/start-static-server-functions/dist/esm/staticFunctionMiddleware.js';
+const SOURCE = 'return `/__tsr/staticServerFnCache/${filename}.json`;';
+
+/** The plugin as the build of a portal served under `base` resolves it. */
+function pluginFor(base: string): Plugin {
+  const plugin = staticFunctionsBase();
+  (plugin.configResolved as (config: { base: string }) => void)({ base });
+  return plugin;
+}
+
+const transform = (plugin: Plugin) => plugin.transform as unknown as Transform;
+
+/** What the plugin reports when the build ends, having failed with `error` or not. */
+function reportAtEnd(plugin: Plugin, error?: Error): string | undefined {
+  let reported: string | undefined;
+  const buildEnd = plugin.buildEnd as (this: { error: (message: string) => void }, error?: Error) => void;
+  buildEnd.call({ error: (message) => (reported = message) }, error);
+  return reported;
+}
+
+describe('staticFunctionsBase', () => {
+  // The server's copy writes the files, joining the address onto the output directory.
+  it('changes the browser build alone', () => {
+    const plugin = staticFunctionsBase();
+    const appliesTo = plugin.applyToEnvironment as (environment: { name: string }) => boolean;
+
+    expect(plugin.apply).to.equal('build');
+    expect(appliesTo({ name: 'client' })).to.be.true;
+    expect(appliesTo({ name: 'ssr' })).to.be.false;
+  });
+
+  it('puts the address cached results are fetched from under the base', () => {
+    expect(transform(pluginFor('/api/')).handler(SOURCE)).to.equal(
+      'return `/api/__tsr/staticServerFnCache/${filename}.json`;'
+    );
+  });
+
+  it('leaves the address as it is at the root, and still counts it found', () => {
+    const plugin = pluginFor('/');
+
+    expect(transform(plugin).handler(SOURCE)).to.equal(SOURCE);
+    expect(reportAtEnd(plugin)).to.be.undefined;
+  });
+
+  it('looks only at modules of that package holding the address', () => {
+    const { filter } = transform(staticFunctionsBase());
+
+    expect(filter.id.test(MODULE)).to.be.true;
+    expect(filter.id.test('C:\\p\\node_modules\\@tanstack\\start-static-server-functions\\dist\\esm\\x.js')).to.be.true;
+    expect(filter.id.test('/p/src/lib/cache.ts')).to.be.false;
+    expect(filter.code).to.equal(CACHE_ADDRESS);
+  });
+
+  it('fails the build when no module held the address, naming the package', () => {
+    expect(reportAtEnd(pluginFor('/api/'))).to.contain('@tanstack/start-static-server-functions');
+  });
+
+  it('adds nothing to a build that has already failed', () => {
+    expect(reportAtEnd(pluginFor('/api/'), new Error('earlier'))).to.be.undefined;
+  });
+
+  // Read from the installed package, so an upgrade that moves the address fails here, not only in a build.
+  it('finds the address in the installed package, where the filter looks', () => {
+    const require = createRequire(import.meta.url);
+    const dist = path.join(
+      path.dirname(require.resolve('@tanstack/start-static-server-functions/package.json')),
+      'dist'
+    );
+    const holding = fs
+      .readdirSync(dist, { recursive: true, encoding: 'utf8' })
+      .filter((file) => file.endsWith('.js'))
+      .map((file) => path.join(dist, file))
+      .filter((file) => fs.readFileSync(file, 'utf8').includes(CACHE_ADDRESS));
+
+    expect(holding).to.not.be.empty;
+    expect(holding.filter((file) => !transform(staticFunctionsBase()).filter.id.test(file))).to.deep.equal([]);
+  });
+});
diff --git a/test/prompts/portal/generate.test.ts b/test/prompts/portal/generate.test.ts
new file mode 100644
index 000000000..93a216c14
--- /dev/null
+++ b/test/prompts/portal/generate.test.ts
@@ -0,0 +1,67 @@
+import { stripVTControlCharacters } from 'node:util';
+import { expect } from 'chai';
+import sinon from 'sinon';
+import { PortalGeneratePrompts } from '../../../src/prompts/portal/generate.js';
+import { DirectoryPath } from '../../../src/types/file/directoryPath.js';
+import { SiteAddress } from '../../../src/types/portal/config/site-address.js';
+
+describe('PortalGeneratePrompts', () => {
+  describe('the next steps', () => {
+    const portal = new DirectoryPath('portal');
+
+    // Boxed or not depending on the terminal's width, but each sentence stays on a line of its own.
+    const printed = (zipped: boolean, url: string | null) => {
+      const site = url === null ? null : SiteAddress.parse(url, 'portal.site.url')._unsafeUnwrap();
+      const write = sinon.stub(process.stdout, 'write').returns(true);
+      try {
+        new PortalGeneratePrompts().nextSteps(portal, zipped, site);
+      } finally {
+        write.restore();
+      }
+      return stripVTControlCharacters(write.args.map(([chunk]) => String(chunk)).join(''));
+    };
+
+    it('sends a portal at the root of a host, or with no address, to any static host', () => {
+      for (const url of ['https://docs.example.com', null]) {
+        const note = printed(false, url);
+
+        expect(note).to.contain(`Upload the contents of '${portal}' to any static host.`);
+        expect(note).to.contain("Configure '404.html' as the error document so deep links resolve.");
+        expect(note).to.not.contain('robots.txt');
+        expect(note).to.not.contain('locally');
+      }
+    });
+
+    it('says where to unpack the archive at the root', () => {
+      expect(printed(true, 'https://docs.example.com')).to.contain(
+        `Unpack 'portal.zip' in '${portal}' onto any static host.`
+      );
+    });
+
+    // Its styles and scripts are requested under the path, so served anywhere else it loads without them.
+    it('says a portal under a path must be served there, with 404.html for the pages under it', () => {
+      const note = printed(false, 'https://acme.github.io/docs/');
+
+      expect(note).to.contain(`Upload the contents of '${portal}' so they are served at https://acme.github.io/docs/.`);
+      expect(note).to.contain(
+        "To check the portal locally, serve it under '/docs/': from the root of a local server, its pages load " +
+          'without their styles and scripts.'
+      );
+      expect(note).to.contain("Serve '404.html' for missing pages under '/docs/', so deep links resolve.");
+      expect(note).to.not.contain('any static host');
+    });
+
+    it('says where to unpack the archive under a path', () => {
+      expect(printed(true, 'https://acme.github.io/docs')).to.contain(
+        `Unpack 'portal.zip' in '${portal}' so its contents are served at https://acme.github.io/docs/.`
+      );
+    });
+
+    it('says why a portal under a path has no robots.txt, and what to add at the root', () => {
+      expect(printed(false, 'https://acme.github.io/docs')).to.contain(
+        "Crawlers read 'robots.txt' only at the root of a host, so none is generated. If you control the root, " +
+          "add 'Sitemap: https://acme.github.io/docs/sitemap.xml' to its 'robots.txt'."
+      );
+    });
+  });
+});
diff --git a/test/prompts/portal/prepare-project.test.ts b/test/prompts/portal/prepare-project.test.ts
index c1ee85160..f73b7ba94 100644
--- a/test/prompts/portal/prepare-project.test.ts
+++ b/test/prompts/portal/prepare-project.test.ts
@@ -3,6 +3,8 @@ import { expect } from 'chai';
 import sinon from 'sinon';
 import { log } from '@clack/prompts';
 import { PreparePortalProjectPrompts } from '../../../src/prompts/portal/prepare-project.js';
+import { DirectoryPath } from '../../../src/types/file/directoryPath.js';
+import { PortalSourceProblem } from '../../../src/types/portal/portal-source.js';
 import { Language } from '../../../src/types/sdk/generate.js';
 
 describe('PreparePortalProjectPrompts', () => {
@@ -32,4 +34,43 @@ describe('PreparePortalProjectPrompts', () => {
       "did not include the SDK docs for 'python', which"
     );
   });
+
+  describe('a source the build refuses', () => {
+    const source = new DirectoryPath('project').join('src');
+    const example =
+      'Run apimatic quickstart in an empty directory with a sample spec to see an example of a valid portal.';
+    let message: sinon.SinonStub;
+
+    const printed = () => message.getCalls().map((call) => stripVTControlCharacters(String(call.args[0])));
+
+    beforeEach(() => {
+      sinon.stub(log, 'error');
+      message = sinon.stub(log, 'message');
+    });
+
+    const describingNoPortal: [string, PortalSourceProblem][] = [
+      ['no apimatic.json', { kind: 'missingConfig' }],
+      [
+        'an apimatic.json with no portal block',
+        { kind: 'invalidConfig', errors: ["'portal' is required."], missingPortal: true }
+      ]
+    ];
+
+    describingNoPortal.forEach(([what, problem]) => {
+      it(`points at quickstart's sample portal for ${what}`, () => {
+        new PreparePortalProjectPrompts().sourceProblem(problem, source);
+
+        expect(printed()).to.include(example);
+      });
+    });
+
+    it('does not point at quickstart for a portal block that is there but invalid', () => {
+      new PreparePortalProjectPrompts().sourceProblem(
+        { kind: 'invalidConfig', errors: ["'portal.site' must be an object."], missingPortal: false },
+        source
+      );
+
+      expect(printed().join('\n')).to.not.contain('quickstart');
+    });
+  });
 });
diff --git a/test/prompts/portal/serve.test.ts b/test/prompts/portal/serve.test.ts
index ef5e580b1..422cdf636 100644
--- a/test/prompts/portal/serve.test.ts
+++ b/test/prompts/portal/serve.test.ts
@@ -37,10 +37,10 @@ describe('PortalServePrompts', () => {
       );
     });
 
-    // The artifacts are fetched once, so what they would have to carry anew waits for a restart.
-    it('says which additions need the preview restarted', () => {
+    // The artifacts are fetched once and Vite reads its base once, so these wait for a restart.
+    it('says which edits need the preview restarted', () => {
       expect(printed()).to.match(
-        /Restart the preview after adding a language or a 'plugin' block \(its SDK or plugin is fetched at startup\), adding or removing a page, creating '.*static', or changing which documents are in '.*spec'\./
+        /Restart the preview after adding a language or a 'plugin' block \(its SDK or plugin is fetched at startup\), adding or removing a page, creating '.*static', changing which documents are in '.*spec', or changing the path in 'portal\.site\.url'\./
       );
     });
 
diff --git a/test/prompts/portal/source.test.ts b/test/prompts/portal/source.test.ts
index 5ce4cbbd3..f6b9b5480 100644
--- a/test/prompts/portal/source.test.ts
+++ b/test/prompts/portal/source.test.ts
@@ -15,6 +15,7 @@ import { DirectoryPath } from '../../../src/types/file/directoryPath.js';
 import { FileName } from '../../../src/types/file/fileName.js';
 import { FilePath } from '../../../src/types/file/filePath.js';
 import { PLUGIN_SECTION, SDK_SECTION } from '../../../src/types/portal/generated-pages.js';
+import { OAUTH_CALLBACK } from '../../../src/types/portal/content-tree.js';
 
 describe('reportSourceProblem', () => {
   const source = new DirectoryPath('project').join('src');
@@ -41,12 +42,6 @@ describe('reportSourceProblem', () => {
     sinon.restore();
   });
 
-  it('points at quickstart for a directory with no apimatic.json', () => {
-    reportSourceProblem({ kind: 'missingConfig' }, source);
-
-    expect(printed()).to.contain('quickstart');
-  });
-
   // Quickstart refuses a directory that is not empty, which a running preview's is.
   it('does not point at quickstart for a file removed while the preview runs', () => {
     new PortalServePrompts().configRejected({ kind: 'missingConfig' }, source);
@@ -191,7 +186,7 @@ describe('reportSourceProblem', () => {
     });
   });
 
-  describe('a page at an address kept for the generated pages', () => {
+  describe("a page at an address kept for the portal's own pages", () => {
     const content = source.join('content');
 
     it('names the page, where it would be served, and what the address is kept for', () => {
@@ -201,14 +196,14 @@ describe('reportSourceProblem', () => {
           {
             file: new FilePath(content.join('(intro)'), new FileName('sdks.md')),
             address: '/sdks',
-            section: SDK_SECTION
+            keptFor: { address: '/sdks', description: SDK_SECTION.description }
           }
         ]
       });
 
       const [heading, ...rest] = printed().split('\n');
 
-      expect(heading).to.match(/^A page in .+ would be served where the portal puts the pages it generates:$/);
+      expect(heading).to.match(/^A page in .+ would be served where the portal puts pages of its own:$/);
       expect(rest).to.deep.equal([
         "  • 'content/(intro)/sdks.md', at '/sdks', which is kept for the SDK pages",
         'Rename or move the page.'
@@ -222,12 +217,12 @@ describe('reportSourceProblem', () => {
           {
             file: new FilePath(content.join('sdks'), new FileName('setup.md')),
             address: '/sdks/setup',
-            section: SDK_SECTION
+            keptFor: { address: '/sdks', description: SDK_SECTION.description }
           },
           {
             file: new FilePath(content, new FileName('context-plugin.mdx')),
             address: '/context-plugin',
-            section: PLUGIN_SECTION
+            keptFor: { address: '/context-plugin', description: PLUGIN_SECTION.description }
           }
         ]
       });
@@ -241,6 +236,23 @@ describe('reportSourceProblem', () => {
       );
       expect(printed()).to.contain('Rename or move each page.');
     });
+
+    it("says a page at /oauth/callback is kept for the API playground's OAuth authorization", () => {
+      reportContent({
+        kind: 'reservedAddresses',
+        pages: [
+          {
+            file: new FilePath(content.join('oauth'), new FileName('callback.md')),
+            address: '/oauth/callback',
+            keptFor: OAUTH_CALLBACK
+          }
+        ]
+      });
+
+      expect(printed()).to.contain(
+        "  • 'content/oauth/callback.md', at '/oauth/callback', which is kept for the API playground's OAuth authorization"
+      );
+    });
   });
 
   it('lists each page whose front matter the build would refuse, and shows front matter that works', () => {
diff --git a/test/prompts/quickstart.test.ts b/test/prompts/quickstart.test.ts
index 3ab4a6f47..c862ffebc 100644
--- a/test/prompts/quickstart.test.ts
+++ b/test/prompts/quickstart.test.ts
@@ -4,10 +4,12 @@ import sinon from 'sinon';
 import { log } from '@clack/prompts';
 import { QuickstartPrompts } from '../../src/prompts/quickstart.js';
 import { convertToOpenApi3 } from '../../src/prompts/portal/source.js';
+import { ApimaticConfigDocument } from '../../src/types/apimatic-config/document.js';
 import { DirectoryPath } from '../../src/types/file/directoryPath.js';
 import { FileName } from '../../src/types/file/fileName.js';
 import { FilePath } from '../../src/types/file/filePath.js';
 import { UrlPath } from '../../src/types/file/urlPath.js';
+import { ServiceError } from '../../src/infrastructure/service-error.js';
 
 describe('QuickstartPrompts', () => {
   const prompts = new QuickstartPrompts();
@@ -33,6 +35,53 @@ describe('QuickstartPrompts', () => {
     expect(printed()[0]).to.contain(fix);
   });
 
+  // The file checked is the wizard's copy in a temporary directory, which the user never chose.
+  it('names the spec by its file name, not by where the wizard copied it', () => {
+    prompts.specFormatUnsupported(new FilePath(specs, new FileName('petstore.json')), 'Swagger 2.0');
+
+    expect(printed()[0]).to.match(/^'petstore\.json' is Swagger 2\.0/);
+  });
+
+  it('names an address that failed to download, and asks again for a file that is not there', () => {
+    const url = new UrlPath('https://example.com/openapi.json');
+    prompts.specUnavailable({ kind: 'downloadFailed', url, error: ServiceError.NetworkError });
+    prompts.specUnavailable({ kind: 'fileUnreadable', file: new FilePath(specs, new FileName('missing.json')) });
+
+    expect(printed()[0]).to.contain(`Could not download ${url}.`);
+    expect(printed()[1]).to.equal(
+      'The specified file does not exist or is not a valid file. Please enter a valid file path.'
+    );
+  });
+
+  it('says a project without apimatic.json is not set up, and how to go on', () => {
+    const message = sinon.stub(log, 'message');
+
+    prompts.configMissing(new DirectoryPath('project').join('src'));
+
+    expect(printed()[0]).to.contain('apimatic.json');
+    expect(stripVTControlCharacters(String(message.firstCall.args[0]))).to.contain('apimatic quickstart');
+  });
+
+  it('names the schema version an apimatic.json is refused for, and the one it reads', () => {
+    const document = ApimaticConfigDocument.parse(JSON.stringify({ schemaVersion: 2 }))._unsafeUnwrap();
+
+    prompts.configUnsupported(document.findingsFor('root'), new DirectoryPath('project').join('src'));
+
+    expect(printed()[0]).to.contain(
+      "its 'schemaVersion' is 2, which this version of the CLI does not read; it reads 1."
+    );
+  });
+
+  it('says whether apimatic.json could not be read or could not be written', () => {
+    const source = new DirectoryPath('project').join('src');
+
+    prompts.configNotWritten('unreadable', source);
+    prompts.configNotWritten('unwritable', source);
+
+    expect(printed()[0]).to.contain('could not be read. Check that it can be read and try again.');
+    expect(printed()[1]).to.contain('could not be written. Check that it can be written and try again.');
+  });
+
   it('gives a spec that names no OpenAPI version the fix portal generate gives', () => {
     prompts.specNotRecognised(new FilePath(specs, new FileName('calculator.raml')));
 
@@ -49,7 +98,7 @@ describe('QuickstartPrompts', () => {
     });
 
     it('suggests an AI agent run validate on a local spec, or the VS Code extension', () => {
-      prompts.specValidationFailed(new FilePath(specs, new FileName('petstore.json')));
+      prompts.specValidationFailed('file');
       write.restore();
 
       expect(howToFix()).to.contain('How to fix');
@@ -62,10 +111,18 @@ describe('QuickstartPrompts', () => {
     });
 
     it('suggests validating a spec that came from a URL by its URL', () => {
-      prompts.specValidationFailed(new UrlPath('https://example.com/openapi.json'));
+      prompts.specValidationFailed('url');
       write.restore();
 
       expect(howToFix()).to.contain('apimatic api validate --url=<url>');
     });
+
+    it("names validate inline and with no flags for a project's spec/", () => {
+      prompts.specValidationFailed('project');
+      write.restore();
+
+      expect(howToFix()).to.contain('Ask an AI coding agent to run apimatic api validate and fix what it reports.');
+      expect(howToFix()).not.to.contain('--');
+    });
   });
 });
diff --git a/test/resources/portal-inputs/subpath/src/apimatic.json b/test/resources/portal-inputs/subpath/src/apimatic.json
new file mode 100644
index 000000000..b44972429
--- /dev/null
+++ b/test/resources/portal-inputs/subpath/src/apimatic.json
@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "portal": {
+    "site": {
+      "name": "Calculator API",
+      "url": "https://docs.test/api"
+    },
+    "brand": {
+      "logo": "static/images/logo.png"
+    }
+  },
+  "languages": {
+    "typescript": {}
+  },
+  "plugin": { "pluginId": "calculator", "pluginName": "Calculator", "pluginVersion": "0.1.0" }
+}
diff --git a/test/resources/portal-inputs/subpath/src/content/authentication.md b/test/resources/portal-inputs/subpath/src/content/authentication.md
new file mode 100644
index 000000000..cee211b45
--- /dev/null
+++ b/test/resources/portal-inputs/subpath/src/content/authentication.md
@@ -0,0 +1,10 @@
+---
+title: Authentication
+description: How requests are authorised.
+---
+
+Authentication for the fixture.
+
+![The flow, by reference][flow]
+
+[flow]: /images/diagram.png
diff --git a/test/resources/portal-inputs/subpath/src/content/index.md b/test/resources/portal-inputs/subpath/src/content/index.md
new file mode 100644
index 000000000..7d2ab6e9d
--- /dev/null
+++ b/test/resources/portal-inputs/subpath/src/content/index.md
@@ -0,0 +1,8 @@
+---
+title: Welcome
+description: Start here.
+---
+
+Hello from the fixture served under a path. Requests need [authentication](/authentication).
+
+![How a calculation flows](/images/diagram.png)
diff --git a/test/resources/portal-inputs/subpath/src/content/nav.json b/test/resources/portal-inputs/subpath/src/content/nav.json
new file mode 100644
index 000000000..886c2cd18
--- /dev/null
+++ b/test/resources/portal-inputs/subpath/src/content/nav.json
@@ -0,0 +1,11 @@
+{
+  "tabs": [
+    "apimatic:sdks",
+    "apimatic:plugin",
+    "apimatic:api"
+  ],
+  "pages": [
+    "index",
+    "..."
+  ]
+}
diff --git a/test/resources/portal-inputs/subpath/src/spec/Apimatic-Calculator.json b/test/resources/portal-inputs/subpath/src/spec/Apimatic-Calculator.json
new file mode 100644
index 000000000..568861b5d
--- /dev/null
+++ b/test/resources/portal-inputs/subpath/src/spec/Apimatic-Calculator.json
@@ -0,0 +1,104 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "APIMATIC Calculator-test",
+    "description": "Simple calculator API hosted on APIMATIC for demo purposes",
+    "contact": {},
+    "version": "2.3"
+  },
+  "servers": [
+    {
+      "url": "https://examples.apimatic.io/apps/calculator",
+      "description": "This environment connect to the LIVE calculator API",
+      "variables": {}
+    }
+  ],
+  "paths": {
+    "/{operation}": {
+      "get": {
+        "tags": [
+          "Simple Calculator"
+        ],
+        "summary": "Calculate",
+        "description": "Calculates the expression using the specified operation.\n\n![How a calculation flows](/images/diagram.png)\n\n```json\n{ \"calculated\": 9 }\n```",
+        "operationId": "Calculate",
+        "parameters": [
+          {
+            "name": "operation",
+            "in": "path",
+            "description": "The operator to apply on the variables",
+            "required": true,
+            "style": "simple",
+            "schema": {
+              "$ref": "#/components/schemas/OperationType"
+            }
+          },
+          {
+            "name": "x",
+            "in": "query",
+            "description": "The LHS value",
+            "required": true,
+            "style": "form",
+            "explode": true,
+            "schema": {
+              "type": "number",
+              "format": "double"
+            }
+          },
+          {
+            "name": "y",
+            "in": "query",
+            "description": "The RHS value",
+            "required": true,
+            "style": "form",
+            "explode": true,
+            "schema": {
+              "type": "number",
+              "format": "double"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "",
+            "headers": {},
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "number",
+                  "format": "double"
+                }
+              }
+            }
+          }
+        },
+        "deprecated": false
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "OperationType": {
+        "title": "OperationType",
+        "enum": [
+          "SUM",
+          "SUBTRACT",
+          "MULTIPLY",
+          "DIVIDE"
+        ],
+        "type": "string",
+        "description": "Possible operators are sum, subtract, multiply, divide",
+        "example": "SUM"
+      }
+    }
+  },
+  "security": [
+    {}
+  ],
+  "tags": [
+    {
+      "name": "Simple Calculator",
+      "description": ""
+    }
+  ]
+}
diff --git a/test/resources/portal-inputs/subpath/src/static/images/diagram.png b/test/resources/portal-inputs/subpath/src/static/images/diagram.png
new file mode 100644
index 000000000..1dacfd38b
Binary files /dev/null and b/test/resources/portal-inputs/subpath/src/static/images/diagram.png differ
diff --git a/test/resources/portal-inputs/subpath/src/static/images/logo.png b/test/resources/portal-inputs/subpath/src/static/images/logo.png
new file mode 100644
index 000000000..42edcaf82
Binary files /dev/null and b/test/resources/portal-inputs/subpath/src/static/images/logo.png differ
diff --git a/test/types/apimatic-config/schema.test.ts b/test/types/apimatic-config/schema.test.ts
index 9fee38f83..4626ee62e 100644
--- a/test/types/apimatic-config/schema.test.ts
+++ b/test/types/apimatic-config/schema.test.ts
@@ -103,6 +103,12 @@ describe('apimatic.schema.json', () => {
         }
       ],
       ['an address with a port', { site: { url: 'https://docs.example.com:8443' } }],
+      ['an address with a path', { site: { url: 'https://x.test/docs' } }],
+      ['an address with a path and a trailing slash', { site: { url: 'https://x.test/docs/ ' } }],
+      ['an address with a deeper path in any case', { site: { url: 'HTTPS://x.test/Docs/v2.1/api_ref~x-y' } }],
+      ['an address with a path of dots alone', { site: { url: 'https://x.test/...' } }],
+      ['an address whose path ends in a version', { site: { url: 'https://x.test/docs/v1.0' } }],
+      ['an address whose path only starts like a page', { site: { url: 'https://x.test/docs.htmlx' } }],
       ['one logo for both modes', { brand: { logo: 'static/images/logo.png' } }],
       ['a logo path with its dots inside a name', { brand: { logo: 'static/..hidden/logo.png' } }],
       ['a three-digit hex primary', { brand: { colors: { primary: ' #FFF ' } } }],
@@ -122,11 +128,25 @@ describe('apimatic.schema.json', () => {
       ['a blank name', { site: { name: '   ' } }],
       ['a name that is not a string', { site: { name: 7 } }],
       ['an unknown site key', { site: { title: 'Calc' } }],
-      ['an address with a path', { site: { url: 'https://x.test/docs' } }],
       ['an address with a query', { site: { url: 'https://x.test/?a=1' } }],
+      ['an address with an empty query', { site: { url: 'https://x.test/docs?' } }],
       ['an address with a fragment', { site: { url: 'https://x.test/#top' } }],
+      ['an address with an empty fragment', { site: { url: 'https://x.test/docs#' } }],
+      ['an address with a backslash in its path', { site: { url: 'https://x.test/docs\\guides' } }],
+      ['an address with a backslash for its path', { site: { url: 'https://x.test\\docs' } }],
+      ['an address with a dot segment', { site: { url: 'https://x.test/docs/.' } }],
+      ['an address with a parent segment', { site: { url: 'https://x.test/docs/..' } }],
+      ['an address with a dot segment before trailing space', { site: { url: 'https://x.test/docs/. ' } }],
+      ['an address with an empty segment', { site: { url: 'https://x.test/docs//x' } }],
+      ['an address whose path starts with two slashes', { site: { url: 'https://x.test//docs' } }],
+      ['an address with an encoded path', { site: { url: 'https://x.test/my%20docs' } }],
+      ['an address with a space in its path', { site: { url: 'https://x.test/my docs' } }],
       ['an address that is not http', { site: { url: 'ftp://x.test' } }],
       ['an address without a scheme', { site: { url: 'x.test' } }],
+      ['an address without a host before its path', { site: { url: 'https:///x.test/docs' } }],
+      ['an address with a tab in its host', { site: { url: 'https://x\t.test/docs' } }],
+      ['an address naming a page', { site: { url: 'https://x.test/docs/index.html' } }],
+      ['an address naming a page in capitals, with a trailing slash', { site: { url: 'https://x.test/INDEX.HTM/ ' } }],
       ['a description that is not a string', { site: { description: 5 } }],
       ['a logo outside static', { brand: { logo: 'images/logo.png' } }],
       ['the static directory itself', { brand: { logo: 'static/' } }],
@@ -318,8 +338,9 @@ describe('apimatic.schema.json', () => {
 
         expect(schemaVerdict({ languages: { [language]: { publishing: { ...release, packageConfiguration } } } }).valid)
           .to.be.true;
-        expect(schemaVerdict({ languages: { [language]: { publishing: { ...release, packageConfiguration: {} } } } })
-          .valid).to.be.false;
+        expect(
+          schemaVerdict({ languages: { [language]: { publishing: { ...release, packageConfiguration: {} } } } }).valid
+        ).to.be.false;
       });
     }
 
@@ -328,7 +349,10 @@ describe('apimatic.schema.json', () => {
     const unknownKey: [string, object][] = [
       ['an entry', { csharp: { notes: 'x' } }],
       ['a publishing record', { csharp: { publishing: { future: 1 } } }],
-      ['a source', { csharp: { publishing: { source: { repositoryUrl: 'https://github.com/acme/calc', tag: 'v1' } } } }],
+      [
+        'a source',
+        { csharp: { publishing: { source: { repositoryUrl: 'https://github.com/acme/calc', tag: 'v1' } } } }
+      ],
       ['a release', { csharp: { publishing: { package: { version: '1.0.0', name: 'Acme.Calc' } } } }],
       [
         'package settings',
diff --git a/test/types/file/resource-input.test.ts b/test/types/file/resource-input.test.ts
new file mode 100644
index 000000000..590c99339
--- /dev/null
+++ b/test/types/file/resource-input.test.ts
@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { expect } from 'chai';
+import { FilePath } from '../../../src/types/file/filePath';
+import { createResourceInput } from '../../../src/types/file/resource-input';
+import { UrlPath } from '../../../src/types/file/urlPath';
+import { ProjectContext } from '../../../src/types/project-context';
+
+describe('createResourceInput', () => {
+  const sourceOf = (spec: unknown) => (spec as ProjectContext).sourceDirectory().toString();
+
+  it('takes the spec in the project at --input when neither --file nor --url is given', () => {
+    const spec = createResourceInput(undefined, undefined, 'project');
+
+    expect(spec).to.be.instanceOf(ProjectContext);
+    expect(sourceOf(spec)).to.equal(path.resolve('project', 'src'));
+  });
+
+  it('takes --file as a file on disk and --url as an address', () => {
+    expect(createResourceInput('specs/openapi.json', undefined, 'project')).to.be.instanceOf(FilePath);
+    expect(createResourceInput(undefined, 'https://example.org/openapi.json', 'project')).to.be.instanceOf(UrlPath);
+  });
+});
diff --git a/test/types/plugin-config-context.test.ts b/test/types/plugin-config-context.test.ts
index 7679a1b8e..4e9f7eb03 100644
--- a/test/types/plugin-config-context.test.ts
+++ b/test/types/plugin-config-context.test.ts
@@ -394,6 +394,91 @@ describe('PluginConfigContext', () => {
     });
   });
 
+  describe('addMetadataIfMissing', () => {
+    it('adds the plugin block, with a default licence, to a file that has none', async () => {
+      withConfig({ portal: {}, languages: { csharp: CSHARP_ENTRY } });
+
+      expect((await context.addMetadataIfMissing(METADATA)).isOk()).to.be.true;
+
+      expect(writtenDocument()).to.deep.equal({
+        portal: {},
+        languages: { csharp: CSHARP_ENTRY },
+        plugin: { ...METADATA, license: 'MIT' }
+      });
+    });
+
+    it('leaves a plugin block the file holds as it is, however little it says', async () => {
+      withFile('{"plugin":{"pluginName":"Ours"}}');
+
+      await context.addMetadataIfMissing(METADATA);
+
+      expect(written()).to.equal('{"plugin":{"pluginName":"Ours"}}');
+    });
+
+    it('adds the block beside a languages block it does not read', async () => {
+      withConfig({ languages: 'csharp' });
+
+      expect((await context.addMetadataIfMissing(METADATA)).isOk()).to.be.true;
+      expect(writtenDocument().plugin).to.include(METADATA);
+    });
+
+    const refusedBlocks: [string, unknown][] = [
+      ['that is not an object', 'acme'],
+      ['whose id the plugin commands refuse', { pluginId: 'Bad Id', pluginName: 'Bad', pluginVersion: '1.0.0' }]
+    ];
+
+    refusedBlocks.forEach(([shape, plugin]) => {
+      it(`leaves a plugin block ${shape} for the commands that read it to report`, async () => {
+        withConfig({ plugin });
+
+        expect((await context.addMetadataIfMissing(METADATA)).isOk()).to.be.true;
+        expect(writtenDocument().plugin).to.deep.equal(plugin);
+      });
+    });
+  });
+
+  describe('languagesMissing', () => {
+    const files: [string, object, boolean][] = [
+      ['has no languages block', { portal: {} }, true],
+      ['names no language in its block', { languages: {} }, true],
+      ['names a language', { languages: { python: {} } }, false],
+      ['has a languages block that is not an object, which the build reports', { languages: 'csharp' }, false]
+    ];
+
+    files.forEach(([file, config, missing]) => {
+      it(`is ${missing} when the file ${file}`, async () => {
+        withConfig(config);
+
+        expect(await context.languagesMissing()).to.equal(missing);
+      });
+    });
+  });
+
+  describe('addLanguagesIfMissing', () => {
+    it('records the languages in a file that names none', async () => {
+      withConfig({ portal: {} });
+
+      expect((await context.addLanguagesIfMissing([Language.CSHARP, Language.TYPESCRIPT])).isOk()).to.be.true;
+
+      expect(writtenDocument()).to.deep.equal({ portal: {}, languages: { csharp: {}, typescript: {} } });
+    });
+
+    it('leaves a file that names a language as it is', async () => {
+      withFile('{"languages":{"python":{}}}');
+
+      await context.addLanguagesIfMissing([Language.CSHARP]);
+
+      expect(written()).to.equal('{"languages":{"python":{}}}');
+    });
+
+    it('records them beside a plugin block it does not read', async () => {
+      withConfig({ plugin: { pluginId: 'Bad Id' } });
+
+      expect((await context.addLanguagesIfMissing([Language.CSHARP])).isOk()).to.be.true;
+      expect(writtenDocument().languages).to.deep.equal({ csharp: {} });
+    });
+  });
+
   describe('the state a write hands back', () => {
     it('reports the metadata it just wrote', async () => {
       const state = (await context.upsertMetadata(METADATA))._unsafeUnwrap();
diff --git a/test/types/portal-source-context.test.ts b/test/types/portal-source-context.test.ts
index f30c1c288..e1192651b 100644
--- a/test/types/portal-source-context.test.ts
+++ b/test/types/portal-source-context.test.ts
@@ -379,6 +379,23 @@ describe('PortalSourceContext', () => {
     });
   });
 
+  describe('resolveSpecs', () => {
+    const resolveSpecs = () => new PortalSourceContext(new DirectoryPath(root)).resolveSpecs();
+
+    it('answers with the specs a build would read, without an apimatic.json', async () => {
+      write('spec/api.json', OPENAPI);
+      write('spec/old.json', JSON.stringify({ swagger: '2.0', info: {}, paths: {} }));
+
+      expect((await resolveSpecs())._unsafeUnwrap().map((spec) => spec.slug)).to.deep.equal(['api']);
+    });
+
+    it('refuses a spec directory with no OpenAPI 3.x document, as resolve does', async () => {
+      write('spec/petstore.json', JSON.stringify({ swagger: '2.0', info: {}, paths: {} }));
+
+      expect((await resolveSpecs())._unsafeUnwrapErr().kind).to.equal('noOpenApiSpec');
+    });
+  });
+
   describe('spec discovery', () => {
     beforeEach(() => writeConfig({ site: { name: 'Calc' } }));
 
@@ -777,34 +794,55 @@ describe('PortalSourceContext', () => {
         throw new Error(`expected a 'reservedAddresses' problem, got '${problem.kind}'`);
       }
       return problem.pages
-        .map(({ file, address, section }) => `${file.relativeTo(new DirectoryPath(root))} ${address} ${section.folder}`)
+        .map(
+          ({ file, address, keptFor }) => `${file.relativeTo(new DirectoryPath(root))} ${address} ${keptFor.address}`
+        )
         .sort();
     };
 
-    // Three of them share /sdks as well, which is not said again.
-    it('refuses every page the SDK pages would share an address with, naming each', async () => {
-      write('content/sdks.md', page('Mine'));
-      write('content/sdks/setup.mdx', page('Setup'));
-      write('content/(intro)/sdks.md', page('Grouped'));
-      write('content/sdks/index.md', page('Index'));
-
-      expect(reserved((await resolve())._unsafeUnwrapErr())).to.deep.equal([
-        'content/(intro)/sdks.md /sdks sdks',
-        'content/sdks.md /sdks sdks',
-        'content/sdks/index.md /sdks sdks',
-        'content/sdks/setup.mdx /sdks/setup sdks'
-      ]);
-    });
-
-    // Reserved with or without a plugin block, so adding one never refuses a page that built.
-    it('refuses a page at the context plugin address although there is no plugin block', async () => {
-      write('content/context-plugin.md', page('Mine'));
-      write('content/context-plugin/faq.md', page('FAQ'));
-
-      expect(reserved((await resolve())._unsafeUnwrapErr())).to.deep.equal([
-        'content/context-plugin.md /context-plugin context-plugin',
-        'content/context-plugin/faq.md /context-plugin/faq context-plugin'
-      ]);
+    (
+      [
+        [
+          // Three of them share /sdks as well, which is not said again.
+          'refuses every page the SDK pages would share an address with, naming each',
+          ['content/sdks.md', 'content/sdks/setup.mdx', 'content/(intro)/sdks.md', 'content/sdks/index.md'],
+          [
+            'content/(intro)/sdks.md /sdks /sdks',
+            'content/sdks.md /sdks /sdks',
+            'content/sdks/index.md /sdks /sdks',
+            'content/sdks/setup.mdx /sdks/setup /sdks'
+          ]
+        ],
+        [
+          // Reserved with or without a plugin block, so adding one never refuses a page that built.
+          'refuses a page at the context plugin address although there is no plugin block',
+          ['content/context-plugin.md', 'content/context-plugin/faq.md'],
+          [
+            'content/context-plugin.md /context-plugin /context-plugin',
+            'content/context-plugin/faq.md /context-plugin/faq /context-plugin'
+          ]
+        ],
+        [
+          // The template's route wins over the page, which would build, sit in the sidebar and never be shown.
+          'refuses a page at the OAuth callback address, and only there',
+          [
+            'content/oauth/callback.md',
+            'content/(auth)/oauth/callback/index.mdx',
+            'content/oauth/index.md',
+            'content/oauth/callback/setup.md'
+          ],
+          [
+            'content/(auth)/oauth/callback/index.mdx /oauth/callback /oauth/callback',
+            'content/oauth/callback.md /oauth/callback /oauth/callback'
+          ]
+        ]
+      ] as const
+    ).forEach(([name, files, refused]) => {
+      it(name, async () => {
+        files.forEach((file) => write(file, page('Page')));
+
+        expect(reserved((await resolve())._unsafeUnwrapErr())).to.deep.equal(refused);
+      });
     });
 
     // A group folder's name is not part of the address; only the folder it groups is.
@@ -1964,18 +2002,24 @@ describe('PortalSourceContext', () => {
       });
     });
 
-    // What a build downloaded from the platform arrives as: `spec/` filled, and nothing else.
+    // What a build downloaded from the platform arrives as: `spec/` filled, beside its own `apimatic.json`.
     describe('adopt', () => {
-      const writeSourceSpec = (name: string, info: Record<string, unknown>): FilePath => {
-        write(path.join('project', 'src', 'spec', name), JSON.stringify({ openapi: '3.0.0', info, paths: {} }));
-        return new FilePath(source.join('spec'), new FileName(name));
+      const inSource = (relative: string) => path.join('project', 'src', relative);
+      const writeSourceSpec = (name: string, document: Record<string, unknown>) =>
+        write(inSource(path.join('spec', name)), JSON.stringify({ openapi: '3.0.0', paths: {}, ...document }));
+      const writeSourceConfig = (config: object) => write(inSource('apimatic.json'), JSON.stringify(config));
+      const adopt = async () => {
+        const context = new PortalSourceContext(source);
+        const [first] = (await context.resolveSpecs())._unsafeUnwrap();
+        return (await context.adopt(first))._unsafeUnwrap();
       };
+      const portalBlock = () => JSON.parse(read('apimatic.json')).portal;
 
       it('writes the tree around a specification already in the source directory', async () => {
-        const specPath = writeSourceSpec('petstore.json', { title: 'Petstore', version: '1' });
+        writeSourceSpec('petstore.json', { info: { title: 'Petstore', version: '1' } });
+        writeSourceConfig({ languages: LANGUAGES });
 
-        (await new PortalSourceContext(source).adopt(specPath, APIMATIC_SCHEMA_URL))._unsafeUnwrap();
-        addLanguages();
+        await adopt();
 
         const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap();
         expect(resolved.config.siteTitle()).to.equal('Petstore');
@@ -1983,24 +2027,134 @@ describe('PortalSourceContext', () => {
         expect(fs.readdirSync(path.join(source.toString(), 'spec'))).to.deep.equal(['petstore.json']);
       });
 
-      it('finds the document the portal speaks for, sorted as every other list sorts it', async () => {
-        writeSourceSpec('zebra.yaml', { title: 'Zebra', version: '1' });
-        writeSourceSpec('alpha.json', { title: 'Alpha', version: '1' });
-        write(path.join('project', 'src', 'spec', 'README.md'), '# not a specification');
+      it('leaves the apimatic.json and content/ the project carries as they are', async () => {
+        writeSourceSpec('petstore.json', { info: { title: 'Petstore', version: '1' } });
+        const config = JSON.stringify({ portal: { site: { name: 'My Company Docs', description: 'Ours' } } });
+        write(inSource('apimatic.json'), config);
+        write(inSource('content/index.md'), page('Our own welcome'));
+        write(inSource('content/nav.json'), JSON.stringify({ pages: ['index', 'guides'] }));
+
+        await adopt();
+
+        expect(read('apimatic.json')).to.equal(config);
+        expect(read('content/index.md')).to.equal(page('Our own welcome'));
+        expect(read('content/nav.json')).to.equal(JSON.stringify({ pages: ['index', 'guides'] }));
+      });
+
+      it('adds a site to a portal block that has none, and keeps the rest of the block', async () => {
+        writeSourceSpec('petstore.json', { info: { title: 'Petstore', version: '1', description: 'All the pets.' } });
+        writeSourceConfig({ portal: { ai: { pageActions: false } } });
+
+        await adopt();
+
+        expect(portalBlock()).to.deep.equal({
+          site: { name: 'Petstore', description: 'All the pets.' },
+          ai: { pageActions: false }
+        });
+      });
+
+      it('adds a portal block holding only the site to a file that has none', async () => {
+        writeSourceSpec('petstore.json', { info: { title: 'Petstore', version: '1' } });
+        writeSourceConfig({ languages: LANGUAGES });
+
+        await adopt();
+
+        expect(portalBlock()).to.deep.equal({ site: { name: 'Petstore' } });
+      });
+
+      it('names a site that has no name, and keeps the rest of it where it was', async () => {
+        writeSourceSpec('petstore.json', { info: { title: 'Petstore', version: '1', description: 'All the pets.' } });
+        writeSourceConfig({ portal: { ai: { pageActions: false }, site: { url: 'https://docs.example.com' } } });
+
+        await adopt();
+
+        expect(portalBlock().site).to.deep.equal({ name: 'Petstore', url: 'https://docs.example.com' });
+        expect(Object.keys(portalBlock())).to.deep.equal(['ai', 'site']);
+      });
+
+      const unreadBlocks: [string, unknown][] = [
+        ['a portal block', 'petstore'],
+        ['a site', { site: 'petstore' }]
+      ];
+
+      unreadBlocks.forEach(([what, portal]) => {
+        it(`leaves ${what} that is not an object for the build to report`, async () => {
+          writeSourceSpec('petstore.json', { info: { title: 'Petstore', version: '1' } });
+          writeSourceConfig({ portal });
+
+          await adopt();
+
+          expect(portalBlock()).to.deep.equal(portal);
+        });
+      });
+
+      it('writes the welcome page and the page order when there is no content/, named as the file names the site', async () => {
+        writeSourceSpec('petstore.json', { info: { title: 'Petstore', version: '1' } });
+        writeSourceConfig({ portal: { site: { name: 'My Company Docs' } } });
 
-        const found = await new PortalSourceContext(source).primarySpec();
+        await adopt();
 
-        expect(found?.name().toString()).to.equal('alpha.json');
+        expect(read('content/index.md')).to.contain('Welcome to the My Company Docs documentation.');
+        expect(fs.readdirSync(path.join(source.toString(), 'content')).sort()).to.deep.equal(['index.md', 'nav.json']);
       });
 
-      it('finds nothing in a project with no source directory', async () => {
-        expect(await new PortalSourceContext(source).primarySpec()).to.be.null;
+      // The spec the build reads first, which is not always the first file in `spec/`.
+      const layouts: [string, [string, Record<string, unknown>][], string][] = [
+        [
+          'shared schemas beside the spec',
+          [
+            ['components.yaml', { openapi: undefined, components: { schemas: {} } }],
+            ['openapi.yaml', { info: { title: 'Pets', version: '1' } }]
+          ],
+          'Pets'
+        ],
+        [
+          'the build settings beside the spec',
+          [
+            ['APIMATIC-META.json', { openapi: undefined, CodeGenSettings: {} }],
+            ['petstore.json', { info: { title: 'Petstore', version: '1' } }]
+          ],
+          'Petstore'
+        ],
+        [
+          'a Swagger 2.0 spec before its OpenAPI 3 conversion',
+          [
+            ['a-legacy.json', { openapi: undefined, swagger: '2.0', info: { title: 'Legacy Swagger', version: '1' } }],
+            ['b-current.json', { info: { title: 'Current API', version: '1' } }]
+          ],
+          'Current API'
+        ]
+      ];
+
+      layouts.forEach(([layout, specs, name]) => {
+        it(`names the portal as the build would, for ${layout}`, async () => {
+          specs.forEach(([fileName, document]) => writeSourceSpec(fileName, document));
+          writeSourceConfig({ portal: {}, languages: LANGUAGES });
+
+          await adopt();
+
+          expect(portalBlock().site.name).to.equal(name);
+          const resolved = (await new PortalSourceContext(source).resolve())._unsafeUnwrap();
+          expect(resolved.config.siteTitle()).to.equal(name);
+        });
       });
 
-      it('finds nothing when the specification directory holds no document', async () => {
-        write(path.join('project', 'src', 'spec', 'notes.txt'), 'nothing here');
+      const unnamedPortals: [string, object][] = [
+        ['no site', {}],
+        ['the empty site the template ships', { site: {} }]
+      ];
 
-        expect(await new PortalSourceContext(source).primarySpec()).to.be.null;
+      unnamedPortals.forEach(([shape, portal]) => {
+        it(`names a portal of several specs with ${shape} after the first, since the build then needs the name written`, async () => {
+          writeSourceSpec('alpha.json', { info: { title: 'Alpha', version: '1' } });
+          writeSourceSpec('zebra.yaml', { info: { title: 'Zebra', version: '1' } });
+          writeSourceConfig({ portal, languages: LANGUAGES });
+
+          await adopt();
+
+          expect(portalBlock().site.name).to.equal('Alpha');
+          expect((await new PortalSourceContext(source).resolve()).isOk()).to.be.true;
+        });
       });
     });
   });
diff --git a/test/types/portal/config/site-address.test.ts b/test/types/portal/config/site-address.test.ts
new file mode 100644
index 000000000..a0979fe69
--- /dev/null
+++ b/test/types/portal/config/site-address.test.ts
@@ -0,0 +1,117 @@
+import { expect } from 'chai';
+import { SiteAddress } from '../../../../src/types/portal/config/site-address';
+
+describe('SiteAddress', () => {
+  const SETTING = 'portal.site.url';
+
+  const address = (value: string) => SiteAddress.parse(value, SETTING)._unsafeUnwrap();
+  const refusal = (value: unknown) => SiteAddress.parse(value, SETTING)._unsafeUnwrapErr();
+
+  describe('parse', () => {
+    it('reads an address at the root of its host', () => {
+      for (const value of ['https://docs.example.com', 'https://docs.example.com/', ' http://docs.example.com:8443 ']) {
+        expect(address(value).path(), value).to.equal('/');
+        expect(address(value).hasPath(), value).to.be.false;
+      }
+      expect(address('https://Docs.Example.com/').toString()).to.equal('https://docs.example.com');
+      expect(address('https://docs.example.com/').addressOf('/sitemap.xml')).to.equal(
+        'https://docs.example.com/sitemap.xml'
+      );
+    });
+
+    it('reads the path an address carries, keeping its case and dropping one trailing slash', () => {
+      const cases: [string, string, string][] = [
+        ['https://acme.github.io/docs', 'https://acme.github.io/docs', '/docs/'],
+        ['https://acme.github.io/docs/', 'https://acme.github.io/docs', '/docs/'],
+        [
+          'https://example.com/Docs/v2.1/api_ref~x-y',
+          'https://example.com/Docs/v2.1/api_ref~x-y',
+          '/Docs/v2.1/api_ref~x-y/'
+        ],
+        ['https://example.com/...', 'https://example.com/...', '/.../'],
+        ['https://example.com/docs.htmlx', 'https://example.com/docs.htmlx', '/docs.htmlx/']
+      ];
+      for (const [value, site, path] of cases) {
+        expect(address(value).toString(), value).to.equal(site);
+        expect(address(value).path(), value).to.equal(path);
+        expect(address(value).hasPath(), value).to.be.true;
+      }
+      expect(address('https://acme.github.io/docs/').addressOf('/')).to.equal('https://acme.github.io/docs/');
+      expect(address('https://acme.github.io/docs').addressOf('/sitemap.xml')).to.equal(
+        'https://acme.github.io/docs/sitemap.xml'
+      );
+    });
+
+    it('refuses what is not a web address', () => {
+      for (const value of [
+        'ftp://x.test',
+        'x.test',
+        'https:x.test',
+        'https://',
+        'https:///x.test/docs',
+        'https://x\t.test',
+        '',
+        7
+      ]) {
+        expect(refusal(value), String(value)).to.deep.equal([
+          `'${SETTING}' must be the address the portal is hosted at, for example 'https://docs.example.com' or 'https://example.com/docs'.`
+        ]);
+      }
+    });
+
+    // As written: the URL parser would read the backslash as a slash and drop the empty query.
+    it('refuses a query, a fragment or a backslash, naming it', () => {
+      const cases: [string, string][] = [
+        ['https://x.test/docs?', '?'],
+        ['https://x.test/?a=1', '?'],
+        ['https://x.test/docs#', '#'],
+        ['https://x.test/docs\\guides', '\\']
+      ];
+      for (const [value, character] of cases) {
+        expect(refusal(value), value).to.deep.equal([
+          `'${SETTING}' cannot contain '${character}'. Give the address the portal is hosted at, for example 'https://example.com/docs'.`
+        ]);
+      }
+    });
+
+    it('refuses an empty part in the path, beyond one trailing slash', () => {
+      for (const value of [
+        'https://x.test//docs',
+        'https://x.test/docs//x',
+        'https://x.test/docs//',
+        'https://x.test//'
+      ]) {
+        expect(refusal(value), value).to.deep.equal([`'${SETTING}' has an empty part ('//') in its path.`]);
+      }
+    });
+
+    it('refuses a part of the path that would be spelled differently once encoded or resolved, naming it', () => {
+      const cases: [string, string][] = [
+        ['https://x.test/docs/.', '.'],
+        ['https://x.test/docs/../x', '..'],
+        ['https://x.test/my%20docs', 'my%20docs'],
+        ['https://x.test/my docs', 'my docs'],
+        ['https://x.test/bücher', 'bücher']
+      ];
+      for (const [value, segment] of cases) {
+        expect(refusal(value), value).to.deep.equal([
+          `'${SETTING}' has '${segment}' in its path. Each part between '/'s can use only letters, digits, '.', '_', '~' and '-', and cannot be '.' or '..'.`
+        ]);
+      }
+    });
+
+    // A home page's address pasted whole would put every asset under `/docs/index.html/`.
+    it('refuses an address that names a page, naming its last part', () => {
+      const cases: [string, string][] = [
+        ['https://x.test/docs/index.html', 'index.html'],
+        ['https://x.test/INDEX.HTM/', 'INDEX.HTM'],
+        ['https://x.test/docs/home.htm', 'home.htm']
+      ];
+      for (const [value, page] of cases) {
+        expect(refusal(value), value).to.deep.equal([
+          `'${SETTING}' ends in '${page}', which names a page. Give the address the portal is hosted at, for example 'https://example.com/docs'.`
+        ]);
+      }
+    });
+  });
+});
diff --git a/test/types/portal/page.test.ts b/test/types/portal/page.test.ts
index fd9775718..a07ef80d7 100644
--- a/test/types/portal/page.test.ts
+++ b/test/types/portal/page.test.ts
@@ -119,15 +119,24 @@ describe('parsePage', () => {
       expect(await images('<Callout>\n\n![a](/a.png)\n', 'page.mdx')).to.deep.equal([]);
     });
 
-    // Fumadocs imports only inline images; a reference, an address and a folder are left to the browser.
+    // An address and a folder are left to the browser, and so is a reference with no definition, which is text.
     it('leaves out what the build does not import', async () => {
       const markdown =
-        '![a][logo]\n\n[logo]: /logo.png\n\n![b](https://example.com/b.png)\n\n![c](//cdn.example.com/c.png)\n\n' +
-        '![d](data:image/png;base64,AA)\n\n![e](/images/)\n\n![f]()\n';
+        '![a][nowhere]\n\n![b](https://example.com/b.png)\n\n![c](//cdn.example.com/c.png)\n\n' +
+        '![d](data:image/png;base64,AA)\n\n![e](/images/)\n\n![f]()\n\n![g][remote]\n\n[remote]: https://example.com/g.png\n';
 
       expect(await images(markdown)).to.deep.equal([]);
     });
 
+    // The template writes each as an inline image before the build imports it.
+    it('reads a reference-style image from the first definition of its label, at the reference', async () => {
+      const markdown = 'Intro.\n\n![a][Logo]\n\n[logo]: /images/logo.png "Logo"\n[logo]: /images/other.png\n';
+
+      expect(await images(markdown)).to.deep.equal([
+        { url: '/images/logo.png', line: 3, from: 'static', path: 'images/logo.png' }
+      ]);
+    });
+
     it('reads a .md page as Markdown, where a tag is HTML and an image after it still counts', async () => {
       const found = await images('<div>\n\n![a](/a.png)\n\n</div>\n\nA { brace }\n');
 
diff --git a/test/types/portal/portal-config.test.ts b/test/types/portal/portal-config.test.ts
index fee70e98d..6f0e692f3 100644
--- a/test/types/portal/portal-config.test.ts
+++ b/test/types/portal/portal-config.test.ts
@@ -89,7 +89,7 @@ describe('PortalConfig', () => {
     it('reports them alongside every invalid setting, so one edit fixes the file', () => {
       const errors = errorsOf({
         theme: {},
-        site: { name: '', url: 'https://x.test/docs' },
+        site: { name: '', url: 'https://x.test/?a=1' },
         brand: { colorMode: 'sepia' },
         ai: { pageActions: 'no' }
       });
@@ -138,25 +138,27 @@ describe('PortalConfig', () => {
       expect(errorsOf({ site: { description: 5 } })).to.deep.equal(["'portal.site.description' must be a string."]);
     });
 
-    it('keeps only the origin of the address, dropping a trailing slash and keeping a port', () => {
+    it('keeps the path of the address, dropping a trailing slash and keeping a port', () => {
       expect(config({ site: { url: 'https://docs.example.com/' } }).identity().siteUrl).to.equal(
         'https://docs.example.com'
       );
       expect(config({ site: { url: 'https://docs.example.com:8443' } }).identity().siteUrl).to.equal(
         'https://docs.example.com:8443'
       );
+      expect(config({ site: { url: 'HTTPS://Example.com/Docs/v2/' } }).identity().siteUrl).to.equal(
+        'https://example.com/Docs/v2'
+      );
     });
 
-    it('refuses an address carrying a path, query or fragment, or one that is not http', () => {
-      for (const url of [
-        'https://x.test/docs',
-        'https://x.test/?a=1',
-        'https://x.test/#top',
-        'ftp://x.test',
-        'x.test',
-        'https:x.test',
-        ''
-      ]) {
+    it('hands over the address it parsed, or none without one', () => {
+      const address = config({ site: { url: 'https://acme.github.io/docs/' } }).siteAddress();
+
+      expect(address?.path()).to.equal('/docs/');
+      expect(config({}).siteAddress()).to.be.null;
+    });
+
+    it('refuses an address carrying a query or fragment, or one that is not http', () => {
+      for (const url of ['https://x.test/?a=1', 'https://x.test/#top', 'ftp://x.test', 'x.test', 'https:x.test', '']) {
         expect(errorsOf({ site: { url } }), url).to.have.lengthOf(1);
       }
     });
@@ -169,8 +171,8 @@ describe('PortalConfig', () => {
           .brandSettings()
           .logoImages();
 
-        expect(logo?.light().siteUrl()).to.equal('/images/logo.png');
-        expect(logo?.dark().siteUrl()).to.equal('/images/logo.png');
+        expect(logo?.light().portalPath()).to.equal('/images/logo.png');
+        expect(logo?.dark().portalPath()).to.equal('/images/logo.png');
       });
 
       it('takes a path per mode', () => {
@@ -178,8 +180,8 @@ describe('PortalConfig', () => {
           .brandSettings()
           .logoImages();
 
-        expect(logo?.light().siteUrl()).to.equal('/light.svg');
-        expect(logo?.dark().siteUrl()).to.equal('/dark.svg');
+        expect(logo?.light().portalPath()).to.equal('/light.svg');
+        expect(logo?.dark().portalPath()).to.equal('/dark.svg');
       });
 
       it('needs both modes once it names either', () => {
@@ -205,7 +207,7 @@ describe('PortalConfig', () => {
           .brandSettings()
           .logoImages();
 
-        expect(logo?.light().siteUrl()).to.equal('/images/logo.png');
+        expect(logo?.light().portalPath()).to.equal('/images/logo.png');
         expect(logo?.light().resolveIn(source).relativeTo(source)).to.equal('static/images/logo.png');
       });
 
@@ -228,7 +230,7 @@ describe('PortalConfig', () => {
           .brandSettings()
           .logoImages();
 
-        expect(logo?.light().siteUrl()).to.equal('/my%20logo%20%231%3F.png');
+        expect(logo?.light().portalPath()).to.equal('/my%20logo%20%231%3F.png');
         expect(logo?.light().resolveIn(source).relativeTo(source)).to.equal('static/my logo #1?.png');
       });
     });
@@ -239,13 +241,13 @@ describe('PortalConfig', () => {
           brand: { logo: { light: 'static/light.svg', dark: 'static/dark.svg' } }
         }).brandSettings();
 
-        expect(brand.faviconImage()?.siteUrl()).to.equal('/light.svg');
+        expect(brand.faviconImage()?.portalPath()).to.equal('/light.svg');
       });
 
       it('is the file the block names when it names one', () => {
         const brand = config({ brand: { logo: 'static/logo.svg', favicon: 'static/favicon.ico' } }).brandSettings();
 
-        expect(brand.faviconImage()?.siteUrl()).to.equal('/favicon.ico');
+        expect(brand.faviconImage()?.portalPath()).to.equal('/favicon.ico');
       });
 
       it('refuses a path outside static/', () => {
diff --git a/test/types/project-context.test.ts b/test/types/project-context.test.ts
index cdcda2db1..016c78b7a 100644
--- a/test/types/project-context.test.ts
+++ b/test/types/project-context.test.ts
@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import AdmZip from 'adm-zip';
 import { expect } from 'chai';
 import sinon from 'sinon';
 import { DirectoryPath } from '../../src/types/file/directoryPath';
@@ -98,6 +99,70 @@ describe('ProjectContext', () => {
       expect(fs.existsSync(inProject('temp', 'src', 'spec', 'openapi.json'))).to.be.true;
       expect(fs.existsSync(inProject('temp', 'src', 'package-settings', 'package.json'))).to.be.true;
     });
+
+    it('zips all of spec/ for validation, so a spec split across files keeps the ones it references', async () => {
+      write('src/spec/openapi.yaml', 'openapi: 3.0.3');
+      write('src/spec/schemas/pet.yaml', 'type: object');
+      write('src/APIMATIC-BUILD.json', '{}');
+      fs.mkdirSync(inProject('temp'));
+
+      const zip = (await project().specZip(new DirectoryPath(inProject('temp'))))._unsafeUnwrap();
+
+      const entries = new AdmZip(zip.toString()).getEntries().map((entry) => entry.entryName);
+      expect(entries).to.have.members(['openapi.yaml', 'schemas/pet.yaml']);
+    });
+
+    it('zips nothing when spec/ is empty, and names the directory it looked in', async () => {
+      fs.mkdirSync(inProject('src', 'spec'), { recursive: true });
+      fs.mkdirSync(inProject('temp'));
+
+      const problem = (await project().specZip(new DirectoryPath(inProject('temp'))))._unsafeUnwrapErr();
+
+      expect(problem.kind).to.equal('noSpec');
+      expect(problem.kind === 'noSpec' && problem.specDirectory.toString()).to.equal(inProject('src', 'spec'));
+      expect(fs.readdirSync(inProject('temp'))).to.be.empty;
+    });
+
+    it('zips nothing when spec/ cannot be read, and says why', async () => {
+      write('src/spec', 'a file where the directory should be');
+      fs.mkdirSync(inProject('temp'));
+
+      const problem = (await project().specZip(new DirectoryPath(inProject('temp'))))._unsafeUnwrapErr();
+
+      expect(problem.kind).to.equal('unreadable');
+      expect(problem.kind === 'unreadable' && problem.specDirectory.toString()).to.equal(inProject('src', 'spec'));
+      expect(problem.kind === 'unreadable' && problem.reason).to.contain('ENOTDIR');
+      expect(fs.readdirSync(inProject('temp'))).to.be.empty;
+    });
+
+    it('zips nothing when spec/ holds symlinks at any depth, and names every one', async () => {
+      write('src/spec/openapi.yaml', 'openapi: 3.0.3');
+      write('shared/pet.yaml', 'type: object');
+      fs.mkdirSync(inProject('src', 'spec', 'schemas'));
+      const symlinks = [inProject('src', 'spec', 'common'), inProject('src', 'spec', 'schemas', 'shared')];
+      for (const symlink of symlinks) {
+        fs.symlinkSync(inProject('shared'), symlink, process.platform === 'win32' ? 'junction' : 'dir');
+      }
+      fs.mkdirSync(inProject('temp'));
+
+      const problem = (await project().specZip(new DirectoryPath(inProject('temp'))))._unsafeUnwrapErr();
+
+      expect(problem.kind).to.equal('symlinks');
+      expect(problem.kind === 'symlinks' && problem.symlinks.map((symlink) => symlink.toString())).to.have.members(
+        symlinks
+      );
+      expect(fs.readdirSync(inProject('temp'))).to.be.empty;
+    });
+
+    it('reports a spec/ it could not zip, naming the directory and why', async () => {
+      write('src/spec/openapi.yaml', 'openapi: 3.0.3');
+
+      const problem = (await project().specZip(new DirectoryPath(inProject('missing-temp'))))._unsafeUnwrapErr();
+
+      expect(problem.kind).to.equal('zipFailed');
+      expect(problem.kind === 'zipFailed' && problem.specDirectory.toString()).to.equal(inProject('src', 'spec'));
+      expect(problem.kind === 'zipFailed' && problem.reason).to.contain('ENOENT');
+    });
   });
 
   describe('versionToBuild', () => {
diff --git a/test/types/resource-context.test.ts b/test/types/resource-context.test.ts
new file mode 100644
index 000000000..47e9353fc
--- /dev/null
+++ b/test/types/resource-context.test.ts
@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import nock from 'nock';
+import { expect } from 'chai';
+import { DirectoryPath } from '../../src/types/file/directoryPath';
+import { FileName } from '../../src/types/file/fileName';
+import { FilePath } from '../../src/types/file/filePath';
+import { ResourceInput } from '../../src/types/file/resource-input';
+import { UrlPath } from '../../src/types/file/urlPath';
+import { ProjectContext } from '../../src/types/project-context';
+import { ResourceContext } from '../../src/types/resource-context';
+
+const HOST = 'http://specs.test';
+
+describe('ResourceContext', () => {
+  let root: string;
+  let tempDirectory: DirectoryPath;
+
+  const contentsOf = (file: FilePath) => fs.readFileSync(file.toString(), 'utf8');
+  const resolve = (input: ResourceInput) => ResourceContext.resolveTo(input, tempDirectory);
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'resource-context-'));
+    tempDirectory = new DirectoryPath(root).join('temp');
+    nock.disableNetConnect();
+  });
+
+  afterEach(() => {
+    nock.cleanAll();
+    nock.enableNetConnect();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('tells a file, a URL and a project apart', async () => {
+    fs.writeFileSync(path.join(root, 'openapi.json'), '{}');
+    fs.mkdirSync(path.join(root, 'src', 'spec'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'src', 'spec', 'openapi.json'), '{}');
+    nock(HOST).get('/openapi.json').reply(200, '{}');
+    const kindOf = async (input: ResourceInput) => (await resolve(input))._unsafeUnwrap().kind();
+
+    expect(await kindOf(new FilePath(new DirectoryPath(root), new FileName('openapi.json')))).to.equal('file');
+    expect(await kindOf(new UrlPath(`${HOST}/openapi.json`))).to.equal('url');
+    expect(await kindOf(ProjectContext.in(new DirectoryPath(root)))).to.equal('project');
+  });
+
+  it('copies a local file under its own name', async () => {
+    fs.writeFileSync(path.join(root, 'openapi.yaml'), 'openapi: 3.0.3');
+    const file = new FilePath(new DirectoryPath(root), new FileName('openapi.yaml'));
+
+    const copy = (await resolve(file))._unsafeUnwrap().file();
+
+    expect(copy.isEqual(file)).to.be.false;
+    expect(copy.name().toString()).to.equal('openapi.yaml');
+    expect(contentsOf(copy)).to.equal('openapi: 3.0.3');
+  });
+
+  it('reports a local file it cannot read as the file the user gave', async () => {
+    const missing = new FilePath(new DirectoryPath(root), new FileName('missing.json'));
+
+    const resolved = await resolve(missing);
+
+    expect(resolved._unsafeUnwrapErr()).to.deep.equal({ kind: 'fileUnreadable', file: missing });
+  });
+
+  it('names a download by the file the server sends', async () => {
+    nock(HOST)
+      .get('/download')
+      .query({ id: '1' })
+      .reply(200, 'openapi: 3.0.3', { 'Content-Disposition': 'attachment; filename="petstore.yaml"' });
+
+    const file = (await resolve(new UrlPath(`${HOST}/download?id=1`)))._unsafeUnwrap().file();
+
+    expect(file.name().toString()).to.equal('petstore.yaml');
+    expect(contentsOf(file)).to.equal('openapi: 3.0.3');
+  });
+
+  it('keeps a download in the temporary directory whatever path its name carries', async () => {
+    nock(HOST)
+      .get('/download')
+      .reply(200, '{}', { 'Content-Disposition': 'attachment; filename="x/../../../escaped.json"' });
+    nock(HOST).get('/x%2F..%2F..%2F..%2Fescaped.json').reply(200, '{}');
+    nock(HOST).get('/nested').reply(200, '{}', { 'Content-Disposition': 'attachment; filename="specs/openapi.json"' });
+
+    for (const address of ['/download', '/x%2F..%2F..%2F..%2Fescaped.json', '/nested']) {
+      const file = (await resolve(new UrlPath(`${HOST}${address}`)))._unsafeUnwrap().file();
+
+      expect(path.dirname(file.toString())).to.equal(tempDirectory.toString());
+    }
+  });
+
+  it('names a download the server does not name by its address, without the query', async () => {
+    nock(HOST).get('/v1/openapi.json').query({ token: 'abc' }).reply(200, '{}');
+
+    const url = new UrlPath(`${HOST}/v1/openapi.json?token=abc`);
+    const file = (await resolve(url))._unsafeUnwrap().file();
+
+    expect(file.name().toString()).to.equal('openapi.json');
+  });
+
+  it('reports a download that failed with the address it was fetched from', async () => {
+    nock(HOST).get('/openapi.json').reply(404);
+    const url = new UrlPath(`${HOST}/openapi.json`);
+
+    const problem = (await resolve(url))._unsafeUnwrapErr();
+
+    expect(problem.kind).to.equal('downloadFailed');
+    expect(problem.kind === 'downloadFailed' && problem.url).to.equal(url);
+  });
+});