sharing-streams Documentation

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

Technical Documentation: langchain-ai/sharing-streams

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

sharing-streams

Agent Skills & Rules Copy Section

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

--- METRICS ---

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

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 as one plain sentence in the description, for example "Prepared with Claude Code."
• Do not add a 🤖 Generated with [Claude Code] badge or similar to PR descriptions or commit messages, and do not add a Co-Authored-By trailer for an AI agent to commits. This aligns with the langster-safety skill. The check-pr-ai-attribution workflow fails a PR whose description contains either one, and a ruleset on main blocks the Claude trailer.

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. If main moved under the agent, create_draft_docs_pr rebases the surgical edit when the hunks still apply; if PR creation still fails after one fresh-file retry, the agent calls note_ship_failure_on_linear_issue to append the failure reason and LangSmith run URL to the open DOC ticket.

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.
• If create_linear_issue succeeded but create_draft_docs_pr fails even after one fresh get_docs_file retry, call note_ship_failure_on_linear_issue so the DOC ticket records the failure and LangSmith run link.
• 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.

If `create_draft_docs_pr` fails Copy Chapter

The tool rebases stale old_content onto live main when the changed hunks still apply. When it still fails (for example old_content does not match / could not be rebased):

1. Call get_docs_file again for every path in the failed PR.
2. Re-apply the same surgical edit on that fresh content.
3. Retry create_draft_docs_pr once with the new old_content / new_content.
4. If the retry also fails, call note_ship_failure_on_linear_issue with the DOC identifier and a short reason. That appends a Ship failure section (and the LangSmith run URL when available) to the issue so a human can debug. Leave the issue open. Do not claim the feature shipped.

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 changes to their durable source, generated-input owner, and proportionate validation. Use this map for versioned OSS content, LangSmith documentation, runnable samples, Mintlify output, and CI automation.

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 routing guide
title: Repository Wiki Quickstart
tags: [quickstart, documentation, routing, validation, mintlify, langsmith]
verified:

• by: openwiki/0.4.3
  at: 2026-10-29T08:15:48.231Z
  sources:
• id: openwiki-source-4d9cccca7700db7220ec055e
  resource: repo://.github/workflows/_test.yml
• id: openwiki-source-164e2da859b5277df81c7d94
  resource: repo://.github/workflows/ci.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-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-2b15ecffacad911ef9db112f
  resource: repo://scripts/test_code_samples.py
• id: openwiki-source-11d4965febd3986495e06a17
  resource: repo://src/code-samples/langsmith/create-an-agent.py
• id: openwiki-source-efb95e7fd1324eefaec0577a
  resource: repo://src/langsmith/create-an-agent.mdx
  generated: { by: "openwiki/0.4.3", at: "2026-10-29T08:15:48.231Z" }

Repository Wiki Quickstart

This repository authors and builds the Mintlify site at docs.langchain.com. Start from the durable input, not from a rendered route: build/, deployment-generated OpenAPI endpoints, extracted snippets, and generated tables are outputs with different owners.

Route the request Copy Chapter

AGENTS.md is the repository-wide authoring contract. It requires manually authored src/ content, plain-text frontmatter descriptions, Tabler icons, navigation updates for new pages, and tested examples. Procedures that apply only to a class of task live in .agents/skills/; run make skills in each Claude Code worktree to link them into .claude/skills/. Changes to tooling—scripts, workflows, Make targets, checks, scheduled jobs, or skills—also require the docs-tooling-notion follow-up before PR handoff.

Choose the correct source and output family Copy Chapter

src/docs.json is the Mintlify configuration, navigation, redirect, and OpenAPI-declaration input. It is not the owner of every page it lists. Navigation labels also do not mirror directories: Build includes OSS and LangSmith content, while No-code agents is sourced from src/langsmith/fleet/. Select the source family first, then make the navigation and redirect decisions.

flowchart TD
  Request["Documentation request"] --> Owner{"Authored or derived surface"}
  Owner -->|"authored"| Family["Choose src source family"]
  Owner -->|"derived"| Input["Find generator or declared input"]
  Family --> Routes["Set navigation and redirects"]
  Routes --> Build["Build and validate emitted routes"]
  Input --> Regenerate["Regenerate owned output"]
  Regenerate --> Build

