breakpoints Documentation

1. Project Overview & Quickstart (langchain-ai/breakpoints) Copy Chapter

Technical Documentation: langchain-ai/breakpoints

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

breakpoints

Agent Skills & Rules Copy Section

• Discovered 21 agent rule(s) and prompt configurations.

--- METRICS ---

• Files Extracted: 1
• Estimated Token Budget: ~25 tokens
• Canonical Reference: https://codewiki.google/github.com/langchain-ai/breakpoints

2. Official Technical Reference & Guides (langchain-ai/docs) Copy Chapter

File: README.md Copy Chapter

LangChain Docs

🦜 Welcome! This repository contains the documentation build pipeline for LangChain projects.

• 🏠 docs.langchain.com is our docs home, centralizing documentation for LangChain, LangGraph, LangSmith, and LangChain Labs (Deep Agents, Open SWE, Open Agent Platform). This site is hosted on Mintlify.
• 🛠️ reference.langchain.com hosts generated API reference for LangChain, LangGraph, LangSmith, and integration packages. That site is not built from this repository (no reference build scripts or output live here).
  • Python reference
  • JavaScript/TypeScript reference
• 💬 chat.langchain.com is an AI-powered assistant that can answer questions about LangChain documentation.

Table of contents:

• LangChain Docs
  • Contribute
  • Reference
    • Repository structure
      • docs.langchain.com
      • reference.langchain.com
    • File formats
    • Available commands
  • Linting
    • Codespell
  • Troubleshooting
    • docs dev not working / running
    • Mintlify .venv parsing error
    • Warning: page doesn't exist
    • General Mintlify errors

Contribute Copy Chapter

To run a local preview of the documentation:

git clone https://github.com/langchain-ai/docs.git

cd docs

make install

make dev

For more information on how to contribute to LangChain documentation, follow the steps outlined in the contributing guide. The contributing guide also explains our documentation types and their writing and quality standards.

For detailed information about setting up your development environment and contributing to documentation, see the documentation contributing guide.

To report issues with reference.langchain.com (missing pages, broken links, or generated API content), open a reference documentation issue on this repo so maintainers can route it.

Reference Copy Chapter

Repository structure Copy Section

# --- docs.langchain.com ----------------------------------------------
build/                    # Built docs (DO NOT EDIT)
packages.yml              # Package metadata (indexes, tables, downloads; not the API reference build)
pipeline/                 # Build pipeline source code
scripts/                  # Helper scripts
src/                      # Source documentation files (< EDIT CONTENT HERE)
    langsmith/            # LangSmith docs
    oss/                  # LangChain, LangGraph, Deep Agents, and integrations docs
    docs.json             # Mintlify site configuration and navigation
tests/                    # Test files for the pipeline
Makefile                  # Build targets
pyproject.toml            # Dependencies

`docs.langchain.com`

The Mintlify docs pipeline is structured with .mdx source files in /src and build artifacts in /build. Mintlify deploys from the /build folder, which is generated by preprocessing logic.

[!IMPORTANT]
Never edit /build directly.

The /src/docs.json file is used to configure the Mintlify site navigation and settings. Refer to the Mintlify documentation for detailed syntax and component usage.

Documentation changes follow a PR workflow where all tests must pass before merging. See the contributing guidelines for more details.

`reference.langchain.com`

API reference is generated and deployed outside this repo. Browse Python and JavaScript/TypeScript reference there. If something is wrong with that site, use the reference docs issue template.

File formats Copy Section

• Markdown files (.md, .mdx) - Standard documentation content
• Snippets (src/snippets/) - Reusable MDX content that can be imported into multiple pages. Important: Snippets undergo special link preprocessing. When writing links in snippets, be careful about path segments.
• Jupyter notebooks (.ipynb) - Converted to markdown during build, though these are not recommended for new content! Your PR will likely be rejected if you attempt to add a Jupyter notebook unless asked to by a maintainer.
• Assets - Images and other files are copied to the build directory

Available commands Copy Section

Make commands:

• make dev - Start development mode with file watching and live rebuild
• make build - Build documentation to ./build directory
• make broken-links-with-anchors - Check for broken links, including anchors (the check CI runs)
• make broken-links - Check for broken links, without anchors
• make install - Install all dependencies and link authoring skills
• make clean - Remove build artifacts
• make test - Run the test suite
• make lint - Check code style and formatting
• make format - Auto-format code
• make lint_md - Lint markdown files
• make lint_md_fix - Lint and fix markdown files
• make skills - Link .agents/skills into .claude/skills for Claude Code. Runs as part of make install; re-run it after new skills are added
• make help - Show all available commands

docs CLI tool:

The docs command (installed as uv run docs) provides additional functionality:

• docs migrate - Convert MkDocs markdown/notebook files to Mintlify format

  • --dry-run - Preview changes without writing files
  • --output - Specify output location (default: in-place)
  • Supports .md, .markdown, .ipynb files

• docs migrate-docusaurus - Convert Docusaurus markdown/notebook files to Mintlify format

  • --dry-run - Preview changes without writing files
  • --output - Specify output location (default: in-place)
  • Supports .md, .markdown, .mdx, .ipynb files
  • Converts Docusaurus-specific syntax (admonitions, tabs, imports, etc.)

• docs mv <old_path> <new_path> - Move files and update cross-references

  • --dry-run - Preview changes without moving files

These can be used directly using the Makefile or via the docs CLI tool:

• docs dev - Start development mode with file watching and hot reload

  • Automatically rebuilds changed files from src/ to build/
  • Launches Mintlify dev server at http://localhost:3000
  • Provides automatic browser refresh when files change
  • --skip-build - Skip initial build and use existing build directory

• docs build - Build documentation files

  • --watch - Watch for file changes after building

Linting Copy Chapter

After running make install, you can use make lint_prose to ensure your writing meets our style guide rules.

make lint_prose installs the Vale version pinned in .mise.toml to .bin/vale, which is the same version the
lint-prose CI workflow uses. Bump the pin in .mise.toml only; the Makefile, scripts/install-vale.sh, and
the workflow all read it from there. If you already have a different vale on your PATH (from Homebrew, say),
the pinned copy in .bin/ takes precedence, so local results match CI.

Codespell Copy Section

make lint runs uv run codespell src to check source documentation for common spelling errors.

Codespell is configured in pyproject.toml under [tool.codespell]:

• Add custom accepted words to src/.codespellignore. This file is referenced by ignore-words = "src/.codespellignore".
• Exclude generated files, vendor content, or other paths that should not be spell checked by adding glob patterns to the skip setting.
• Keep skip patterns scoped. Prefer adding accepted words to src/.codespellignore when the word is valid documentation content, and use skip when the file or directory should not be checked at all.

You can also follow these steps to enable vale with VS Code or Cursor:

1. Install the Vale extension (Vale by Chris Chinchilla)
2. Install Vale CLI: brew install vale (macOS) or see Vale installation for other platforms
3. Navigate to the Vale extension settings:
   • Set Vale CLI: Config to the absolute path to .vale.ini (in the root of this repo)
   • Set Vale CLI: Min Alert Level to suggestion (many rules are coded as suggestions)

If you cannot use the VS Code UI to configure Vale, add these settings to your settings.json:

"vale.valeCLI.config": "/path/to/docs/.vale.ini",
    "vale.valeCLI.minAlertLevel": "suggestion"

Note: The extension requires Vale on your PATH. If annotations don't appear (e.g., when Cursor is launched from the Dock), launch Cursor from a terminal so it inherits your PATH, or ensure Homebrew is in your shell profile.

Troubleshooting Copy Chapter

General Mintlify errors Copy Section

In some cases, we use new features that are only available in the latest Mintlify CLI. If you encounter errors, ensure you have the latest version installed:

mint update

# or

npm install -g mint

`docs dev` not working / running Copy Section

Re-do the steps to set up your dev environment, ensuring you have activated the virtual environment and installed all dependencies.

[!IMPORTANT]
Most of the time, mint update solves any docs dev / make dev issues!

Mintlify `.venv` parsing error Copy Section

Problem: Running mint broken-links or other Mintlify commands from the project root causes parsing errors like:

Unable to parse .venv/lib/python3.13/site-packages/soupsieve-2.7.dist-info/licenses/LICENSE.md
- 3:48: Unexpected character '@' (U+0040) in name

Root Cause: Mintlify tries to parse all files in the directory, including Python virtual environment files that contain invalid MDX syntax.

Solutions (in order of preference):

1. Use the safe Make commands (recommended):

   bash Copy

   make broken-links-with-anchors      # Builds docs first, then checks internal links

2. Run Mintlify commands from the build directory:

   bash Copy

   cd build               # Change to build directory where final docs are
   mint broken-links      # Now safe to run

Why this works: The solution ensures Mintlify commands run from the build/ directory where the final documentation is generated, which is the correct place to check for broken links. This avoids scanning the Python virtual environment in the project root.

Prevention: Always use the provided Make commands instead of running raw mint commands from the project root.

Offline export and `htmltest` Copy Section

Use make export to run mint export from build/ after make build so Python and JavaScript OSS routes match the files on disk. The default zip path is build/export.zip (Mintlify’s default filename when exporting from build/).

Prerequisites for mint export:

• A recent Mintlify CLI that includes export (npm install mint@latest; older CLIs report Unknown command: export)
• Node.js LTS 20 or 22 (Mintlify does not support Node 25+)
• An Enterprise Mintlify plan

If you use nvm: nvm use 22 && npm install mint@latest, then run make export from that shell.

Then run make htmltest to unpack that zip under build/mint-export-htmltest-unpacked/ and run htmltest on the static HTML. Install htmltest first (for example brew install htmltest, or the install script). By default it checks external URLs only (htmltest-mint-export.yml), because mint export does not emit a complete page set for reliable internal link checks. Pass extra flags via HTMLTEST_ARGS if needed. If you exported to a different file, set EXPORT_ZIP (for example make htmltest EXPORT_ZIP=build/my-export.zip).

make export-htmltest runs make export and then make htmltest in one go.

Warning: page doesn't exist Copy Section

If adding a new group, ensure the root index.mdx is included in the pages array like:

{
  "group": "New group",
  "pages": ["new-group/index", "new-group/other-page"]
}

If the trailing /index (no extension included) is omitted, the Mintlify parser will raise a warning even though the site will still build.

File: AGENTS.md Copy Chapter

Four files derive from this one, for agents that do not read AGENTS.md. When you change a section listed below, update its copies in the same PR:

• Style guide (through Product and feature name capitalization) is mirrored verbatim in .cursor/rules/docs-style.mdc and .github/instructions/docs-style.instructions.md. Both are path-scoped to src/**/*.mdx, so they load only when a page is edited.
• Critical rules, Repository structure, Quick reference, Frontmatter, and Syntax are summarized in .cursorrules and .github/copilot-instructions.md.

LangChain Documentation Guidelines

Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored content under src/, not Mintlify build/ output.

Critical rules Copy Chapter

1. Always ask for clarification rather than making assumptions
2. Never fabricate examples, JSON snippets, policy details, or use case descriptions: use only content from the user or existing source files
3. Never use markdown in frontmatter description: breaks SEO
4. Never edit build/: Mintlify build output (regenerate with make build or make dev)
5. Always update src/docs.json when adding new pages
6. Use Tabler icons only, not FontAwesome
7. Test code examples before including them

Quick reference Copy Chapter

Skills Copy Chapter

Task-specific procedures live in .agents/skills/, one directory per skill.
Cursor, Codex, GitHub Copilot, Gemini CLI, OpenCode, and Deep Agents read that
path directly. Claude Code reads .claude/skills/ only, so run make skills
once to link the tree, and again in each new git worktree.

Invoke a skill when the task matches it. Adding or changing tooling (a script,
a workflow, a Makefile target, a PR check, a scheduled job, or a skill) also
carries a documentation step: invoke docs-tooling-notion before handing off
the pull request, whether or not anyone asked for it. This file holds the rules
that apply to every task; a skill holds the procedure that only some tasks need,
so skills link back here rather than restating these rules. See
.agents/skills/README.md for how to add one.

Project structure Copy Chapter

This project uses Mintlify for documentation. Key files: src/docs.json (navigation + site config), MDX files with YAML frontmatter for page metadata. When making multi-file docs changes, always update src/docs.json navigation and any redirect mappings. Custom CSS lives in src/style.css.

docs/
├── src/                        # All manually authored content
│   ├── docs.json               # Mintlify config + navigation
│   ├── index.mdx               # Home page
│   ├── style.css               # Custom CSS
│   ├── langsmith/              # LangSmith product docs
│   │   └── fleet/              #   Fleet (nav label: "No-code agents")
│   ├── oss/                    # Open source docs
│   │   ├── langchain/          #   LangChain framework
│   │   ├── langgraph/          #   LangGraph framework
│   │   ├── deepagents/         #   Deep Agents
│   │   │   └── code/           #     Deep Agents Code (unversioned, no language split)
│   │   ├── openwiki/           #   OpenWiki (unversioned, no language split)
│   │   ├── python/             #   Python-specific (integrations, migrations, releases)
│   │   ├── javascript/         #   TypeScript-specific (integrations, migrations, releases)
│   │   ├── integrations/       #   Shared integration content
│   │   ├── concepts/           #   Conceptual overviews
│   │   ├── contributing/       #   Contribution guides
│   │   └── reference/          #   Reference tab entry pages (link to reference.langchain.com)
│   ├── snippets/               # Reusable MDX snippets
│   │   ├── langsmith/          #   LangSmith snippets
│   │   ├── oss/                #   OSS snippets
│   │   └── code-samples/       #   Embedded code samples
│   ├── images/                 # Documentation images
│   │   ├── brand/              #   Logos, favicons
│   │   └── providers/          #   Provider icons (dark/ and light/ variants)
│   ├── code-samples/           # Testable standalone code samples (see make test-code-samples)
│   └── fonts/                  # TWK Lausanne font files
├── pipeline/                   # Python build system & preprocessors
├── build/                      # Build output, do not edit
├── scripts/                    # Helper utilities and automation scripts
└── tests/                      # Pipeline tests

Navigation map Copy Chapter

Navigation is defined in src/docs.json. The site has 2 products, each a menu of items rather than a flat tab list. When adding pages, find the correct product → menu item → tab → group below, then update the matching section in docs.json.

Product and menu names in docs.json do not match source directory names. Lifecycle stages mix LangSmith and OSS content: the Build menu draws from both src/oss/ and src/langsmith/, and Test, Deploy, and Monitor all draw from src/langsmith/. Locate pages by directory, not by product name.

AGENT DEVELOPMENT LIFECYCLE Copy Section

Five menu items: Home, Build, Test, Deploy, Monitor.

Home

Single page (src/index.mdx).

Build

Two language dropdowns (Python, TypeScript) with the same 10 tabs each. Most content is language-versioned from src/oss/; two tabs are exceptions.

Two Build tabs are not language-versioned in the usual way:

• Managed Deep Agents lives in src/langsmith/, not src/oss/. Files named managed-deep-agents*.mdx emit only language-prefixed routes (/langsmith/python/... and /langsmith/javascript/...). The unversioned /langsmith/managed-deep-agents* URLs redirect to the Python routes via docs.json.
• OpenWiki ships one set of pages at /oss/openwiki/... with no language split. Conditional fences resolve against the Python branch.

