Skip to main content

​
CLAUDE.md - valyu-docs

​
Confidentiality

Never mention or reference internal models (Anthropic, Gemini, Nova, etc.), internal services, or subprocessors (Brave, etc.) in any code, documentation, comments, or user-facing text. Valyu is model-agnostic — treat all underlying infrastructure as an implementation detail that must not be exposed.

​
Feature Rollout Order

When adding new features, update SDKs first, then docs:
  1. valyu-py + valyu-js (sibling repos) - implement the feature in both SDKs
  2. valyu-docs (this repo) - update API reference, SDK guides, and integration docs

​
Repository Layout

valyu-docs/
├── docs.json                     # Mintlify config: navigation, tabs, theme, redirects
├── custom.js                     # "Copy AI Prompt" button functionality
├── api-reference/
│   ├── openapi.json              # OpenAPI spec (update BEFORE endpoint docs)
│   └── endpoint/                 # API endpoint pages (.mdx)
│       ├── search.mdx
│       ├── contents.mdx / contents-jobs.mdx
│       ├── answer.mdx
│       ├── datasources-list.mdx / datasources-categories.mdx
│       ├── deepresearch-*.mdx    # create, status, list, update, cancel, delete
│       └── deepresearch-batch-*.mdx  # create, list, status, add-tasks, list-tasks, cancel
├── sdk/                          # SDK documentation
│   ├── python-sdk.mdx            # Python SDK landing
│   ├── python-sdk/               # Per-endpoint Python guides
│   ├── typescript-sdk.mdx        # TypeScript SDK landing
│   ├── typescript-sdk/           # Per-endpoint TypeScript guides
│   ├── rust-sdk.mdx              # Rust SDK landing (Alpha)
│   └── rust-sdk/                 # Per-endpoint Rust guides
├── integrations/                 # Third-party integration guides
│   ├── mcp-server.mdx / mcp-desktop.mdx
│   ├── langchain.mdx / llamaindex.mdx / vercel-ai-sdk.mdx
│   ├── anthropic.mdx / openai.mdx / google.mdx
│   └── ... (n8n, agno, claude-code-plugin, aws-agentcore, etc.)
├── guides/                       # Guides & best practices
│   ├── search/                   # Search guides (quickstart, prompting, filtering/, tips)
│   ├── deepresearch*.mdx         # DeepResearch guides
│   ├── content-extraction.mdx / answer-api.mdx / datasources.mdx
│   └── ai-sdk-*.mdx             # AI SDK tooling guides
├── use-cases/                    # academic, finance, healthcare, news
├── concepts/                     # design-philosophy, data-coverage
├── sources/                      # Data source pages (pubmed, arxiv, sec-filings, etc.)
├── compare/                      # Competitor comparison pages
├── changelog/                    # platform.mdx, sdk-and-api.mdx
├── images/                       # Documentation images
├── logo/                         # Brand logos (light/dark variants)
├── home.mdx / overview.mdx / quickstart.mdx  # Top-level pages
└── AGENTS.md                     # Additional repo guidelines
  1. Home - Landing page
  2. Documentation - Getting started, guides, use cases, concepts, data sources, comparisons
  3. API Reference - OpenAPI-driven endpoint docs (search, contents, answer, deepresearch, batch, datasources)
  4. SDKs - Python, TypeScript, Rust SDK guides
  5. Integrations - MCP, frameworks, LLM providers, automation
  6. Changelog - Platform + SDK/API changes

​
Build & Preview

  • npm i -g mintlify - Install CLI
  • mintlify dev - Local hot-reload preview
  • mintlify build - Validate and build static site

​
Git, PRs & CI/CD

  • Default branch: main
  • DANGER: Pushing to main auto-deploys the live docs site. Mintlify watches the main branch and deploys on every push.
  • Never push or merge to main. The maximum you can do is open a PR to main — the user will review and merge manually.
  • Always work on a feature branch and open a PR to main. Never push directly to main under any circumstances, even if the user asks.
  • PRs should target main and follow the branch naming convention feature/feature-name.
  • Preview changes locally with mintlify dev before pushing.

​
Adding a New Feature to Docs

  1. Update api-reference/openapi.json if there are API changes
  2. Add/update endpoint pages in api-reference/endpoint/
  3. Add/update SDK usage guides in sdk/python-sdk/ and sdk/typescript-sdk/
  4. Update navigation in docs.json to include new pages
  5. Add guides in guides/ if the feature needs a walkthrough
  6. Preview with mintlify dev

​
Conventions

  • MDX files with YAML frontmatter (title, description, sidebarTitle)
  • Sentence case headings starting at ##
  • kebab-case file and directory names
  • Mintlify components: <Note>, <Warning>, <Tip>, <Card>, <CodeGroup>, <Steps>/<Step>
  • Commit style: [TYPE] Short description (e.g., [FEAT], [FIX], [DOCS], [CHORE])