Route changes begin with ownership; generated output is regenerated from its owner rather than edited directly.

A full DocumentationBuilder build clears build/, builds Python and JavaScript OSS variants, emits the unversioned exceptions and LangSmith content, builds Managed Deep Agents variants, then copies shared files. Inspect output to verify a change, but make corrections in its durable input. For shared OSS content, an unfenced @[ref] must resolve for both language scopes; put language-only names in :::python or :::js blocks and run make check-cross-refs.

Handle generated and deployment-time surfaces correctly Copy Chapter

Runnable samples and LangSmith documentation Copy Chapter

A program in src/code-samples/ is both the executable example and the source of displayed snippets. make test-code-samples runs selected samples. make code-snippets extracts marked regions into ignored src/code-samples-generated/ and renders committed MDX in src/snippets/code-samples/. Therefore, change and execute the program first, then regenerate; extraction does not execute the sample.

For LangSmith agent and observability changes, follow the connected owner rather than changing one visible page in isolation:

• src/langsmith/agents.mdx owns the agent/environment model.
• src/langsmith/create-an-agent.mdx owns registration and compatibility-project retrieval; its display fragments derive from src/code-samples/langsmith/create-an-agent.py.
• src/langsmith/log-traces-to-agent.mdx owns trace-destination configuration.
• Shared LangSmith snippets own rules reused across guides. Reconcile their consumers when a shared prerequisite or routing rule changes.
• The LangSmith REST reference is a deployment-generated surface. Change the refresh/processor policy or service-owned OpenAPI input, not individual endpoint pages.

The registration sample is deliberately deterministic: it directs the SDK at a loopback fixture and asserts the create and retrieval requests rather than creating a live agent. Keep visible calls, hidden fixture assertions, marker IDs, generated fragments, and the importing guide consistent.

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

Develop and validate at the affected boundary Copy Chapter

Python 3.13 or later is required. make install synchronizes Python dependencies, installs project npm dependencies and the global Mintlify CLI, and links Claude Code skills. make dev performs an initial build unless --skip-build is supplied, watches src/, and serves build/ through mint dev --port 3000; an initial build failure stops development rather than serving stale 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 invokes reusable test, lint, and link workflows and separately checks merge-conflict markers, cross-references, external integration URL schemes, and generated provider-overview drift. Built link checking rebuilds first and validates links, anchors, and redirects.

The code-sample workflow is intentionally separate because some samples use repository secrets. It skips fork pull requests, uses independent OSS and LangSmith legs, runs changed supported files on same-repository pull requests, and runs all samples on manual or scheduled invocations. Only a guarded full OSS run can refresh public trace links and generated snippets; inspect its review PR rather than treating it as source.

Continue by domain Copy Chapter

• Documentation Build System: generated-tree routing, preprocessing, watcher limits, and build tests.
• Repository Source Map: durable owners and deployment boundaries.
• Adding and Moving Documentation Pages: page lifecycle, navigation, redirects, and focused validation.
• Testing and Validation Overview: what each local, generated-site, and credentialed check proves.
• Runnable Code Samples and Snippet Generation: markers, runner behavior, rendering, tracing, and CI.
• LangSmith Agent and Observability Documentation Changes: connected LangSmith pages, samples, snippets, Managed Deep Agents, and REST references.
• GitHub Actions and CI Automation: workflow authority, scheduled automation, previews, and bot PR boundaries.

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

