[waseem196]

Summary

Generated portals can now offer an Ask AI chat that answers questions from the portal's own pages. It is opt-in: a portal turns it on with a new portal.ai.copilot block in src/apimatic.json. A portal without that block builds exactly as before, and an e2e test checks that it doesn't download any chat code.

This PR adds three things:

1. The chat in the portal template. It uses Fumadocs' @fumadocs/ai-chat panel, sits behind an "Ask AI" button and is answered by an external Ask AI service. The portal itself stays static.
2. A copy of the pages published with the portal. apimatic portal generate now writes the pages' Markdown into <portal>/__copilot/ so the Ask AI service can fetch them from the deployed site.
3. A new apimatic portal copilot sync command. It pushes a generated portal's pages straight to the Ask AI service. Use it when the service can't reach the deployed portal, or when you want to update the chat right away.

Configuration

// src/apimatic.json
{
  "portal": {
    "ai": {
      "copilot": {
        "key": "pk_…",                        // public key, bound to this portal and its allowed origins
        "apiUrl": "https://ask.example.com",  // the Ask AI service; http:// is accepted only for localhost
        "suggestions": ["How do I authenticate?"] // optional, up to 3, each at most 120 characters
      }
    }
  }
}

apimatic.schema.json describes the same block. apiUrl is required for now because there is no hosted service yet. Once there is one, it should become a default that this setting overrides (there is a comment about this in copilot-config.ts).

How it works

portal generate ──► build ──► llms.txt + <page>.md files
                                  │
                                  ▼
                       GeneratedPortalContext.bundle()
                                  │
                ┌─────────────────┴──────────────────┐
                ▼                                    ▼
  written to <portal>/__copilot/          portal copilot sync
  bundle.json + build.json               POST {apiUrl}/v1/ingest (gzip)
  (deployed, so the service              then polls GET /v1/ingest/{versionId}
   fetches it)                           until the version is active

Browser:  "Ask AI" button ──► POST /v1/sessions {key} → short-lived token
                          ──► POST /v1/chat (Bearer token, streamed reply)

• The bundle (CopilotBundle, format version 1) holds generator, generatedAt, siteUrl, basePath and pages[] { path, title, description?, markdown }. The page list comes from the portal's llms.txt, each page's text from its Markdown copy, and pages under __downloads/ are skipped. build.json holds the SHA-256 of the bundle, so the service downloads it again only when a deploy changed it.
• generate: the bundle is written before the portal is saved, so a zipped portal includes it too. If the bundle can't be written, generate only warns and tells the user to run portal copilot sync after deploying. It does not fail the build.
• sync: reads the portal settings → stops early if there is no copilot block, no generated portal or no pages → uploads → reports unchanged straight away. Otherwise it waits for indexing, unless --no-wait is passed. Indexing is polled every 2 s for up to 10 minutes. A version replaced by a newer sync (superseded) counts as success, with a warning. Failures are reported through the telemetry event PortalCopilotSyncFailedEvent.

What reviewers should look at

🔐 Security decisions

• The saved APIMatic login goes only to services we trust. receivesSavedLogin() in copilot-config.ts allows apimatic.io, *.apimatic.io and loopback addresses. For any other apiUrl, sync refuses to run unless the user passes --auth-key explicitly. That stops a third party's apimatic.json from collecting a user's credentials.
• Plain http:// is accepted only for loopback, so the keys are never sent unencrypted (the config parser and the JSON schema both check this).
• The browser only gets the public key and the service address. The e2e test checks this. The chat swaps the key for a short-lived session token and renews it 30 s before it expires or once after a 401. Every request uses credentials: 'omit', so portal cookies are never sent.
• If the service turns the portal away (copilot_disabled, invalid_key, origin_not_allowed), the Ask AI button hides itself.

📦 Dependencies

Package	Change	Why
@fumadocs/ai-chat	new, 0.1.0 (pinned)	The chat panel. It is 0.x: check the chat by hand on every upgrade.
@ai-sdk/react	new, 4.0.131	useChat
ai	new, 7.0.128	DefaultChatTransport
fumadocs-core, fumadocs-ui	16.15.17 → 16.16.2	@fumadocs/ai-chat needs fumadocs-ui >= 16.16

All three new packages are added to LINKED_DEPENDENCIES in portal-project-service.ts, so the portal build can resolve them. Most of the pnpm-lock.yaml change comes from these packages.