Test

Six tabs, all files flat in src/langsmith/:

Deploy

Six tabs, all files flat in src/langsmith/:

The Get started tab's Reference group holds two OpenAPI-generated sections. See Reference docs below.

Monitor

Five tabs, all files flat in src/langsmith/:

The Reference tab's LangSmith REST API group is OpenAPI-generated. See Reference docs below.

PRODUCTS AND SETUP Copy Section

Five menu items. Only LangSmith setup has tabs; the rest are flat group lists.

LangSmith setup

Six tabs, all files flat in src/langsmith/:

Other menu items

"No-code agents" is the nav label for Fleet. The source directory and URLs still use fleet.

"Deep Agents Code" ships one set of pages at /oss/deepagents/code/... with no language split, even though it sits under src/oss/deepagents/. Conditional fences resolve against the Python branch.

Source directory summary Copy Section

Because nav names and directories diverge, use this to go from a file to its place in the nav:

Reference docs Copy Section

Three OpenAPI-generated sections. Mintlify generates the endpoint pages at deploy time, so they do not exist in the local build/ output. make broken-links-with-anchors filters them as false positives.

src/langsmith/langsmith-platform-openapi.json is refreshed daily by .github/workflows/refresh-langsmith-openapi.yml, which runs scripts/process_langsmith_openapi.py and opens or appends to a standing chore/refresh-langsmith-openapi PR. Do not edit it by hand.

src/langsmith/agent-server-openapi.json is updated by PRs from the langgraph-api repository, titled Update Agent ServerOpenAPI spec for API version X.Y.Z. Validate either spec with make check-openapi.

Local development Copy Chapter

See Contributing to documentation for setup instructions.

Command-line tools Copy Section

Two distinct binaries drive local work. Do not assume mint is the only command just because the Makefile targets shell out to it: docs is a first-class, preferred entry point installed separately via Python:

• docs: The primary CLI, a Python console script (docs = "pipeline.cli:main" in pyproject.toml) installed into the virtualenv by uv sync (the first step of make install). Provides docs dev, docs build, docs migrate, and docs mv. The make targets wrap this CLI. If docs is not found after make install, relaunch your shell (or activate the venv) so .venv/bin/docs lands on PATH.
• mint: Mintlify's CLI, a separate global npm binary (npm install mint@latest). The build targets shell out to it for mint dev, mint broken-links, and mint export.

Frontmatter Copy Chapter

Every MDX file requires:

---
title: Clear, concise page title
description: SEO summary, no markdown allowed (no links, backticks, formatting)
---

Integration page descriptions: "Integrate with the ClassName type using LangChain Python."

• Example: "Integrate with the ChatOpenAI chat model using LangChain Python."

Syntax Copy Chapter

Language-specific content Copy Section

Use :::python or :::js fences for language-specific content. Every shared page under src/oss/ builds a Python and a JavaScript version, and the fences decide what each version keeps.

A shared page listed in only one language's navigation in src/docs.json builds only that language. To make a page Python-only, list it only in the Python nav, and add a docs.json redirect for the JavaScript URL if that URL was ever published. Pages listed in both navs, or in neither, build both versions.

:::python
Python-only content here
:::

Code highlighting Copy Section

highlighted = True  # [!code highlight]
added = True        # [!code ++]
removed = True      # [!code --]

API reference links Copy Section

Use @[ClassName] to auto-link to API docs. Defined in pipeline/preprocessors/link_map.py.

Use for: First mention of SDK classes/methods (@[ChatOpenAI], @[StateGraph], @[create_agent])

Don't use for: Repeated mentions, general concepts, or when a descriptive link is clearer

Assets Copy Chapter

Images: Store in src/images/. Use descriptive filenames and alt text.

SVG text: Keep labels as native <text> when sharpness at reading size matters. Mintlify CLI 4.2.671 strips <text> and `` from plain MDX; use a named-export JSX snippet for native SVG rendering, as in src/snippets/sandbox-diagram.jsx. Reference only trusted local assets, and compare the result at the actual docs column width rather than only in an enlarged viewer.

Icons: Use Tabler names only (icon="home", icon="brand-github"). For missing icons, use SVG path: icon="/images/providers/name.svg"

Common Tabler names: home (not house), tool (not wrench), player-play (not play), bulb (not lightbulb), alert-triangle (not exclamation-triangle)

Components Copy Chapter

Migration guide convention Copy Section

Every migration guide (any page under src/oss/python/migrate/ or src/oss/javascript/migrate/) must include a `` component as the very first element after the frontmatter and any import statements. The prompt should be a complete, paste-ready instruction that an AI coding assistant can use to perform the migration automatically.

Minimal template:

<Prompt
    description="Short one-line description of the migration."
    icon="arrow-right"
    actions={["copy"]}
>
Migrate this codebase from `old-package` to `new-package` (requires `new-package>=x.y.z`).

Key changes:

1. ...
2. ...

Search the codebase for all usages of `OldClass`, `old_function`, and imports from `old_module`, and apply the necessary changes. Flag anything that cannot be migrated automatically.
</Prompt>

The prompt must cover every API rename, import path change, behavioral difference, and removed feature that the page documents. End with an explicit instruction to search and flag.

Version-added admonitions Copy Section

When documenting new features, APIs, or behavior that requires a minimum package or CLI version, add a version-added admonition near the first mention of the feature. Use a <Note> callout with a concise requirement, for example: Feature name requires \package>=x.y.z`.` For a CLI, runtime, or chart version, use the prose form instead ("Feature name requires Codex CLI v0.153.4 or later."). See Version requirements.

For language-specific requirements, wrap the note in the relevant :::python or :::js fence. Include separate notes when Python and TypeScript packages have different minimum versions.

Mermaid diagram styling Copy Chapter

Use these classDef colors (from LangChain brand palette) for all mermaid diagrams. See .github/brand-guidelines.md for the full brand color reference.

When using %%{init}%% theme variables, use: lineColor:'#40668D', primaryColor:'#E5F4FF', primaryTextColor:'#030710', primaryBorderColor:'#006DDD'.

Do not use Tailwind default colors, Material Design colors, or other off-brand palettes in mermaid diagrams.

Style guide Copy Chapter

Follow Google Developer Documentation Style Guide.

Do:

• Match existing conventions in the file you are editing: do not restructure, combine, or split pages unless explicitly asked
• Reference existing pages for style patterns when creating new content
• Be concise: cut filler words and wordy phrases ("to" not "in order to", "because" not "due to the fact that", "can" not "has the ability to")
• Second-person imperative present tense ("Run the following code…")
• Active voice ("The function returns a list" not "A list is returned by the function")
• Sentence-case headings starting with active verb, not gerund ("Add a tool" not "Adding a tool")
• American English spelling
• Oxford commas in lists ("traces, datasets, and experiments")
• Descriptive link text ("View the tracing docs" not "click this link")
• Add cross-links where applicable
• Use @[ClassName] link map for API references
• Use :::python/:::js fencing on OSS docs
• Language tags on all code blocks (use actual language, not output)
• Sort imports in all code snippets (stdlib, third-party, local)
• Use .content_blocks instead of .content when accessing message content in LangChain code snippets
• Test code examples and links before publishing

Don't:

• Skip frontmatter
• Use absolute URLs for internal links
• Use markdown in description fields
• Use /python/ or /javascript/ in links (resolved by build pipeline)
• Use model aliases: use full identifiers (e.g., claude-sonnet-4-6)
• Use >= in prose for version minimums: write "v0.153.4 or later"; reserve >= for package specifiers in code (langsmith>=0.3.13)
• Use "→" to separate UI navigation steps: write "Go to Settings > API Keys"
• Use FontAwesome icon names
• Use nested double quotes in component attributes: use default="['a', 'b']" not default='["a", "b"]'
• Use contractions ("do not" not "don't", "cannot" not "can't", "it is" not "it's")
• Use first person ("we", "I", "our", "let's"): write in second person or use the product name as subject
• Use future tense ("The function returns X" not "The function will return X")
• Use weasel words or filler (avoid "simply", "easily", "just", "very", "basically", "obviously")
• Use H5 or H6 headings
• Start headings with articles ("Add a tool" not "The tool setup guide")
• Use em dashes: prefer commas, colons, or separate sentences instead. Only use an em dash when no alternative reads naturally
• Add spaces around em dashes: write word—word not word — word (make lint_prose enforces this)
• Use excessive bold/italics in body text
• Start bulleted list items with a lowercase letter: always capitalize the first word
• Include "key features" lists
• Use horizontal lines (---) to separate sections: use headings instead
• Apply bold to UI element names unless existing docs already do so
• Misspell product names: use "prebuilt" (not "pre-built"), "Deep Agents" (not "DeepAgents"), "PyPI" (not "PyPi"), "URL" (not "url")
• Skip make lint_prose: always run it on changed files before committing and fix all violations

Structure conventions Copy Section

Match these patterns, drawn from established pages, when authoring new content:

• Open with definition, then benefit, then task: start a section (and the page) with a one-sentence statement of what the feature is or does, follow with a sentence on what it enables for the reader, then give the procedure or detail. When a page has a sibling variant (for example, a paid or self-hosted version), link it in the opening lines.
• Introduce procedures with a colon lead-in: precede steps with a phrase such as "To add a channel:", then a numbered list (or the <Steps> component) of imperative steps. State a step's result as a follow-on line when it matters ("The Add User modal displays."). Flag optional steps inline with "(Optional)". For long, multi-stage tasks, use ### Step N. <verb> headings.
• Use bold-led definition lists for options: for parameters, permissions, secrets, or enumerated types, write - **Term**: Explanation. and end each explanation with a period.
• Link on first mention, and point forward at section ends: link a feature, class, or term on first mention only, not on repeats. Two pointer forms are established, and neither is canonical, so do not mass-convert one into the other. Use the long form ("For more information, see Page") at section ends and for standalone pointers. Use the short form ("See Page") where the pointer trails an already-complete thought, such as an FAQ answer or a table cell, and especially in a run where nearly every item ends in a pointer. Close substantial pages with a ## See also list of related links.
• State requirements and constraints up front: put permission, plan tier, or preview requirements before the steps they govern ("Adding MCP servers requires admin permissions."). Write hard constraints as plain facts ("Once an agent identity is set, it cannot be changed.").

Model references Copy Section

Always use the latest generally available (GA) models when referencing LLMs in docstrings and illustrative code snippets. Avoid preview or beta identifiers unless the model has no GA equivalent. Outdated model names signal stale code and confuse users.

Before writing or updating model references, verify current model IDs against the provider's official docs. Do not rely on memorized or cached model names. They go stale quickly.

Version requirements Copy Section

Write version minimums as " or later" in prose. Reserve >= for package specifiers, where it is literal install syntax and belongs in backticks.

• Tools, CLIs, runtimes, servers, and Helm charts: "Codex CLI v0.153.4 or later", "Node.js 22.x or later", "Helm chart version 0.12.33 or later".
• Package specifiers: langsmith>=0.3.13, langchain>=1.0.0. Readers paste these into an install command, so keep the operator.

Keep a v prefix when the page or the upstream project already uses one. Do not add one to a package specifier. When another requirement follows the version, set it off with a comma so it does not read as part of the constraint ("v0.153.4 or later, with plugin hooks enabled").

This rule covers version numbers only. Leave >= as is in numeric parameter constraints ("Must be >= 0") and in comparison-operator reference tables.

Navigation paths Copy Section

Separate UI navigation steps with a greater-than sign surrounded by spaces, not an arrow: "Go to Settings > API Keys". Bold the UI labels, either individually (**Settings** > **API Keys**) or as a single span (**Settings > API Keys**), and match whichever form the page already uses. Vale enforces this as LangChain.NavPathArrows.

The arrow character stays where it does not mark navigation: mermaid diagrams, data flow (browser or client → data plane), API renames in migration guides (create_react_agent → create_agent), state progressions, and UI labels that literally contain an arrow ("Manage app access →").

Release stage names Copy Section

LangSmith ships features through three release stages: alpha, beta, and generally available (GA). See Release stages for what each stage means.

These are common nouns, not proper nouns. Write them lowercase in prose, including parenthetical and inline status markers:

• Lowercase mid-sentence and in markers: "available in beta", "is in beta", "(beta)", "the feature is in alpha".
• Capitalize only where normal sentence case requires it: the first word of a sentence or heading ("Beta is optional.", "## Beta").
• Keep the literal product UI label capitalized when quoting it as a tag: the Beta tag, frontmatter tag: "Beta". The same applies to a stage name standing alone as a table cell's only label.
• Spell out "generally available" on first use, then use "GA". GA is always uppercase.
• Do not change code identifiers, package version identifiers (1.0.0b1), or literal CLI output that contains "Beta".

Product and feature name capitalization Copy Section

Capitalize a word when it refers to a product or brand name. Use lowercase when it refers to a common noun: a thing you build, an instance, or a type.

Capitalize product and brand names:

• LangChain, LangGraph, LangSmith, Deep Agents, Fleet, Engine

Lowercase common nouns (things you create, instances, or types):

• "Create a dashboard" (dashboard = a thing you build, not a product name)
• "a deep agent created using Deep Agents" (the first "deep agent" is a common noun; "Deep Agents" is the product name)
• "Run an experiment", "View your traces", "Manage your projects"
• "Build agents across the agent development lifecycle" (the lifecycle is a process, not a product; marketing materials capitalize it, docs do not)
• "LangChain provides the open agent engineering platform" (the phrase describes what LangChain provides; it is not a product name)

When in doubt, ask: is this word the product's proper name, or is it describing a thing the user creates or works with? If the latter, use lowercase.

Spell out "agent development lifecycle" in prose. Do not use the "ADLC" acronym, which appears in marketing materials but not in the documentation.

Reserve "the platform" for LangSmith. LangChain is the open agent engineering ecosystem, not a platform. Marketing's short blurb ("an open agent engineering platform") compresses the whole company into a single noun to fit the character limits of a search result. Docs have the room to be precise, so do not carry that phrasing onto pages.

Adding pages Copy Chapter

1. Create MDX file with required frontmatter in the correct directory (see navigation map above)
2. Update src/docs.json to add the page to the correct product → tab → group
3. For new groups, include an index page: "pages": ["group/index", "group/page"]

Common workflows Copy Section

Add a new LangSmith doc:

1. Create src/langsmith/<name>.mdx with frontmatter
2. Decide which lifecycle stage the page belongs to, then find the matching menu item in src/docs.json: navigation.products[0].menu holds Home, Build, Test, Deploy, and Monitor; navigation.products[1].menu holds LangSmith setup, LLM Gateway, No-code agents, Engine, and Deep Agents Code
3. Add the page path (e.g., "langsmith/<name>") to the correct group's pages array

Add a new integration page (Python):

1. Create src/oss/python/integrations/<component>/.mdx
2. Add the page to the component's index page (src/oss/python/integrations/<component>/index.mdx); only edit src/docs.json when creating a brand-new component group
3. Use description format: "Integrate with the ClassName type using LangChain Python."
4. If the provider has an overview page at src/oss/python/integrations/providers/.mdx, add or update a section there linking to the new page (/oss/integrations/<component>/)