{
"updatedAt": "2026-10-29T08:40:02.198Z",
"command": "update",
"gitHead": "df8e50b7a43d29baf36ea6b48c4b8eca49a226cf",
"model": "gpt-5.6-terra",
"status": "interrupted",
"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-29T08:15:48.231Z
  sources:
• id: openwiki-source-012f2c78e3b1446dfc35803f
  resource: repo://Makefile
• 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-23775c3de52f3ab95a13cb8b
  resource: repo://README.md
• id: openwiki-source-a9a8730b7e43a5ad2d0af4f1
  resource: repo://src/docs.json
• 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-29T08:15:48.231Z" }

Documentation Build System

DocumentationBuilder is the boundary between authored src/ content and build/, the generated tree consumed by Mintlify. build/ is disposable: a full build deletes it before recreating it. Edit src/, not build/.

Entrypoints and full reconstruction Copy Chapter

make build installs npm dependencies and invokes uv run pipeline build. The docs console script exposes the same CLI. The build handler verifies that src/ exists, constructs DocumentationBuilder(src, build), and calls build_all(); a missing source returns exit code 1.

flowchart TD
    Source["Authored src tree"] --> Clear["Clear and recreate build"]
    Clear --> Py["Build OSS Python output"]
    Py --> Js["Build OSS JavaScript output"]
    Js --> Unversioned["Build Deep Agents Code OpenWiki and LangSmith"]
    Unversioned --> Managed["Build Managed Deep Agents variants"]
    Managed --> Shared["Copy shared files and render snippets"]
    Shared --> Overlay["Overlay npm components"]
    Overlay --> Mint["Mintlify consumes build"]
    Source --> Watch["Watcher receives file event"]
    Watch --> Incremental["Incremental build_file"]
    Incremental --> Touch["Touch expected output for reload"]
    Touch --> Mint

This flowchart distinguishes the authoritative full reconstruction (top path) from the narrower watch path (bottom path).

A full build proceeds in the order shown: two ordinary OSS passes, unversioned Deep Agents Code and OpenWiki, ordinary LangSmith, Managed Deep Agents variants, shared-file copying, and the npm component overlay. The overlay runs last and can replace source-tree copies. The builder does not generate llms artifacts.

Routing is content-aware Copy Chapter

The source location selects a routing family, but ordinary shared OSS Markdown is not blindly duplicated. The builder recursively reads navigation from src/docs.json, collecting routes below oss/python/ and oss/javascript/; the result is cached until the configuration modification time changes. A shared .md or .mdx page listed only in one language navigation is emitted only for that language. A page listed in both, in neither, or a non-Markdown asset is emitted for both. A navigation entry for dir can stand for dir/index, unless a language-specific src/oss/python/dir.mdx or src/oss/javascript/dir.mdx owns that route. If docs.json is missing or invalid, the safe fallback is both languages.

Deep Agents Code and OpenWiki are deliberate OSS exceptions: they retain unprefixed routes and their :::python branch. Managed Deep Agents is the LangSmith exception. Direct Markdown/MDX files whose names begin managed-deep-agents get both language routes; docs.json supplies redirects from unversioned Managed Deep Agents URLs to the Python routes. The renderer also changes unprefixed Managed Deep Agents links to the current language route.

For language-targeted output, absolute /oss/... links are rewritten as /oss/python/... or /oss/javascript/.... Already-prefixed links, image paths, and Deep Agents Code and OpenWiki routes are exempt, because those destinations are not language-duplicated.

Markdown transformation pipeline Copy Chapter

Markdown and MDX are transformed only for output. Processing order is: standard preprocessing, language-specific snippet-import rewriting when there is a language target, OSS-link rewriting, Managed Deep Agents-link rewriting, then the contributor footer. .md inputs become .mdx output.

Standard preprocessing resolves @[LinkName] references using scope-specific SCOPE_LINK_MAPS, adds UTM parameters to selected LangSmith CTA links, then evaluates conditionals. :::python content is retained for Python and removed for JavaScript; :::js behaves conversely. Unsupported conditional labels remain intact, and escaped \::: is unescaped to literal text. A missing autolink is logged rather than making the build fail. The UTM pass preserves existing query parameters, leaves functional LangSmith paths alone, and skips fenced code.

The output-only contributor footer is omitted for the root index.mdx and any path containing snippets. Other Markdown includes calls to connect the documentation, edit the source on GitHub, or file an issue.

Shared files and snippets Copy Chapter

is_shared_file() identifies docs.json; selected root pages; every path under snippets, images, .well-known, or fonts; and .js and .css files. Full builds collect these from the whole source tree once. Supported types include Markdown, JSON and YAML, common image/video formats, CSS/JS, JSX/TSX, text/HTML, and common web fonts. TEMPLATE.mdx and unsupported extensions are skipped; docs.yml is converted to JSON and other supported non-Markdown files are copied with copy2.

Markdown snippets have a special contract. Each is written at its source-relative path with Python-resolved links, and also beneath build/snippets/python/ and build/snippets/javascript/ with the corresponding conditions and links. A language-targeted MDX page importing from '/snippets/foo.mdx' is rewritten to import the corresponding language-specific Markdown copy. JSX and TSX snippet components remain shared.

Finally, the builder copies PatternEmbed.jsx and ExampleEmbed.jsx from node_modules/@langchain/docs-sandbox/dist into build/snippets/, and ChatLangChainEmbed.js to the build root. Available package files overwrite copies previously obtained from src; missing package directories or mapped files are warnings.

Development is incremental, not reconstruction Copy Chapter

make dev installs npm dependencies and starts pipeline dev. Unless --skip-build is supplied, it performs the full build first, then watches src/ recursively and runs mint dev --port 3000 with build/ as its working directory. It fails if initial construction fails, mint cannot be started, the Mint process exits nonzero, or the watcher stops unexpectedly; shutdown stops the watcher and terminates Mint, escalating to kill after five seconds.

The watcher queues supported created and modified files, rejects editor backups and temporary files, debounces events for 0.2 seconds, and builds a batch in worker threads (up to four). Afterwards it touches predicted output files so Mintlify detects the change. Incremental output is intentionally weaker than a full build:

• Deletion removes only the source-relative output path, not every language or special route. A deleted versioned or Managed Deep Agents source can therefore leave generated variants until the next full build.
• build_file() does not rerun whole-tree shared-file collection or the npm overlay. Use a full build after cross-file, navigation, package, or deletion changes.
• Managed Deep Agents pages rebuild into both routes, but the watcher treats LangSmith as unversioned for touching and does not touch those routes. Perform a full build if hot reload misses such an edit.

Validation, safety, and change tests Copy Chapter

Validation operates on generated output. make broken-links builds first, then runs mint broken-links --check-redirects from build/, filters known deployment-time OpenAPI and standalone-snippet reports, and fails if remaining broken-link lines exist. make broken-links-with-anchors also checks anchors. Deployment-time OpenAPI endpoint pages are intentionally absent from local output. make export runs Mint export from build/ after verifying CLI support and rejecting Node major versions 25 or newer; make htmltest unpacks the export and checks external links only.

Whole-tree collection rejects symlinks—even symlinks to regular files—and only accepts regular files resolving beneath the requested source root. This prevents source-tree links from carrying host content into artifacts.

The focused builder tests cover navigation-aware selection, language-routing exceptions, link and snippet rewriting, Managed Deep Agents output, and symlink rejection. Watcher tests cover filtering editor backup and temporary names. When changing routing or generated output, update these observable-output tests and run a full build as well as the focused suite.

Related pages Copy Chapter

• Preprocessing
• Versioning
• Mintlify integration
• Builder tests
• Local development

File: openwiki/architecture/index.md Copy Chapter

Files

• Documentation Build System - How the documentation pipeline reconstructs the Mintlify build tree from src, selects language-aware OSS output, preprocesses Markdown, and supports local development.
• Repository Source Map - Maps the durable owners of documentation, navigation, generated source, automation, and deployment output. Use it to select the safe change boundary and avoid editing derived artifacts.

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

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

• by: openwiki/0.4.3
  at: 2026-10-29T08:15:48.231Z
  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-efb95e7fd1324eefaec0577a
  resource: repo://src/langsmith/create-an-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
  generated: { by: "openwiki/0.4.3", at: "2026-10-29T08:15:48.231Z" }

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

flowchart TD
    Source["Authored source in src"] --> Builder["DocumentationBuilder"]
    Builder --> Output["Disposable build output"]
    Config["src/docs.json"] --> Mintlify["Mintlify deployment"]
    Output --> Mintlify
    Mintlify --> Site["docs.langchain.com"]
    Metadata["Package and integration metadata"] --> Generators["Committed-source generators"]
    Generators --> Source
    Upstream["LangSmith OpenAPI host"] --> Processor["OpenAPI processor"]
    Processor --> Spec["Committed OpenAPI input"]
    Spec --> Mintlify

This flow distinguishes authored and generated-but-committed inputs from deployment output. Mintlify generates configured OpenAPI endpoint pages during deployment; reference.langchain.com is an external build.

Ownership boundaries Copy Chapter

Authored documentation, labels, and routes Copy Chapter

src/ is organized for authoring ownership, not as a URL or reader-navigation mirror. For example, LangSmith content is in src/langsmith/, OSS content is in src/oss/, reusable MDX and components are in src/snippets/, images and fonts are shared inputs, and src/code-samples/ holds runnable programs. Reader-facing product and menu labels deliberately cross those directories: the Build menu includes both OSS and LangSmith content, while Test, Deploy, and Monitor draw from LangSmith. Find the owner by directory; find the reader-facing location in src/docs.json.

A page emitted by the builder is not automatically discoverable. src/docs.json independently owns menus, redirects, and OpenAPI configuration, so adding or moving a page requires an explicit navigation decision and a redirect when retaining a public URL.

DocumentationBuilder.build_all() recreates build/, builds Python and JavaScript OSS variants, emits Deep Agents Code and OpenWiki once at unversioned OSS routes, builds LangSmith content, then copies shared files including docs.json. Regular OSS pages land 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 OpenWiki paths under both language dropdowns. Managed Deep Agents is a distinct exception: matching src/langsmith/managed-deep-agents*.mdx files produce Python and JavaScript routes, while configured unversioned legacy URLs redirect to the Python route.

Source collection is containment-safe: the builder skips source-tree symlinks and files whose resolved path leaves the collection root. Preserve that safeguard when changing traversal or adding a collection.

Markdown, snippets, and cross-references Copy Section

Before writing MD or MDX, the builder resolves @[...] cross-references, adds UTM parameters to eligible LangSmith CTA links, and selects the target :::python or :::js content while leaving unsupported conditional labels intact. The scoped entries in pipeline/preprocessors/link_map.py are the authority for cross-reference symbols. An unresolved symbol is logged and left literal rather than receiving a guessed URL.

Snippets are shared source but have language-aware Markdown copies: the build writes the source-relative copy plus Python and JavaScript copies, and rewrites language-targeted MDX imports to the corresponding copy. JSX and TSX components stay shared.

API-reference boundaries Copy Chapter

Do not conflate three reference surfaces:

• reference.langchain.com is generated and deployed outside this repository. This repository only routes issue reports for it.
• src/docs.json declares Agent Server, Control Plane, and LangSmith REST OpenAPI sources. Mintlify creates their endpoint pages during deployment; they are neither authored MDX nor builder output.
• src/langsmith/langsmith-platform-openapi.json is a generated-but-reviewed committed input. Its processor fetches only an allow-listed LangSmith host (or reads a local input), hides fleet/internal and configured health operations, assigns and orders tag groups, and normalizes visible operation titles before writing the file.

The daily OpenAPI workflow runs that processor, makes no commit when the specification is unchanged, and appends changes to the existing chore/refresh-langsmith-openapi pull request. Change the processing policy or upstream contract rather than hand-editing endpoint pages.

Development, verification, and publication Copy Chapter

The docs console script exposes the pipeline CLI. docs dev builds initially unless --skip-build is selected, watches src/, and starts mint dev in build/; an initial build failure prevents server startup. make build, make dev, and the link-check targets are the standard wrappers.

CI calls reusable test, lint, and link-validation workflows and cancels an older run for the same workflow and ref when a newer push arrives. Separate jobs check merge-conflict markers, cross-references, external integration URL schemes, and generated provider output. The link workflow builds the site, validates links with anchors and redirects, and checks the Agent Server OpenAPI specification. The generated-file check regenerates src/oss/python/integrations/providers/overview.mdx and rejects drift except for its stated automation and label bypasses.

Publication is separate from CI: a main push runs make build, verifies build/, places it at public/build, and publishes it to the prod branch. That makes reproducibility, rather than edits to output, the operational requirement.

Runnable samples and derived snippets Copy Chapter

src/code-samples/ owns executable documentation examples. make test-code-samples executes them; make code-snippets extracts marked regions to the ignored src/code-samples-generated/ intermediate and renders committed display MDX under src/snippets/code-samples/. Edit and test the program, then regenerate; do not hand-edit either derived layer.

Snippet markers make the source-to-display relationship deterministic. For example, rag-deep.py marks rag-deep-index-py, whose display fragment is src/snippets/code-samples/rag-deep-index-py.mdx. The extractor removes marked non-display regions and errors on an unclosed removal marker; repair markers in the runnable source. The generator supports Python, TypeScript, Java, Kotlin, Go, and shell intermediates.

The agent-registration guide demonstrates the boundary: create-an-agent.mdx imports create-agent-py.mdx, derived from a marked region in src/code-samples/langsmith/create-an-agent.py. That sample points the SDK at a loopback fixture and asserts create and retrieve requests, so running it does not create a live agent.

Package and integration metadata Copy Chapter

packages.yml is package metadata for generated integration surfaces. The partner-package generator writes the Python provider overview, and CI rejects manual edits to it. The weekly package-download workflow updates metadata, regenerates the overview plus download and featured snippets, and creates a pull request only when tracked outputs changed.

Integration download tables combine hosted integration-page frontmatter with scripts/data/integration_external_docs.yaml. An external entry's validated docs_url supplies the name link instead of a hosted guide; CI validates allowed schemes. Use the YAML entry for a third-party row, not a handwritten generated row.

The Monday repository-liveness workflow runs the checker with --write and maintains one standing draft PR on chore/dead-integration-repos. For a dead third-party GitHub home, the checker can adopt a live third-party replacement evidenced by PyPI, npm, or external documentation. It keeps live GitLab, partner-documentation, and first-party alternatives for human attention; with no live alternate, it delists the package and removes associated listing surfaces.

Change guide Copy Chapter

1. Add or move a page: edit the owning src/ MDX, then update src/docs.json; do not infer navigation from the directory name.
2. Change routes, language rendering, snippets, or 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 the rendered snippet MDX—not the ignored intermediate.
4. Change provider or integration listings: choose packages.yml, hosted-page frontmatter, or integration_external_docs.yaml by ownership, then regenerate.
5. Change Mintlify API reference: change src/docs.json, the committed specification, or process_langsmith_openapi.py; never author deployment-generated endpoint MDX.
6. Fix an API symbol link: amend the scoped mapping in pipeline/preprocessors/link_map.py and verify preprocessing rather than pasting a guessed URL into output.
7. Change verification or scheduled maintenance: update the workflow, script, and tests together; preserve the standing-PR behavior of OpenAPI and integration-repository maintenance.

Related pages Copy Chapter

• Build system
• Versioning
• Reference docs
• Adding pages
• Code sample lifecycle

File: openwiki/concepts/index.md Copy Chapter

Files

• Markdown Preprocessing - 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 Routes and Language Versioning - Explains how source families and docs.json navigation determine generated documentation routes, language variants, conditional content, and compatibility redirects. Covers unversioned product exceptions and safe verification of route changes.

File: openwiki/concepts/preprocessing.md Copy Chapter

type: documentation pipeline
title: Markdown Preprocessing
tags: [build, markdown, preprocessing, cross-references, language-versioning, api-reference]
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-29T08:15:48.231Z" }
  verified:
• by: openwiki/0.4.3
  at: 2026-10-29T08:15:48.231Z

Markdown Preprocessing

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:

• A shared oss/ Markdown page is emitted for both Python and JavaScript unless docs.json navigation lists its route in exactly one language; in that case it is emitted only for that language. Files already below oss/python/ or oss/javascript/ are selected only for their matching build.
• 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 every shared, unfenced oss/ reference against both Python and JS maps, independent of navigation-based build selection. 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 a JavaScript variant. 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.