⚡ Bundle size

The chat is loaded with React.lazy, so it is its own chunk (portal-template/src/lib/layout.tsx). A portal without copilot never downloads it. A portal with it still prerenders the button, because the prerender waits for the chunk. Both cases have e2e tests.

🔌 Contract with the Ask AI service (not in this repo)

The paths below are built into every published portal, so the service has to keep serving them. A breaking change needs a /v2 path.

Caller	Endpoint	Notes
CLI	POST /v1/ingest	gzipped bundle; headers Authorization: X-Auth-Key <key> and X-Copilot-Key: <public key>; answers { versionId, status: queued|unchanged, pageCount }
CLI	GET /v1/ingest/{versionId}	{ status: queued|building|active|superseded|failed, pageCount, changedPages, removedPages, chunkCount, error? }
Browser	POST /v1/sessions	{ key } → { token, expiresAt }
Browser	POST /v1/chat	Bearer token; body { threadId, trigger, message }, carrying only the latest message (the service keeps the thread); streams data-thread, data-sources and tool-search parts

Errors come back as { code, message }. The CLI shows the message for 400, 401, 403, 404 and 413.

Other things to know

• New oclif topic portal:copilot, and the README section is regenerated.
• eslint.config.js adds the fetch/Response/Headers globals to the test config, because the portal template's browser code is tested against Node's own fetch.
• The service links pages by their path inside the portal. copilot-links.ts adds the portal's base path to those links, so they work when the portal is served under a sub-path.
• No breaking changes. Portals without the new block build as before.

File map

Layer	Files
Command	src/commands/portal/copilot/sync.ts
Action	src/actions/portal/copilot/sync.ts, src/actions/portal/generate.ts (writes the bundle)
Prompts	src/prompts/portal/copilot/sync.ts, src/prompts/portal/generate.ts
Infrastructure	src/infrastructure/services/copilot-ingest-service.ts, src/infrastructure/portal-project-service.ts
Types	src/types/portal/config/copilot-config.ts, ai-config.ts, portal-config.ts; src/types/portal/copilot/{copilot-bundle,generated-portal-context,ingest,llms-index}.ts; src/types/events/portal-copilot-sync-failed.ts
Portal template	components/copilot.tsx, lib/copilot-client.ts, lib/copilot-links.ts, lib/layout.tsx, lib/portal-types.ts, styles/app.css
Config / docs	apimatic.schema.json, package.json, pnpm-lock.yaml, eslint.config.js, README.md

Testing

Run locally on this branch, with the latest dev merged in:

• ✅ pnpm build
• ✅ pnpm lint
• ✅ pnpm test: 1911 passing, 72 pending (the e2e suites, which are skipped unless APIMATIC_E2E=1 is set)
• ✅ APIMATIC_E2E=1 test/e2e/portal-build.test.ts: 70 passing, which builds real portals with and without the chat

New tests:

• Action (test/actions/portal/copilot/sync.test.ts): a full sync that waits for indexing; unchanged; --no-wait; superseded; the service refusing the upload; the service unreachable; indexing failing; the saved login withheld from untrusted services and sent to APIMatic's and loopback ones; failing early with no copilot block, no apimatic.json, no generated portal or no Markdown pages.
• Service (copilot-ingest-service.test.ts, nock): the upload's headers and gzipped body; stored key vs. flag; no key → asked to sign in, no request sent; 400/413 messages; network errors; polling to active/superseded/failed; timeout; a status body it can't read.
• Types: parsing llms.txt (base path, __downloads, .. paths), building the bundle from a generated portal, and validating the copilot block in portal-config.
• Portal template: the session, token renewal, thread tracking and turn-away handling in CopilotClient, and base-path links in copilot-links.
• e2e (portal-build.test.ts, new copilot fixture): the chat button is prerendered; the chat is in its own chunk; a real build lists its pages with their Markdown; the browser gets only the public key and the service address; a portal without the chat loads no chat code.
• generate.test.ts: the bundle and its build ID are written with the portal; a zipped portal includes them; a portal with no pages still saves, and the user is pointed to sync.

Manual check

