From fa2efb4246721b3ae684a25c36693192c88443b4 Mon Sep 17 00:00:00 2001 From: Bruno Campana <7632562+BrunoCampana@users.noreply.github.com> Date: Wed, 6 May 2026 20:00:22 -0300 Subject: [PATCH 1/7] doc: examples changed path in sdk/examples --- .../website/content/docs/sdk/examples/ai-tasks/completion.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/website/content/docs/sdk/examples/ai-tasks/completion.mdx b/docs/website/content/docs/sdk/examples/ai-tasks/completion.mdx index c36e95674a..8c0b3ba1d4 100644 --- a/docs/website/content/docs/sdk/examples/ai-tasks/completion.mdx +++ b/docs/website/content/docs/sdk/examples/ai-tasks/completion.mdx @@ -77,7 +77,7 @@ The following script shows how to provide tool definitions to `completion()`, co -```js file=/packages/sdk/dist/examples/llamacpp-native-tools.js title="completion-tool-call.js" lineNumbers +```js file=/packages/sdk/dist/examples/tools/llamacpp-native-tools.js title="completion-tool-call.js" lineNumbers ``` @@ -85,7 +85,7 @@ The following script shows how to provide tool definitions to `completion()`, co -```ts file=/packages/sdk/examples/llamacpp-native-tools.ts title="completion-tool-call.ts" lineNumbers +```ts file=/packages/sdk/examples/tools/llamacpp-native-tools.ts title="completion-tool-call.ts" lineNumbers ``` From 7d91fb14140ce868f74b2cfd7e3ddc8e0670834d Mon Sep 17 00:00:00 2001 From: Bruno Campana <7632562+BrunoCampana@users.noreply.github.com> Date: Wed, 6 May 2026 20:01:18 -0300 Subject: [PATCH 2/7] doc: CLI - doctor - fix issue + create new page troubleshooting --- docs/website/content/docs/cli.mdx | 14 +++++-- docs/website/content/docs/troubleshooting.mdx | 37 +++++++++++++++++++ docs/website/src/lib/custom-tree.ts | 6 +++ 3 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 docs/website/content/docs/troubleshooting.mdx diff --git a/docs/website/content/docs/cli.mdx b/docs/website/content/docs/cli.mdx index e70e04a1eb..2a482ed90f 100644 --- a/docs/website/content/docs/cli.mdx +++ b/docs/website/content/docs/cli.mdx @@ -7,7 +7,7 @@ schemaType: TechArticle ## Overview -QVAC CLI is provided through the `@qvac/cli` npm package and requires `@qvac/sdk` to be installed alongside it in your project. At the moment, it provides the following functionality: +QVAC CLI is provided through the `@qvac/cli` npm package. The CLI itself is installed globally so the `qvac` command is available on your `PATH`; `@qvac/sdk` is installed in your project so the CLI can resolve and run it. At the moment, it provides the following functionality: - OpenAI-compatible HTTP server - SDK bundling - System requirements check @@ -16,10 +16,18 @@ QVAC CLI is provided through the `@qvac/cli` npm package and requires `@qvac/sdk -Install the SDK and CLI in your project: +You must install the CLI globally so the `qvac` command is available on your `PATH`: ```bash -npm install @qvac/sdk @qvac/cli +npm install -g @qvac/cli +``` + + + +Install the SDK as a dependency of the project where you'll run the CLI: + +```bash +npm install @qvac/sdk ``` See [Installation](/sdk/getting-started/installation) for environment-specific instructions of the SDK. diff --git a/docs/website/content/docs/troubleshooting.mdx b/docs/website/content/docs/troubleshooting.mdx new file mode 100644 index 0000000000..48dadfdcdf --- /dev/null +++ b/docs/website/content/docs/troubleshooting.mdx @@ -0,0 +1,37 @@ +--- +title: Troubleshooting +description: Resolve common issues when using QVAC. +schemaType: TechArticle +--- + +## `qvac: command not found` + +### Situation + +You ran a `qvac` command (e.g., `qvac doctor`) and the shell responded with: + +``` +zsh: command not found: qvac +``` + +(On bash: `bash: qvac: command not found`.) + +### Cause + +The `qvac` binary is shipped by the `@qvac/cli` npm package. It is only added to your shell `PATH` when `@qvac/cli` is installed globally. Without a global install, the binary is not discoverable by name from your shell. + +### Solution + +Install `@qvac/cli` globally: + +```bash +npm install -g @qvac/cli +``` + +Then re-run your command. For example: + +```bash +qvac doctor +``` + +See [CLI → Usage](/cli#usage) for the full setup, including installing `@qvac/sdk` in your project. diff --git a/docs/website/src/lib/custom-tree.ts b/docs/website/src/lib/custom-tree.ts index 3767d88461..4d6112ed3e 100644 --- a/docs/website/src/lib/custom-tree.ts +++ b/docs/website/src/lib/custom-tree.ts @@ -190,6 +190,12 @@ export const customTree: Node[] = [ type: 'page', icon: resolveIcon('Stethoscope'), }, + { + name: 'Troubleshooting', + url: '/troubleshooting', + type: 'page', + icon: resolveIcon('Bug'), + }, { name: 'HTTP server', url: '/http-server', From 9fbcce35065124c5e182590b5b7388ac823bd450 Mon Sep 17 00:00:00 2001 From: Bruno Campana <7632562+BrunoCampana@users.noreply.github.com> Date: Wed, 6 May 2026 20:11:48 -0300 Subject: [PATCH 3/7] doc: CLI - doctor - fix issue + create new page troubleshooting --- docs/website/content/docs/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/content/docs/troubleshooting.mdx b/docs/website/content/docs/troubleshooting.mdx index 48dadfdcdf..4c6e6d2968 100644 --- a/docs/website/content/docs/troubleshooting.mdx +++ b/docs/website/content/docs/troubleshooting.mdx @@ -1,7 +1,7 @@ --- title: Troubleshooting description: Resolve common issues when using QVAC. -schemaType: TechArticle +schemaType: HowTo --- ## `qvac: command not found` From d179c08635ac27b89a495d87f95df09821aad993 Mon Sep 17 00:00:00 2001 From: Bruno Campana <7632562+BrunoCampana@users.noreply.github.com> Date: Wed, 6 May 2026 20:48:18 -0300 Subject: [PATCH 4/7] doc: fix sitemap generation in staging env --- docs/website/src/app/sitemap.ts | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/website/src/app/sitemap.ts b/docs/website/src/app/sitemap.ts index 7988abf567..d86ec18feb 100644 --- a/docs/website/src/app/sitemap.ts +++ b/docs/website/src/app/sitemap.ts @@ -2,6 +2,7 @@ import type { MetadataRoute } from 'next'; import { source } from '@/lib/source'; import { allowDocsIndexingAtBuildTime } from '@/lib/docs-indexing'; import { + DOCS_SITE_ORIGIN, buildCanonicalDocsUrl, isArchivedVersionSlug, } from '@/lib/docs-open-graph'; @@ -15,8 +16,11 @@ export const dynamic = 'force-static'; * * Indexing policy — mirrors `robots.ts`: * - Production (`DOCS_ALLOW_INDEXING=true`): emit one entry per latest page. - * - Preview / local / PR builds (default): emit an empty sitemap so non-canonical - * deploys don't advertise any URLs even if the file is fetched directly. + * - Preview / local / PR builds (default): emit a semantically-empty sitemap + * (two duplicate entries for the canonical site root) so non-canonical + * deploys don't advertise any internal URL even if the file is fetched + * directly. See the in-function comment for why two entries (and not zero + * or one) are required. * * Non-canonical bundles (`dev` preview + `vX.Y.Z` back-versions) are excluded * entirely. Those pages still render so the in-page version selector keeps @@ -29,7 +33,25 @@ export const dynamic = 'force-static'; * ignored, so they would only add noise. */ export default function sitemap(): MetadataRoute.Sitemap { - if (!allowDocsIndexingAtBuildTime()) return []; + if (!allowDocsIndexingAtBuildTime()) { + // Non-canonical deploys (preview / PR / staging): we don't want to + // advertise any internal URL, but the post-build link checker + // (`@vahor/next-broken-links`, invoked from `package.json`) parses + // `out/sitemap.xml` with fast-xml-parser default settings and crashes + // when `` has zero `` children — `urlset.url` is + // `undefined`, and its `for (... of urlset.url)` then throws + // `TypeError: x.urlset.url is not iterable`. + // + // Emitting two duplicate entries for the canonical site root is + // semantically equivalent to "empty" for crawlers (the homepage is + // implicit by visiting the deploy at all, and identical entries are + // deduplicated) while forcing fast-xml-parser to materialize + // `urlset.url` as an array — it only coerces to an array when there + // are 2+ children; a single child becomes an object, which is also + // not iterable. Verified empirically against fast-xml-parser 5.5.9. + const root = `${DOCS_SITE_ORIGIN}/`; + return [{ url: root }, { url: root }]; + } return source .getPages() From 3d84b24469ab2aa0b8a830df04bf464a79227e08 Mon Sep 17 00:00:00 2001 From: Bruno Campana <7632562+BrunoCampana@users.noreply.github.com> Date: Thu, 7 May 2026 16:06:18 -0300 Subject: [PATCH 5/7] doc: frontend - make it possible to have ToCs using less subsections headings --- docs/website/content/docs/troubleshooting.mdx | 3 ++- docs/website/source.config.ts | 1 + docs/website/src/app/(docs)/[[...slug]]/page.tsx | 7 +++++-- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/website/content/docs/troubleshooting.mdx b/docs/website/content/docs/troubleshooting.mdx index 4c6e6d2968..73b48c1224 100644 --- a/docs/website/content/docs/troubleshooting.mdx +++ b/docs/website/content/docs/troubleshooting.mdx @@ -2,9 +2,10 @@ title: Troubleshooting description: Resolve common issues when using QVAC. schemaType: HowTo +tocMaxDepth: 2 --- -## `qvac: command not found` +## CLI error: command not found ### Situation diff --git a/docs/website/source.config.ts b/docs/website/source.config.ts index 72ad2b6fbd..6707c5f0c6 100644 --- a/docs/website/source.config.ts +++ b/docs/website/source.config.ts @@ -24,6 +24,7 @@ export const docs = defineDocs({ version: z.string().optional(), ogImage: z.string().optional(), schemaType: z.enum(SCHEMA_TYPES).optional(), + tocMaxDepth: z.number().int().min(2).max(5).optional(), }), postprocess: { includeProcessedMarkdown: true, diff --git a/docs/website/src/app/(docs)/[[...slug]]/page.tsx b/docs/website/src/app/(docs)/[[...slug]]/page.tsx index f9012c063e..e9bab652b0 100644 --- a/docs/website/src/app/(docs)/[[...slug]]/page.tsx +++ b/docs/website/src/app/(docs)/[[...slug]]/page.tsx @@ -56,8 +56,11 @@ export default async function Page(props: PageProps<'/[[...slug]]'>) { }) : null; - // Filter ToC to include H2 through H5 (depth 2, 3, 4, and 5) - const filteredToc = page.data.toc?.filter(item => item.depth >= 2 && item.depth <= 5) || []; + // Filter ToC to include H2 through H5 by default. A page can opt into a + // shallower ToC by setting `tocMaxDepth` in its frontmatter (e.g. `2` to + // index only H2 headings). + const tocMaxDepth = page.data.tocMaxDepth ?? 5; + const filteredToc = page.data.toc?.filter(item => item.depth >= 2 && item.depth <= tocMaxDepth) || []; const isHomePage = !params.slug || params.slug.length === 0; const jsonLdBlocks = buildDocsJsonLd(page, params.slug ?? [], isHomePage); From 3d5fae6e09b1560f2e53d1b5d6fabd242fa8633b Mon Sep 17 00:00:00 2001 From: Bruno Campana <7632562+BrunoCampana@users.noreply.github.com> Date: Fri, 8 May 2026 11:04:15 -0300 Subject: [PATCH 6/7] doc: add tip - requested by reviewer --- docs/website/content/docs/cli.mdx | 16 +++++++++++++++- docs/website/content/docs/troubleshooting.mdx | 16 +++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/website/content/docs/cli.mdx b/docs/website/content/docs/cli.mdx index 2a482ed90f..33c37a3ced 100644 --- a/docs/website/content/docs/cli.mdx +++ b/docs/website/content/docs/cli.mdx @@ -16,7 +16,7 @@ QVAC CLI is provided through the `@qvac/cli` npm package. The CLI itself is inst -You must install the CLI globally so the `qvac` command is available on your `PATH`: +Install the CLI globally so the `qvac` command is available on your `PATH`: ```bash npm install -g @qvac/cli @@ -48,6 +48,20 @@ qvac --help + +**Tip:** If you cannot install the CLI globally, install it as a dev dependency instead: + +```bash +npm install --save-dev @qvac/cli +``` + +Then run QVAC CLI commands with `npx`. For example: + +```bash +npx qvac --help +``` + + ## OpenAI-compatible HTTP server QVAC CLI provides an HTTP server that is compatible with the [OpenAI REST API](https://developers.openai.com/api/reference/overview), enabling broad integration with the AI ecosystem. It internally translates HTTP requests into SDK calls. As a result, any system compatible with the OpenAI REST API can point to `http://localhost:11434/v1/` and work without changes. diff --git a/docs/website/content/docs/troubleshooting.mdx b/docs/website/content/docs/troubleshooting.mdx index 73b48c1224..304e51002a 100644 --- a/docs/website/content/docs/troubleshooting.mdx +++ b/docs/website/content/docs/troubleshooting.mdx @@ -35,4 +35,18 @@ Then re-run your command. For example: qvac doctor ``` -See [CLI → Usage](/cli#usage) for the full setup, including installing `@qvac/sdk` in your project. + +**Tip:** If you cannot install the CLI globally, install it as a dev dependency instead: + +```bash +npm install --save-dev @qvac/cli +``` + +Then run QVAC CLI commands with `npx`. For example: + +```bash +npx qvac --help +``` + + +See [CLI → Usage](/cli#usage) for the full setup, including installing `@qvac/sdk` in your project. \ No newline at end of file From b470d493295caa1d68d75e8bc7e3f9a67dddb768 Mon Sep 17 00:00:00 2001 From: Bruno Campana <7632562+BrunoCampana@users.noreply.github.com> Date: Fri, 8 May 2026 11:42:26 -0300 Subject: [PATCH 7/7] doc: add tip - requested by reviewer --- docs/website/content/docs/cli.mdx | 10 ++-------- docs/website/content/docs/troubleshooting.mdx | 10 ++-------- 2 files changed, 4 insertions(+), 16 deletions(-) diff --git a/docs/website/content/docs/cli.mdx b/docs/website/content/docs/cli.mdx index 33c37a3ced..6ccc915b65 100644 --- a/docs/website/content/docs/cli.mdx +++ b/docs/website/content/docs/cli.mdx @@ -49,16 +49,10 @@ qvac --help -**Tip:** If you cannot install the CLI globally, install it as a dev dependency instead: +**Tip:** if you cannot install the CLI globally, you can run it with `npx` instead: ```bash -npm install --save-dev @qvac/cli -``` - -Then run QVAC CLI commands with `npx`. For example: - -```bash -npx qvac --help +npx --package "@qvac/cli" qvac --help ``` diff --git a/docs/website/content/docs/troubleshooting.mdx b/docs/website/content/docs/troubleshooting.mdx index 304e51002a..a873553b40 100644 --- a/docs/website/content/docs/troubleshooting.mdx +++ b/docs/website/content/docs/troubleshooting.mdx @@ -36,16 +36,10 @@ qvac doctor ``` -**Tip:** If you cannot install the CLI globally, install it as a dev dependency instead: +**Tip:** If you cannot install the CLI globally, you can run it with `npx` instead: ```bash -npm install --save-dev @qvac/cli -``` - -Then run QVAC CLI commands with `npx`. For example: - -```bash -npx qvac --help +npx --package "@qvac/cli" qvac doctor ```