Add VitePress documentation site

[christopherkarani]

Summary

• Adds a VitePress documentation site in docs/ that migrates all 20 DocC articles for web browsing
• Includes GitHub Actions workflow to deploy to GitHub Pages at christopherkarani.github.io/Conduit/
• Swift orange brand theme, local search, full sidebar navigation

What's included

• 26 new files: VitePress config, theme, homepage, 10 guide articles, 10 provider articles, deployment workflow
• 3 DocC transformations applied: <doc:> links → VitePress paths, double backticks → single, ## Topics sections removed
• .gitignore updated for node_modules/ and VitePress build artifacts

After merge

Go to Repository Settings → Pages → Source: "GitHub Actions" to enable deployment.

Test plan

• npm run docs:build succeeds with zero errors
• npm run docs:preview serves all pages at localhost:4173/Conduit/
• No remaining DocC syntax (<doc:>, double backticks, ## Topics)
• All 20 pages render with Swift syntax highlighting
• After merge, verify GitHub Actions deployment succeeds
• Verify site at christopherkarani.github.io/Conduit/

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[claude]

PR Review: Add VitePress Documentation Site

Overall, this is a well-structured PR that successfully migrates DocC articles into a browsable VitePress site with a coherent theme, working GitHub Actions deployment, and clean navigation. The content quality is high. A few concrete issues are worth addressing before merge.

---

Bugs / Correctness

1. Placeholder URL in swift-agents-integration.md

The adapter package example contains an unfilled template URL:

.package(url: "https://github.com/your-org/Conduit.git", from: "1.0.0"),

Should be:

.package(url: "https://github.com/christopherkarani/Conduit.git", from: "0.3.0"),

The version is also inconsistent with the 0.3.x series documented everywhere else.

2. Undocumented model ID .claude4Sonnet in swift-agents-integration.md

The usage example at the bottom uses .claude4Sonnet:

let inferenceProvider = ConduitInferenceProvider(
    provider: anthropic,
    model: .claude4Sonnet,   // ← not listed in providers/anthropic.md

providers/anthropic.md documents .claudeSonnet45, .claudeSonnet4, etc. This looks like a stale or speculative ID — it should match what's actually available.

3. Trait compile flag inconsistency in getting-started.md

The trait reference table shows the compile flag for Llama as just Llama:

| `Llama` | `Llama` | LlamaProvider (llama.cpp via llama.swift) |

Every other trait follows the CONDUIT_TRAIT_* convention. If the correct flag for Llama is also CONDUIT_TRAIT_LLAMA, the table should be corrected. If it genuinely differs, a note explaining why would help.

---

Performance (CI/CD)

4. Unnecessary fetch-depth: 0 in workflow

The deploy workflow uses fetch-depth: 0 (full git history), which is typically needed only for the VitePress lastUpdated feature. Since lastUpdated is not enabled in docs/.vitepress/config.mts, this is fetching unused data on every push:

- name: Checkout
  uses: actions/checkout@v4
  with:
    fetch-depth: 0   # ← slow, not needed without lastUpdated: true

Either set fetch-depth: 1 to speed up the build, or enable lastUpdated: true in the config if the edit timestamps are desired on each page.

5. Workflow trigger misses package-lock.json

paths:
  - 'docs/**'
  - 'package.json'

If dependencies are updated (via npm update, resulting in a package-lock.json change), the docs won't be rebuilt automatically. Consider adding 'package-lock.json' to the paths filter.

---

Code Quality / Maintainability

6. Favicon path hardcodes the base in config.mts

head: [
  ['link', { rel: 'icon', href: '/Conduit/conduit-logo.svg' }],
],

The /Conduit/ prefix duplicates the base setting. If the base ever changes, this needs a separate manual update. VitePress provides a withBase() helper for exactly this:

import { defineConfig, withBase } from 'vitepress'

head: [
  ['link', { rel: 'icon', href: withBase('/conduit-logo.svg') }],
],

This is a minor maintainability concern, not a bug (the current value works correctly).

7. Duplicate :root block in style.css

There are two separate :root blocks in docs/.vitepress/theme/style.css. CSS engines merge them correctly, but combining into one block reduces the chance of ordering surprises as the file grows:

:root {
  --vp-c-brand-1: #F05138;
  --vp-c-brand-2: #e6432b;
  --vp-c-brand-3: #cc3520;
  --vp-c-brand-soft: rgba(240, 81, 56, 0.14);

  /* hero */
  --vp-home-hero-name-color: transparent;
  ...
}

---

Documentation Accuracy

8. Force-unwrap in retry example in error-handling.md

The exponential backoff example ends with:

throw lastError!

If maxAttempts is 0, lastError is still nil and this crashes. For documentation code that users will copy, a safer form avoids the gotcha:

throw lastError ?? AIError.generationFailed(underlying: nil)

9. CoreML listed as supporting Tool Calling in capability matrix

providers/index.md marks CoreML with "Yes" for Tool Calling. CoreML is a neural engine runtime for running .mlmodel files — tool calling typically requires the model to return structured JSON and for the framework to parse and dispatch it. Please verify this is actually implemented for CoreMLProvider before shipping; it's likely a copy-paste error.

---

Minor Notes

• Footer copyright reads Copyright 2024-present. Not a blocking issue but worth updating if this ships in 2025+.
• The package.json has no name field. This is fine since "private": true, but adding one ("name": "conduit-docs") is conventional.
• The package-lock.json commit (2510 lines) is the right practice for reproducible builds — no issue there.
• The Swift orange brand theme and SVG logo are clean and on-brand.

---

Summary

Category	Count
Bugs / Correctness	3
Performance	2
Maintainability	2
Documentation accuracy	2

Items 1, 2, and 3 are the most important to fix before merge. Items 4–9 are improvements but won't break anything as-is.

[claude]

PR Review: Add VitePress Documentation Site

Overall this is a well-structured documentation PR. The VitePress setup is clean, the sidebar navigation covers all 20 articles, and the CI/CD workflow follows GitHub Pages best practices. A few issues need attention before merging.

---

Bugs / Functional Issues

1. CNAME conflicts with PR description target URL (high priority)

docs/public/CNAME contains conduit.dev, but the PR description says the site will deploy to christopherkarani.github.io/Conduit/. These are mutually exclusive:

• If using a custom domain (conduit.dev): base: '/' in config.mts is correct, but you must own and configure DNS for conduit.dev to point to GitHub Pages. As of this PR, that domain appears unrelated to this project.
• If using the default GitHub Pages URL (christopherkarani.github.io/Conduit/): remove docs/public/CNAME and change base: '/' → base: '/Conduit/'. Without the correct base path, all assets and internal links will 404.

The current combination (CNAME for conduit.dev + base: '/' + PR description referencing christopherkarani.github.io/Conduit/) is inconsistent. Decide on one deployment target and align all three.

2. Placeholder URL in swift-agents-integration.md

docs/guide/swift-agents-integration.md line ~46 contains:

.package(url: "https://github.com/your-org/Conduit.git", from: "1.0.0"),

This should be the actual repo URL:

.package(url: "https://github.com/christopherkarani/Conduit.git", from: "0.3.0"),

Also note from: "1.0.0" — the current version per the nav and getting-started guide is 0.3.0.

3. Unknown model constant .claude4Sonnet in swift-agents-integration.md

The usage example uses model: .claude4Sonnet:

let inferenceProvider = ConduitInferenceProvider(
    provider: anthropic,
    model: .claude4Sonnet,   // ← not listed in the model table
    ...
)

The Anthropic provider docs list .claudeOpus45, .claudeSonnet45, .claudeOpus4, .claudeSonnet4, .claude35Sonnet, etc. — but not .claude4Sonnet. This looks like a typo; likely should be .claudeSonnet4 or .claudeSonnet45.

---

Minor Issues

4. Workflow cancellation policy

concurrency:
  group: pages
  cancel-in-progress: false

cancel-in-progress: false means a rapid second push will queue behind the first rather than replacing it. For a docs site this is usually fine, but cancel-in-progress: true is more common and avoids deploying stale content when a fix commit quickly follows.

5. package.json triggers docs deployment

The workflow triggers on changes to package.json:

paths:
  - 'docs/**'
  - 'package.json'

A root-level package.json change unrelated to docs content (e.g. updating a script name) would trigger a full docs deployment. Consider narrowing this to package-lock.json only, which is the actual dependency artifact.

6. Force-unwrap in error handling example

In docs/guide/error-handling.md:

throw lastError!

This is in a documentation snippet, but lastError will always be non-nil here (the loop runs maxAttempts times only on retryable errors and sets lastError each time), so the force-unwrap is safe. Still, using guard let or throw AIError.generationFailed(underlying: lastError) would be a better example of Swift best practices for readers to follow.

---

Positive Notes

• Workflow structure is correct: separate build and deploy jobs with needs: build, uses actions/configure-pages@v5, actions/upload-pages-artifact@v3, and actions/deploy-pages@v4 — the current recommended approach.
• fetch-depth: 0 is correctly used to enable VitePress lastUpdated timestamps.
• Permissions are minimal and correct (contents: read, pages: write, id-token: write).
• "private": true in package.json prevents accidental npm publish.
• .gitignore updates are appropriate (node_modules/, docs/.vitepress/dist/, docs/.vitepress/cache/).
• The Swift orange brand colors are a nice touch consistent with the ecosystem.
• All 20 DocC articles appear to be migrated with DocC-specific syntax (<doc:> links, double backticks, ## Topics) correctly removed.

---

Summary

Issue	Severity	File
CNAME / base URL mismatch	High	docs/public/CNAME, docs/.vitepress/config.mts
Placeholder your-org URL	High	docs/guide/swift-agents-integration.md
Unknown model .claude4Sonnet	Medium	docs/guide/swift-agents-integration.md
Workflow cancel policy	Low	.github/workflows/deploy-docs.yml
Overly broad workflow path trigger	Low	.github/workflows/deploy-docs.yml
Force-unwrap in example code	Low	docs/guide/error-handling.md

The CNAME/base URL conflict and placeholder URL are the two changes needed before this is deployment-ready.

🤖 Generated with Claude Code

[claude]

PR Review: Add VitePress Documentation Site

Overall this is a well-executed documentation addition. The structure is clean, the DocC-to-VitePress migration looks thorough, and the CI/CD workflow follows current best practices. A few issues worth addressing before merge:

---

Issues

1. Placeholder URL in swift-agents-integration.md

The Package.swift example uses a placeholder repository URL:

.package(url: "https://github.com/your-org/Conduit.git", from: "1.0.0"),

This should be the real repo URL (https://github.com/christopherkarani/Conduit) and the version should match the current 0.3.0 tag documented elsewhere. As-is, a user who copy-pastes this will get a package resolution failure.

---

2. Inconsistent Llama compile flag in Trait Reference table (getting-started.md)

The table shows Llama as its own compile flag, breaking the CONDUIT_TRAIT_* naming convention used by every other trait:

Trait	Compile Flag
Llama	Llama
MLX	CONDUIT_TRAIT_MLX

Either the compile flag should be CONDUIT_TRAIT_LLAMA (if that is what the Swift package defines), or the table needs a note explaining why Llama differs. HuggingFaceHub also shows — for its compile flag with no explanation — a brief note would help.

---

3. Workflow path trigger missing package-lock.json

paths:
  - 'docs/**'
  - 'package.json'

package-lock.json is missing from the trigger list. A lockfile-only update (e.g. a security patch from npm audit fix) won't trigger a redeploy, leaving the live site built from the old dependency set. Add 'package-lock.json' to the paths list.

---

4. Force-unwrap in retry example (error-handling.md)

throw lastError!

If maxAttempts: 0 is passed, lastError is never set and this crashes. The example code is documentation-only, but users often adapt it directly. A safer pattern:

throw lastError ?? AIError.generationFailed(underlying: nil)

Or guard at the top: guard maxAttempts > 0 else { throw ... }.

---

5. SwiftUI example message ordering (chat-session.md)

In the ChatView example:

let response = try await session.send(prompt)
messages.append("You: \(prompt)")   // appended AFTER await
messages.append("AI: \(response)")

Because await suspends, "You: ..." appears visually after "AI: ..." in the list. The user message should be appended before the await:

messages.append("You: \(prompt)")
let response = try await session.send(prompt)
messages.append("AI: \(response)")

---

Observations (non-blocking)

fetch-depth: 0 — This fetches the entire git history, presumably for VitePress's "last updated" timestamps. That feature is not enabled in config.mts, so fetch-depth: 0 appears unnecessary and can be removed to speed up CI.

GitHub Actions version pinning — Pinning to major version tags (@v4) is standard and acceptable. For a deployment workflow, pinning to full commit SHAs provides stronger supply-chain guarantees, but this is a low-risk project context.

Copyright — copyright: 'Copyright 2024-present Christopher Karani' — conventional to include the copyright symbol. Minor.

---

What's done well

• Workflow permissions follow least-privilege (contents: read, pages: write, id-token: write only)
• cancel-in-progress: false on the pages concurrency group correctly prevents a deploy from being cancelled mid-flight
• npm ci (not npm install) ensures the lockfile is respected exactly
• All DocC syntax fully converted — no remaining <doc:> links or double backticks
• Sidebar navigation and guide/provider split is well-organized
• Code examples are consistent with the SDK's protocol API
• No secrets or real credentials committed