1. Add the copilot block to a project's src/apimatic.json, pointing at a local Ask AI service (http://localhost:8787).
2. Run apimatic portal generate and check that portal/__copilot/bundle.json and build.json exist.
3. Run apimatic portal serve, open "Ask AI", ask a question and check that the source links open the right pages.
4. Run apimatic portal copilot sync, then again (it should report "already up to date"), then with --no-wait.
5. Point apiUrl at a non-APIMatic https:// host without --auth-key. Sync should refuse to send the saved login.

Commits

• de67589 feat(portal): add an Ask AI copilot chat and a portal copilot sync command
• 7ca4d20 test(portal): cover llms.txt parsing and make the copilot tests pass lint
• 7d039c5 fix(portal): keep the saved APIMatic login from Ask AI services it does not trust
• 08dffb5 perf(portal): load the Ask AI chat only in portals that offer it
• 48c4d17 refactor(portal): tidy the Ask AI copilot and test how its chat links pages
• 1e77599 feat(portal): publish the Ask AI bundle with the generated portal
• 5c73989 merges dev (brings in feat(portal): build a portal from the spec folders APIMATIC-META.json merges #435, already reviewed. It is not part of this diff.)
• 9f1927a test(portal): restores the Ask AI e2e suite that the merge had folded into the merged-spec-folders block

🤖 Generated with Claude Code

[saeedjamshaid]

The opt-in block, the lazy chat chunk and the HTTPS-only service address are good. Requesting changes for the items under "Must fix".

Must fix

1. An empty --auth-key sends the saved APIMatic login to any apiUrl.
2. Under a sub-path (site.url = https://x.com/docs), the chat's source links go to /docs/docs/… and 404.
3. Pages with non-ASCII names are silently left out of the bundle.
4. A user's own static/llms.txt decides what Ask AI sees. With full URLs, it sees nothing.
5. Portals without the chat still change. Measured on the default fixture against dev:
   • CSS: +11.7 KB raw, of which the chat's @source is 7.8 KB.
   • JS loaded up front: +18.3 KB gzipped, of which the Fumadocs upgrade is 13.1 KB.
   • The 60 KB chat chunk ships in every portal's output.
6. Merge order with #437, which also bumps Fumadocs, lucide-react and shiki.

Should fix

• The build ID changes on every generate.
• An error while bundling stops generate before the portal is saved.
• sync can't read a zipped portal.
• Timeouts are reported as "could not be reached".
• generate and sync --help give different advice on when to sync.
• *.localhost is trusted as loopback.
• Every chat message sends the visitor's full page URL.

Design

• The page list is parsed from llms.txt instead of coming from the template.
• The poll loop is a copy of pollUntilCompleted.
• The service address is kept as a string.
• The saved-login rule is split across two layers.
• Ask AI reads each operation page's Markdown (the METHOD /path line and the ```yaml block, code samples included), so the layout llms.server.ts writes is now part of the Ask AI contract. It isn't in the description's contract table and no test pins it. A change to that renderer, such as moving the samples out of the YAML, would quietly stop parameters and samples being indexed. Pin it with a test, or send structured fields in the bundle.

Also: portals with the chat hydrate about 0.5 s later on Slow 4G (3.58 s vs 3.08 s), and the feature is "Ask AI" to readers but copilot to authors.

The 136 unit tests this PR touches pass on this head, and CI is green.

[saeedjamshaid]

llms.txt lists encoded paths (/guides/caf%C3%A9), but the .md files are written decoded (guides/café.md). This lookup misses them and drops the page without a warning. In a test build, 7 pages were listed and 5 bundled.

[waseem196]

Fixed in a2ce8488. The CLI no longer maps llms.txt links to .md files.

The template now writes the pages itself from source.getPages(), each with its path as the router links it. The copilot e2e fixture has a café page and a page the navigation leaves out. The test now checks that the bundle holds exactly the pages the build wrote Markdown copies for, no more and no fewer.

[saeedjamshaid]

Parsing llms.txt (a file written for LLMs) and rebuilding the page-to-file rule here duplicates what the template already knows. It breaks in several ways:

• encoded paths (see the comment above);
• a user's own static/llms.txt replaces the file;
• sync uses today's base path, not the one the portal was built with;
• Fumadocs escapes (, ), [ and ], so some links don't match;
• pages hidden from the navigation are never listed.

Suggestion: have the template emit the bundle as a prerendered route next to llms.txt. generate then gets it from the build, sync reads one file, and this file, markdownOf and most of GeneratedPortalContext go away.

[waseem196]

Done along the lines you suggested, in a2ce8488. llms-index.ts, markdownOf and the file lookup are gone.

One difference: the template prerenders the page list (/api/copilot-pages.json) rather than the finished bundle. generate wraps it into __copilot/bundle.json and build.json, so the bundle format and the build ID stay in the CLI, next to sync, which uses them. The page list is a build-only file that generate removes, so it is never deployed (1af59d49).

What this fixes, point by point:

• Encoded paths: pages come from the source, not from links.
• A user's static/llms.txt: no longer read.
• sync and today's base path: sync uploads the bundle generate wrote, under the base path it was built with.
• Escaping: links are no longer parsed.
• Hidden pages: included.

[saeedjamshaid]

This is reachable when a user's static/llms.txt uses full URLs (0 pages). It then tells them to run sync, which reads the same files and fails the same way. Say what to check instead.

[waseem196]

Fixed. llms.txt no longer decides the pages, so the case you describe cannot happen, and the message no longer points to sync (a2ce8488).

What is left are two different situations, each with its own message (cc8bffca):

• The portal has no pages: the message says so, without suggesting sync.
• The build wrote no page file at all: the message says to generate again, and whom to contact if the pages are still missing, rather than sending the author through their docs.

[saeedjamshaid]

This file is @source '../dist/**/*.js', so every portal's CSS gets the chat's classes (+7.8 KB raw), whether it has the chat or not.

[waseem196]

Fixed in bacb58ce.
app.css no longer imports the chat's preset. The CLI writes it into theme.css only for a portal with ai.copilot, and portal serve rewrites it when the block changes.

[saeedjamshaid]

A portal generated with --zip holds only portal.zip, so this tells the user to generate a portal they just generated. Read the zip, or say that zipped portals aren't supported.

[waseem196]

Fixed in 26cf47ca.
When the folder has no __copilot/bundle.json, sync reads the same path inside portal.zip, through a new ZipService.readEntry that reads one file without unpacking the rest. A test syncs a folder that holds only portal.zip.

[saeedjamshaid]

Timeouts land here as network errors, so a slow upload or status check reports "could not be reached. Check the address".

[waseem196]

Fixed in fe50480e:

• A timeout is now recognised as one. The client uses axios's clarifyTimeoutError, so a request that runs out of time fails as ETIMEDOUT.
• It is reported as a timeout, naming how long the CLI waited.
• The advice depends on the step:
  • after an upload: sync again, which reports "nothing changed" if the pages arrived;
  • while indexing: check back later.

[saeedjamshaid]

This doubles the base path. The chat renders Fumadocs' Link, which becomes <Link to={href}>, and the router adds its basepath again. With basepath: '/docs', to="/docs/guides/intro" renders /docs/docs/guides/intro. Every source link then 404s, and the conversation is lost. Pass the service's paths through unchanged, and add a test under a sub-path.

[waseem196]

Fixed in a647b1af.
copilot-links.ts is gone, and the service's paths go through unchanged, so the router adds the base path once.

test/portal-template/copilot-chat-links.test.ts (renamed in 984940b9, which also dropped a check that matched the chat package's minified code) renders the chat's sources in a TanStack router with basepath: '/docs'. It checks that /guides/intro becomes /docs/guides/intro, and that a full address is left alone.

[saeedjamshaid]

bundle() isn't guarded, so a read error stops generate before the portal is saved. The bundle also repeats a slice of the spec for every operation, which llms-full.txt deliberately avoids, so it grows large.

[waseem196]

Both fixed:

• A read error (53d0a790) returns an error instead of throwing. generate warns and still saves the portal.
• The spec slice (a2ce8488): pages are rendered as llms-full.txt renders them, without each operation's slice of the specification. The e2e test checks that no operation page carries one.

[saeedjamshaid]

AIChatProvider adds location.href and document.title to every message, so the service receives visitors' full URLs. Strip them, or document it.

[waseem196]

The full page URL with every message Stripped, in 5e9293b1.
The chat now builds its questions through toMessage, sending:

• the page: origin and path only, with no query or fragment (for example, an OAuth callback's ?code= is never sent);
• the page's title, as before.

A test checks that a callback address loses its code.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.0% Duplication on New Code

See analysis details on SonarQube Cloud