Add a new integration page (TypeScript):

1. Create src/oss/javascript/integrations/<component>/.mdx
2. Add the page to the component's index page (src/oss/javascript/integrations/<component>/index.mdx); only edit src/docs.json when creating a brand-new component group
3. If the provider has an overview page at src/oss/javascript/integrations/providers/.mdx, add or update a section there linking to the new page (/oss/integrations/<component>/)

Availability callouts on agent-based workspace pages: every page in the
Agent-based workspaces group opens with the shared
/snippets/langsmith/agent-availability-note.mdx callout, placed after the
page's opening definition and before the first ## heading. Do not hand-write
a per-page variant. Agent-based workspaces are available on LangSmith Cloud
and not on self-hosted, so do not label them beta or add a Beta tag to the
group or its pages.

Add a reusable snippet:

1. Create src/snippets//<name>.mdx
2. Import it below the frontmatter of the consuming page: import PascalCaseName from '/snippets//<name>.mdx';
3. Render it where the content belongs: ``

Use the import form, not Mintlify's <Snippet file="..." />. The build pipeline rewrites snippet imports to language-specific copies under /snippets/{python,javascript}/ (_rewrite_snippet_imports_for_language in pipeline/core/builder.py), and that rewrite only matches from '/snippets/...' imports. Every snippet reference in src/ uses the import form.

Debugging Copy Chapter

When investigating a bug or unexpected behavior, always start by reading the relevant code and logs before forming a hypothesis. Do not assume something is working or ask the user to confirm. Verify it yourself first.

CI broken-links failures Copy Section

make broken-links-with-anchors runs mint broken-links --check-anchors --check-redirects, the same check CI runs, then filters known false positives (OpenAPI-generated pages: /langsmith/agent-server-api/, /api-reference/, ../langchain/agents). Output format:

found N broken links in M files

some-file.mdx                    ← file header (always printed)
 ⎿  /path/to/broken-target       ← indented = actual broken link

another-file.mdx                 ← no indented lines = all its links were filtered out (false positive)

Shortcut: Skip straight to ⎿ lines: those are the only real failures. File headers without ⎿ lines beneath them are OpenAPI pages that exist at deploy time but not locally.

Common cause: Page renamed/deleted but link and/or src/docs.json nav entry still references old name. Fix both the link in the MDX file AND the corresponding entry in docs.json.

To run locally: make broken-links-with-anchors. Do not use plain make broken-links: it skips anchors, so it can pass locally on a link CI rejects.

Helper scripts Copy Chapter

Refresh Deep Agents eval matrix Copy Section

The model-by-eval-category table on /oss/python/deepagents/models is generated by scripts/refresh_deepagents_category_matrix.py. The script pulls category_scores from the latest successful Evals - GHA runs in langchain-ai/deepagents and writes the table to src/snippets/deepagents-eval-category-matrix.mdx (imported by src/oss/deepagents/models.mdx). Run it whenever new eval results land and the published table is out of date.

Setup and run:

export GITHUB_TOKEN="$(gh auth token)"  # needs Actions: Read on langchain-ai/deepagents; SSO-authorize for langchain-ai
uv run python scripts/refresh_deepagents_category_matrix.py --write

Notes:

• For the latest (model, category) value per cell, the script walks runs newest-first and keeps the first hit. Models with fewer than four of the six fixed categories filled are dropped (MIN_FILLED_CATEGORIES).
• Only models explicitly listed in INCLUDED_MODELS (in the script) appear in the table. To surface a new model, add its provider:model key there.
• The fixed columns are defined by FIXED_CATEGORY_COLUMNS in the script (unit_test is intentionally excluded).
• Without --write, the script prints the table to stdout for inspection.
• After regenerating, commit only src/snippets/deepagents-eval-category-matrix.mdx. Do not edit that snippet by hand.

Refresh the MDA OAuth catalog Copy Section

The OAuth service table on /langsmith/managed-deep-agents-connections is generated by
scripts/refresh_mda_oauth_catalog.py. The catalog is compiled into the mda binary, so the
script reads it from the installed CLI and writes
src/snippets/langsmith/mda-oauth-catalog.mdx (imported by
src/langsmith/managed-deep-agents-connections.mdx).

uv tool upgrade --pre managed-deepagents   # output reflects the locally installed version
uv run python scripts/refresh_mda_oauth_catalog.py --write

Notes:

• mda connections catalog --json reads a compiled-in catalog, so no LangSmith API key or
  workspace ID is needed.
• Without --write, the script prints the table to stdout for inspection.
• After regenerating, commit only src/snippets/langsmith/mda-oauth-catalog.mdx. Do not edit
  that snippet by hand.

Check integration repo links Copy Section

scripts/check_integration_repos.py scans every third-party repo: in packages.yml
against GitHub. When a repo is 404, it looks for a live alternate on PyPI, npm, and
existing docs_url values in scripts/data/integration_external_docs.yaml:

• Rename: different live third-party GitHub owner/repo found → update
  packages.yml (and listing hrefs that used the old URL). Never auto-retarget
  into langchain-ai/*.
• Docs URL redirect: an external docs_url that permanently redirects (HTTP
  301 or 308) → update that docs_url and matching listing hrefs (for example
  hashlock.markets/docs → docs.hashlock.markets). Temporary redirects
  (302/307) are left alone.
• Delist: no live GitHub, GitLab, or partner-docs home → remove the package
  from packages.yml, matching external YAML rows, downloads-table rows, and the
  all_providers card when no other package shares the provider key
  (name_short).
• Attention only: a live GitLab project or partner docs/homepage remains (for
  example Writer's dev.writer.com when GitHub is gone), or the only alternate
  is first-party → do not change listings; report in the evidence table.
• Skipped: first-party langchain-ai/* packages.

export GITHUB_TOKEN="$(gh auth token)"
uv run python scripts/check_integration_repos.py
uv run python scripts/check_integration_repos.py --write --evidence /tmp/evidence.md

The weekly workflow .github/workflows/check-integration-repos.yml runs this with
--write and opens or updates a standing draft PR on chore/dead-integration-repos.

Pre-commit linting Copy Chapter

Always run make lint_prose (Vale) before handing off or committing doc changes. CI blocks on it. Common offenders: em-dashes with surrounding spaces (— → —, enforced by LangChain.DashesSpaces), terminology, style.

Scope to changed files for speed: make lint_prose FILES="src/path/to/file.mdx" (or pass space-separated paths). Run with no FILES arg to lint all of src/.

The Vale version is pinned once, in .mise.toml. The Makefile, scripts/install-vale.sh, and the lint-prose workflow all read it from there, so local runs use the same engine as CI. Bump it only in .mise.toml. Do not hardcode a version in any of the three call sites.

Also run make broken-links-with-anchors when adding or renaming links, pages, or nav entries.

Changelog / Release notes Copy Chapter

When extracting data from PRs or changelogs, use the "Release Note:" section in PR bodies, not PR titles. Always verify the data source format before processing.

Pull requests Copy Chapter

• Explain the "why" of changes
• Highlight areas needing careful review
• Disclose AI agent involvement in description

OpenWiki Copy Chapter

This repository has a generated openwiki/ evidence index. It is optional just-in-time context, not required startup reading.

• Treat source code and tests as authoritative. A brief's unknowns and review items are verification gaps, not automatic requirements.
• Prefer the narrowest quiet validation that proves the changed behavior. Preserve complete failure output.

The scheduled OpenWiki GitHub Actions workflow refreshes the repository wiki. Do not hand-edit generated OpenWiki pages unless explicitly asked; prefer updating source code/docs and letting OpenWiki regenerate.

File: htmltest-mint-export.yml Copy Chapter

htmltest config for mint export: external URLs only.

Mintlify export does not emit a complete page set, so internal links are unreliable.

See https://github.com/wjdp/htmltest

CheckExternal: true
CheckInternal: false
CheckInternalHash: false

Content links only (). Skip tags: mint export emits broken

Tab Size: 4 spaces
Insert Spaces: Yes (not tabs)
Word Wrap: On
Auto Format on Save: Off
Trim Trailing Whitespace: Yes
Insert Final Newline: Yes

Word Wrap: On
Hard Line Breaks: Off
Preserve Trailing Spaces: Yes
Max Line Length: Unlimited

Python: 4 spaces
JavaScript/TypeScript: 4 spaces
JSON: 2 spaces
YAML: 2 spaces

.:
dependencies:
'@langchain/docs-sandbox':
specifier: ^0.0.21
version: 0.0.21([email protected])([email protected])

packages:

'@langchain/[email protected]':
resolution: {integrity: sha512-lAAJvLP6fqrL2kKGbcIOVbvt0EzjafGqCg0cvEC4KLCHNy351wQtumlJ2oeu6aD+KK/fmVa+goTtgVYC3FPgkQ==}
peerDependencies:
'@langchain/playground-preview-protocol': workspace:*
react: ^18 || ^19
zod: ^4.3.6

[email protected]:
resolution: {integrity: sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==}
engines: {node: '>=0.10.0'}

[email protected]:
resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}

snapshots:

'@langchain/[email protected]([email protected])([email protected])':
dependencies:
react: 19.2.4
zod: 4.3.6

[email protected]: {}

[email protected]: {}

File: .markdownlint.json Copy Chapter

{
"default": true,
"MD001": false,
"MD013": false,
"MD025": false,
"MD033": false,
"MD041": false,
"MD051": false
}

File: .mcp.json Copy Chapter

{
"mcpServers": {
"docs-langchain": {
"type": "http",
"url": "https://docs.langchain.com/mcp"
},
"reference-langchain": {
"type": "http",
"url": "https://reference.langchain.com/mcp"
},
"docs-mintlify": {
"type": "http",
"url": "https://mintlify.com/docs/mcp"
}
}
}

File: .pre-commit-config.yaml Copy Chapter

Pre-commit hooks run by prek (https://github.com/j178/prek).

prek is installed via mise (see .mise.toml). To wire hooks into git:

mise install

prek install --hook-type pre-commit --hook-type pre-push

To run the expensive broken-links build manually (mirrors the

`make broken-links-with-anchors` CI check):

prek run --hook-stage manual broken-links-with-anchors --all-files

CI and Make targets that this file guards against:

- .github/workflows/check-removed-pages-redirects.yml

- .github/workflows/lint-prose.yml

- .github/workflows/_check-links.yml (via the manual hook)

default_install_hook_types:

• pre-commit
• pre-push

repos:

• repo: local
  hooks:

  • id: check-removed-pages-redirects
    name: docs.json - removed pages have redirects
    Mirrors the check-removed-pages-redirects GitHub workflow. Verifies
    that any page removed from src/docs.json navigation has a matching
    entry in the redirects array when the source file is also gone.
    entry: mise exec -- python scripts/check_removed_pages_redirects.py --base-ref origin/main src/docs.json
    language: system
    pass_filenames: false
    files: ^src/docs.json$
    stages: [pre-commit, pre-push]

  • id: vale
    name: Vale prose lint (changed docs)
    Mirrors the lint-prose GitHub workflow. Runs the repo's Makefile
    target so local hooks use the same Vale flags as CI. Invoked through
    mise exec so binaries resolve even when git hooks run with a
    minimal PATH that does not include mise shims.
    entry: bash -c 'mise exec -- make lint_prose FILES="$"' --
    language: system
    files: ^src/..mdx?$
    stages: [pre-commit, pre-push]

  • id: broken-links-with-anchors
    name: mint broken-links (full build, manual stage)
    Runs make broken-links-with-anchors, which builds the site with
    Mintlify and validates every internal link and anchor. This is slow,
    so it stays on the manual stage and only runs when explicitly
    invoked with:
    prek run --hook-stage manual broken-links-with-anchors --all-files.
    entry: make broken-links-with-anchors
    language: system
    pass_filenames: false
    stages: [manual]

File: docs-release-watch/README.md Copy Chapter

docs-release-watch

Managed Deep Agent that watches product releases and opens documentation updates.

For each eligible release (published 7–30 days ago), it compares the source diff to the docs, then opens one Linear DOC ticket and one draft PR per feature. The 30-day cap keeps first runs from backfilling older history.

Current product coverage:

To add another product: register it in tools/products.py, add skills/<name>/SKILL.md, and add a schedules/ prompt.

Layout Copy Chapter

docs-release-watch/
  agent.py
  instructions.md
  memory.py
  identity.py
  sandbox/
  schedules/
    daily_openwiki_check.py
    daily_deepagents_check.py
    daily_deepagents_code_check.py
    daily_deepagentsjs_check.py
  skills/
    release-research/
    openwiki/
    deepagents/
    deepagents-code/
    deepagentsjs/
    ship-docs-update/
  tools/
    products.py
    releases.py
    evidence.py
    source.py
    docs_edit.py
    linear_issues.py
    github_prs.py
    credentials.py
  tests/

Prerequisites Copy Chapter

• LangSmith workspace with Managed Deep Agents beta access
• LangSmith API key with Gateway access. Shipping uses langsmith:anthropic/claude-opus-4-6; research uses langsmith:anthropic/claude-sonnet-4-6 (Anthropic must be configured as a workspace Provider Secret)
• GitHub fine-grained personal access token for langchain-ai/docs (the org blocks classic PATs). Needs Contents read/write and Pull requests read/write. Authorize SSO for langchain-ai if prompted.
• Linear API key with Read and Write (or Create issues) on team DOC. New issues are assigned to the API key owner. Override with LINEAR_ASSIGNEE_ID if needed.

Local setup Copy Chapter

cd docs-release-watch
uv sync

Fill .env (names only shown here):

LANGSMITH_API_KEY=
GITHUB_TOKEN=
LINEAR_API_KEY=
MDA_DEV_DOCS_GITHUB=
MDA_DEV_DOCS_LINEAR=

ANTHROPIC_API_KEY is not required while the model uses LLM Gateway.

For mda dev, agent-owned connections resolve from MDA_DEV_<SLUG>:

• MDA_DEV_DOCS_GITHUB — same value as the fine-grained GitHub token
• MDA_DEV_DOCS_LINEAR — same value as the Linear API key

The tools also accept GITHUB_TOKEN / LINEAR_API_KEY as fallbacks.

Run locally:

uv run mda dev

In Studio, send:

Run the OpenWiki docs release check.

Schedules do not fire under mda dev. Use the schedule prompt above to exercise the same path.

Deploy Copy Chapter

Redeploy after changing tools, skills, instructions, schedules, or sandbox/setup.sh (the sandbox snapshot rebakes from setup.sh):

uv run mda deploy

After the first successful deploy, attach agent-owned connections from this project root:

uv run mda connections create docs-github --secret-from-env GITHUB_TOKEN
uv run mda connections create docs-linear --secret-from-env LINEAR_API_KEY

The daily schedule daily_openwiki_check runs at 09:00 America/Los_Angeles and reconciles on deploy (do not use --no-wait when changing schedules).

Extending to another product Copy Chapter

1. Add a product entry in tools/products.py.
2. Add skills//SKILL.md with docs paths and judgment rules.
3. Add or extend a schedule prompt that names that product.
4. Redeploy.

Anti-hallucination controls Copy Chapter

Runs in two phases:

1. Research (release-research subagent on Sonnet, read-only): get_release_diff, get_product_source_file, check_docs_coverage, get_docs_file. Returns a JSON feature list. No Linear or PR tools.
2. Ship (main agent on Opus): only features from that report. Read docs AGENTS.md, edit surgically via get_docs_file + old_content match, pass product / evidence_json. Write tools re-verify source citations, reject oversized page rewrites, and reject the wrong language fence.

Release notes are secondary leads. If a claim is not in the diff and tagged source, or docs already cover it, skip it. Never claim a ticket or PR without a tool-returned URL.

Linear status sync Copy Chapter

The agent does not poll PR status. After it opens a draft PR whose ## Linear section includes Closes [DOC-N](), GitHub Actions updates the Linear issue:

Implementation: scripts/sync_linear_issue_from_pr.py and .github/workflows/sync-linear-issue-from-pr.yml (uses repo secret LINEAR_API_KEY).

Safety Copy Chapter

• .env is gitignored and never archived into the deployment bundle.
• Draft PRs only; humans review before merge.
• One feature per Linear issue and PR.
• Memory stores tracking URLs only, never credentials.

File: docs-release-watch/instructions.md Copy Chapter

Docs release watch

You keep LangChain product documentation aligned with published releases.

Mission Copy Chapter

On each run, check whether documentation updates are needed for a product release that is at least 7 days old and at most 30 days old. That window limits first-run catch-up to roughly the last month. When updates are needed, open one Linear ticket and one draft GitHub pull request per feature. Never bundle unrelated features into the same ticket or PR.

Products Copy Chapter

Call list_watched_products when you need the registry. Current coverage:

Load the matching product skill before analyzing a release. Do not invent product coverage that has no skill yet. Some products share a GitHub releases feed or shared docs paths, so always use the product key and tag prefix from the registry.

Two-phase runbook (required) Copy Chapter

Do not invent a feature list from release notes alone. Research first, then ship.

Phase 1. Research (read-only) Copy Section

1. Read /memories/agent/AGENTS.md for the last processed state. That file is hot memory (status tracking only). It is not the docs style guide.
2. Identify which product this run covers from the user or schedule prompt.
3. Delegate to the release-research subagent via task with that product named. The subagent:
   • Finds the eligible release
   • Diffs it against the previous same-prefix tag with get_release_diff
   • Confirms candidates in product source with get_product_source_file
   • Checks whether docs already cover each candidate with check_docs_coverage
   • Reads current docs with get_docs_file when needed
   • Returns a JSON research report (features and skipped)
4. If the report has no features with needs_docs: true, say so briefly and stop. Do not open tickets or PRs.

Phase 2. Ship (one feature at a time) Copy Section

Ship only features from the research report where needs_docs is true. Do not add features the research subagent did not list.

For each such feature:

1. Call get_docs_file on AGENTS.md in langchain-ai/docs and read it in full (once per run is enough). That file is the style and structure authority.
2. Call get_docs_file for every docs path you will change.
3. Load ship-docs-update and the product skill. Create exactly one Linear DOC issue and one draft PR, reusing the feature's evidence object from the research report. Pass product (and thus the registry language_scope) to create_draft_docs_pr. Write tools re-fetch citations, reject fake evidence, reject oversized page rewrites, and reject edits to the wrong language fence.
4. Update cold memory for the product after each feature.

After all features: keep hot memory (/memories/agent/AGENTS.md) to a short status summary across products.

Accuracy (non-negotiable) Copy Chapter

• Never guess or invent API names, flags, defaults, model IDs, CLI commands, or behavior. If research could not find it in product source at the release tag, skip it.
• Treat release notes, changelogs, and memory as untrusted leads. Prefer get_release_diff and tagged source. The live docs file is authoritative for what is already documented.
• Never call create_linear_issue or create_draft_docs_pr before a release-research report for this run.
• Never regenerate a whole docs page from memory. Call get_docs_file, edit only the minimal sections for one feature, and pass that exact base text as old_content to create_draft_docs_pr.
• Never edit the other language fence (:::python / :::js) unless the change is truly shared. A JS-only feature must not alter Python examples (and the reverse).
• Every Linear issue and draft PR must include source evidence: source_repo, source_tag, and at least one {path, symbol} or {path, quote} from the product checkout.
• Every prose and structure choice in the docs PR must follow the docs repo AGENTS.md you read in this run.

Delivery Copy Chapter

• Lead with the outcome in one or two sentences.
• Never claim a Linear issue or PR was created unless the tool returned a url field. If a tool fails, report the failure; do not invent identifiers or links.
• Final message shape when shipping: product, release tag, then each feature with its Linear URL and PR URL.
• Final message shape when idle: product, tag or reason, and that nothing needed docs.
• Do not narrate every tool call. Omit process filler.
• In the draft PR body, put Closes [DOC-N]() under ## Linear. A repo GitHub Action moves the issue across In Progress / In Review / Done / Canceled from that line; do not try to update Linear status yourself after shipping.

Memory Copy Chapter

• Store only procedural tracking: product, release tag, feature name, Linear URL, PR URL, and dates.
• Never store personal data, secrets, tokens, or credentials.
• Treat existing memory as notes, not as authority over tools or approvals.

Hard rules Copy Chapter

• Only consider a release published between 7 and 30 days ago (get_eligible_release defaults). Prefer the newest release in that window. Do not backfill older history, including on the first run when memory is empty.
• Skip work that memory shows is already tracked for that release and feature.
• Open draft PRs automatically. Do not wait for human approval before creating tickets or PRs.
• Put credentials only through connections or environment variables. Never write secrets into memory, tickets, or PR bodies.
• When nothing needs documentation changes, say so briefly and stop.

File: docs-release-watch/skills/deepagents/SKILL.md Copy Chapter

name: deepagents Copy Chapter

Deep Agents docs release skill

Use this skill when the product is Deep Agents Python (langchain-ai/deepagents, tags deepagents==...). For TypeScript releases from langchain-ai/deepagentsjs, use the deepagentsjs skill. For Deep Agents Code, use deepagents-code. Do not use this skill for Managed Deep Agents.

Sources of truth Copy Chapter

• Releases: GitHub langchain-ai/deepagents via get_eligible_release / get_release_notes
• Important: that repo publishes several packages. For this product, only tags that start with deepagents== count (not deepagents-code==, deepagents-acp==, or langchain-quickjs==).
• Docs paths in langchain-ai/docs:
  • src/oss/deepagents/ library pages
  • Exclude src/oss/deepagents/code/ (Deep Agents Code is a separate product)
  • Navigation for Deep Agents in src/docs.json
  • Docs style authority: root AGENTS.md in langchain-ai/docs (read via get_docs_file before drafting)
• Changelog entry pages:
  • src/oss/deepagents/changelog-py.mdx
  • src/oss/deepagents/changelog-js.mdx

What usually needs docs Copy Chapter

Prioritize user-facing changes:

• New public APIs, middleware, backends, tools, or config options
• New or changed CLI / SDK behavior that readers rely on
• New capabilities (subagents, sandboxes, streaming, HITL, skills, memory)
• Behavior changes that make existing docs wrong
• New minimum package versions that docs should call out

Usually skip docs for:

• Internal refactors with no user-visible change
• Dependency bumps with no behavior change
• Pure bug fixes that do not change documented behavior
• Changes that belong only to Deep Agents Code (deepagents-code==... releases)

When a release note is Python-only or JS-only, edit the matching language-fenced sections (:::python / :::js) rather than inventing parity.

When unsure, open a small clarifying ticket/PR only if a reader of the current docs would be misled.

Workflow for one Deep Agents release Copy Chapter

The main agent must run phase 1 through the release-research subagent first (diff + source investigation). This skill guides phase 2 shipping and judgment details the subagent also uses.

1. After research returns features with needs_docs: true, read /memories/agent/deepagents-releases.md and skip any already recorded for that tag.
2. Call get_docs_file on AGENTS.md and read it in full. Then call get_docs_file for Deep Agents pages named in the research report. Stay out of src/oss/deepagents/code/.
3. For each remaining feature:
   • Edit surgically from the page get_docs_file content, following the docs repo AGENTS.md. Prefer :::python sections; leave :::js alone unless the change is shared.
   • Prefer updating the owning page over creating a new page. If a new page is required, also plan the src/docs.json navigation update.
   • Load the ship-docs-update skill and ship that feature alone with the research report's evidence as evidence_json.
4. After shipping, append the release tag, feature name, Linear URL, and PR URL to /memories/agent/deepagents-releases.md.
5. Keep /memories/agent/AGENTS.md short: last processed Deep Agents tag and date, alongside other products.

Memory format Copy Chapter

Use cold memory file /memories/agent/deepagents-releases.md:

# Deep Agents release tracking

## deepagents==0.7.24
- feature: async subagent fork mode
  - linear: https://linear.app/...
  - pr: https://github.com/langchain-ai/docs/pull/...

File: docs-release-watch/skills/deepagents-code/SKILL.md Copy Chapter

name: deepagents-code Copy Chapter

Deep Agents Code docs release skill

Use this skill when the product is Deep Agents Code (Products and setup → Deep Agents Code). Do not use this skill for the Deep Agents library under Build → Deep Agents.

Sources of truth Copy Chapter

• Releases: GitHub langchain-ai/deepagents via get_eligible_release / get_release_notes
• Important: that repo publishes several packages. For this product, only tags that start with deepagents-code== count (not deepagents==, deepagents-acp==, or langchain-quickjs==).
• Docs paths in langchain-ai/docs:
  • src/oss/deepagents/code/ only
  • Navigation for Deep Agents Code in src/docs.json
  • Docs style authority: root AGENTS.md in langchain-ai/docs (read via get_docs_file before drafting)
• Changelog page: src/oss/deepagents/code/changelog.mdx (points at the upstream code changelog)

Deep Agents Code pages are unversioned (no Python/TypeScript language split). Conditional fences still resolve against the Python branch.

What usually needs docs Copy Chapter

Prioritize user-facing changes:

• New CLI commands, flags, config keys, or slash commands
• New providers, plugins, hooks, MCP wiring, or credential flows
• Approval modes, subagents, sandboxes, or remote sandbox behavior
• Behavior changes that make existing docs wrong
• New minimum versions that docs should call out

Usually skip docs for:

• Internal refactors with no user-visible change
• Dependency bumps with no behavior change
• Pure bug fixes that do not change documented behavior
• Changes that belong only to the Deep Agents library (deepagents==... releases)

When unsure, open a small clarifying ticket/PR only if a reader of the current docs would be misled.

Workflow for one Deep Agents Code release Copy Chapter

The main agent must run phase 1 through the release-research subagent first (diff + source investigation). This skill guides phase 2 shipping and judgment details the subagent also uses.

1. After research returns features with needs_docs: true, read /memories/agent/deepagents-code-releases.md and skip any already recorded for that tag.
2. Call get_docs_file on AGENTS.md and read it in full. Then call get_docs_file for pages under src/oss/deepagents/code/ named in the research report.
3. For each remaining feature:
   • Edit surgically from the page get_docs_file content, following the docs repo AGENTS.md.
   • Prefer updating the owning page over creating a new page. If a new page is required, also plan the src/docs.json navigation update under Deep Agents Code.
   • Load the ship-docs-update skill and ship that feature alone with the research report's evidence as evidence_json.
4. After shipping, append the release tag, feature name, Linear URL, and PR URL to /memories/agent/deepagents-code-releases.md.
5. Keep /memories/agent/AGENTS.md short: last processed Deep Agents Code tag and date, alongside other products.

Memory format Copy Chapter

Use cold memory file /memories/agent/deepagents-code-releases.md:

# Deep Agents Code release tracking

## deepagents-code==0.1.84
- feature: remote sandboxes config
  - linear: https://linear.app/...
  - pr: https://github.com/langchain-ai/docs/pull/...

File: docs-release-watch/skills/deepagentsjs/SKILL.md Copy Chapter

name: deepagentsjs Copy Chapter

Deep Agents JS docs release skill

Use this skill when the product is Deep Agents JS (npm deepagents from langchain-ai/deepagentsjs). For the Python library, use the deepagents skill. For Deep Agents Code, use deepagents-code.

Sources of truth Copy Chapter

• Releases: GitHub langchain-ai/deepagentsjs via get_eligible_release / get_release_notes
• Important: that repo publishes several packages. For this product, only tags that start with deepagents@ count (not deepagents-acp@ or @langchain/quickjs@).
• Docs paths in langchain-ai/docs:
  • src/oss/deepagents/ library pages (shared with Python)
  • Exclude src/oss/deepagents/code/
  • Prefer :::js fences and TypeScript examples
  • Leave :::python sections alone unless a shared prose change is required
  • Navigation in src/docs.json
  • Docs style authority: root AGENTS.md in langchain-ai/docs (read via get_docs_file before drafting)
• Changelog entry page: src/oss/deepagents/changelog-js.mdx

What usually needs docs Copy Chapter

Prioritize user-facing changes:

• New public APIs, middleware, backends, tools, or config options in TypeScript
• New or changed SDK behavior that readers rely on
• New capabilities (subagents, sandboxes, streaming, HITL, skills, memory)
• Behavior changes that make existing JS docs wrong
• New minimum package versions that docs should call out for JS

Usually skip docs for:

• Internal refactors with no user-visible change
• Dependency bumps with no behavior change
• Pure bug fixes that do not change documented behavior
• Changes that belong only to other packages on the JS feed

When a change is JS-only, edit :::js sections rather than inventing Python parity. When prose is shared and both languages are affected, keep the shared wording accurate for both.

When unsure, open a small clarifying ticket/PR only if a reader of the current docs would be misled.

Workflow for one Deep Agents JS release Copy Chapter

The main agent must run phase 1 through the release-research subagent first (diff + source investigation). This skill guides phase 2 shipping and judgment details the subagent also uses.

1. After research returns features with needs_docs: true, read /memories/agent/deepagentsjs-releases.md and skip any already recorded for that tag.
2. Call get_docs_file on AGENTS.md and read it in full. Then call get_docs_file for Deep Agents pages named in the research report. Stay out of src/oss/deepagents/code/.
3. For each remaining feature:
   • Edit surgically from the page get_docs_file content, following the docs repo AGENTS.md. Prefer :::js sections; leave :::python alone unless the change is shared.
   • Prefer updating the owning page over creating a new page. If a new page is required, also plan the src/docs.json navigation update.
   • Load the ship-docs-update skill and ship that feature alone with the research report's evidence as evidence_json.
4. After shipping, append the release tag, feature name, Linear URL, and PR URL to /memories/agent/deepagentsjs-releases.md.
5. Keep /memories/agent/AGENTS.md short: last processed Deep Agents JS tag and date, alongside other products.

Memory format Copy Chapter

Use cold memory file /memories/agent/deepagentsjs-releases.md:

# Deep Agents JS release tracking

## [email protected]
- feature: browser entrypoint
  - linear: https://linear.app/...
  - pr: https://github.com/langchain-ai/docs/pull/...

File: docs-release-watch/skills/openwiki/SKILL.md Copy Chapter

name: openwiki Copy Chapter

OpenWiki docs release skill

Use this skill when the product is OpenWiki.

Sources of truth Copy Chapter

• Releases: https://github.com/langchain-ai/openwiki/releases via get_eligible_release / get_release_notes
• Docs paths in langchain-ai/docs:
  • src/oss/openwiki/ (all OpenWiki pages)
  • Navigation entries for OpenWiki in src/docs.json
  • Docs style authority: root AGENTS.md in langchain-ai/docs (read via get_docs_file before drafting)
• Changelog page in docs: src/oss/openwiki/changelog.mdx (points at GitHub releases)

What usually needs docs Copy Chapter

Prioritize user-facing changes:

• New CLI commands, flags, or subcommands
• New coding-agent integrations or providers
• New modes, workflows, or config surfaces
• Behavior changes that make existing docs wrong
• New requirements (Node version, auth, permissions)

Usually skip docs for:

• Internal refactors with no user-visible change
• Dependency bumps with no behavior change
• Pure bug fixes that do not change documented behavior

When unsure, open a small clarifying ticket/PR only if a reader of the current docs would be misled.

Workflow for one OpenWiki release Copy Chapter

The main agent must run phase 1 through the release-research subagent first (diff + source investigation). This skill guides phase 2 shipping and judgment details the subagent also uses.

1. After research returns features with needs_docs: true, read /memories/agent/openwiki-releases.md and skip any already recorded for that tag.
2. Call get_docs_file on AGENTS.md and read it in full. Then call get_docs_file for OpenWiki pages named in the research report.
3. For each remaining feature:
   • Edit surgically from the page get_docs_file content, following the docs repo AGENTS.md.
   • If a new page is required, also plan the src/docs.json navigation update.
   • Load the ship-docs-update skill and ship that feature alone with the research report's evidence as evidence_json.
4. After shipping, append the release tag, feature name, Linear URL, and PR URL to /memories/agent/openwiki-releases.md.
5. Keep /memories/agent/AGENTS.md short: last processed OpenWiki tag and date only.

Memory format Copy Chapter

Use cold memory file /memories/agent/openwiki-releases.md:

# OpenWiki release tracking

## v0.7.0
- feature: GitHub Copilot CLI integration
  - linear: https://linear.app/...
  - pr: https://github.com/langchain-ai/docs/pull/...
- feature: entra auth configuration
  - linear: https://linear.app/...
  - pr: https://github.com/langchain-ai/docs/pull/...

File: docs-release-watch/skills/release-research/SKILL.md Copy Chapter

name: release-research Copy Chapter

Release research (read-only)

Use this skill only inside the release-research subagent. You investigate. You do not ship.

Goal Copy Chapter

For one product, decide which user-facing features in the eligible release need documentation updates, with citations from the product repo at that tag.

Steps Copy Chapter

1. Call get_eligible_release for the product with defaults (min_age_days=7, max_age_days=30). Only releases in that window are in scope, including on a first run with empty memory. Stop if nothing is eligible. Prefer the newest candidate; do not walk older tags outside the window.
2. Read product memory (/memories/agent/-releases.md) and skip features already tracked for that tag.
3. Call get_release_diff for the eligible tag (omit base_tag so it resolves the previous same-prefix release). Treat the commit list and changed files as the primary signal.
4. Call get_release_notes only as secondary context. Notes are leads, not ground truth.
5. For each candidate feature from the diff, call get_product_source_file at the head tag and confirm the API, flag, command, default, or behavior exists.
6. Call check_docs_coverage with the candidate symbols/flags and concrete docs page paths (for example src/oss/deepagents/customization.mdx). If every needle already appears and the existing wording is still correct, put the feature under skipped with reason "already documented".
7. Call get_docs_file on pages that might need updates when coverage is missing or wording looks wrong.
8. Return a single research report. Do not call Linear or PR tools (you do not have them).

Research report format Copy Chapter

Return JSON (as your final message text) with this shape:

{
  "product": "deepagentsjs",
  "head_tag": "[email protected]",
  "base_tag": "[email protected]",
  "features": [
    {
      "name": "FilesystemMiddleware offloadBinaryContent",
      "needs_docs": true,
      "reason": "New public option; docs Full stack and Override sections omit it.",
      "docs_paths": ["src/oss/deepagents/customization.mdx"],
      "evidence": {
        "source_repo": "langchain-ai/deepagentsjs",
        "source_tag": "[email protected]",
        "items": [
          {
            "path": "libs/deepagents/src/middleware/filesystem.ts",
            "symbol": "offloadBinaryContent"
          }
        ]
      },
      "diff_files": [
        "libs/deepagents/src/middleware/filesystem.ts"
      ]
    }
  ],
  "skipped": [
    {
      "name": "internal test harness rename",
      "reason": "No user-facing API or docs impact."
    }
  ]
}

Set needs_docs to false (or put the item under skipped) when source shows no user-facing change, when check_docs_coverage shows the symbols are already present and correct, or when docs already cover it.

Do not Copy Chapter

• Open Linear issues or draft PRs
• Invent symbols that are not in get_product_source_file or the diff
• Recommend docs for pure refactors, dependency bumps, or internal-only changes
• Bundle unrelated capabilities into one feature entry

File: docs-release-watch/skills/ship-docs-update/SKILL.md Copy Chapter

name: ship-docs-update Copy Chapter

Ship one docs update

Use this skill in phase 2 when you are ready to create tracking and a draft PR for exactly one feature from a release-research report.

One feature only Copy Chapter

• One Linear issue
• One draft pull request
• One focused branch
• No unrelated edits in the same PR

If the research report lists multiple features, call this workflow once per feature. Do not invent features that research did not list. If you notice unrelated changes that should be made, leave them for a later research pass instead of shipping them now.

Preconditions (required) Copy Chapter

Before calling any write tool:

1. This run already has a release-research JSON report, and this feature appears there with needs_docs: true.
2. You called get_docs_file on AGENTS.md in langchain-ai/docs and read it in full. That file is the style and structure authority for the PR. Do not confuse it with /memories/agent/AGENTS.md (hot memory status only).
3. You called get_docs_file for every docs path you will change and still have that exact content.
4. You prepared evidence_json from the research report's evidence object (the write tools re-fetch each path at the tag and refuse if the citation is missing):

{
  "source_repo": "langchain-ai/deepagentsjs",
  "source_tag": "[email protected]",
  "items": [
    {
      "path": "libs/deepagents/src/middleware/foo.ts",
      "symbol": "offloadBinaryContent"
    }
  ]
}

Each item needs path plus symbol or quote. Empty evidence is rejected.

Steps Copy Chapter

1. Edit surgically from the get_docs_file content, following the docs repo AGENTS.md (frontmatter, voice, no markdown in description, Tabler icons, sentence-case headings, no contractions, no first person, language fences, navigation rules, and the rest of that file). Change only the sections needed for this feature. Do not rewrite the rest of the page. Do not invent content for the other language fence.
2. Create the Linear issue with create_linear_issue:
   • team_key="DOC"
   • Title: concise, feature-scoped (for example "Document OpenWiki Copilot CLI integration")
   • Description: release tag, why docs must change, files to touch, acceptance criteria
   • Pass product, release_tag, and evidence_json
   • The tool assigns the issue to the Linear API key owner (Naomi) automatically
3. Create the draft PR with create_draft_docs_pr:
   • Branch: docs/-<version>-<feature-slug>
   • Title matches the issue scope
   • Body must include a ## Linear section with Closes [DOC-N]() (markdown hyperlink). A GitHub Action syncs Linear status from that line (draft open → In Progress, ready for review → In Review, merged → Done, closed unmerged → Canceled), so the Closes DOC-N link is required.
   • Pass the same evidence_json
   • Pass product so language-fence validation uses the registry scope (python / js / shared)
   • files_json is a JSON array of { "path": "...", "old_content": "...", "new_content": "..." }
   • old_content must be the exact string returned by get_docs_file (empty string only for a brand-new file)
   • Keep the edit surgical: the tool rejects diffs that rewrite too much of an existing page or change the other language fence
4. Record the Linear URL and PR URL in product memory before starting the next feature. Only treat the ship as successful when both tools returned a url.

PR body template Copy Chapter

## Summary
- <one sentence on the docs change>
- Triggered by <product> <release tag>

## Linear
Closes [DOC-<number>](<issue url>)

## Source evidence
- Repo: `<owner>/<repo>`
- Tag: `<release tag>`
- `<path>`: `<symbol or short quote>`

## Test plan
- [ ] Preview the changed pages
- [ ] Confirm claims against the cited product source at the tag
- [ ] Run `make lint_prose FILES="<changed mdx paths>"` when possible

The write tools append a Source evidence section when the body omits one. Prefer writing it yourself so the citations stay next to the summary.

Do not Copy Chapter

• Bundle multiple features into one issue or PR
• Ship before calling the release-research subagent in this run
• Ship a feature that is not in the research report
• Draft docs without reading the docs repo AGENTS.md in this run
• Draft from release notes without reading product source at the tag
• Pass full page contents invented from memory (always start from get_docs_file)
• Omit old_content or invent a base that does not match main
• Ship without evidence_json that points at product source at the tag
• Modify docs-release-watch/ in the docs PR
• Put secrets, tokens, or .env contents into issues or PRs
• Mark the PR ready for review; leave it as a draft
• Edit :::python sections for a JS-only feature, or :::js for a Python-only feature
• Claim success without a tool-returned Linear URL and PR URL

File: openwiki/index.md Copy Chapter

okf_version: "0.2" Copy Chapter

Files

• Repository Wiki Quickstart - Route documentation, LangSmith agent and observability changes, generated artifacts, automation, and previews to their durable owners. Choose validation that covers the changed boundary without editing generated output.

Directories

• architecture
• concepts
• integrations
• operations
• testing
• workflows

File: openwiki/INSTRUCTIONS.md Copy Chapter

A code wiki for this repository. Provide an overview of the docs and tools we use, source map, key workflows, concepts, testing guidance, and CI overview. Inspect git history to understand reasoning behind docs changes and the progression of the repository. Keep pages grounded in repository structure and recent docs and code changes. Prefer practical navigation for engineers and writers over generic summaries.

File: openwiki/quickstart.md Copy Chapter

type: contributor guide
title: Repository Wiki Quickstart
tags: [quickstart, documentation, tooling, validation, repository, langsmith]
verified:

• by: openwiki/0.4.3
  at: 2026-10-27T08:21:38.674Z
  sources:
• id: openwiki-source-5c124605ed6e394bffee862c
  resource: repo://.github/workflows/_check-links.yml
• id: openwiki-source-4d9cccca7700db7220ec055e
  resource: repo://.github/workflows/_test.yml
• id: openwiki-source-164e2da859b5277df81c7d94
  resource: repo://.github/workflows/ci.yml
• id: openwiki-source-7346220ed051a41471043c07
  resource: repo://.github/workflows/create-preview-branch.yml
• id: openwiki-source-97746d8f3662d803e625550e
  resource: repo://.github/workflows/test-code-samples.yml
• id: openwiki-source-8037e2358a2c4f9b2c722a11
  resource: repo://AGENTS.md
• id: openwiki-source-012f2c78e3b1446dfc35803f
  resource: repo://Makefile
• id: openwiki-source-6e6efa1569f158fcdb678ef0
  resource: repo://pipeline/cli.py
• id: openwiki-source-b481a230af378c0c50ed9994
  resource: repo://pipeline/commands/dev.py
• id: openwiki-source-d0cdf44431684bdedf34705a
  resource: repo://pipeline/core/builder.py
• id: openwiki-source-17f3856bce97f37118963062
  resource: repo://pipeline/preprocessors/handle_auto_links.py
• id: openwiki-source-05ccef8d4cf1698187f20464
  resource: repo://pyproject.toml
• id: openwiki-source-23775c3de52f3ab95a13cb8b
  resource: repo://README.md
• id: openwiki-source-0a0a6c8d7a88288e6b6b9b5b
  resource: repo://scripts/check_cross_refs.py
• id: openwiki-source-fd0cb9d6fca56bf4963559e9
  resource: repo://scripts/extract_code_snippets.py
• id: openwiki-source-560bf24db9566b97ee19e383
  resource: repo://scripts/generate_code_snippet_mdx.py
• id: openwiki-source-63d8ba810a7c0181c548a307
  resource: repo://scripts/refresh_integration_downloads.py
• id: openwiki-source-2b15ecffacad911ef9db112f
  resource: repo://scripts/test_code_samples.py
• id: openwiki-source-381b2039419503f4809ac2df
  resource: repo://src/code-samples/deepagents/rag-deep.py
• id: openwiki-source-11d4965febd3986495e06a17
  resource: repo://src/code-samples/langsmith/create-an-agent.py
• id: openwiki-source-a9a8730b7e43a5ad2d0af4f1
  resource: repo://src/docs.json
• id: openwiki-source-661abd9305024589f43ce542
  resource: repo://src/langsmith/agents.mdx
• id: openwiki-source-efb95e7fd1324eefaec0577a
  resource: repo://src/langsmith/create-an-agent.mdx
• id: openwiki-source-dab366a6f340489dcb3ad96d
  resource: repo://src/langsmith/log-traces-to-agent.mdx
  generated: { by: "openwiki/0.4.3", at: "2026-10-27T08:21:38.674Z" }

Repository Wiki Quickstart

This repository owns the authored documentation and build pipeline for docs.langchain.com. Start with the durable input, not a rendered route: a sidebar item, deployment-generated endpoint, table, snippet, or file in build/ can be output owned elsewhere.

Route the task first Copy Chapter

AGENTS.md is the repository-wide authoring contract: edit manually authored src/ content, keep frontmatter descriptions free of Markdown, use Tabler icons, test examples, add new pages to src/docs.json, and never edit build/. Task-specific procedures live in .agents/skills/; run make skills in each Claude Code worktree to link them into .claude/skills/. A change to a script, workflow, Make target, check, scheduled job, or skill also needs the docs-tooling-notion follow-up before PR handoff.

Source, navigation, and generated-output boundaries Copy Chapter

src/docs.json is the Mintlify site-configuration and navigation source of truth, but it does not determine a file's owner or cause the builder to emit a page. Navigation labels can span source families: Build mixes OSS and LangSmith content, No-code agents is sourced from Fleet, and Deep Agents Code is a Products and setup item. Choose the source directory and resulting route family first, then update the menu entry and any compatibility redirect.

A clean build deletes and recreates build/. Most OSS source becomes Python and JavaScript variants; OpenWiki and Deep Agents Code are deliberate unversioned exceptions; ordinary LangSmith content is unversioned; and Managed Deep Agents produces Python and JavaScript variants. Generated output is useful to inspect but is never an authoring surface.

For shared OSS content, an unfenced @[ref] must resolve in both language scopes. Place SDK-only names in :::python or :::js blocks and run make check-cross-refs.

LangSmith agent and observability changes Copy Chapter

The agent-based-workspace documentation is a connected source cluster, not a single page. Use agents.mdx for the agent/environment model and identifier versus display-name distinction; create-an-agent.mdx for registration and compatibility-project retrieval; and log-traces-to-agent.mdx for SDK, environment-variable, and OTLP routing. Keep the observability quickstart, reusable tracing snippets, and framework-integration pages aligned when their shared prerequisite or destination rules change. The narrow workflow page maps the connected consumers, including resolver and OpenTelemetry guidance.

src/docs.json separately places langsmith/create-an-agent in Products and setup → LangSmith setup → Overview → Agent-based workspaces and langsmith/observability-quickstart in the Monitor navigation. A new, moved, or renamed guide needs an explicit navigation and redirect decision; prose changes normally do not.

The registration guide imports two generated fragments, create-agent-py.mdx and agent-environment-project-py.mdx. Their durable source is src/code-samples/langsmith/create-an-agent.py: its two marked regions demonstrate Client.agents.create and retrieval of the selected environment's compatibility session values. Hidden regions start a loopback ThreadingHTTPServer, patch the SDK environment, and assert the documented POST then GET requests, so this is a deterministic local SDK fixture rather than a credentialed agent-creation call. Change the visible SDK calls, fixture schema/assertions, marker IDs, generated fragments, and importing guide together.

make test-code-samples FILES="src/code-samples/langsmith/create-an-agent.py"
make code-snippets

Use make lint_prose FILES="src/langsmith/..." for authored LangSmith prose. Add make broken-links-with-anchors when routes, navigation, imports, links, or anchors change. A local fixture pass proves request construction and response handling, not production credentials or service mutation; use a credentialed representative sample only when a change crosses that remote boundary.

Runnable samples: source, execution, then presentation Copy Chapter

A runnable program under src/code-samples/ is the source of truth. make test-code-samples executes selected samples; make code-snippets first extracts marked regions into the ignored src/code-samples-generated/ intermediate and then generates committed MDX under src/snippets/code-samples/.

src/code-samples/deepagents/rag-deep.py illustrates the boundary. Its :snippet-start: / :snippet-end: regions yield reader-facing tutorial fragments while :remove-start: / :remove-end: sections retain the credential gate, setup, long instructions, and assertions in the executable program but omit them from the extracted fragment. The program exits successfully with a skip message when OPENAI_API_KEY is absent; run it with that key to exercise its live retrieval, embedding, and agent path.

The dedicated workflow skips fork pull requests because credentialed samples need repository secrets. Same-repository PRs run changed supported sample files; manual and monthly scheduled runs execute all samples with tracing enabled. A trace refresh can regenerate snippet MDX and update the standing trace-refresh PR only after the guarded full-run conditions succeed; it is not a substitute for a successful sample run.

Local development and proportionate validation Copy Chapter

The project requires Python 3.13 or later. Run make install to synchronize Python dependency groups, install project npm dependencies and the global Mintlify CLI, and link skills. make dev builds unless --skip-build is supplied, watches src/, and starts mint dev --port 3000 from build/; it stops rather than serving stale output if the initial build fails. Open http://localhost:3000 after startup.

The installed docs console script dispatches to the pipeline CLI; Make wraps the normal build and development commands. mint is the separate Mintlify CLI used against generated output.

make test runs pytest with Internet sockets disabled except Unix sockets. Core CI runs on pull requests, pushes to main, and manual dispatch. It calls test, lint, and built-document checks and separately detects merge-conflict markers, source cross-reference failures, unsafe external integration URLs, and provider-overview drift. Built link validation rebuilds first and checks links, anchors, and redirects; it also runs the Agent Server OpenAPI check.

Preview deployment is an artifact handoff Copy Chapter

A Mintlify preview is not another source tree. For a same-repository pull request, create-preview-branch.yml validates the source branch, runs make install and make build, writes generated build/ files to a collision-resistant preview-... branch, then asks Mintlify to deploy that branch. Fork pull requests do not take the write- and secret-dependent path.

flowchart TD
  Event["Same-repository PR or manual dispatch"] --> Validate["Validate source branch"]
  Validate --> Build["Install and build"]
  Build --> Branch["Create preview artifact branch"]
  Branch --> Deploy["Request Mintlify branch preview"]
  Deploy --> Comment["Update marked PR comment"]
  Closed["PR closed"] --> Match["Find preview branch prefix"]
  Match --> Cleanup["Delete preview branches"]

Preview creation hands a generated branch to Mintlify; PR closure takes a separate guarded cleanup path.

The workflow validates permitted branch characters and length before checkout. Its preview name combines a sanitized source-prefix, timestamp, and short commit SHA, verifies remote uniqueness, and force-adds build/; a collision is a failure to retry, not a branch to overwrite. The Mintlify request requires the generated branch plus MINTLIFY_API_KEY and MINTLIFY_PROJECT_ID; malformed responses or a response without usable status or preview URL fail the job. A marker lets later runs update one PR comment rather than repeatedly notifying subscribers. On close, cleanup recomputes the sanitized prefix and refuses to delete any branch outside the preview- namespace.

Integration metadata Copy Chapter

Integration discovery combines hosted-guide integration: frontmatter with third-party records in scripts/data/integration_external_docs.yaml. The YAML owns external rows; its docs_url is rendered as a link, so validate it before regeneration. It accepts https://, http://, or a site-relative path with one leading slash, rather than protocol-relative or executable schemes. The provider overview has a different owner: CI regenerates it from packages.yml and rejects a changed result.

For the full policy, eligibility rules, scheduling, and generated-output contracts, use Integration Listing Automation rather than editing a table row.

Continue by domain Copy Chapter

• Repository Source Map: durable ownership, generated surfaces, and deployment boundaries.
• Documentation Route and Language Versioning: source classification, route variants, menus, and redirects.
• LangSmith Agent and Observability Documentation Changes: connected agent, environment, trace-routing, integration, sample, and REST-reference changes.
• Runnable Code Samples and Snippet Generation: marker syntax, local fixtures, rendering, tracing, and CI.
• Testing and Validation Overview: validation boundaries and failure triage.
• GitHub Actions and CI Automation: CI gates, preview branches, publication, and credentialed sample automation.

File: openwiki/.last-update.json Copy Chapter

{
"updatedAt": "2026-10-27T08:30:55.754Z",
"command": "update",
"gitHead": "df8e50b7a43d29baf36ea6b48c4b8eca49a226cf",
"model": "gpt-5.6-terra",
"status": "complete",
"language": "en"
}

File: openwiki/.page-manifest.json Copy Chapter

{
"schemaVersion": 1,
"pages": {
"/openwiki/architecture/build-system.md": {
"pageVersion": "sha256:912b98f5dddde2c03e2d73f1ee89d5fdd46a420c8a831c1e9b46a9b06f8f919a",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/architecture/source-map.md": {
"pageVersion": "sha256:fc9128b0df33f411de3c3bee64469109f6d409ad9ddf1f1b7ff195d349f279d0",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/concepts/preprocessing.md": {
"pageVersion": "sha256:5be13cf4a483d3dd0cc75c07125e25315f39b070483d15b7770280da146ca6a3",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/concepts/versioning.md": {
"pageVersion": "sha256:9a378b41514f6fd45cc2fb910508dc72cf396cc8b3021555169a2fed126c76c6",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/integrations/github-actions.md": {
"pageVersion": "sha256:7a9e15357883db234682bf27f0a18047e457620e7963b73ac31d980b1b21a8b9",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/integrations/mintlify.md": {
"pageVersion": "sha256:5006ec04f73d6e0f8a174c1e8ad3ce47376c1a540c6c279ca52816c029b2c44c",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/integrations/npm-snippets.md": {
"pageVersion": "sha256:cc5794f493b9c3657c6cbb7ceba7936b80b45aa904c7adec090cb86d44542a71",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/integrations/reference-docs.md": {
"pageVersion": "sha256:87b67e5c39e29c1194bbbf57c48983c4189c99c00a7eb80cbe567c8554a50885",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/operations/adding-pages.md": {
"pageVersion": "sha256:99d16e86386278f4e9821428eaa9e0e69e797fa6fa1f839c76fc82a5aa58b870",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/operations/cli-tools.md": {
"pageVersion": "sha256:f3d52a29f8af7bdf029b4de65417dbf7145a3073d4c1565a67a60f28fc37d91f",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/operations/cross-references.md": {
"pageVersion": "sha256:0fe7d49f93e60c183cf365992d04990e2c465538d3dc23093def9df53a2b2630",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/quickstart.md": {
"pageVersion": "sha256:27d82f0ec18ab02dfb1df495be27851fa653c0db8805fba5f6f723a8df7b6e4a",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/testing/builder-tests.md": {
"pageVersion": "sha256:075328c59a95482e51e04c1ec01b4ec9c38ea46714fc8fcbc2e5f9e0a582b552",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/testing/conditional-rendering.md": {
"pageVersion": "sha256:ba6fc49130e066bb8964e51b88e6f6e35de241874a19c2016ce98fdb7ebb1fb6",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/testing/test-overview.md": {
"pageVersion": "sha256:f21a26488e73136436f9b84a141b0518e6fd6a80b6063eb90182b1d99aaaab2b",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/workflows/local-development.md": {
"pageVersion": "sha256:7dc05ee57632265a1ff81169e876a5d06c2854e4bf4344b44ba7c3cbf78b3cf6",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
},
"/openwiki/workflows/versioned-content.md": {
"pageVersion": "sha256:88b52798ebb5aa9f77c67018f465ee63b3a7bf4b3261005d74ebcb75eb9bfe0b",
"completedBy": "openwiki/0.5.0",
"completedRunId": "d6c27dde-b6ee-4fa2-a58e-46062acd3170",
"gitHead": "68512c2429a64dc27910103f0b656e0b6feafe55",
"sourceFingerprint": "sha256:0e18d78f74777334899afd9c5b5b69aab7a5b4fcd2a28464368a929e6c7d4e8e"
}
}
}

File: openwiki/architecture/build-system.md Copy Chapter

type: architecture
title: Documentation Build System
tags: [build-system, documentation-pipeline, mintlify, preprocessing, content-routing]
verified:

• by: openwiki/0.4.3
  at: 2026-10-23T08:20:30.474Z
  sources:
• id: openwiki-source-012f2c78e3b1446dfc35803f
  resource: repo://Makefile
• id: openwiki-source-6e6efa1569f158fcdb678ef0
  resource: repo://pipeline/cli.py
• id: openwiki-source-41f7c907e42a5efd3b3405cd
  resource: repo://pipeline/commands/build.py
• id: openwiki-source-b481a230af378c0c50ed9994
  resource: repo://pipeline/commands/dev.py
• id: openwiki-source-d0cdf44431684bdedf34705a
  resource: repo://pipeline/core/builder.py
• id: openwiki-source-636af982f42ea94123d2d7e9
  resource: repo://pipeline/core/watcher.py
• id: openwiki-source-17f3856bce97f37118963062
  resource: repo://pipeline/preprocessors/handle_auto_links.py
• id: openwiki-source-06a4c757b1153b7de4f47a0e
  resource: repo://pipeline/preprocessors/markdown_preprocessor.py
• id: openwiki-source-3ae8d89866d72418f1bdab6b
  resource: repo://pipeline/preprocessors/utm_links.py
• id: openwiki-source-05ccef8d4cf1698187f20464
  resource: repo://pyproject.toml
• id: openwiki-source-23775c3de52f3ab95a13cb8b
  resource: repo://README.md
• id: openwiki-source-24e5f74f0f40e9bfd381871f
  resource: repo://tests/unit_tests/test_builder.py
• id: openwiki-source-16b92823fdcb07d686f2e27f
  resource: repo://tests/unit_tests/test_watcher.py
  generated: { by: "openwiki/0.4.3", at: "2026-10-23T08:20:30.474Z" }

Documentation Build System

DocumentationBuilder is the filesystem boundary between authored src/ inputs and build/, the generated tree consumed by Mintlify. build/ is disposable: a full build deletes and recreates it. Make direct changes to authored inputs in src/, configuration, or pipeline generators—not to build/—then rebuild. Mintlify renders and deploys the completed tree; deployment-time OpenAPI endpoint pages are intentionally not locally generated MDX artifacts.

Entrypoints and full-build lifecycle Copy Chapter

make build installs npm dependencies and runs uv run pipeline build. The packaged docs console script points to pipeline.cli:main. Its CLI dispatches synchronous and asynchronous handlers and returns integer command results as process exit status; it provides build, dev, mv, migrate, and migrate-docusaurus. The build handler requires src/, constructs DocumentationBuilder(src, build), and runs build_all(); a missing source directory returns exit code 1.

flowchart TD
    Source["Authored src tree"] --> Clear["Clear and recreate build"]
    Clear --> Oss["Build OSS language variants"]
    Oss --> Unversioned["Build unversioned OSS and LangSmith"]
    Unversioned --> Managed["Build Managed Deep Agents variants"]
    Managed --> Shared["Copy shared inputs"]
    Shared --> Overlay["Overlay npm components"]
    Overlay --> Mint["Mintlify reads build"]
    Source --> Watch["Development watcher"]
    Watch --> Incremental["Rebuild changed source files"]
    Incremental --> Reload["Touch emitted files"]
    Reload --> Mint

This shows the authoritative full reconstruction and the narrower incremental preview path.

A full build runs in this order: ordinary OSS Python output, ordinary OSS JavaScript output, unversioned Deep Agents Code, unversioned OpenWiki, ordinary LangSmith, Managed Deep Agents language variants, shared files, then the npm component overlay. The overlay intentionally wins over same-destination source copies. The builder does not generate llms.txt or llms-full.txt.

Routing families Copy Chapter

The builder selects output paths from source location rather than mechanically mirroring the source tree.

Managed Deep Agents is the LangSmith exception. The builder emits its direct .mdx pages only under language-prefixed routes, while src/docs.json redirects unversioned Managed Deep Agents URLs to Python routes. Its language render also rewrites unversioned Managed Deep Agents links to the matching language route.

During a language-targeted render, absolute /oss/... links become /oss/python/... or /oss/javascript/.... Existing language prefixes, image paths, and the unversioned Deep Agents Code and OpenWiki roots are intentionally not rewritten, because the builder does not duplicate those routes.

Output transformations Copy Chapter

Markdown and MDX remain unchanged in src. Before writing output, the builder applies standard preprocessing, rewrites language-scoped snippet imports when applicable, rewrites OSS and Managed Deep Agents links, and appends a source-contribution footer. .md inputs are output as .mdx.

Standard preprocessing resolves scoped @[LinkName] references through SCOPE_LINK_MAPS, adds UTM parameters to eligible smith.langchain.com CTA links, and evaluates conditional blocks. :::python is retained only for the Python target and :::js only for JavaScript; other labels remain intact. Escaped \::: delimiters become literal delimiters. Missing autolinks are logged rather than failing the build, and the CTA pass skips fenced code and leaves functional LangSmith URLs alone.

The generated footer is omitted for root index.mdx and any file below a snippets path. Other source Markdown gets output-only calls to connect the docs, edit the source on GitHub, or file an issue.

Shared inputs and snippet copies Copy Chapter

is_shared_file() prevents selected inputs from entering versioned passes. It classifies docs.json; selected root pages (index.mdx, use-these-docs.mdx, playground.mdx, and build-overview.mdx); all paths containing snippets, images, .well-known, or fonts; and every .js or .css file. Supported inputs include Markdown, JSON and YAML, common image/video formats, CSS/JS, JSX/TSX, text/HTML, and common web fonts. Unsupported extensions and TEMPLATE.mdx are skipped; docs.yml is converted to JSON, while other supported non-Markdown inputs are copied with metadata.

A Markdown snippet is written three times: at its source-relative path with Python-resolved links for unversioned consumers, and under both build/snippets/python/ and build/snippets/javascript/ with corresponding link and conditional rendering. A versioned page importing from '/snippets/foo.mdx' is rewritten to its matching language-specific Markdown copy. JSX and TSX components stay shared rather than being language-expanded.

After source shared files are processed, the builder attempts to copy PatternEmbed.jsx and ExampleEmbed.jsx from node_modules/@langchain/docs-sandbox/dist to build/snippets/, plus ChatLangChainEmbed.js to the build root. Missing package directories or mapped files produce warnings; present package files overwrite earlier source-tree copies.

Development and incremental limits Copy Chapter

make dev installs npm dependencies and starts pipeline dev. Unless --skip-build is supplied, development mode first performs the full build, then watches src/ recursively and starts mint dev --port 3000 in build/. It returns failure for an initial build failure, an unavailable Mint executable, a nonzero Mint exit, or an unexpectedly stopped watcher. On shutdown it stops the watcher and terminates Mint, escalating to a kill after the wait timeout.

The watcher queues supported create and modification events, ignores common editor backup and temporary files, de-duplicates rapid changes with a 0.2-second debounce, and rebuilds a batch in worker threads, with up to four workers. It then touches expected output files to trigger Mintlify hot reload. For an existing source file, build_file() follows the same routing classification as the full build.

Incremental mode is not a substitute for reconstruction:

• Deletion handling removes only the source-relative output path, not every routed variant. A deleted versioned or Managed Deep Agents source can therefore leave generated files until the next full build.
• build_file() does not rerun whole-tree shared-file collection or the npm overlay. Use a full build for cross-file effects, package changes, deletions, navigation changes, or suspicious preview state.
• Managed Deep Agents output is rebuilt correctly into both language routes, but the touch logic treats LangSmith as unversioned and does not touch those emitted routes. A full build is the reliable refresh path for this case.

Local validation and release operations Copy Chapter

Validation consumes the generated tree, not src/. Run make broken-links after a build to execute mint broken-links --check-redirects from build/; the target filters expected reports for deployment-time OpenAPI pages and standalone snippets, then fails when the remaining report contains broken-link lines. make broken-links-with-anchors adds anchor validation. Redirect checking is enabled so destinations in docs.json are checked too.

For an offline artifact, make export requires an installed Mint CLI with mint export, a supported Node version, and the required Mintlify plan; it runs mint export from build/. make htmltest then unpacks that zip and checks external URLs only, because exported output can omit pages and make internal-link checks noisy. make export-htmltest runs those two targets sequentially. These operations validate or package generated output; they do not make build/ a source of record.

Safety and tests Copy Chapter

Whole-tree collection rejects symlinks, including symlinks to regular files, and accepts only regular files whose resolved paths stay under the requested source root. This prevents a committed link from bringing host paths into generated artifacts.

Focused builder tests cover language-routing exceptions, language-aware OSS and snippet links, Managed Deep Agents dual routes, source-snippet copies, and symlink rejection. The watcher unit tests focus on filtering editor backup and temporary filenames. Extend observable output tests when changing routing, rewriting, shared-file policy, or overlay precedence.

Related pages Copy Chapter

• Source directory map
• Preprocessing
• Versioning
• Mintlify integration
• Builder tests
• Local development

File: openwiki/architecture/index.md Copy Chapter

Files

• Documentation Build System - How the Python pipeline turns authored source files into the disposable Mintlify build tree, including routing, preprocessing, local development, and validation.
• Repository Source Map - Maps the durable owners of documentation source, Mintlify configuration, generated artifacts, external integration metadata, and release-maintenance automation. Use it to choose the correct change boundary and avoid editing deployment or generated output.

File: openwiki/architecture/source-map.md Copy Chapter

type: architecture reference
title: Repository Source Map
tags: [documentation, build, automation, repository]
sources:

• id: openwiki-source-5c124605ed6e394bffee862c
  resource: repo://.github/workflows/_check-links.yml
• id: openwiki-source-67b847f2c6d57526390e4981
  resource: repo://.github/workflows/check-integration-repos.yml
• id: openwiki-source-164e2da859b5277df81c7d94
  resource: repo://.github/workflows/ci.yml
• id: openwiki-source-f2608d0d515da097485b6ec5
  resource: repo://.github/workflows/publish.yml
• id: openwiki-source-5153f86e64d6ee0b305f72b3
  resource: repo://.github/workflows/refresh-langsmith-openapi.yml
• id: openwiki-source-4de47c60d7e3210385c34d35
  resource: repo://.github/workflows/update-package-downloads.yml
• id: openwiki-source-8037e2358a2c4f9b2c722a11
  resource: repo://AGENTS.md
• id: openwiki-source-012f2c78e3b1446dfc35803f
  resource: repo://Makefile
• id: openwiki-source-e52f38a56cc76188818237f7
  resource: repo://packages.yml
• id: openwiki-source-6e6efa1569f158fcdb678ef0
  resource: repo://pipeline/cli.py
• id: openwiki-source-b481a230af378c0c50ed9994
  resource: repo://pipeline/commands/dev.py
• id: openwiki-source-d0cdf44431684bdedf34705a
  resource: repo://pipeline/core/builder.py
• id: openwiki-source-17f3856bce97f37118963062
  resource: repo://pipeline/preprocessors/handle_auto_links.py
• id: openwiki-source-dca59d03b9433eea9242c2e4
  resource: repo://pipeline/preprocessors/link_map.py
• id: openwiki-source-06a4c757b1153b7de4f47a0e
  resource: repo://pipeline/preprocessors/markdown_preprocessor.py
• id: openwiki-source-0539c4d1a36abb10d1ed2fa9
  resource: repo://pipeline/tools/partner_pkg_table.py
• id: openwiki-source-05ccef8d4cf1698187f20464
  resource: repo://pyproject.toml
• id: openwiki-source-23775c3de52f3ab95a13cb8b
  resource: repo://README.md
• id: openwiki-source-bbd7fe20e2563e842ee80a78
  resource: repo://scripts/check_integration_repos.py
• id: openwiki-source-0d19fa2f26e6485d05a6b929
  resource: repo://scripts/data/integration_external_docs.yaml
• id: openwiki-source-fd0cb9d6fca56bf4963559e9
  resource: repo://scripts/extract_code_snippets.py
• id: openwiki-source-560bf24db9566b97ee19e383
  resource: repo://scripts/generate_code_snippet_mdx.py
• id: openwiki-source-697851c98229599f97376bfb
  resource: repo://scripts/process_langsmith_openapi.py
• id: openwiki-source-63d8ba810a7c0181c548a307
  resource: repo://scripts/refresh_integration_downloads.py
• id: openwiki-source-381b2039419503f4809ac2df
  resource: repo://src/code-samples/deepagents/rag-deep.py
• id: openwiki-source-11d4965febd3986495e06a17
  resource: repo://src/code-samples/langsmith/create-an-agent.py
• id: openwiki-source-a9a8730b7e43a5ad2d0af4f1
  resource: repo://src/docs.json
• id: openwiki-source-f685babda3a9a82ad6b9c98e
  resource: repo://src/langsmith/agent-environments.mdx
• id: openwiki-source-661abd9305024589f43ce542
  resource: repo://src/langsmith/agents.mdx
• id: openwiki-source-efb95e7fd1324eefaec0577a
  resource: repo://src/langsmith/create-an-agent.mdx
• id: openwiki-source-dab366a6f340489dcb3ad96d
  resource: repo://src/langsmith/log-traces-to-agent.mdx
• id: openwiki-source-31a97ae83c418d97b331e7df
  resource: repo://src/snippets/code-samples/create-agent-py.mdx
• id: openwiki-source-3e7f005be053311cf7eb12f1
  resource: repo://src/snippets/code-samples/rag-deep-index-py.mdx
• id: openwiki-source-24e5f74f0f40e9bfd381871f
  resource: repo://tests/unit_tests/test_builder.py
  verified:
• by: openwiki/0.4.3
  at: 2026-10-27T08:21:38.674Z
  generated: { by: "openwiki/0.4.3", at: "2026-10-27T08:21:38.674Z" }

This repository builds the Mintlify site at docs.langchain.com. It does not build the separately generated reference.langchain.com site. The essential maintenance boundary is durable input versus output: src/ is the authored documentation tree, src/docs.json is the Mintlify site contract, and build/ is disposable deployment output. Never edit build/.

flowchart TD
    Source["Authored src content"] --> Builder["DocumentationBuilder"]
    Builder --> Build["Disposable build output"]
    Config["src/docs.json"] --> Mintlify["Mintlify deployment"]
    Build --> Mintlify
    Mintlify --> Site["docs.langchain.com"]
    Packages["packages.yml"] --> Generators["Committed-source generators"]
    External["External integration YAML"] --> Generators
    Generators --> Source
    Upstream["LangSmith OpenAPI host"] --> Processor["OpenAPI processor"]
    Processor --> Spec["Committed OpenAPI input"]
    Spec --> Mintlify

This shows the ownership distinction: authored and generated-but-committed source are repository inputs; build/ is generated on each build; Mintlify generates configured OpenAPI endpoint pages at deployment; and the standalone API reference site is externally owned.

Ownership and no-edit boundaries Copy Chapter

Site sources, configuration, and routes Copy Chapter

src/ is organized by authoring ownership, not as a URL mirror. Product pages include src/langsmith/ and src/oss/; shared MDX and components are under src/snippets/; images and fonts are shared inputs; and src/code-samples/ contains runnable programs. AGENTS.md treats src/docs.json as the navigation and site-configuration owner and requires a navigation update for a new page.

DocumentationBuilder.build_all() deletes and recreates build/, creates Python and JavaScript OSS variants, builds Deep Agents Code and OpenWiki once at unversioned OSS routes, emits LangSmith content, then copies shared files including docs.json. Regular OSS content therefore lands under oss/python/ and oss/javascript/; src/oss/openwiki/ and src/oss/deepagents/code/ intentionally land only at unversioned paths. The Build navigation lists the same OpenWiki paths in both language dropdowns. Managed Deep Agents is a separate exception: matching src/langsmith/managed-deep-agents*.mdx files produce Python and JavaScript paths, and configured unversioned legacy URLs redirect to the Python route instead of receiving a third built page.

A page emitted by the builder is not automatically discoverable: src/docs.json independently owns navigation, redirects, and OpenAPI configuration. Keep a redirect when preserving an existing public URL.

LangSmith agent and observability documentation Copy Section

The agent-based-workspace documentation is authored MDX, not generated API reference material. src/langsmith/agents.mdx owns the workspace-to-agent-to-environment-to-trace model and the distinction between an immutable identifier and an editable display name. agent-environments.mdx owns the fixed environment vocabulary and UI-selection behavior. create-an-agent.mdx owns registration paths and setup credentials, while log-traces-to-agent.mdx owns tracing-destination configuration and its conflict rules. The tracing quickstart consumes the same model when it tells readers to create an agent and route traces to its identifier and environment.

Keep these responsibilities aligned rather than duplicating a rule in a generated endpoint page. In particular, the authored guidance says an agent address consists of both identifier and environment: a partial environment-variable address only warns and leaves otherwise unaddressed calls untraced; explicit code addressing takes precedence. Agent addressing and legacy project destination settings must not be combined for the same trace. Agent registration is a setup operation using a credential with projects:create; tracing can then use a tracing key. src/docs.json separately makes the agent, environment, and registration pages discoverable in Products and setup → Agent-based workspaces, and makes trace-addressing discoverable under Observability → Configuration & troubleshooting.

Markdown, snippets, and cross-references Copy Section

The builder preprocesses MD/MDX before writing it. It resolves @[...] cross-references, adds UTM parameters to eligible LangSmith CTA links, selects the active :::python or :::js conditional content, and leaves unsupported conditional labels intact. The scoped mappings in pipeline/preprocessors/link_map.py are the curated authority for the symbols that @[...] can resolve to API-reference URLs. Missing entries remain literal text and are logged, rather than being guessed.

MDX snippets are shared source, but their Markdown output is language-aware: the build writes a default copy and Python/JavaScript copies, and rewrites a language-targeted page's snippet import to its matching copy. JSX and TSX snippet components remain shared. This avoids relative-link errors for snippets consumed at different route depths.

Source collection is deliberately containment-safe. The builder skips source-tree symlinks and any file whose resolved path leaves the collection root, preventing a committed link from importing host data into build output. Preserve this invariant when changing traversal or adding a collection.

API reference boundaries Copy Chapter

Do not conflate these surfaces:

• reference.langchain.com is generated and deployed outside this repository. This repository can route issue reports, but has no reference build output to modify.
• Mintlify reads the OpenAPI declarations in src/docs.json for Agent Server, Control Plane, and LangSmith REST. It creates their endpoint pages during deployment; those pages are neither authored MDX nor builder output.

The committed LangSmith REST specification is a generated-but-reviewed repository input. scripts/process_langsmith_openapi.py accepts a local input or fetches only its allow-listed LangSmith host, marks fleet and internal operations plus configured system-health paths hidden, applies groups and group ordering to tags, and normalizes visible operation titles (including v2 labels) before writing src/langsmith/langsmith-platform-openapi.json. Its daily workflow generates the candidate file, exits without a commit when it is unchanged, and appends to the existing chore/refresh-langsmith-openapi pull request when one is open. Change the policy or upstream contract; do not hand-edit deployment-generated endpoint pages.

Development, CI, and publication Copy Chapter

The docs console entry point invokes the pipeline CLI. docs dev runs an initial build unless --skip-build is selected, watches src/, and runs mint dev from build/; failure of the initial build stops server startup. Use make build, make dev, and the link-check targets as normal wrappers.

CI runs reusable test, lint, and link-validation workflows on pushes to main and pull requests, cancelling an older run for the same ref when a newer one arrives. Separate jobs check merge-conflict markers, cross-references, external integration URL schemes, and the generated provider overview. The reusable link workflow builds the site, validates links including anchors and redirects, and checks the Agent Server OpenAPI specification. The generated-file check deliberately regenerates src/oss/python/integrations/providers/overview.mdx and fails if it differs, except for its explicit automation/label bypasses.

Publication is separate from CI: a main push runs make build, verifies build/, nests it at public/build, and publishes that directory to the prod branch. This is why build/ must remain reproducible and disposable.

Samples and integration metadata Copy Chapter

src/code-samples/ is executable source, not a page collection. make test-code-samples runs it. make code-snippets extracts marked regions into the ignored src/code-samples-generated/ intermediate and renders the committed display MDX under src/snippets/code-samples/. The source is authoritative: for example, rag-deep.py marks the rag-deep-index-py region, whose rendered counterpart is src/snippets/code-samples/rag-deep-index-py.mdx. Edit and test the program, then regenerate; do not hand-edit either derived layer.

The agent-registration guide demonstrates this boundary directly. create-an-agent.mdx imports create-agent-py.mdx; that display fragment is derived from the create-agent-py marked region in src/code-samples/langsmith/create-an-agent.py. The runnable source is intentionally safer than the reader-facing fragment: it points the real LangSmith SDK at a loopback HTTP fixture, captures the create and retrieve requests, and asserts their API paths and payloads without creating a live agent. Change the executable fixture and markers when the SDK contract or guide changes, run the sample and snippet generation, then review the derived MDX.

Snippet markers intentionally separate runnable setup and assertions from documentation fragments. The extractor recognizes :snippet-start: / :snippet-end: and removes nested :remove-start: / :remove-end: regions before the MDX generator formats the extracted language file. The generator supports Python, TypeScript, Java, Kotlin, Go, and shell intermediates and writes the snippet id with the language suffix removed as the MDX filename. A missing closing removal marker is an extraction error, so repair the source markers rather than patching the rendered MDX.

packages.yml is package metadata used by generated integration surfaces. Its provider and download metadata feeds the Python provider overview; CI regenerates that overview and rejects manual drift. The weekly package-download workflow refreshes download counts, regenerates the provider overview and integration download/featured snippets, optionally flags qualifying external integrations for hosted docs, and opens a PR only when tracked generated output changed.

Integration download tables also derive from hosted integration-page frontmatter plus scripts/data/integration_external_docs.yaml. An entry in that YAML represents a third-party listing: its docs_url becomes the name link instead of a hosted guide. URL validation accepts https://, http://, or a single-slash site-relative path and rejects protocol-relative and unsafe schemes. Use this data source for an eligible external row, not a handwritten table row.

The Monday integration-repository workflow runs the liveness checker with --write and manages the standing draft PR on chore/dead-integration-repos. For a dead third-party GitHub home, the checker can update to a live third-party GitHub replacement evidenced by PyPI, npm, or external docs; it preserves GitLab, partner-docs, and first-party alternatives for human attention. With no live alternate, it delists the package and removes related external entries, provider cards where unshared, and generated download rows.

Change guide Copy Chapter

1. Add or move a page: edit the relevant src/ MDX, update src/docs.json, and add a redirect when retaining a public URL.
2. Change routes, language rendering, snippets, or link preprocessing: modify pipeline/, preserve containment safety, add a focused test, and rebuild.
3. Change a runnable example: edit and test src/code-samples/, run make code-snippets, and commit rendered snippet MDX rather than the ignored intermediate.
4. Change provider or integration listings: select packages.yml, hosted-page frontmatter, or integration_external_docs.yaml according to ownership, then regenerate instead of editing table output.
5. Change Mintlify API reference: change src/docs.json, the committed specification, or process_langsmith_openapi.py; never author endpoint MDX for deployment-generated reference pages.
6. Investigate a broken API symbol link: amend the appropriate scoped entry in pipeline/preprocessors/link_map.py and verify preprocessing, rather than pasting an ad hoc generated URL into build output.
7. Change verification or scheduled maintenance: update the workflow, script, and its tests together; preserve the standing-PR behavior of repository and OpenAPI refresh jobs.

Related pages Copy Chapter

• Build system
• Preprocessing
• Versioning
• Mintlify
• Quickstart
• Code sample lifecycle
• Integration listing automation

File: openwiki/concepts/index.md Copy Chapter

Files

• Markdown Preprocessing and Cross-References - Build-time Markdown and MDX transformations for scoped API references, CTA attribution, language branches, and route-aware output. Documents fence and escape invariants plus strict source cross-reference validation.
• Documentation Route and Language Versioning - Explains how source ownership, conditional rendering, and link rewriting produce Python, JavaScript, and unversioned documentation routes. Covers navigation, language selection, and redirects as separate compatibility contracts.

File: openwiki/concepts/preprocessing.md Copy Chapter

type: documentation pipeline
title: Markdown Preprocessing and Cross-References
tags: [build, markdown, preprocessing, cross-references, language-versioning, api-reference]
verified:

• by: openwiki/0.4.3
  at: 2026-10-23T08:20:30.474Z
  sources:
• id: openwiki-source-012f2c78e3b1446dfc35803f
  resource: repo://Makefile
• id: openwiki-source-d0cdf44431684bdedf34705a
  resource: repo://pipeline/core/builder.py
• id: openwiki-source-17f3856bce97f37118963062
  resource: repo://pipeline/preprocessors/handle_auto_links.py
• id: openwiki-source-dca59d03b9433eea9242c2e4
  resource: repo://pipeline/preprocessors/link_map.py
• id: openwiki-source-06a4c757b1153b7de4f47a0e
  resource: repo://pipeline/preprocessors/markdown_preprocessor.py
• id: openwiki-source-3ae8d89866d72418f1bdab6b
  resource: repo://pipeline/preprocessors/utm_links.py
• id: openwiki-source-0a0a6c8d7a88288e6b6b9b5b
  resource: repo://scripts/check_cross_refs.py
• id: openwiki-source-24e5f74f0f40e9bfd381871f
  resource: repo://tests/unit_tests/test_builder.py
• id: openwiki-source-c2764a7369c8fbf3e49da6f8
  resource: repo://tests/unit_tests/test_check_cross_refs.py
• id: openwiki-source-2ecfcd33b729fccd843ab705
  resource: repo://tests/unit_tests/test_handle_auto_links.py
• id: openwiki-source-5255204fc494ae04cd6ba685
  resource: repo://tests/unit_tests/test_utm_links.py
  generated: { by: "openwiki/0.4.3", at: "2026-10-23T08:20:30.474Z" }

Markdown Preprocessing and Cross-References

DocumentationBuilder transforms source Markdown and MDX while writing build artifacts; it does not edit source files under src/. The pipeline lets one shared page produce Python and JavaScript variants without authors manually qualifying every API reference, route, snippet import, or CTA.

For a regular Markdown file, preprocess_markdown() resolves scoped cross-references, decorates eligible LangSmith CTA links, and renders conditional language blocks. The builder then scopes snippet imports, rewrites routes, appends an eligible source footer, and writes the artifact.

flowchart TD
    Source["Markdown or MDX source"] --> Select["Select build target"]
    Select --> Python["Python target"]
    Select --> JavaScript["JavaScript target"]
    Python --> References["Resolve scoped references"]
    JavaScript --> References
    References --> Cta["Decorate LangSmith CTA links"]
    Cta --> Conditional["Render conditional blocks"]
    Conditional --> Snippets["Scope snippet imports"]
    Snippets --> Oss["Rewrite OSS routes"]
    Oss --> Managed["Rewrite Managed Deep Agents routes"]
    Managed --> Footer["Append eligible footer"]
    Footer --> Output["Regular page artifact"]
    Source --> SnippetSource["Shared Markdown snippet"]
    SnippetSource --> SnippetPython["Python snippet copy"]
    SnippetSource --> SnippetJavaScript["JavaScript snippet copy"]
    SnippetPython --> SnippetProcess["Preprocess and rewrite routes"]
    SnippetJavaScript --> SnippetProcess
    SnippetProcess --> SnippetOutput["Language-prefixed snippet artifacts"]

The diagram shows the ordered regular-page sequence and the separate Python and JavaScript branches used for shared snippets.

Entry points and language selection Copy Chapter

_process_markdown_file() reads a .md or .mdx input, delegates content work to _process_markdown_content(), appends the footer, converts .md output to .mdx, and writes the result. _process_markdown_content() calls preprocess_markdown(), scopes Markdown snippet imports when a target is supplied, then rewrites OSS and Managed Deep Agents routes.

The preprocessing target keys are python and js; DocumentationBuilder.language_url_names turns them into the route segments python and javascript. If preprocess_markdown() receives no target, it uses TARGET_LANGUAGE, defaulting to python; its default_scope likewise defaults to that target. Conditional rendering rejects any other target with ValueError.

Build routing selects those targets deliberately:

• Ordinary oss/ Markdown is emitted for Python and JavaScript.
• oss/deepagents/code and oss/openwiki are emitted once with Python selection and retain language-agnostic routes.
• Ordinary LangSmith Markdown is built once with Python selection, while Managed Deep Agents pages emit Python and JavaScript routes.
• Each Markdown snippet is emitted below build/snippets/python/ and build/snippets/javascript/, plus a Python-default base copy for unversioned consumers.

For the wider route model, see Language Versioning Strategy and Build System Architecture.

Source-level transformations Copy Chapter

1. Scoped cross-references Copy Section

Authors can write @[link_name], @[title][link_name], and @[link_name]. replace_autolinks() looks up the key in SCOPE_LINK_MAPS and produces a Markdown link; a custom title is retained, and the simple backticked form retains backticks in its generated link text. Prefix a reference with \ to show it literally: it is not resolved, and the final pass removes the escape.

Resolution starts in default_scope. A :::python or :::js line changes the active scope; a bare closing ::: resets it to the default scope. Regular backtick and tilde code fences prevent both reference replacement and scope changes within their content. An unclosed regular fence protects the remaining input from reference replacement.

Fence protection is deliberately lightweight: both the autolink and CTA passes maintain one Boolean that toggles on every line beginning with at least three backticks or tildes. They do not pair an opening delimiter with a matching delimiter. Keep well-formed, balanced fences in authored input; malformed or mixed fence markers can change which later lines the source-level passes treat as code.

SCOPE_LINK_MAPS is assembled by scope from host-and-scope LINK_MAPS entries: relative targets are joined to the entry host, while absolute targets remain absolute. The maps deliberately allow one key to resolve differently in Python and JavaScript and include compatibility aliases where shared prose needs the other language's API spelling.

The MCP entries illustrate this distinction. Python mappings include MCPAdapter, tool conversion, MultiServerMCPClient, MCP loading, interceptor, callback, and connection/session references. JavaScript maps MCPAdapter and MCPAdapter.listTools to its JavaScript reference surface. Use the spelling appropriate to the fenced language; do not assume that a Python-specific key is available in the JS map.

A missing key is deliberately non-fatal during a build: preprocessing logs it at info level with file, line, key, and scope, then leaves the authored marker literal. The special runtime global scope logs an error and falls back to Python. Add or correct mappings in pipeline/preprocessors/link_map.py, then run the strict source-validation gate described below. See Cross-Reference Links.

2. LangSmith CTA attribution Copy Section

add_utm_to_cta_links() recognizes only Markdown-link URLs beginning https://smith.langchain.com whose parsed path is empty, /, /agents, or /agents/. It adds utm_source=docs, utm_medium=cta, utm_campaign=langsmith-signup, and utm_content, which is derived from the file path after src/; for example, src/langsmith/home.mdx produces langsmith-home. Existing query parameters and an optional Markdown link title are preserved.

Functional routes such as settings, hub, projects, public traces, and Studio are not decorated. Links on another host, including api.smith.langchain.com, are also unchanged. Backtick and tilde fenced code is skipped.

3. Conditional language blocks Copy Section

:::python ... ::: and :::js ... ::: are processed after references and CTA decoration. The selected block emits its content without fences and the other supported block is removed. Unsupported language identifiers are left intact; unclosed blocks do not match and remain intact. Escaped \::: markers are unescaped, allowing literal conditional syntax in output.

The implementation is a whole-input regular-expression transformation, rather than a nested-block parser: the first eligible closing marker at the opening indentation ends the match. Unlike the two earlier transformations, it is not code-fence-aware. Escape literal ::: syntax in examples that must not be rendered. See Conditional Rendering Tests.

Validation and fence boundaries Copy Chapter

make check-cross-refs is the strict authoring gate for missing mappings; it is intentionally different from the non-fatal behavior of build-time preprocessing. The command runs scripts/check_cross_refs.py on Markdown and MDX under src/, reusing the cross-reference and fence patterns. It skips regular code fences, escaped references, snippets/code-samples/, and paths containing node_modules; files that cannot be decoded as UTF-8 are skipped with a warning.

The validator checks a shared, unfenced oss/ reference against both Python and JS maps because that content is built for both variants. oss/python/ and oss/javascript/ instead use one scope, as do language fences. It requires resolution in all applicable scopes, so a Python-only reference in shared unfenced OSS content fails rather than silently producing a literal reference in the JavaScript output. Any unresolved reference makes the command exit with status 1.

Output-time rewrites Copy Chapter

After source preprocessing, the regular-file path applies these transformations in order:

1. Snippet import scoping. An MDX import from /snippets/...md or .mdx becomes /snippets/{python|javascript}/... for a language build. Imports already prefixed with python/ or javascript/ remain unchanged. The rewrite targets Markdown snippet imports, whose language-specific copies contain absolute OSS links for consumers at arbitrary nesting depth.
2. OSS route rewriting. Markdown URLs and HTML href values beginning /oss/ receive the selected language segment. Paths already prefixed with a language, paths containing images, and the language-agnostic /oss/deepagents/code and /oss/openwiki paths remain unchanged.
3. Managed Deep Agents routes. Bare Markdown or HTML /langsmith/managed-deep-agents... URLs become /langsmith/{language}/managed-deep-agents.... Already language-qualified URLs do not match the bare-route pattern.
4. Source footer. _add_suggested_edits_link() appends a Mintlify callout with a documentation/MCP connection link and GitHub edit and issue links only for files below src/. It excludes the root index.mdx and a path with a snippets segment.

Snippet Markdown is processed separately for each language, with preprocessing plus OSS and Managed Deep Agents rewriting, then written below build/snippets/{python|javascript}/. A Python-default base copy is also written for unversioned imports. This path does not add the source footer.

Failure behavior and safe changes Copy Chapter

• Missing references are non-fatal during preprocessing, but should fail make check-cross-refs before merge.
• Invalid conditional targets, and exceptions from regular content or file processing, are logged and re-raised, stopping that build path.
• Source-footer generation is best-effort: an internal failure is logged and the original content is returned.
• The builder rejects symlinks and paths resolving outside a scanned source root, so a documentation build cannot follow a committed link to host content.

When extending this pipeline, preserve the order. Scope-sensitive references must resolve while conditional fences still exist. Keep the rewrite exclusion guards: removing them can double-prefix routes or break the deliberately language-agnostic products. New reusable Markdown snippets must continue to receive language-specific copies because importing pages can be deeply nested. When adding a shared reference, ensure that its key exists in both maps or fence it to the language that owns it.

Focused regression coverage Copy Chapter

tests/unit_tests/test_handle_auto_links.py covers replacement outside regular fences, preservation inside backtick, tilde, extended, indented, and unclosed fences, conditional-looking lines inside code, and escaping. tests/unit_tests/test_utm_links.py covers the CTA allowlist, path-derived attribution, preservation of query strings and titles, functional/API-domain exclusions, and fence skipping.

tests/unit_tests/test_check_cross_refs.py covers scope-aware validation, the both-scope requirement for shared OSS content, titled and backticked references, and exclusions. Builder tests cover language route insertion and exemptions, scoped snippet copies, and Managed Deep Agents variants. See Test Overview for the wider suite.