DEV Community: Alisa Hester

How to keep Fumadocs docs in sync with your code

Alisa Hester — Mon, 12 Oct 2026 15:43:01 +0000

To keep Fumadocs docs in sync with a Next.js app and its API, let Fumadocs generate every page it can from code (OpenAPI reference pages and TypeScript props tables), then give the hand-written guides around those pages an update loop of their own. A generated page changes when its source changes. A guide, a migration note, or a usage example changes only when someone edits it.

Take one change: an engineer removes a prop from a TypeScript component. On the next build, Auto Type Table renders the props table without it, while the quickstart's usage example still passes the removed prop. API pages built with generateFiles() stay stale until someone runs the generation script again.

What Fumadocs builds from your source

Fumadocs MDX compiles Markdown and MDX from a directory you configure (content/docs in its examples) and works with Next.js or Vite, so your docs can live in the same repository as the app they describe. Two parts of its toolkit go further and write pages straight from code.

The fumadocs-openapi integration gives you two ways to turn a spec into pages. generateFiles() writes MDX files to disk, and you refresh them by running a script again. staticSource() writes no files: it "generates pages directly to your loader(), hence it allows dynamic content generation, such as re-generating page tree as schema changes."

For components, Auto Type Table "generates a table for your docs based on TypeScript definitions." It comes from the fumadocs-typescript integration, and it "relies on the file system, hence, the page referencing this component must be built in build time."

Where a Fumadocs site still drifts

Test it with your own history: find the latest merged pull request that removed a prop or changed an endpoint. Did anything flag the guide that still uses the old one? Here is what each tool reads:

Native check	What it verifies	What it does not see	Where EkLine fits
Auto Type Table	Props tables built from TypeScript types at build time	Usage examples typed into MDX	Automatic PR review reads the code pull request and can draft the example fix
fumadocs-openapi	API pages from the spec, live with `staticSource()` or on rerun with `generateFiles()`	Guides that call those endpoints	Docs Agent edits that hand-written MDX in your docs repository
Fumadocs MDX	That your Markdown and MDX compile	Whether a compiled sentence is still true	Docs Agent drafts the correction, and Docs Reviewer checks the MDX in CI, without a Fumadocs framework value

Generated files are only as fresh as their last run. In March 2026, piersonmarks opened a feature request for an OpenAPI watch mode and described the gap: "The fumadocs-mdx bundler watches for MDX file changes, but nothing watches the upstream OpenAPI spec that produces those MDX files." The maintainer closed the request and replied that, because schemas can also come from URLs and custom functions, a watcher written in your own project is simpler and more flexible than a built-in wrapper. On a generateFiles() setup, keeping the reference current is your job.

Auto Type Table has its own failure case: the docs warn that "Rendering the component on serverless runtime may cause problems," and its setup example sets a cache for serverless platforms.

The bigger gap sits outside generation. In the removed-prop example, the table corrects itself and the usage example does not, because a person typed it. The same holds for the quickstart prose about the prop and the migration note that should name its replacement. The Fumadocs MDX documentation describes no built-in AI writer that would draft those edits.

Why not generate everything?

The strongest answer to drift is to generate more, and on Fumadocs it goes far. If an endpoint or a prop can be described from the spec or the type, generate it and stop maintaining it by hand.

Generation still stops at the type. A type says which props exist. It does not say which two props you combine for a common layout, why the removed prop went away, or what a reader on the old version should change before upgrading. Guides, migration notes, and worked examples carry that knowledge, and none of it can be generated from types.

So generation plus a same-PR rule is enough when the docs sit in the app repository and every fact the guide needs is in that pull request. It falls short when the facts come from a ticket, Slack, a spec, or another repository; in an Ask HN thread on the subject, practitioners write docs first or script nightly passes.

A Fumadocs sync checklist for this week

Prefer staticSource() when your spec changes often, so the page tree follows the schema instead of a file someone forgot to regenerate.
Where you need generateFiles() (for example, to edit the generated MDX), run the generation script in CI on every change to the spec, and fail the job when the committed files differ from fresh output.
Use Auto Type Table for every public component, build those pages at build time, and set the cache the docs ask for if you deploy to a serverless host.
Keep a list of hand-written pages that mention a generated thing (a prop, an endpoint, a type name), and review that list as part of every release.

Adding EkLine to a Fumadocs repository

EkLine adds the update loop for the hand-written half.

Question	On a Fumadocs site
Where your content lives	MDX in `content/docs`, inside the Next.js app repository or in a separate docs repository, on GitHub or GitLab.
What EkLine watches	The GitHub App separates documentation repositories, where you set the docs path, from code repositories, which it "reviews for documentation impact." Your app repository can be the code repository.
Where the pull request lands	A docs pull request (a merge request on GitLab) that edits hand-written MDX. Generated pages stay with Fumadocs; say so in custom instructions, which hold up to 5,000 characters and apply to every new session.
Which CI check runs	Docs Reviewer checks MDX for style, consistency, links, and accuracy. Its framework values cover mintlify, astro, fern, docusaurus, and gitbook, with no Fumadocs value, and the CLI docs note that "Without framework awareness, EkLine might skip content inside these components."
Which Scheduled Agents check fits	Code Sample Review, which "Verifies that code samples in your docs are accurate and runnable."
What stays in Fumadocs	OpenAPI pages, Auto Type Table, the page tree, and your Next.js build and deploy.

In the removed-prop example, when the engineer opens the pull request (or moves it out of draft), automatic PR review reads the diff, title, and description once. A low-confidence result stays silent, a medium one posts a suggestion comment, and a high one opens a docs pull request that rewrites the quickstart example without the prop. The props table needs no edit, because the next build regenerates it. GitLab merge requests get the same review since May 2026. If the change merged before EkLine was connected or scored below the threshold, the weekly Docs Drift Review audits the last 30 days of GitHub activity and fixes the highest-priority gap. Someone on your team reviews and merges every one of these pull requests.

Will engineers review docs instead of writing them? P0 Security, whose docs are hosted on GitBook, reports "15 integration guides shipped, zero new headcount" with EkLine, and its engineers spent their time "reviewing documentation instead of writing it."

If you move off Fumadocs one day

Keep the docs as MDX in Git, and the move costs the least of your accuracy work: the update loop for hand-written pages keeps working. Potluck Docs, which EkLine maintains, is one option: an MIT-licensed Astro + Starlight template whose OpenAPI references are rendered by Scalar with a client for sending real requests. It adds private and org-scoped docs, and it generates a sitemap and llms.txt on every build. It calls itself "a template, not a hosted product."

FAQ

Does EkLine replace your docs platform?

No. Fumadocs keeps generating your OpenAPI pages and type tables, and your Next.js or Vite build keeps rendering and deploying the site. EkLine works on the MDX you write by hand: Docs Agent drafts updates as pull requests when code changes, Docs Reviewer checks the MDX in CI, and Scheduled Agents review code samples. Your team merges every change.

Can Fumadocs regenerate OpenAPI pages automatically?

With staticSource(), yes: the fumadocs-openapi docs say it generates pages directly to your loader(), which allows re-generating the page tree as the schema changes. With generateFiles(), you run the generation script again after each spec change. A March 2026 request for a built-in watch mode was closed, and the maintainer suggested a watcher in your own project, so most teams also run the script in CI.

Does Auto Type Table work on serverless hosting like Vercel?

Build the pages that use it at build time. The Auto Type Table docs say the component relies on the file system, warn that rendering it on a serverless runtime may cause problems, and its setup example sets a cache for serverless platforms such as Vercel.

Can't we script this ourselves?

For the generated half, the maintainer's answer to the watch-mode request was a watcher in your own project. For the hand-written half, cyanydeez described "a for loop that runs nightly on any files updated the prior day," letting local AI revise the Markdown file next to each one. A quickstart in content/docs sits apart from the component it uses. Every rewrite still needs checking, the part rstagi called hard: "it's hard to fact-check everything all the time." EkLine drafts the guide edit as a pull request from the code change, and your team decides.

Pick the last pull request that removed a prop or changed an endpoint, and bring it. Docs Agent is available on all plans, with access granted on request. Book a demo to see what EkLine drafts for the hand-written half of your Fumadocs site.

How to keep Docusaurus docs in sync with your source code

Alisa Hester — Mon, 12 Oct 2026 14:23:00 +0000

Docusaurus keeps docs in sync with source code through the repository. It gives you three real sync tools: a monorepo, code blocks imported from files, and a build that fails on broken links. All three assume the code lives next to the docs. Answering that exact question in Docusaurus discussion #3722 in November 2020, a maintainer said that with docs and code in separate repositories, keeping them in sync is your job.

Your Docusaurus site lives in its own docs repository, and your SDK lives in another. An engineer renames a configuration option in the SDK. Every guide that names the old option is now wrong, and no Docusaurus tool flags it.

What Docusaurus already does to keep docs and code together

The installation guide suggests a monorepo when you document an existing project: "Then, your contributors can update the docs as they implement features."

Inside one repository, you can import a source file as raw text with raw-loader and render it with Docusaurus's CodeBlock component. The docs add a warning: "This feature is experimental and might be subject to breaking API changes in the future."

In the configuration reference, onBrokenLinks defaults to throw, so a link to a moved or deleted page fails the build. It has two limits: "The broken links detection is only available for a production build (docusaurus build)." And onBrokenAnchors defaults to warn, so a dead heading link ships with a warning.

Versioning copies the full docs/ folder into versioned_docs/version-[versionName]/ when you create a version, and each copy is edited independently. The docs advise against versioning unless you need it, because it adds build time and complexity.

The docusaurus-openapi-docs plugin generates MDX "using the OpenAPI specification as the source." Palo Alto Networks maintains it under the MIT license, outside the official Docusaurus project.

Where the renamed option slips through

Try it on your own site. Open the last merged SDK pull request that renamed an option. Did anything flag the guide that still names the old one? Each Docusaurus check answers a narrower question:

Native check	What it verifies	What it does not see	Where EkLine fits
`onBrokenLinks`	Links to moved or deleted pages, in production builds	A guide that names a renamed option with every link intact	Automatic PR review treats "renamed configuration" as a high-confidence case
raw-loader imports	Code blocks that match a file in the docs checkout	Code in a separate SDK repository	The GitHub App watches the SDK repository and writes to the docs repository
docusaurus-openapi-docs	Reference MDX generated from your spec	Guides and samples written around it	The Code Sample Review agent in Scheduled Agents checks those samples

The raw-loader example imports a relative path such as ./myComponent, so the file has to be reachable from the docs project, which in practice means it sits in the same checkout. A renamed option breaks no link, so onBrokenLinks has nothing to throw on. The build passes, and the guide still tells readers to set the old name.

With versioning on, the page in docs/ belongs to the current version, the frozen copy under versioned_docs/ also names the old option, and each copy changes only when someone edits it.

A build can also fail without failing your deploy. In a Docusaurus 3.9.2 issue about an .md and an .mdx file sharing one name, josh-wong reported that "a site with build errors still goes live instead of failing the deployment." The maintainer traced it to a custom build script whose pipe to tee made it exit with code 0.

A Docusaurus sync checklist for this week

Move the docs into the code repository if your team can, so the guide edit rides in the same pull request as the rename.
Replace pasted snippets with raw-loader imports wherever the code shares the docs repository, and treat the experimental label as an upgrade risk.
Run a full docusaurus build on every docs pull request, since link checks run only in production builds, and consider setting onBrokenAnchors to throw.
Confirm that your build script exits non-zero on a Docusaurus error (a pipe to tee can hide the exit code), so your deploy job stops.
After each SDK release, search docs/ and every versioned_docs/ folder for renamed options, and decide per version whether the frozen copy changes.
Generate API reference pages from your OpenAPI spec with the community plugin, so review time goes to the guides.

Should you move the docs into the SDK monorepo?

For most teams it is the best native answer, and the Docusaurus installation guide suggests it for documenting an existing project: the guide sits in the same pull request as the rename. It still leaves the prose to whoever opens the pull request. The Docusaurus docs we reviewed describe no check that compares a guide's sentences with the code, and a rename's reason often sits in a ticket or Slack thread outside the pull request.

Here is the line. A monorepo plus a same-PR rule is enough when the pull request carries every fact the guide needs; that is the shared-repository case the maintainer described in discussion #3722. It stops being enough once a fact lives in a ticket, a Slack thread, a spec, or the separate SDK repository. Docs-first habits and nightly scripts are what practitioners describe in an Ask HN thread on keeping docs current.

How EkLine plugs into a Docusaurus repository

Question	On a Docusaurus site
Where your content lives	Your docs repository, added in the EkLine GitHub App as a Documentation Repository, with paths such as `docs/`
What EkLine watches	Your SDK and service repositories, added separately as Code Repositories: "Source code repositories that EkLine reviews for documentation impact"
When it reads a change	Automatic PR review assesses each pull request once, when it opens or leaves draft; a weekly Docs Drift Review audits the last 30 days of GitHub activity
Where its pull request lands	Your docs repository, opened by Docs Agent
Which CI check runs	Docs Reviewer, through the EkLine GitHub Action, posts inline comments on the pull request, covering style, consistency, links, and accuracy; Docs Reviewer accepts a `docusaurus` framework value, and "Support for other frameworks is expanding."
What stays in Docusaurus	The build, theme, plugins, versioning, previews, and hosting

When the engineer opens the SDK pull request, automatic PR review lists "renamed configuration" among its high-confidence cases, which "Posts a comment that automatically triggers the docs update flow." Docs Agent drafts the update as a pull request in the docs repository, where your build runs as usual and a reviewer merges or closes it. The assessment reads only the diff, title, and description; when the reason for the rename sits in a Jira ticket or a Slack thread, you can combine those sources in a Docs Agent session and get one pull request.

For snippets that raw-loader cannot reach, use the Code Sample Review agent in Scheduled Agents, which "Verifies that code samples in your docs are accurate and runnable." Docs Agent works with GitHub and GitLab and is available to all plans, with access granted on request.

Worried about engineering time? At P0 Security, which hosts its docs on GitBook, "In 6 months, engineers reclaimed 150+ hours of product development time by reviewing documentation instead of writing it."

If you are starting fresh or leaving Docusaurus

If you do leave, the target that puts the least of your accuracy work at risk keeps your docs as Markdown in Git, because the same pull request loop then works on the new repository. Potluck Docs is one such target: an MIT-licensed Astro + Starlight template maintained by EkLine, with OpenAPI references "rendered by Scalar with a built-in client for sending real requests," private docs behind your SSO, org-scoped docs, and a sitemap and llms.txt generated on every build. It is "a template, not a hosted product." Nothing about EkLine requires the move. Compare EkLine vs Docusaurus, or see Docusaurus alternatives.

FAQ

Does EkLine replace your docs platform?

No. Docusaurus keeps building, versioning, and hosting your site. EkLine adds Docs Agent pull requests in your Docusaurus repository, drafted from changes in your SDK repositories, and Docs Reviewer comments in CI.

How does Docusaurus sync with the source code?

Through a shared repository. In discussion #3722, a maintainer replied that code and docs in the same Git repository "remain in sync automatically," and that with separate repositories "you have the responsibility to maintain sync." He linked an example of importing a code block from a source file. EkLine covers that separate-repository case.

Can Docusaurus import code from a file?

Yes, from a file the build can reach. Import it as raw text with raw-loader and render it with Docusaurus's CodeBlock component. The feature is marked experimental, and the import is a relative path, so in practice the file sits in the docs checkout.

Can't we script this ourselves?

You can script part of it. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," and has local AI rewrite the Markdown file that sits next to each one. That pairing assumes the doc sits beside the code, the shared-repository case from discussion #3722; your guides live in a separate Docusaurus repository, and versioned copies multiply them. rstagi named the remaining cost: "it's hard to fact-check everything all the time." EkLine reads the SDK pull request and, when the impact is clear, opens a docs pull request your team reviews.

Bring the last SDK pull request that renamed an option. Book a demo and walk an SDK change through to a Docusaurus pull request.

How to keep VitePress docs in sync with your code

Alisa Hester — Mon, 12 Oct 2026 14:20:01 +0000

To keep VitePress docs in sync with your code, import every code sample from your source files and leave dead-link checking on, so the build fails when a linked page goes missing and, on the VitePress 2.0 alpha line, when an imported file goes missing. Then review the sentences next to those samples on each release, because no VitePress setting checks that prose against the code.

Say a function's default value changes. The snippet you import with VitePress's code-snippet directive shows the new code on the next build. The paragraph above it still explains the old default, and the page's last-updated date looks recent because someone fixed a typo last week.

What VitePress keeps in sync for you

Its getting started guide says "Markdown files outside the .vitepress directory are considered source files." These tools act on those files, as described in the 2.0.0-alpha.20 docs. The stable release on npm is still the 1.6.x line, and missing-file handling differs between the two, as noted below.

Code snippet imports. The Markdown guide shows how its code-snippet directive pulls a code block from a file, where "The value of @ corresponds to the source root." Import one VS Code #region instead of the whole file, and the page shows only the lines that matter.
Markdown includes. The Markdown include directive inserts one Markdown file into another, with line ranges or a region, so shared steps live in one file.
Missing-file errors. According to the same guide, "Importing a file or region that does not exist throws a build error," and "Including a missing file, region, heading anchor, or an out-of-range line selection throws a build error." On 2.0 alpha releases, rename a source file or delete a region marker and the build stops; setting markdown.snippet.silent or markdown.include.silent to true turns that error into a warning. The VitePress changelog for 2.0.0-alpha.17 notes that includes previously "silently ignored errors when files did not exist," so on the stable 1.6.x line, check the rendered output.
Dead links. In the site config reference, ignoreDeadLinks defaults to false, and the description reads: "When set to true, VitePress will not fail builds due to dead links."
Last-updated dates. lastUpdated controls "Whether to get the last updated timestamp for each page using Git," and with the default theme, "enabling this option will display each page's last updated time."

Where the prose falls behind

Run this check against your repository. Open the newest merged pull request that changed a default, a parameter, or a return value. Did anything flag the paragraph that explains it? The import did its job, and the build passes because every file and region it references still exists. Nothing in that pipeline compares the sentence that names the default with the code below it, so the page now contradicts itself.

Native check	What it verifies	What it does not see	Where EkLine fits
Code-snippet imports	The code block matches a file the build can read	The sentence above the block, and code in another repository	Automatic PR review reads the code pull request and can draft the prose fix
`ignoreDeadLinks` left off	Markdown links point at pages that exist	Sidebar entries, per issue 3244, and prose that went stale	Docs Reviewer checks links and writing rules on each pull request through the GitHub Action
`lastUpdated`	When a commit last touched the page	Whether the page still matches the product	A weekly Docs Drift Review audits changes that merged without docs

Sidebar entries are a second gap. In a VitePress issue titled "Dead links in sidebar not reported," koebi wrote in November 2023 that a sidebar link to a missing page "builds even if Bar doesn't exist." The issue was still open when we checked in October 2026, so treat sidebar entries as unchecked.

The @ alias resolves to the source root, so a snippet stays current only when the build can read the file; code in a separate repository is outside that build unless you check it out or copy it in. A sample pasted by hand from a separate SDK repository is a copy that nothing in the build compares with its original.

That sets the boundary. Imports, the dead-link check, and a same-PR rule are enough when the code sits inside the docs build and every fact the paragraph needs is in the pull request. When the facts live in tickets, Slack threads, specs, or a separate SDK repository, nothing ties them to the page; an Ask HN thread on keeping docs current collects docs-first habits and nightly scripts.

Does lastUpdated tell readers a page is current?

A fair objection: lastUpdated shows when a page last changed, so readers can judge its age for themselves. The date comes from Git, so it reflects a real commit and is honest metadata.

But it records that a commit touched the file, which is a different fact from the page matching the product. In the example, the typo fix moved the date forward while the paragraph about the default stayed wrong. Show the date to readers, and keep it out of how you decide which pages need review.

A VitePress sync checklist for this week

Find every hand-pasted code block that has a source file in the repository, and replace it with a VitePress code-snippet import of a #region in code your tests already exercise.
Confirm that ignoreDeadLinks is unset or false in your site config, and, on 2.0 alpha, that no one has set markdown.snippet.silent or markdown.include.silent; on 1.6.x, open the rendered pages that import code.
Check sidebar entries on their own: after any page rename or deletion, open each sidebar link in a local build or preview.
Turn on lastUpdated for readers, and track review status somewhere else.
On each release, list the code changes that alter defaults, parameters, or behavior, and read the paragraphs around every imported snippet for those files.

The last item costs the most, because someone has to connect each code change to the right page.

Adding EkLine to a VitePress repository

EkLine works on that last item, and VitePress keeps building the site.

Question	On a VitePress site
Where your content lives	Markdown outside `.vitepress`, in a GitHub or GitLab repository
What EkLine watches	Code repositories, which the GitHub App lists apart from documentation repositories; GitLab merge requests too, per the May 2026 changelog
When it reads a change	Each pull request when it opens or leaves draft, once; a weekly Docs Drift Review sweeps what already merged
Where its pull request lands	Your docs repository, as a pull request your team reviews
Which CI check runs	Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, through the GitHub Action; its framework list has no VitePress value, so it reviews the Markdown without VitePress-specific handling
Samples that are not imported	The Code Sample Review agent in Scheduled Agents, which "Verifies that code samples in your docs are accurate and runnable"
What stays in VitePress	The build, imports and includes, the dead-link check, `lastUpdated`, theme, and hosting

In the example, the engineer opens the code pull request that changes the default. Docs Agent assesses it from the diff, title, and description; at high confidence it starts a docs pull request, and at medium confidence it leaves a suggestion comment. The draft rewrites the paragraph about the default and leaves the import line alone. You review and merge it, and the VitePress build runs as today. Automatic review reads the pull request alone, so for a change decided in a ticket, start a Docs Agent session from that ticket.

Do reviewers end up rewriting what it drafts? At ContextQA, whose docs are hosted on GitBook, the team reviewed EkLine's updates from April 7 to July 6, 2026, and "Two-thirds merged as a single commit," which the ContextQA case study reads as "the page was right the first time."

If your team leaves VitePress

Should you move, pick a target that keeps the docs as Markdown in Git, because that way the pull request loop you build here keeps working after the move. Potluck Docs is one such target, an open-source Astro + Starlight template under the MIT license that EkLine maintains. Its OpenAPI references render with Scalar and include a client for real requests; private docs and org-scoped docs are built in; and each build writes a sitemap and llms.txt. The project describes itself as "a template, not a hosted product."

FAQ

Does EkLine replace your docs platform?

No. VitePress still builds and serves your site, and its imports and link checks keep working. EkLine adds the prose check: Docs Agent drafts Markdown updates from code pull requests and opens them in your docs repository for your team to approve.

Does VitePress fail the build on dead links?

Yes, for links in your Markdown. ignoreDeadLinks defaults to false, and setting it to true stops VitePress from failing builds on dead links. Sidebar links are a separate case: a 2023 issue reports one to a missing page that still builds.

Can't we script this ourselves?

Partly, since the imports already keep code blocks current. For the prose, cyanydeez described "a for loop that runs nightly on any files updated the prior day," and has local AI update the Markdown file beside it. On VitePress, the paragraph that explains a default sits on a page that imports the source file, not beside it. Each nightly rewrite needs a reader, which rstagi summed up as "it's hard to fact-check everything all the time." EkLine drafts that paragraph fix as a pull request from the code change, and your team approves it.

Choose one pull request from your last release that changed a default, and bring it. To see Docs Agent draft prose fixes on your own VitePress repository, book a demo. Docs Agent is available to all plans, and access is granted on request.

Material for MkDocs maintenance mode: keep your docs accurate now

Alisa Hester — Mon, 12 Oct 2026 06:46:01 +0000

"Material for MkDocs is in maintenance mode and MkDocs 2.0 won't support it. What do I do with my docs now?" As of October 8, 2026, you can stay on MkDocs 1.x for now, wait for Zensical, or move. None of those choices makes a stale page true, so audit and fix accuracy first: stale pages migrate with you, and the fixes count under any choice.

An engineer renames an argument on a Python function. mkdocstrings regenerates the API reference from the docstring, but the tutorial that calls the function with the old argument stays wrong. The same week, someone moves a file that a pymdownx snippet pulls from; the build passes and the snippet is gone from the page.

Where the MkDocs stack stands on October 8, 2026

Material for MkDocs: on November 5, 2025, its team announced that "Material for MkDocs is in maintenance mode," with support "for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed."
MkDocs 2.0: the Material team's post (February 18, 2026, updated October 2, 2026) says MkDocs 2.0 was "published as a pre-release on PyPI" in August 2026, that "No official release date has been announced yet," and that "MkDocs 2.0 won't have a plugin system." Of its own theme, the team writes that "it will cease to work with MkDocs 2.0."
Zensical: version 0.0.68 shipped on October 5 and 0.0.69 followed on October 8, both classified as alpha on PyPI. Its roadmap banner announces a "November 5 Zensical 0.1.0, Studio, and Spark Community launch," and the roadmap says "Our roadmap is directional and does not promise delivery dates." Its compatibility page says "Zensical can build existing MkDocs projects without requiring changes."
mkdocstrings: the project homepage, checked October 8, 2026, warns "mkdocstrings is in maintenance mode!"

To stay on 1.x is one team's choice; FeldrinH wrote on April 6, 2026, "We are using MkDocs 1.6 and for the time being have no plans or bandwidth to migrate." Waiting for Zensical trades an alpha release and a directional roadmap for keeping your mkdocs.yml and Markdown, with plugins checked against Zensical's replacement list. If you move, the target that risks least of your accuracy work keeps your docs as Markdown in Git, because the fixes you make now, and the pull request loop around them, move with the files. Potluck Docs is one: an MIT-licensed Astro and Starlight template maintained by EkLine. Its site lists "Three example OpenAPI references, rendered by Scalar with a built-in client for sending real requests," private docs for signed-in readers and org-scoped docs for one org's members, and a sitemap and llms.txt "generated on every build." It describes itself as "a template, not a hosted product," so hosting stays with you. For the side-by-side platform comparison, read our guide to Material for MkDocs maintenance mode.

What MkDocs and its extensions already check

The strict setting: "Set to true to halt processing when a warning is raised." It defaults to false. In MkDocs 1.6, a missing file reports as a warning and a missing anchor only as info, so a strict build fails on a deleted page but passes a dead heading link until you raise anchor validation to warn.
pymdownx Snippets: "an extension to insert markdown or HTML snippets into another markdown file." With line ranges, a page can show selected lines of a real file. With check_paths at its default of off, a missing file means "the markup will be removed"; with it on, the build fails.
mkdocstrings: "Automatic documentation from sources, for MkDocs." Reference pages are rebuilt from docstrings, so signatures follow the code.

Plugins lose their home in MkDocs 2.0. Snippets is, by our reading, a Markdown extension instead, but neither source says whether MkDocs 2.0 supports it, so test it.

What still drifts on a Material site

Run a test on your own site. Open the last merged pull request that renamed an argument or changed what a function does. Did anything flag the tutorial that calls it? On the next build, mkdocstrings shows the new signature, the strict build is green, and the tutorial still passes the old argument.

Native check	What it verifies	What it does not see	Where EkLine fits
`strict`	Links to missing files, and anchors once you raise their level	A tutorial whose links all resolve but whose call is out of date	Automatic PR review assesses the code pull request that renamed it
Snippets	Lines pulled from a real file, and with `check_paths` on, that the file exists	The prose around the snippet, and code in another repository	Docs Agent drafts the prose fix as a Markdown pull request
mkdocstrings	Reference pages rebuilt from docstrings	Tutorials and how-tos that call the function	A weekly Docs Drift Review sweeps changes that merged without docs

The moved snippet is quieter. With check_paths off, Snippets removes the include and the page publishes with a hole where the example was.

When is that enough? If your Python code and docs share a repository and the pull request holds every fact a tutorial needs, mkdocstrings plus a same-PR rule keeps pages right. If the facts sit in a ticket, a Slack thread, a spec, or another repository, the rule runs on memory, and the Ask HN thread on keeping documentation current shows commenters relying on docs-first habits and nightly scripts.

Four checks to run on your MkDocs site this week

Turn on strict and raise anchor validation from info to warn, so broken headings fail the build alongside missing pages.
Set check_paths to true for Snippets, so a moved source file stops the build instead of leaving a blank.
List every plugin your site depends on: plugins don't carry to MkDocs 2.0, and each one needs a match in Zensical or in the framework you would move to.
Audit your most-visited pages for accuracy before any move, starting with tutorials that call functions whose signatures changed recently.

Why not fix accuracy during the migration?

A migration touches every page, so cleaning up then feels efficient. But migration work competes with accuracy work: Redocly's tips for documentation migration include a rollback plan: "Rolling back early is better than rolling back late." The migration date may also never come: MkDocs 2.0 is undated, and Zensical is in alpha.

How EkLine plugs into a Material for MkDocs repo

Question	On a Material for MkDocs site
Where your content lives	Markdown in `docs/` next to `mkdocs.yml`, as the Material setup guide lays out, in a GitHub or GitLab repository
What EkLine watches	Code repositories you select in the GitHub App, listed apart from documentation repositories; GitLab merge requests too
When it reads a change	Docs Agent reads each pull request as it opens; a weekly Docs Drift Review audits the last 30 days of GitHub activity
Where its pull request lands	Your docs repository, as Markdown edits in a pull request under the configured documentation path
Which CI check runs	Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, through the GitHub Action. Its framework values are mintlify, astro, fern, docusaurus, and gitbook, so on MkDocs it reviews your Markdown without framework-specific component handling
What stays in MkDocs	`mkdocs.yml`, the Material theme, your plugins, your build, and your hosting

Follow the rename through it. The engineer opens the pull request in the code repository, and automatic PR review assesses it once, from "the PR diff, title, and description." A high-confidence result triggers a docs pull request; a medium one posts a suggestion comment and leaves the call to you. The fix to look for is the tutorial line that still passes the old argument; your team merges it, and your MkDocs build publishes it. If the reason for the rename lives in a Jira ticket, the PR review won't read it, so open a Docs Agent session and combine the pull request with the ticket. Docs Agent is available to all plans, but we grant access on request.

Docs Agent works on Markdown in a GitHub or GitLab repository, so after a move, point the documentation path at the new content folder.

Can an accuracy pass cover most of a site before you decide on a move? ContextQA, whose docs are hosted on GitBook rather than MkDocs, used EkLine over one quarter, April 7 to July 6, 2026, and "brought about 80% of the documentation set, 90 of 113 pages, up to date." Finish a pass like that before you move, and the new site starts from true pages.

FAQ

Does EkLine replace your docs platform?

No. MkDocs, the Material theme, mkdocs.yml, your plugins, and your hosting stay where they are. EkLine reads pull requests in your code repositories, opens Markdown pull requests in your docs repository, and adds Docs Reviewer as a CI check on that Markdown.

Does EkLine still work if we move off MkDocs later?

It should, as long as the new site keeps its Markdown or MDX in a GitHub or GitLab repository, because Docs Agent works on repositories and pull requests. On an Astro and Starlight site such as Potluck Docs, Docs Reviewer's astro framework value applies.

Can't we script this ourselves?

A script covers some ground. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," pointing local AI at the Markdown beside each changed file. On MkDocs, docstrings already play that role through mkdocstrings, while the tutorials that call a function sit elsewhere in the docs folder. Someone still checks every rewrite, the half rstagi flagged: "it's hard to fact-check everything all the time." EkLine drafts tutorial fixes as pull requests for review, and because they are plain Markdown, they carry over if you move.

Bring one recent pull request that changed a Python signature. To see what EkLine would change in your tutorials, book a demo with EkLine.

How to keep ReadMe docs in sync with your code and OpenAPI spec

Alisa Hester — Mon, 12 Oct 2026 06:31:02 +0000

"How do I keep ReadMe docs in sync with my code and my OpenAPI spec?" ReadMe handles half of that job. When you re-sync an OpenAPI file, ReadMe updates the spec-derived parts of each API page in place and leaves the Markdown you wrote alone. Your guides, recipes, and examples are that Markdown, so they need an update path of their own.

Follow one change: your API adds a new required request parameter. You run rdme openapi upload, and the reference page for that operation shows the parameter in an updated request panel. The getting-started guide and the recipe that call the same endpoint still show a request without it.

TL;DR

When you re-sync the spec, ReadMe updates the reference pages and keeps your hand-written Markdown exactly as you left it.
Use bi-directional sync or rdme for Markdown, never both, and keep every operationId stable.
Guides, recipes, and samples need a review step tied to code changes, which EkLine adds from GitHub or GitLab.

What ReadMe keeps current when you re-sync

Bi-directional sync connects your project to "a GitHub, GitLab, or Bitbucket repository so content stays in step whether you edit in ReadMe or in your repo," and "All content types sync, including guides, API reference pages, custom pages, recipes, and changelogs." The repository "must be empty" before you connect it, with "no commits or files," so it cannot be your existing API codebase. Your code and your docs end up in separate repositories.

rdme is "ReadMe's official command-line interface (CLI) and GitHub Action," and it "pushes one way, from your files to ReadMe, so edits made in the ReadMe editor don't flow back to your repository."

ReadMe matches pages on operationId and "updates the existing API Reference pages in place rather than creating a second set." "The parts of the page that come from the document, such as the summary, parameters, and request and response panels, update to match the new definition." The new required parameter appears on the reference page with no edit from you.

Where hand-written ReadMe pages drift

Test it on your own hub. Open the last merged pull request that added or changed a request parameter. Did anything flag the guide or recipe that calls that endpoint? Each native tool did its own job:

Native check	What it verifies	What it does not see	Where EkLine fits
OpenAPI re-sync	Spec-derived parts of each reference page, matched on `operationId`	Your hand-written Markdown, which it keeps as is	Automatic PR review assesses the API pull request and can start a guide edit
Bi-directional sync	The repository and the hub hold the same pages	Whether a recipe's request still matches the API	Docs Agent opens its pull request in that documentation repository
rdme	Files in Git reach ReadMe, one way	Whether the files it pushes are still true	Docs Reviewer checks the Markdown in CI, without a ReadMe framework value

The same re-sync page says your Markdown "is kept through every kind of re-sync." That protects your writing, and it also means no ReadMe process updates it. Three places still hold the old request:

The getting-started guide that walks a reader through a first call.
The recipe for that endpoint.
Any prose or sample you added to the reference page itself, now sitting beside refreshed panels.

Third-party sync glue brings failure modes of its own. In May 2026, JohnRDOrazio found his project's old github-readme-sync action "no longer maintained" and filed "Replace broken ReadMe.io sync workflow with self-hosted docs (OntoKit pattern)." davidt99 reported that "Docs upload format are incompatible with bi-directional sync"; ReadMe closed it as not fixable. An operationId change is worse than a rename: to ReadMe, "a changed ID is a deleted endpoint plus a new one. The old page, its URL, and any edits made to it are removed."

Does the GitHub AI Writer close the gap?

For some teams, yes. ReadMe's GitHub AI Writer "Proposes documentation updates when pull requests change your codebase." When a pull request opens in a connected repository, it "analyzes the diff, identifies new endpoints that need documentation or setup steps that have changed, and drafts the update on a review branch in ReadMe." It is "Available on Pro plans and above." If your API code is on GitHub and the pull request holds everything the guide needs, it covers the example change.

Its docs describe only a GitHub integration, so GitLab code has no documented path. Its docs describe it reading the diff and describe no input from tickets, Slack threads, or specs. It starts when a pull request opens, so work that merged before you connected it waits for someone to notice.

When is ReadMe's tooling enough on its own? When the guide edit can ride in the same pull request as the code and that pull request carries every fact, as with Markdown kept beside the code and pushed by rdme. Bi-directional sync needs an empty repository when you connect it, so in practice the guides start in a repository of their own. Once facts sit there, or in a ticket, a Slack thread, or a spec, the same-PR rule leans on memory; commenters in an Ask HN thread on the topic rely on docs-first rules and nightly scripts.

A ReadMe sync checklist for this week

Pick one path for Markdown pages. ReadMe says "If your project has Bi-Directional Sync enabled, you don't need rdme," though you still need the CLI for OpenAPI files.
Check every synced branch's rules: "your Git provider can reject the commits ReadMe pushes to it" when protection rules or rulesets apply.
Name branches exactly after your ReadMe versions, as ReadMe requires, so the branch a change merges into is the version it updates.
Give every operation an explicit, stable operationId, because a generated ID changes with the path and takes the old page with it.
When the spec changes, search your guides, recipes, and reference-page prose for the changed operation before you close the release.

How EkLine plugs into a ReadMe setup

Part of the workflow	Where it sits
Your Markdown pages	The GitHub or GitLab repository ReadMe syncs, or the repository your CI runs rdme from.
What EkLine watches	Your API code. The GitHub App separates Code Repositories from Documentation Repositories, and Docs Agent also reviews GitLab merge requests.
Where the Docs Agent pull request lands	Your docs repository, on the branch for the ReadMe version it documents.
How the change reaches your hub	ReadMe's sync, or your rdme step, after your team merges.
CI check	Docs Reviewer checks the Markdown for style, consistency, links, and accuracy. Its framework support page lists no ReadMe value, so it works without ReadMe-specific component handling.
Bitbucket	Docs Reviewer only, as a Bitbucket Pipelines check.
What stays in ReadMe	Hosting, the editor, versions, and the reference generated from your spec.

An engineer opens a pull request in the API repository that adds the required parameter. Automatic PR review assesses its diff, title, and description once, when it opens. A high-confidence result starts a docs pull request editing existing pages such as the guide and the recipe; a medium result posts a suggestion comment. You merge it, ReadMe's sync or your rdme step carries the guide to the hub, and the reference updates from the spec. If the review stayed silent, the weekly Docs Drift Review audits the last 30 days of GitHub activity. When the parameter came from a ticket or spec, a Docs Agent session can combine that source with the pull request. Code Sample Review "Verifies that code samples in your docs are accurate and runnable."

Can one writer keep pace with a busy API? At Socure, an identity intelligence company, one technical writer merged 348 documentation updates in seven weeks with no added headcount. The case study does not say which docs platform Socure uses.

If you are weighing a self-hosted move, Potluck Docs, EkLine's open-source Astro and Starlight template, renders OpenAPI references with Scalar and a built-in client for sending real requests.

FAQ

Does EkLine replace your docs platform?

No. ReadMe keeps hosting your hub, generating the reference from your spec, and running sync or rdme. EkLine covers the pages ReadMe leaves to you: it reads code changes as pull requests open, sweeps merged work on a schedule, and opens pull requests against your guides and recipes for review. For a side-by-side view, read EkLine vs ReadMe.

Should I use rdme or bi-directional sync?

Use one for Markdown pages. Bi-directional sync fits a team that edits in both the ReadMe editor and Git, and it needs an empty repository, branch names that match versions, and branch rules that let ReadMe push. rdme fits a team that treats Git as the only source, because it pushes one way.

Does EkLine work if ReadMe syncs to Bitbucket?

Partly. Docs Agent works with GitHub and GitLab, so it does not open pull requests in a Bitbucket repository. Docs Reviewer runs as a Bitbucket Pipelines check on your Markdown.

Can't we script this ourselves?

Some teams do. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," handing the Markdown file next to each changed file to local AI to revise. With bi-directional sync, guides start in their own repository, so a recipe has no file beside the API code to pair with. Each rewrite also needs checking, which rstagi called hard: "it's hard to fact-check everything all the time." EkLine starts from the API pull request and drafts guide edits as a pull request in the repository ReadMe syncs, where a person approves them.

Take the last pull request that added a parameter to your API, and bring it to the call. To see what Docs Agent would change in your ReadMe guides after your next spec update, book a demo. Docs Agent is available to all plans, with access granted on request.

How to keep Mintlify docs up to date when code changes

Alisa Hester — Mon, 12 Oct 2026 06:16:01 +0000

Mintlify already automates the structural half of keeping docs current: it builds API reference pages from your OpenAPI spec, checks links, validates builds, syncs with GitHub, and can draft pull requests when code merges. The half that slips is the prose and the examples whose facts live in other repositories, tickets, and threads. That half needs a review step, and it is where an EkLine pull request fits.

Follow one change through this post: an endpoint's auth header changes. The reference page generated from your spec updates. The quickstart and a guide still show the old header, and mint broken-links passes, because every link on those pages still resolves.

TL;DR

Mintlify regenerates API reference pages from your OpenAPI spec; a spec hosted at a URL needs a Trigger deployment call.
The Mintlify CLI checks links and build warnings, so an outdated header in valid MDX passes.
Mintlify automations draft pull requests after code merges, and Mintlify's own guidance still keeps review and sign-offs.
EkLine reads each code pull request as it opens and lands its docs pull request in the repository Mintlify deploys from.

What Mintlify already keeps current

Generated API pages. Mintlify's OpenAPI setup lets you "Reference any number of OpenAPI specifications in the navigation element of your docs.json to create pages for your API endpoints." When the spec lives in your repository, a spec change is a Git push and the site redeploys. When you host the spec at a URL, Mintlify warns that "changes to the spec don't trigger a Git push, so your docs won't redeploy automatically," and tells you to call the Trigger deployment API endpoint in the same CI action that generates or updates the spec.

Link and build checks. In the Mintlify CLI, mint broken-links checks internal links; --check-anchors also validates anchor links against heading slugs, and --check-external also checks external URLs. mint validate "Validate[s] your documentation build in strict mode. Exits with an error if there are any warnings or errors."

Git sync. Mintlify "uses a GitHub App to automatically sync your documentation with your GitHub repository" and deploys when you push. In a monorepo, you can "specify a subdirectory if your docs are not at the repository root."

Drafted updates. Mintlify automations include a code change trigger that "Runs when a pull request merges in one or more connected source code repositories." The agent "reads your project content and any connected repositories, then follows the prompt to make updates." Automations require a Pro or Enterprise plan, "Each run that updates your docs costs 250 credits," and each automation can run up to 500 times per day. If the auth header change merges in a connected repository, this feature may already cover it, so check it before you add another tool.

Mintlify still keeps people in the loop. Its maintenance guide says "Update docs in the same pull request as the code change" and "Require a docs sign-off before closing any ticket that changes user-facing behavior," then sets monthly, quarterly, and annual reviews. A June 18, 2026 Mintlify article on stopping documentation drift adds that "pull request review is the safer setup for user-facing documentation."

Where the auth header change still slips through

Test your own repository. Open the last merged pull request that changed how your API authenticates or what a request must send. Did anything flag the quickstart or guide that shows the old request? If nothing did, the reason is in what each Mintlify check reads.

Native check	What it verifies	What it does not see	Where EkLine fits
`mint broken-links`	Internal links, plus anchors and external URLs with flags	A working link on a page whose sample sends the old header	Automatic PR review reads the API pull request and can start the docs fix
`mint validate`	The build in strict mode, failing on any warning or error	Valid MDX that describes old behavior	Docs Reviewer comments on the docs change, with Mintlify component support
OpenAPI pages	Reference pages generated from your spec	Quickstarts and guides written by hand in MDX	Docs Agent edits those pages in your documentation repository

Two gaps sit outside every check: a migration note that lives in a ticket or a Slack thread, and hand-kept files. In a Mintlify-based repository, drewdrewthis reported on August 21, 2026 that llms-full.txt "is maintained by hand, which means it drifts silently and there is no signal when it does."

So when are native tools enough? When your API code and docs share a repository and every fact the guide needs is in the pull request, Mintlify's checks plus the same-PR rule from its maintenance guide cover the change. When the facts live in tickets, Slack, specs, or a separate code repository, the rule depends on memory; practitioners in an Ask HN thread on keeping docs current describe docs-first habits and homemade nightly scripts.

A Mintlify upkeep checklist for this week

You need write access to the docs repository and its CI. None of these steps needs EkLine.

If your OpenAPI spec is hosted at a URL, call the Trigger deployment endpoint in the CI action that updates the spec.
Run mint broken-links with --check-anchors and --check-external before you publish; renamed headings change their slugs.
Add mint validate to CI so a warning fails the build before readers see it.
When a header, parameter, or endpoint name changes, search the whole docs repository for the old string, including hand-maintained files such as llms-full.txt. The link checks pass on this failure.
Adopt the two process rules from Mintlify's maintenance guide: docs in the same pull request as the code, and a docs sign-off before closing any ticket that changes user-facing behavior.
If you run automations, keep their pull requests on review. Mintlify's drift article calls review the safer setup.

How EkLine plugs into a Mintlify repository

EkLine works in the repository Mintlify already deploys from, so your publishing path stays as it is.

Question	On Mintlify
Where your content lives	The repository Mintlify's GitHub App deploys from, at the root or in a monorepo subdirectory.
What EkLine watches	The code repositories you select in the EkLine GitHub App, which lists them apart from your documentation repository. Docs Agent also reviews GitLab merge requests.
Where its pull request lands	Your docs repository. Mintlify deploys on merge, as it does today.
Which CI check runs	Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, with the `mintlify` framework value, set in its configuration or with `--framework`. The framework support page says "Mintlify currently has the most comprehensive component support."
What stays in Mintlify	`docs.json`, generated API pages, hosting, deploys, and any automations you run.

Walk the auth header change through Docs Agent. When the engineer opens the API pull request, or marks a draft ready, automatic PR review reads the diff, title, and description once and scores the documentation impact. A low score stays silent, a medium score leaves a suggestion comment, and a high score starts a docs pull request in your Mintlify repository for the pages that need the new header. You review and merge it, and Mintlify deploys. Automatic PR review reads the pull request alone and leaves linked tickets out. When the migration note sits in a Jira ticket or a Slack thread, open a Docs Agent session and combine the sources; if they disagree, "the agent flags the conflict in the chat so you can decide." A weekly Docs Drift Review sweeps what merged before you connected EkLine or scored below the threshold, and the Code Sample Review agent in Scheduled Agents "Verifies that code samples in your docs are accurate and runnable."

If your doubt is whether reviewers will trust drafts they did not write: over one quarter, April 7 to July 6, 2026, ContextQA's engineers "merged 97.5% of what the agent proposed, 79 updates, and set aside only two." ContextQA hosts its docs on GitBook, so read this as an EkLine result on another platform.

The limits: the assessment runs once per pull request, you cannot customize its confidence thresholds, and Docs Agent works with GitHub and GitLab. Docs Agent is available to all plans, and EkLine grants access on request.

FAQ

Does EkLine replace your docs platform?

No. Mintlify keeps your docs.json, generated API reference, hosting, and deploys. EkLine adds a step before them: it reads code pull requests as they open, drafts docs pull requests into the repository Mintlify deploys from, and runs a Docs Reviewer check that handles Mintlify components. For a feature-by-feature view, read EkLine vs Mintlify.

Do Mintlify automations replace a docs review step?

Mintlify's own guidance keeps the review step. Its drift article says Mintlify "can be configured to automerge workflow pull requests, but pull request review is the safer setup for user-facing documentation," and its maintenance guide still asks for docs sign-offs and scheduled reviews. An automation drafts the change; a reviewer decides whether it is right before it goes live.

Can't we script this ourselves?

You can, and the Ask HN thread shows one version: cyanydeez described "a for loop that runs nightly on any files updated the prior day," with local AI revising the Markdown file next to each one. On Mintlify, when the quickstart lives in a separate docs repository, nothing sits beside the changed API file to revise. Someone also has to check each nightly rewrite, and rstagi named that cost in the same thread: "it's hard to fact-check everything all the time." EkLine reads the API pull request and, at high confidence, opens a docs pull request for the pages that need the change, so the check happens in review.

Bring one recent API pull request, such as the last auth change, and see what EkLine would have changed in your quickstart. Book an EkLine demo to walk through your own Mintlify setup.

How to keep GitBook in sync with GitHub, and accurate

Alisa Hester — Mon, 12 Oct 2026 06:01:01 +0000

To keep GitBook in sync with GitHub without losing edits, and keep the content accurate, turn on Git Sync, choose the first sync direction on purpose, and edit each page in one place while a change is open. That keeps the editor and your repository identical. For accuracy, make the synced repository the place where every correction lands, whether a writer, an engineer, or EkLine makes it.

Take a common collision. An engineer renames a CLI flag in the code repository while a writer has an open change request in the GitBook editor on the page that documents that flag. The path below lands both edits without either one overwriting the other.

What Git Sync already handles

GitBook describes Git Sync as bi-directional: "changes you make directly in GitBook's editor are automatically synced, as are any commits made on GitHub or GitLab." Your pages sit in the repository as Markdown, and GitBook adds safeguards around the sync:

When you enable GitHub Sync, you "Choose the source of truth for the initial sync," and GitBook warns that "GitHub → GitBook can replace your section's content," for example with an empty repository's empty content.
Edits merged in GitBook reach Git as commits named GITBOOK-{change_request_number}: {change_request_subject}, so your history shows which changes came from the editor.
If your docs live in the code repository, site-wide Git Sync can "sync multiple spaces from one repository and branch," each space in its own directory.
A change request that conflicts with the space's live content is resolved with Keep primary or Keep changed.
You can add an OpenAPI spec by file upload, URL, or CLI. For a URL, "GitBook checks for updates automatically every 6 hours."

Where the flag rename still slips through

Try this on your own space. Open the last merged pull request that renamed a flag, option, or command. Did anything flag the GitBook page that documents it? Each safeguard checks something real, and none of their docs describes comparing a page with the code.

Native check	What it verifies	What it does not see	Where EkLine fits
Git Sync	The editor and the repository hold the same content	Whether that content still matches the code	Automatic PR review reads the code pull request behind the rename
Keep primary or Keep changed	Which side of a conflicting change request wins	A pull request on the same page, which GitBook tracks separately	The docs pull request lands in the synced repository for review
OpenAPI by URL	The reference, checked every 6 hours	The guides written around it	Code Sample Review checks the samples in those guides
GitBook Agent	Change requests, as a linter, and support signals	Code diffs, which its docs do not describe reading	EkLine starts from the code change

GitBook's Git Sync troubleshooting page is clear that the two sides track work separately: "Creating a pull request in GitHub or GitLab doesn't create a change request in GitBook, and creating a change request in GitBook doesn't create a pull request in your repository." The writer's change request and a pull request on the same page proceed without seeing each other.

Existing repositories add two traps. The same page says GitBook "may create new markdown files instead of using the existing ones," and that creating readme files through the GitBook UI "Creates duplicate README files in your repository." In a June 2025 issue filed against GitBook, marmarmo listed "Loss of documentation with overwrites," called it "a common pitfall in GitHub-synced projects," and reported that "the GitBook space had to be hard reset to remove duplicated instances."

Accuracy is a separate job: Git Sync mirrors the old flag name to both sides. On Hacker News, themast wrote that "writing an OpenAPI spec and then keeping a separate GitBook in sync felt like twice the work."

GitBook Agent covers part of this. GitBook's documentation says it writes docs from a prompt, can "Review change requests" as a docs linter, and can use "support conversations, tickets, and threads from your connected tools" to propose updates. It is free for all plans in beta, with 10 free messages a week outside Pro and trials. For a fix that starts in support, it works inside the editor your writers already use. Its December 10, 2025 launch post said that "Soon, GitBook Agent will be able to connect to" support conversations, Slack threads, GitHub issues, and more, and it describes no reading of pull requests or code diffs, where the flag rename starts.

Is a native setup enough? Yes, if your space syncs from the code repository itself, which site-wide Git Sync allows, and the pull request holds every fact the page needs: a rule that the rename and its doc edit merge together covers you. No, when the reason for the rename sits in a ticket, a Slack thread, a spec, or a separate code repository. In an Ask HN thread about keeping documentation up to date, commenters trade docs-first rules and nightly scripts.

A Git Sync safety checklist for this week

Choose the first sync direction on purpose, and confirm the repository holds the content you want before you pick GitHub → GitBook.
Create README.md in the repository and avoid creating readme files in the GitBook UI.
Give each page one place of editing during a change: when a pull request touches a page with an open change request, finish one before you merge the other.
Add your OpenAPI spec by URL so the reference refreshes on the 6-hour check, and click Check for updates after a release.
Know the recovery path: if Git Sync shows an unexpected error, GitBook says merging a small change request exports all content again, and a small commit imports it again.

Where EkLine fits in a Git-synced space

EkLine works in the repository, so Git Sync has to be on; a space edited only in GitBook has no repository to receive a pull request.

Question	With GitBook
Where your content lives	Your GitBook space, synced to a GitHub or GitLab repository. Docs Agent works with GitHub and GitLab, not Bitbucket.
What EkLine watches	Code repositories, which the EkLine GitHub App lists apart from documentation repositories.
When it reads a change	Automatic PR review assesses each pull request once, when it opens or moves from draft to ready. A weekly Docs Drift Review sweeps what merged before EkLine was connected or fell below the threshold.
Where its pull request lands	The Git Sync repository, as a docs pull request your team reviews.
Which CI check runs	Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, through its GitHub Action; `gitbook` is one of its five framework values.
What stays in GitBook	The editor, change requests, hosting, GitBook Agent, and Git Sync.

Back to the flag rename. When the engineer opens the pull request, Docs Agent reads its diff, title, and description. A high-confidence result opens a docs pull request in the synced repository that updates the affected page; a medium one leaves a suggestion comment. The writer merges or closes the open change request on that page first, then reviews the docs pull request and merges it through the normal branch, and Git Sync, GitBook's own feature, carries it into the editor. The review reads the pull request alone ("Linked Jira or Linear tickets are not included"), so a rename that starts in a ticket goes through a Docs Agent session that can combine sources. For a feature-by-feature view, read EkLine vs GitBook.

Will your engineers go along with it? P0 Security, a GitBook team, kept "Same GitHub. Same PR workflow. Same GitBook hosting. Same review process." Its case study reports its engineers reclaimed 150+ hours in 6 months.

Will it reach pages that are already stale? ContextQA, also on GitBook, brought 90 of 113 pages up to date in one quarter; the ContextQA case study adds, "The pages doing that answering are the ones EkLine refreshed."

FAQ

Does EkLine replace your docs platform?

No. GitBook keeps the editor, change requests, hosting, and Git Sync. EkLine adds docs pull requests in your synced GitHub or GitLab repository when code changes, plus a Docs Reviewer check with GitBook framework support. Writers keep working in GitBook and see each merged update there.

Which side wins when the GitBook editor and the repo both change?

GitBook's Git Sync overview and troubleshooting pages do not say. They state that pull requests and change requests are separate, and inside GitBook a conflicting change request is settled with Keep primary or Keep changed. Avoid the race: edit a page in one place at a time, and close or merge the change request before merging a pull request on the same page.

Do I need a GitBook alternative to keep API docs current?

Not for the reference, since GitBook checks a spec added by URL every 6 hours. The guides around it need the repository workflow above. If you decide to leave GitBook for a self-hosted, Git-native site, Potluck Docs is EkLine's open source (MIT) Astro + Starlight template.

Can't we script this ourselves?

Partly. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," with local AI revising the Markdown file beside each changed file. When your space syncs from a separate docs repository, the page that documents a flag does not sit beside the code that renamed it. And every nightly rewrite still needs a reader, the cost rstagi named: "it's hard to fact-check everything all the time." EkLine reads the code pull request instead, and its reviewed pull request reaches the editor through Git Sync.

Pick one merged pull request that renamed something your GitBook pages mention, and bring it along. To see what EkLine would change in your GitBook repository, book a demo. Docs Agent is available to all plans, and access is granted on request.

How to keep Astro Starlight docs accurate after a green build

Alisa Hester — Mon, 12 Oct 2026 05:46:01 +0000

"My Starlight build is green. How do I know the docs are still right?" A green build tells you the site is well-formed: frontmatter matches its schema, internal links resolve once you add a validator, and API pages render from your spec. It cannot tell you whether a sentence in a how-to is still true, which takes a content check driven by what changed in the product.

Take one change: your product renames a component prop. The frontmatter schema passes, the links validate, the starlight-openapi pages regenerate from the updated spec, and the English how-to still shows the old prop. Every translation of that page now repeats the mistake.

TL;DR

Starlight's schema, link, and OpenAPI checks prove the site is well-formed; none reads a how-to against the product.
Translations inherit English errors, and Git-based tracking can flag them once the English page is fixed.
A content check driven by product pull requests closes the gap, with Starlight unchanged.

What Starlight and its plugins already check

Starlight pages live in an Astro content collection, and Astro validates them. In the words of the content collections guide, "Schemas enforce consistent frontmatter or entry data within a collection through Zod validation," and "If any file violates its collection schema, Astro will provide a helpful error to let you know." Starlight's docsSchema() helper takes an extend option that can make built-in fields required or add fields of your own, so a page missing something you care about surfaces as an error.

Link checking came from the community. In June 2023, Starlight issue #247 asked for "basic tooling to ensure the integrity of internal links," and the thread pointed to starlight-links-validator, an MIT-licensed plugin by HiDeoo. Its getting started page describes "A Starlight plugin to validate internal links in Markdown and MDX files," and the check runs during a production build.

The API reference can come from the spec. starlight-openapi, also by HiDeoo under MIT, is a "Starlight plugin to generate documentation from OpenAPI/Swagger specifications," so endpoint pages follow the spec your engineers maintain.

Translations have two tools. Starlight's i18n guide handles missing pages: when a translation does not exist yet, readers get the default-language page with the notice "This content is not available in your language yet." Tracking stale translations belongs to a separate project, Lunaria, which describes "a custom tracking system that keeps track of your source and localized content changes powered by Git." Lunaria's May 2024 launch post lists Astro and Starlight among the projects using it to track translations.

Where the renamed prop slips through

Try this on your docs. Pick the most recent merged pull request that renamed a prop or changed what a component does. Did anything flag the how-to that shows it? Run the rename past each check:

Native check	What it verifies	What it does not see	Where EkLine fits
Collection schema	Frontmatter against its Zod schema	The page body, where the old prop sits	Automatic PR review reads the product pull request
starlight-links-validator	Internal links in Markdown and MDX, in production builds	A how-to whose links resolve and whose example is out of date	Docs Agent opens an MDX edit in your docs repository
starlight-openapi	Endpoint pages generated from the spec	Hand-written how-tos around those pages	Docs Agent drafts their fixes, and Docs Reviewer checks their writing with the astro framework value
Lunaria	Which translations predate a change to the English source	An English page that is wrong and unchanged	A merged English fix gives Lunaria a change to track

The i18n guide describes no outdated-translation check, and once a translated page exists, the fallback notice has no reason to appear, so translated readers see the old prop with no warning. Until someone notices the English error, nothing in the stack flags it.

A checklist you can run this week without EkLine

Extend docsSchema() with an owner or last-reviewed field, so every page names who answers for it and when someone last checked it.
Add starlight-links-validator to the production build your CI already runs, and confirm in your own pipeline how a broken link is reported.
Generate the API reference with starlight-openapi from the spec your engineers ship, and stop hand-editing endpoint pages.
Track translations with Git-based tooling such as Lunaria, so a change to an English source page can show up against each locale.
After each release, reread your most-visited how-to pages against what shipped, starting with pages that show code.

Is a same-PR docs rule enough for a small team?

For most small teams it is: when the engineer who renames the prop also edits the how-to in the same pull request, the docs stay right without new tooling. Practitioners on Ask HN describe docs-first and docs-in-the-PR habits: "Update the documentation first ... Followed by the code changes," and "every AI-heavy PR still needs a human owner, reproducible tests, and docs explaining the behavior change." Starlight's authoring guide describes no built-in AI writer, so a second layer here would not overlap with a platform agent.

Draw the line here. The same-PR rule and Starlight's checks are enough when the product and the docs share a repository and every fact the how-to needs is in that pull request. They fall short once those facts sit in a ticket, a Slack thread, a spec, or a repository the docs team does not watch, or when each how-to has translations to keep in step.

How EkLine fits a Starlight repository

Question	On a Starlight site
Where your content lives	`src/content/docs` in a GitHub or GitLab repository.
What EkLine watches	Your code repositories. The GitHub App lists Code Repositories separately from Documentation Repositories, so the product and the docs can live in different repositories.
When it reads a change	Automatic PR review assesses each pull request once, when it opens or leaves draft, from the diff, title, and description. GitLab merge requests get the same review, per the May 2026 changelog. A scheduled Docs Drift Review sweeps what merged.
Where its pull request lands	Your docs repository, as an edit to the MDX that your team reviews and merges.
Which CI check runs	Docs Reviewer, which checks each docs change for style, consistency, links, and accuracy, set to the `astro` framework value in its config or CLI.
What stays in Starlight	Your Astro build and preview, plugins, schema, and translation workflow.

Take the prop rename again. When it opens as a pull request in the product repository, automatic PR review assesses it. At high confidence, Docs Agent opens a docs pull request that edits the English how-to; at medium, it leaves a suggestion comment; at low, it stays silent. That assessment uses the pull request alone: "Linked Jira or Linear tickets are not included." If the rename merged before you connected EkLine or scored below the threshold, the Drift Review catches it, using a default prompt that starts "Audit the last 30 days of GitHub activity for customer-facing changes that lack documentation." The framework page says "Mintlify currently has the most comprehensive component support" and "Support for other frameworks is expanding," so test your custom components. If the old prop also appears in samples across other pages, the Code Sample Review agent in Scheduled Agents "Verifies that code samples in your docs are accurate and runnable." Docs Agent "is available to all plans, but we grant access on request."

Worried about volume once every product change gets a docs check? At Socure, "One technical writer merged 348 documentation updates in seven weeks" using EkLine, "with no added headcount." The case study does not name Socure's docs platform.

Moving to Starlight, or starting fresh

If you are moving to Starlight from another framework, the path that puts the least accuracy work at risk keeps your docs as Markdown and MDX in Git, so the pull request loop you run today works on the new site too. EkLine maintains Potluck Docs, an open-source Astro + Starlight template under the MIT license, for that kind of start. It ships "Three example OpenAPI references, rendered by Scalar with a built-in client for sending real requests," private docs for signed-in readers and org-scoped docs for each org's members, and a sitemap and llms.txt "generated on every build." By its own description, it is "a template, not a hosted product." Use it to start a site or as a reference; EkLine does not require it.

FAQ

Does EkLine replace your docs platform?

No. Starlight keeps building, previewing, and serving your site, and your schema, plugins, and translation workflow stay where they are. EkLine adds a content layer on top: Docs Agent proposes MDX edits as pull requests when a product change makes a page wrong, and Docs Reviewer checks those pages in CI with its astro framework value.

Does Starlight check for broken links?

Starlight's answer to the 2023 request for link checking, issue #247, was a community plugin: starlight-links-validator by HiDeoo. It validates internal links in Markdown and MDX files during a production build. External URLs are outside its stated scope, and its pages do not say outright that a broken link fails the build, so confirm the behavior in your own CI before you treat it as a gate.

Can't we script this ourselves?

To a point. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," with local AI revising the Markdown next to each one. A Starlight how-to lives in src/content/docs, apart from the component it documents, and each translation adds pages to pair. Each rewrite also needs a reviewer, the gap rstagi named: "it's hard to fact-check everything all the time." EkLine reads the product pull request and proposes the English edit for review.

Open one product pull request from your last release and bring it along. To see what Docs Agent would flag in your Starlight repository after your next release, book a demo with EkLine.

Claude Code mods: what they are and when to build one

Alisa Hester — Mon, 05 Oct 2026 04:30:01 +0000

An hour into a Claude Code session, you scroll back through the transcript to answer three questions: what changed, how much context is left, and whether Claude ran something you would have stopped. The answers are in there, buried under every tool call.

Mods, which Anthropic launched on October 1, 2026, let you put those answers where you already look. The Claude Code mods overview defines a mod as "a plugin that changes how Claude Code looks and behaves," built from JavaScript or TypeScript handlers that run on events such as a tool call or a submitted prompt and "can watch the event, change it, or take it over."

Build one when it shows a signal you keep scrolling for (context left, a risky command, what changed) in the place you already watch the agent work. When a settings hook, a status-line script, or a skill already does the job, skip the mod.

TL;DR

A mod is a plugin whose functions run inside Claude Code on events such as tool calls and prompts.
Good first mods are small: a context band, a guard on risky commands, a replay of the last turn's edits.
Mods run with your permissions, aren't sandboxed, and draw nothing in the VS Code extension's chat panel.

What a Claude Code mod is

A mod is a plugin with code in it. The Create a mod guide says the modules key in a plugin's hooks/hooks.json "is what makes the plugin a mod," and a small mod has three files: plugin.json, hooks.json, and register.js.

A hook observes, rewrites, or answers each event it receives.

Each function in register.js is a hook that takes ($, e, next): the mods API, the event, and the next handler. A hook can observe an event, rewrite it, or answer it so the usual behavior never runs. Drawing, commands, model calls, files, and network access all go through $: "A hook has no other way to do those things, which is why Claude Code can list what a mod does before you install it." The overview's worked example uses two hooks to count tool calls and show "Thinking · tool calls: 3…" on the spinner, in about a dozen lines without comments. "Mods require Claude Code v2.1.287 or later, and they're on by default."

Why mods exist: what hooks could not do

Claude Code already had hooks, which the mods docs call settings hooks: a shell command, HTTP request, or prompt in a settings file that runs on a lifecycle event. Anthropic's launch post names their limit: "Hooks helped give users some of this control, but hooks can't rewrite events, draw new UI, or replace features. Mods can."

The overview lists five things a mod can do that settings hooks, skills, status lines, and MCP servers cannot:

Draw a pane beside the transcript or a band above the prompt.
Redraw Claude Code's own interface, such as the spinner.
Step into a tool call, for example to hold it while it asks you a question.
Run "a /command that runs your function at once, with no Claude turn, even while Claude is working."
Share data between hooks, so "one hook can count tool calls while another shows the count beside the spinner."

Where the hype came from

Mods began as a GitHub proposal for "function hooks," opened September 3, 2026, and now titled "Mods - make Claude 10x more extensible." On September 9 the thread settled the name: "we are going to be calling this functionality 'Claude Mods.'" On October 1 it posted "We're live!"

Many early shared mods are playful or meter-style. OneWave, promoting its own set, open-sourced ten, including "burn-meter," "boss-fight," and "code-pet," and describes mods as changing "what you see while it works." On Reddit, Claude Fables retells the latest moment of a session "as a short art scene in the band above the prompt."

Mod, settings hook, status line, skill, or MCP server?

Pick the simplest option that delivers your signal. Quotes come from the overview's table and the status line docs.

Pick	When you want	What it cannot do
Mod	"a pane, a band above the prompt, a custom command, or to rewrite an event"	Draw in the VS Code extension's chat panel, `claude -p`, or cloud sessions
Settings hook	"to block, allow, or log an event with a script you already have"	Draw in the interface
Status-line script	A persistent line of session data, such as context usage or cost	Draw a pane or buttons, or hold, change, or answer a tool call
Skill	To stop pasting "the same instructions into chat"	Draw in the interface
MCP server	Claude "needs to reach an external system"	Draw in the interface

Only a mod draws panes, bands, or buttons, or runs a command with no Claude turn, and "A plugin can hold all of them," so you can combine them. For the skills side of documentation work, see this ranking of Claude skills for documentation.

The case that mods are cosmetic

One objection is that mods are cosmetic: settings hooks, MCP servers, and skills already cover anything that changes what the agent does. The evidence partly supports it: the docs send you to a settings hook to block, allow, or log. The built-in status line already "receives JSON session data on stdin and displays whatever your script prints," including context usage and cost. An open, undecided proposal in the Codev project rates a mod for role injection "No gain; keep the flag (cross-harness)" and says "shell hook, role flag and render gate remain the cross-harness floor."

The objection fails on control flow. The docs' comparison table says a settings hook can decide whether a tool call goes ahead and can change its arguments. A mod can also hold the call while it asks you a question, answer it without running the tool, and run a /command while Claude is still working. The status line reruns on events such as "A new assistant message arrives," so it can show state but cannot hold, change, or answer a tool call. If your status line and CLAUDE.md show what you need, keep them, and build a mod for the signal they cannot reach.

Creative uses: first mods to try

Anthropic shares its samples "as they are, without support," and MindStudio's mods setup guide warns that stacking several mods clutters the interface, so build the one that solves a real workflow problem.

A context band

One developer's first mod, written up on dev.to, began with "I wanted one thing: to see my context window without typing /context." Anthropic's token-weather sample "draws a forecast of your context window above the prompt."

A guard on risky commands

The blast-radius sample "holds a risky shell command, such as rm -rf or a force push, and shows what it would change, with buttons to proceed or cancel." A guard mod shared on r/claude "asks me to confirm before any commit, push or deploy" and "redacts API keys from tool output before the model reads it."

A replay of the last turn

The replay-theater sample "adds a /replay command that steps through the file edits Claude made in the last turn," which answers what changed without scrolling.

FAQ

What is the difference between a Claude Code mod, a plugin, and a hook?

A mod is a plugin whose hooks/hooks.json has a modules key. A hook is a function inside the mod that Claude Code calls on an event. A settings hook is the older kind: a script in a settings file that can block, allow, or log an event, or change a tool call's arguments, but cannot draw in the interface.

Do I need to know how to code to build a Claude Code mod?

No. Describe the mod in a session and "Claude works from a built-in skill named plugin-authoring," writes it under ~/.claude/dev-mods/, and Claude Code asks whether to enable hot reloading. That mod "loads only in the session that made it," so copy its folder out to keep it. The dev.to author still hit silent failures and a PATH mismatch: "This cost me twenty confused minutes."

Are Claude Code mods safe?

"A mod is code that runs with your permissions," and "Mods aren't sandboxed." A mod can "approve a tool call before you're asked," "Read your secrets," and "Spend your usage," but cannot change the permission prompt. Before installing, run claude plugin validate on its folder: the "hooks: and calls: lines" list what it does without running it.

How do I install a Claude Code mod?

Install it like any plugin from a marketplace, for example /plugin install token-chart@your-org. To turn mods off, disable one in /plugin, start with --safe-mode for one session, or set "disableAllHooks": true to stop every mod you installed in every session. That setting also stops your settings hooks and custom status line; built-in and organization-managed mods keep running.

Do mods work in the VS Code extension?

Hooks run there, but what a mod draws does not appear in the extension's chat panel, claude -p, or cloud sessions. It appears in the terminal, including an editor's integrated terminal and the JetBrains plugin, and in the Desktop app's Code tab, except in WSL sessions and for terminal-only elements. Open issue #99423 (October 4, 2026) reports that in the extension "a mod that loads and hot-reloads correctly draws nothing."

Can my organization block mods?

Yes. Administrators can restrict mods through managed settings, including allowManagedModsOnly. On Team and Enterprise plans and on machines with managed settings, the built-in cc-plugin-sec-default mod loads ahead of every mod a user installs and "Guards what your organization manages from the mods a user installs."

Will the mods API change?

Yes. The Create a mod guide says "The events and methods can change between releases, so trust these files over any page, this one included, when they disagree." Re-validate your mods after you update Claude Code.

Where to start

Pick the one thing you scrolled for in your last long session and ask Claude for a mod that shows it.

If that thing is whether the agent left the docs behind, you could build a tool.call hook that notices edits to .md or .mdx files and shows "docs touched: 3 files, not reviewed" above the prompt, or a /docs-check command that runs a docs linter. EkLine does not ship that mod; it is an idea. EkLine's Docs Agent covers the pull-request side: when a pull request opens on GitHub, it decides whether your documentation needs updating and, depending on its confidence, stays silent, posts a suggestion, or triggers an update. It is available on all plans by request; read how automatic documentation review on pull requests works.

Gemini 4 Argon: What It Does and Where It Falls Short

Alisa Hester — Fri, 02 Oct 2026 20:07:01 +0000

Google announced Gemini 4 Argon on September 30, 2026, with a benchmark table that puts it highest in 13 of 19 rows. If you choose models at a developer-tool or API company, you now have to decide whether that changes this quarter's evaluation plan, budget, or roadmap, working from a launch post, because almost nobody can call the model yet.

Access is what limits that decision. Google's announcement says Argon is "rolling out to a set of trusted cyber defenders through our Fairwind Program." The Gemini API models page, last updated October 1, 2026, lists no Gemini 4 model. There is no API model ID, no date for wider access, and no stated end to the introductory price of $2 per million input tokens and $10 per million output tokens.

This week, decide which workloads to queue for evaluation once a model ID appears. Going by where Argon leads and trails in the published results, queue long-output generation and repo-scale code migration first, and keep terminal-driven agent loops on the model you use now. We have not run Argon. Every performance figure below is Google's or comes from a named third party, as of October 1, 2026.

TL;DR

Gemini 4 Argon is announced but not callable: rollout is limited to Google's Fairwind Program, and no Gemini 4 model appears on the Gemini API models or pricing pages as of October 1, 2026.
Google's own table has Argon highest in 13 of 19 rows, with clear leads on DeepSWE, long context from 256k to 1M tokens, and multimodal (LVBench). It trails GPT-6 Astra and Claude Opus 5.5 on the terminal-driven agent benchmarks.
Independent scoring is less flattering. On Artificial Analysis's Intelligence Index, Argon ties GPT-6 Astra at 53 and trails Claude Opus 5.5 and Sonnet 5.5. It has the lowest hallucination rate of any model scoring 45+ there, but lower accuracy than GPT-6 Astra.
The $2/$10 price is introductory and undated. The regular $4/$20 price matches Claude Opus 5.5, and Argon used about 2.3 times Astra's output tokens per task in Artificial Analysis's runs.

What Google announced

The announcement, "Gemini 4 Argon: our next era of frontier intelligence", signed by "Koray Kavukcuoglu, SVP, Google DeepMind and Chief AI Architect, Google," makes these claims:

An output token limit of "an industry-leading 1M tokens, up from the previous 64K tokens," which Google ties to "longer, more complex use cases."
Introductory pricing of "$2 per million input tokens and $10 per million output tokens, with cached input tokens priced at 95% off input token price," followed by "$4 per 1M input tokens and $20 per 1M output tokens" once the introductory period expires. Google does not say when that is.
Internal coding use: "Google engineers have been using Argon for their daily tasks, from everyday debugging to large-scale codebase migrations and algorithm designs."
Operations work: Argon agents "autonomously identify and apply memory optimizations across Google's data centers, freeing up over 300 TiB of memory once rolled out."
Security: Argon can "autonomously find, validate, and patch critical software vulnerabilities," with safety resting on "misalignment mitigations that monitor Argon's chain-of-thought and actions and stop execution when necessary."

Google's own take on timing is cautious: "We'll continue to gather feedback from early testers as we iterate on guardrails before making Argon available to developers, enterprises, and consumers as soon as possible." For the wider release it names an order, "starting with paid API customers and Google AI Ultra subscribers," but no timeframe for the API, Vertex AI, AI Studio, or the Gemini app.

The post does not state the context window or the input modalities. Artificial Analysis lists a "Context Window: 1M tokens" in its launch article. On modalities, that article and its model page disagree, so treat both facts as unconfirmed until Google publishes a model card.

What the 1M output limit means, and how it differs from the context window

The context window caps what goes in; the output limit caps what one response can return.

The output limit is the less familiar of the two. One Hacker News reader wrote on launch day: "I don't understand the point or meaning of an output token limit." The context window is what the model reads in; the output limit caps what it writes back in one response.

A 64K output cap means a long artifact, such as a multi-file migration diff, a generated SDK, or a long report, has to be split across several calls and stitched back together. A 1M cap should remove much of that splitting for the workloads Google names: "longer, more complex use cases." DataCamp notes there are "no published rate limits in the announcement," so how often you could request a response that long is unknown.

Long outputs cost money. Calculated from Google's list prices, a response using the full 1M output tokens would cost $10 in output at the introductory price and $20 at the regular price. Argon also writes a lot per task: in Artificial Analysis's runs it averaged "62k output tokens per task, compared with 27k for GPT-6 Astra (max)."

Where Argon leads and trails in Google's table

The Google DeepMind model page compares Argon with GPT-6 Astra, Claude Fable 5.1, and Claude Opus 5.5. Argon is highest outright in 13 of 19 rows, tied in one, and behind in five. The rows that matter most for a developer-tool team:

Benchmark (Google's table)	Argon's position	Gemini 4 Argon	Compared with
DeepSWE v1.1	Leads	77.9%	Claude Opus 5.5 74.2%, GPT-6 Astra 74.1%
GraphWalks 256k to 1M	Leads	84.2%	GPT-6 Astra 71.8%
Harvey's Legal Agent Benchmark	Leads	19.6%	Claude Fable 5.1 6.7%
AutomationBench	Leads	51.3%	Claude Opus 5.5 42.5%
LVBench	Leads	91.7%	GPT-6 Astra 87.5%
CWE-bench v1	Tied	68.0%	GPT-6 Astra 68.0% (tie)
FrontierSWE v2	Trails	55.0%	GPT-6 Astra 65.5%
Terminal-bench 4.0	Trails	57.4%	Claude Opus 5.5 66.4%
PostTrainBench	Trails	45.3%	Claude Opus 5.5 49.3%
Terminal-Bench Science 0.1	Trails	57.6%	GPT-6 Astra 68.1%
OSWorld-2.0 (Offline subset)	Trails	69.2%	GPT-6 Astra 72.6%

"Agentic coding" splits in two. Argon leads DeepSWE by about four points and trails FrontierSWE v2 by more than ten. If you run coding agents, look at the benchmark that resembles your loop.

Two third-party results favor Argon. The Vals Index leaderboard, updated 9/30/2026, ranks Argon first at "68.90%," ahead of Claude Sonnet 5.5 at "67.04%."

On AA-Omniscience, Artificial Analysis found that "Gemini 4 Argon has a 15% hallucination rate, the lowest of any model scoring 45+ on the Intelligence Index."

Where Gemini Argon falls short

Terminal-driven agents are the clearest weak spot. The two sources measuring it disagree on details, so keep their figures apart. In Google's table, Argon scores 57.4% on Terminal-bench 4.0 against 66.4% for Claude Opus 5.5 and 58.2% for GPT-6 Astra.

In its own runs, Artificial Analysis reports that "Gemini 4 Argon achieves 57%, ... only behind Claude Sonnet 5.5 (max, 64%), Claude Opus 5.5 (max, 60%) and GPT-6 Astra (59%)." The harnesses and sources differ, so the competitor numbers do not line up, but both sources place Argon behind Opus 5.5.

On the independent index, Argon is not in front. Artificial Analysis says "Gemini 4 Argon (high) scores 53 on the Artificial Analysis Intelligence Index, matching GPT-6 Astra (max, 53)." The Decoder adds: "Anthropic's models still lead. Claude Opus 5.5 sits at 58 points and Claude Sonnet 5.5 at 56." Its headline sums it up: Argon "closes the gap with OpenAI and Anthropic but doesn't take a clear lead."

A low hallucination rate comes with lower accuracy. On the same AA-Omniscience evaluation, Argon scores 50%, which Artificial Analysis calls "a 5 point decrease from Gemini 3.1 Pro Preview."

GPT-6 Astra scores 63% on that test. For a product that answers factual questions, Argon's two numbers point in different directions.

Argon uses more tokens per task. The 62k versus 27k output-token gap means a per-token price comparison overstates the saving. The Decoder concludes: "The price advantage comes from lower token rates, not from efficiency."

Whose numbers these are

Read the methodology note in Google's model evaluation PDF. It says: "All the results for non-Gemini models are sourced from providers' self reported numbers unless otherwise mentioned below." Two of Argon's own coding results are Google's runs: "DeepSWE v1.1 results for Gemini 4 Argon are self computed, using a mini-swe agent harness" and "Terminal-Bench 4.0 results for Gemini 4 Argon are self computed." Argon's scores are "pass @1" at "the highest thinking settings" unless the PDF notes otherwise.

So the table mixes Google's own runs (of Argon on most rows, and of every model on GraphWalks, PostTrainBench, and LVBench) with providers' self-reported numbers and public leaderboards such as Vals AI, and the real-world vulnerability benchmark uses "an internal dataset." One commenter on the Hacker News launch thread, nonethewiser, asked: "How is it even possible for every model to release benchmark results where they are #1 in 75% of categories?" We found no independent hands-on coding reports as of October 1, 2026. With no public access, DataCamp notes, "Almost nobody outside the Fairwind cohort has used Argon yet."

Gemini 4 Argon vs GPT-6 Astra, Claude Fable, Opus, and the model you use now

The table compares every option on the same criteria, read on October 1, 2026. Prices are list prices per 1M tokens from OpenAI API pricing (standard tier, short context is "≤272K input tokens") and Claude pricing.

Option	Public API status, Oct 1, 2026	List price per 1M input / output tokens	Google's benchmark table	Artificial Analysis Intelligence Index	Vals Index
Gemini 4 Argon	No API model ID; Fairwind Program only	$2 / $10 introductory, then $4 / $20	Highest in 13 of 19 rows, tied in 1	53 (high)	68.90%
GPT-6 Astra	Listed on OpenAI API pricing	$10 / $50 (short context)	Leads FrontierSWE v2, Terminal-Bench Science 0.1, OSWorld-2.0; ties CWE-bench v1	53 (max)	63.13%
GPT-6.1 Sol	Listed on OpenAI API pricing	$2 / $10 (short context)	Not in Google's table	52 (max)	61.15%
Claude Fable 5.1	Listed on Claude pricing	$10 / $50	In the table; leads no row	Ties Argon and Astra, per The Decoder	65.83%
Claude Opus 5.5	Listed on Claude pricing	$4 / $20	Leads Terminal-bench 4.0 and PostTrainBench	58, per The Decoder	66.97%
Claude Sonnet 5.5	Listed on Claude pricing	$2 / $10	Not in Google's table	56, per The Decoder	67.04%
Status quo: the model you run today	In production now	What you pay today	Your own results on your own tasks	Not applicable	Not applicable

Argon leads on Google's scoreboard and tops the Vals Index. On Artificial Analysis's index it ties GPT-6 Astra and Claude Fable 5.1, behind two Anthropic models. At its regular price it costs the same as Claude Opus 5.5, and it is the only option in the table you cannot run today.

The status quo is an option too. Hacker News commenter deanc: "I can open codex or claude code apps or CLI and get real work done today with the latest models (even on the cheapest plans)." Argon has no public API, so anything you ship this quarter runs on a model you can call today.

The case for planning a migration now

The strongest opposing view: Google's table has Argon ahead, the Vals Index puts it ahead of Claude Sonnet 5.5 and Opus 5.5, and at $2/$10, Argon's introductory price is a fifth of GPT-6 Astra's $10/$50 short-context price and Claude Fable 5.1's $10/$50. If that holds the day the API opens, Argon becomes the obvious default, and a team with a migration plan ready saves first.

Four facts limit that argument:

The lead depends on the scoreboard. It holds in Google's table, which mixes Google's own runs with providers' self-reported numbers and public leaderboards. On Artificial Analysis's index, Argon ties GPT-6 Astra and trails Claude Opus 5.5 and Sonnet 5.5.
The price is temporary. Google gives no end date for the introductory period, and Vals already lists Argon at "$4 / $20" with a cost of "$15.68" per test. At $4/$20, Argon costs exactly what Claude Opus 5.5 costs.
The low price is not unique. The introductory $2/$10 matches GPT-6.1 Sol's short-context price and Claude Sonnet 5.5, which you can call today.
Cost per task depends on token use. Artificial Analysis puts Argon at "$1.99 per Intelligence Index task" while the price is "currently discounted 50%." Argon also writes about 2.3 times as many output tokens per task as Astra.

What survives is a narrower claim: Argon deserves a place in your evaluation queue, budgeted at the regular price. Prepare the tests now; a roadmap rewrite can wait for access and your own results. VentureBeat's Carl Franzen wrote that "model choice is still workload-dependent, even if Argon now gives Google its strongest claim yet to overall frontier leadership by benchmark count."

Which workloads to queue for Argon

Use one rule for every workload: queue it when published results show Argon leading on that kind of task and the result would change what you ship; leave it where it is when they show Argon behind. Budget every test at $4/$20 and compare cost per task.

Workload	Published evidence	What to do
Long-output generation: large generated files, long reports, multi-file changes in one response	1M output token limit, up from 64K (Google)	Queue first
Repo-scale code migration and long-context code work	DeepSWE v1.1 lead (Google's own run); GraphWalks 256k to 1M lead; Google reports internal use for "large-scale codebase migrations"	Queue first
Factual answers where a wrong answer is costly	Lowest hallucination rate of any model scoring 45+ on its index, but 50% accuracy against Astra's 63% (Artificial Analysis)	Test against your own question set
Terminal-driven agent loops	Trails on Terminal-bench 4.0, FrontierSWE v2, and Terminal-Bench Science 0.1 (Google); behind three models on Terminal Bench 4 (Artificial Analysis)	Stay on your current model
Vulnerability finding and patching	Google's headline claim, from an internal dataset with no counts or false-positive rates; Fairwind access only	Watch; you cannot test it outside the program

This matches DataCamp's Argon guide: "When it opens up to regular users, I would reach for Argon on long-context document and repository work and stay with Claude Opus 5.5 or GPT-6 Astra for terminal-driven agent loops." The guide describes reactions so far as "first impressions of the announcement, not hands-on tests."

By situation:

If your product generates long artifacts, such as SDKs or migration tooling, build your Argon evaluation set now.
If your core loop is a coding agent driving a terminal, keep it on whatever wins your own tests today, and recheck when independent hands-on reports appear.
If cost is your reason to look, compare Argon with Claude Opus 5.5 at the same $4/$20, counting output tokens.
If you defend software and are in the Fairwind Program, you are among the few who can test Google's security claims now.

How to evaluate Argon once access opens

Freeze a task set from your own backlog for the queued workloads, with the expected result for each task.
Run Argon through the harness you use for your current model, and record the thinking level. Google's DeepSWE result came from "a mini-swe agent harness," and Argon's scores use "the highest thinking settings" unless the PDF notes otherwise, so your numbers may differ.
Log output tokens and cost per task at the regular $4/$20 price, next to the same figures for your current model.
Count wrong answers separately from refusals or abstentions, because Artificial Analysis's results separate hallucination rate from accuracy.

What Argon means for developer-tool companies

For a developer-tool company, Argon is a model you might build with, and also one more agent that reads your API and developer docs. When Argon reaches developers, coding agents built on it can read the same pages your users read and repeat whatever is out of date in them.

EkLine works on that side of the problem. It "keeps product, API, and developer docs accurate enough for AI engines, search systems, and agents to find, trust, and cite," as EkLine's post on AI visibility puts it. EkLine Journeys (in beta), described on EkLine's AI visibility page, run the questions people ask through Perplexity, ChatGPT, Gemini, and Claude, and let Claude Code or Codex try your product in a sandbox. You see what each assistant or coding agent says about your product and which pages it cited, so you know which pages to fix.

EkLine is not built to choose or benchmark models, and we have not tested Argon. The page names Gemini, not Argon specifically. EkLine cannot make an assistant cite your page; it shows you what the assistants say and keeps the pages they read accurate.

FAQ

Why is Gemini 4 Argon being released to cybersecurity teams first?

Google says Argon is "rolling out to a set of trusted cyber defenders through our Fairwind Program" while it iterates on guardrails. Security is also Google's headline claim: it says Argon can "autonomously find, validate, and patch critical software vulnerabilities." Google adds that it is "actively engaged in the U.S. government's voluntary process for pre-release model access while we gradually expand access."

How do I get access to Gemini 4 Argon?

As of October 1, 2026, the announcement gives no sign-up or waitlist link outside the Fairwind Program. DataCamp reports that "There is no free tier, no waitlist link, and no published rate limits in the announcement." Google says the wider rollout will start with paid API customers and Google AI Ultra subscribers, without a date. Watch the Gemini API models page for a Gemini 4 model ID.

Did Google catch up after being behind for months?

Partly. Artificial Analysis titled its review "Google is back as one of the top three labs in intelligence achieved" and scores Argon 53, matching GPT-6 Astra, while The Decoder notes that Claude Opus 5.5 and Sonnet 5.5 still score higher. Google's own table, which combines Google's runs with providers' and leaderboards' numbers, shows a lead in 13 of 19 rows.

To check what AI assistants and coding agents read and repeat from your developer docs, see how EkLine shows what AI assistants say about your product.

What Is WebMCP? When to Expose Browser Tools to AI Agents

Alisa Hester — Fri, 02 Oct 2026 14:58:01 +0000

WebMCP lets a web app declare structured tools that a browser agent can call. As the WebMCP specification defines it, each tool runs inside the page with access to the user's authenticated session and current application state.

That context supports actions tied to what the user already has open, such as updating the current cart, saving a draft on the active support ticket, or creating an issue in the selected workspace.

On September 28, 2026, Shopify added checkout WebMCP tools that can read checkout state; update buyer details, fulfillment, discount codes, declared fields, and payment; and place an order after buyer confirmation. Shopify's checkout WebMCP changelog notes that its storefront and cart tools were already available.

Cloudflare's WebMCP beta changelog says Browser Run extended support to Kitesurf that day and migrated Chrome Lab sessions from the earlier testing API to document.modelContext.

WebMCP is still experimental. Its specification is a Draft Community Group Report. The project's implementation-status page lists origin trials in Chrome 149 and Edge 150, experimental Leo support in Brave, and ChatGPT Desktop support. It does not list Firefox or Safari implementations, so broad browser interoperability is not available.

Use WebMCP for actions tied to the current browser session, an MCP server for capabilities that must run without the page, and browser automation when a site exposes no adequate structured agent interface.

TL;DR

The WebMCP specification lets a page expose named, schema-defined tools to AI agents through the browser.
It is a good fit for session-aware actions such as searching a catalog, updating a cart, saving a draft, or changing the object open in the current tab.
It is a poor fit for unattended jobs, cross-service orchestration, or integrations that must work after the website closes.
Declarative WebMCP turns HTML forms into tools. Imperative WebMCP registers JavaScript tools through document.modelContext.
Treat it as progressive enhancement. The implementation-status page shows why the existing interface or API path must remain available while browser support is experimental.
Start with one read-only or reversible workflow. Do not make payment, deletion, publishing, or permission changes your first test.

What is WebMCP?

WebMCP is a browser API for exposing web application actions as structured tools. Each tool defines an action, its accepted inputs, its execution path, and what value, if any, execution returns. Imperative tools can also supply optional risk or debugging hints.

The proposal has two authoring models: declarative metadata on HTML forms and imperative registration through document.modelContext.

This contract lets an agent call an action directly rather than infer it from the DOM, accessibility tree, screenshots, labels, or layout. Chrome's WebMCP guide describes the structured path as more reliable and token-efficient than element-by-element navigation.

The website remains the application surface. It keeps the state and business logic, while the browser exposes only the tools the page registers.

How WebMCP works

A typical flow has five steps:

The user opens and signs in to a web application.
The page declares or registers tools relevant to its current state.
A browser agent discovers the available tools.
The agent selects a tool and supplies arguments that match its schema.
The page executes the action. An imperative callback's serializable return value is passed to the caller; an invocation that navigates the page can resolve to null.

WebMCP tools run in the page context, so they can use the session, account, cart, draft, route, or other frontend state already open.

Declarative WebMCP

Use the declarative API when the action is already represented by an HTML form. Add a tool name and description to the form, then describe the parameters on the relevant controls.

form action: /catalog/search
method: GET
tool name: search_catalog
tool description: Search products by query and maximum price.
auto-submit: enabled

query input
 type: search
 required: yes
 parameter description: Product name or feature to search for.

maximum price input
 type: number
 minimum: 0
 parameter description: Highest acceptable price in US dollars.

The declarative API's toolautosubmit attribute lets the agent submit the form directly, which suits read-only searches. For payments, deletions, publishing, or permission changes, follow Chrome's security guidance and leave it off so users keep the existing review step.

Declarative tools let people and agents use the same form, validation, and submission path. The team maintains one workflow for both.

Imperative WebMCP

Use the imperative API when the action depends on dynamic application logic or cannot be represented cleanly as a form.

async function registerSupportDraftTool() {
 if (!("modelContext" in document)) return null;

 const controller = new AbortController();

 await document.modelContext.registerTool({
 name: "save_support_draft",
 description: "Save a draft reply for the support ticket open in the app.",
 inputSchema: {
 type: "object",
 properties: {
 ticketId: {
 type: "string",
 description: "The ID of the open support ticket."
 },
 body: {
 type: "string",
 description: "The reply text to save as a draft."
 }
 },
 required: ["ticketId", "body"]
 },
 annotations: {
 readOnlyHint: false
 },
 execute: async function ({ ticketId, body }) {
 const draft = await saveDraft({ ticketId, body });

 return {
 draftId: draft.id,
 status: "saved",
 reviewRequired: true
 };
 }
 }, {
 signal: controller.signal
 });

 return controller;
}

The imperative API supports unregistration through an AbortSignal. In a single-page application, abort the existing registration and register a replacement when the route, selected object, or available action changes.

const supportDraftRegistration = await registerSupportDraftTool();

// When the route, permissions, or state changes:
supportDraftRegistration?.abort();

WebMCP vs browser automation vs a backend MCP server

Choose the interface based on where the required state lives and how long the task must run. These layers can also be combined. Cloudflare's WebMCP beta shows how a browser-automation client can invoke WebMCP tools when a site exposes them and fall back to DOM, accessibility-tree, or visual interaction when it does not.

Approach	Best fit	Main advantage	Main tradeoff
WebMCP	Actions inside the current authenticated page	Reuses live browser state and lets the site define a stable tool contract	Experimental browser support and page-bound availability
DOM or visual browser automation	Sites or workflows without an adequate structured tool interface	Works without cooperation from the product team	Depends on selectors, layout, visual interpretation, or other interface details that can change
MCP server, usually remote for service-level integrations	Remote tools, background work, cross-client access, and service-level integrations	Runs independently of the page and fits MCP's client-server model	Requires a separate integration and may need explicit session or object context

MCP uses a host-client-server architecture. An MCP server can run locally or remotely and expose tools and other capabilities to a host through an MCP client. By contrast, WebMCP's page-level path does not require an MCP server, although a page tool may still call backend services.

Browser automation covers sites with no WebMCP or API integration, including exploratory work and compatibility testing. Selectors, layouts, and visual cues can change, which makes the automation fragile. Chrome's comparison explains how WebMCP replaces that inference step with a contract defined by the product team.

Apply the same rule to implementation:

Use WebMCP when the task depends on state in the current tab.
Use an MCP server when the state lives in a service or the task must work across clients.
Use browser automation when neither structured option exists, and budget for maintenance as the interface changes.

Five signs that WebMCP fits your product

1. The current browser session matters

WebMCP is useful when the user has already selected the relevant account, workspace, cart, ticket, document, or draft. The agent can act inside that context instead of reconstructing it through a second authentication and selection flow.

Shopify's checkout WebMCP implementation shows the pattern. Its tools operate on the active checkout and cover reading state, updating checkout fields such as contact details, fulfillment, discounts, and payment, and placing the order after buyer confirmation. Cart-item changes remain the job of storefront or cart tools, or the checkout interface.

2. The action already exists in the interface

A WebMCP tool should map to an existing interface action, such as searching the catalog, adding an item, saving a draft, creating an issue, or applying a filter. That shared path preserves a visible fallback and reuses the product's validation and business rules. Actions with no clear interface meaning usually need a narrower contract before agent use.

3. The user should remain close to the action

WebMCP suits workflows where users need to inspect state before or after execution, especially payments, publishing, privacy, and access changes.

Shopify's checkout tools require confirmation before completion. Apply the same boundary to consequential actions: let the agent prepare the change, while application policy and user approval govern execution.

4. The task has bounded inputs and a clear result

Tools work best when their names, descriptions, schemas, and return values remove ambiguity. search_catalog is better than interact_with_store. save_support_draft is better than handle_ticket.

Chrome's WebMCP best practices recommend concise descriptions, focused tools, and dynamic registration based on the current application state. If you need a long prompt to explain what a tool might do, the action is probably too broad.

5. The agent can call product logic directly

A WebMCP tool can call the same application function as a button or form. The contract can stay stable as the control's placement or label changes. Keep interface tests for the human path.

When WebMCP is the wrong interface

The capability must outlive the page

Scheduled jobs, long-running processing, webhooks, background orchestration, and tools used from multiple clients belong at the service layer. Use an API or MCP server when the task must run after the page closes or from an IDE, desktop assistant, command line, support platform, or automated workflow.

The workflow crosses several products

Keep cross-service orchestration outside the page. It needs explicit authentication, retries, observability, and ownership at the service layer.

The action cannot be made safe enough for agent use

Do not expose a destructive or irreversible operation because it is technically possible. Some actions need a review screen, a confirmation token, a second factor, a transaction limit, or no agent path at all.

Browser coverage would block the core workflow

The WebMCP implementation-status page still shows limited browser interoperability. Keep the existing interface and API path available so the workflow works outside supported browsers.

WebMCP makes invocation explicit. The application still owns policy, permissions, and confirmation.

Enforce security in application code

WebMCP makes tool invocation explicit. Product controls still determine whether an action is authorized and safe.

For imperative tools, Chrome's security guidance covers prompt injection, untrusted tool output, origin boundaries, and confirmation for consequential actions. Optional annotations such as readOnlyHint, untrustedContentHint, and consequentialHint give the agent risk signals; application code enforces the policy.

A practical security baseline includes:

Validate every argument on the server, even if the page already validated it.
Authorize the requested action against the current user and object.
Require explicit confirmation for payment, deletion, publication, permission, and identity changes.
Return the minimum data the agent needs.
Treat page content and tool results as untrusted input to the model.
Log the tool name, actor, result, confirmation path, and only the argument data permitted by the product's privacy policy.
Rate-limit actions independently of the chat interface.

The tools Permissions Policy defaults to self. An embedding page can delegate it to a cross-origin iframe through the iframe's allow="tools" attribute. For cross-origin in-page agents, the registering document must also include the caller's secure origin in registerTool(..., { exposedTo: [...] }), and the caller must request the tool owner's origin through getTools({ fromOrigins: [...] }). Chrome's security guidance makes clear that these browser boundaries do not replace application authorization.

Cloudflare's Browser Run documentation notes an important beta limitation: Kitesurf does not yet implement the tools Permissions Policy or origin-based tool filtering, and tools registered in iframes or popup windows are not exposed through its CDP integration.

Keep the tool surface smaller than the interface

Large web applications may have hundreds of actions. Exposing them all can make selection harder and consume more agent context.

Chrome's Lighthouse audit flags pages with more than 40 declared tools. Treat 40 as an audit trigger. Most routes should expose far fewer.

A project list can expose search_projects and create_project.
A project detail route can expose rename_project, add_member, and archive_project.
A support ticket can expose summarize_ticket, save_reply_draft, and change_status.

Chrome's best practices recommend unregistering tools when the user leaves the route or loses access so the agent sees only actions relevant to the current route and permissions.

A seven-step WebMCP pilot

1. Pick one reversible outcome

Start with search, filtering, drafting, or saving a non-public change. Avoid purchases, deletion, publication, and permission changes in the first pilot.

2. Write the contract before the code

Define the tool name, one-sentence description, input schema, success result, error cases, permission checks, and confirmation rule.

3. Reuse the existing product action

Call the same domain function used by the form or button, keeping one implementation for human and agent paths.

4. Preserve the human path

WebMCP requires a secure, origin-isolated document. Chrome documents that pages using document.domain, including pages configured with Origin-Agent-Cluster: ?0, cannot use the API.

Keep the form or controls functional when document.modelContext is unavailable. The current implementation status is a strong reason to detect support at runtime and add WebMCP as progressive enhancement.

5. Add risk controls

Set the relevant annotations, then follow Chrome's security guidance by enforcing authorization, validation, confirmation, and rate limits in application code.

6. Test the tool and the fallback

Run direct tool calls with valid, invalid, stale, unauthorized, and adversarial inputs. Test the normal interface without WebMCP. Chrome also provides Lighthouse checks for common tool-definition problems.

7. Measure task success

Track tool choice, argument validity, task completion, human correction, and fallback to browser navigation. Use completion and correction rates as the decision metrics; tool-call volume measures activity rather than success.

For a fuller measurement model, see How to Measure Whether AI Coding Agents Use Your Developer Documentation.

Choose by state, lifetime, and fallback

Start by identifying the product action, the state it needs, and how long it must remain available. Use WebMCP when the action depends on the current tab. Use an API or MCP server when it must outlive the tab, run in the background, or serve many clients.

Pilot one reversible action on one route, define its success condition, and verify that the existing interface still works when WebMCP is unavailable.

When to Hire a Technical Writer, When to Automate, and How They Work Together

Alisa Hester — Fri, 02 Oct 2026 14:22:03 +0000

TL;DR

Hire a technical writer when nobody owns the documentation program or when the work requires audience judgment, information architecture, stakeholder alignment, and editorial accountability.
Automate when a writer or another docs owner is buried in change detection, context gathering, routine drafting, repetitive checks, and follow-up.
If the company lacks ownership and the current workflow cannot keep pace, solve both problems together: give a technical writer clear authority and add an agent around the repeatable steps.
Socure used this model across 25+ products. Peter Schwarck reviewed and published the updates while EkLine prepared source-grounded drafts, giving him more time for information architecture and larger documentation improvements.

How Socure paired a technical writer with automation

Socure had one technical writer supporting more than 25 products across two platforms. Documentation requests reached him through chat messages, tickets, and a release tracker. Identifying affected documentation consumed time before he could assess the change, resolve open questions, and shape the update.

Socure already had a technical writer with clear ownership. Its bottleneck was detecting affected documentation and preparing updates across a large product surface, so the company added EkLine around Peter Schwarck's workflow. EkLine surfaced likely documentation work and prepared source-grounded drafts. Peter decided what needed to change and approved publication.

Peter also gained time for information architecture and larger documentation improvements that had been waiting for attention.

In seven weeks, Socure reported 348 merged documentation updates, the estimated equivalent of more than 1,000 hours of documentation work, with no added headcount. This establishes Socure's result only; staffing requirements vary by company. It shows how a writer-led workflow can increase coverage when automation handles defined preparation steps.

Read the full Socure case study.

Diagnose the documentation work before setting headcount

A request for a technical writer often bundles several different problems:

Nobody is accountable for the documentation.
The product changes faster than the current owner can track.
Engineers know the product but cannot keep writing every guide.
Existing docs lack structure, consistency, or a clear audience.
Support answers useful questions that never become public documentation.
Routine maintenance consumes the time needed for strategic work.

Different items require different responses. Missing ownership calls for a hire or an explicit assignment. Repeatable workflow gaps call for automation around that owner.

Before opening a requisition, list the documentation work from the last month. For each item, mark where audience judgment, source validation, structure, or approval was required, then mark which steps followed a repeatable pattern. Most documentation work contains both. This map will show whether the immediate gap is ownership, capacity, or both.

Type of work	Examples	Best owner
Judgment	deciding what the audience needs, resolving conflicting sources, choosing the right explanation	technical writer
Program ownership	information architecture, editorial standards, roadmap, stakeholder alignment	technical writer
Subject-matter validation	confirming API behavior, security details, and product intent	engineer or product owner, coordinated by the writer
Detection	finding which pages are affected by a code change, release, or recurring support question	automation
Preparation	gathering source context and drafting a routine update	automation, reviewed by the writer
Repeatable review	checking terminology, style rules, links, structure, and required sections	automation, governed by the writer

If no one owns the documentation program, hire or assign that owner first. If an owner exists but cannot keep pace with product change, add automation around their workflow. Teams facing both problems should do both.

The agent prepares the work. The technical writer owns the decision and approval.

When to hire a technical writer

Open the requisition when the missing capability is human judgment or clear ownership.

Nobody owns the user's learning experience

Documentation is a product surface. Someone has to understand what a developer is trying to accomplish, where the current explanation fails, and how the pieces should fit together. A queue of generated pages does not provide that ownership.

A technical writer can turn scattered requests into a coherent program. They define the audience, establish the structure, set standards, and decide what deserves attention first.

The documentation needs information architecture

A growing product accumulates pages, examples, release notes, and troubleshooting articles. The hard work is deciding how users should move through them.

Automation can identify duplicated or disconnected content. A writer decides whether to merge pages, split a long guide, change the navigation, introduce a new concept, or remove material that no longer helps.

Product teams disagree about the correct explanation

Code, tickets, internal discussions, and support answers do not always agree. Someone must resolve the conflict and produce an explanation the company is willing to stand behind.

This is editorial and organizational work. It often requires interviewing engineers, product managers, support, security, and customers. Hire for it.

The company needs an accountable editorial standard

Terminology, tone, examples, accessibility, and risk boundaries need an owner. Automation can apply rules after the rules exist. A writer creates those rules, updates them when the product changes, and knows when an exception is justified.

High-risk content requires careful judgment

Authentication, billing, permissions, migrations, security, and breaking API changes deserve a named owner. An agent can gather evidence and prepare a draft. A writer should coordinate the review and make sure the final guidance is clear, complete, and approved.

When to automate documentation work

Automation makes sense when the company already has a qualified documentation owner, but repeatable workflow steps with stable inputs and review rules consume too much of that person's time.

The writer has to chase every product change

A writer cannot attend every engineering discussion or inspect every merged pull request. When the documentation process depends on someone remembering to file a ticket, important changes will arrive late or remain invisible.

Automation can monitor defined product signals, identify likely documentation impact, and bring the change to the writer. The writer then decides whether an update is needed.

Routine updates begin with the same research every time

Many documentation tasks start with gathering a code diff, release context, an existing page, a support conversation, and the current style rules. An agent can assemble that context and prepare a reviewable first draft.

The writer starts with relevant sources and a draft to assess, then decides whether the update is useful, accurate, and ready for broader review.

Reviewers repeat the same checks

Style, terminology, links, headings, required sections, and structural rules can be checked consistently before a human review. The writer should define the rules and own exceptions. The agent should run the routine inspection every time.

Documentation requests arrive faster than they can be triaged

A crowded queue hides the difference between a small factual correction and a new guide that needs research. Automation can classify and route the work so the writer spends attention according to risk and user impact.

The docs owner has no time for strategic improvements

When maintenance and change-chasing fill the week, the writer has less time for onboarding research, information architecture, and other program-level improvements. Automating defined preparation and checking steps restores that capacity without removing editorial ownership.

How the writer and the agent should work together

The writer defines and owns the documentation system, including its priorities, standards, and approval rules. The agent works within those boundaries.

A practical workflow looks like this:

A code change, release, repeated support question, or documentation audit creates a signal.
The agent gathers the relevant sources and identifies the affected documentation.
The agent prepares a draft or a focused recommendation with its source trail.
The writer checks audience fit, product accuracy, structure, terminology, and risk.
An engineer or product owner resolves any open technical question.
The writer approves, edits, rejects, or redirects the work.
The team measures whether the update reduced drift, repeated questions, or reviewer effort.

This model keeps publication authority with the team. It also creates a visible path from product change to documentation change, which is difficult to maintain through ad hoc tickets alone.

Technical writers evaluating what this changes in their daily work can read EkLine for technical writers. The writer retains program and editorial ownership: deciding what users need, shaping the information architecture, resolving ambiguity, coordinating technical review, and approving publication. The agent expands coverage by preparing traceable work for review.

A decision guide for the requisition you are about to open

Use the following questions before deciding what to buy or whom to hire.

Question	If the answer is yes	Recommended action
Is there no accountable documentation owner?	Strategy and judgment are missing.	Hire a technical writer.
Are engineers writing most customer-facing docs from scratch?	The company needs editorial ownership and a better contribution workflow.	Hire a writer and automate source gathering plus first drafts.
Does a capable writer spend most of the week chasing updates and doing routine maintenance?	Capacity is trapped in repeatable work.	Add automation around the writer.
Are the docs poorly structured or hard to navigate?	The problem requires information architecture.	Hire or assign a senior documentation owner before automating broadly.
Are updates late because teams forget to notify docs?	Change detection is broken.	Automate detection and routing.
Is there nobody qualified to review generated updates?	The approval layer is missing.	Establish ownership before adding generation.
Is the product surface growing across many teams?	Ownership and coverage must scale together.	Use a writer-led, agent-assisted model.

Open the requisition when the company needs an accountable documentation owner. If maintenance volume is also a problem, define the writer's remit and automate the repeatable parts of the workflow as part of the same plan.

What to take from the Socure example

Socure's result shows one condition where this model can work: a capable writer already owns the program, while change detection and draft preparation limit coverage across a broad product surface.

Treat the 25+ product ratio as specific to Socure. Product complexity, release cadence, existing documentation quality, review requirements, and source access will change the staffing and workflow a different company needs.

Peter remained responsible for editorial judgment and publication. The workflow gave him more time for information architecture and documentation improvements that had been crowded out by incoming requests.

Documentation automation should increase the writer's control over the program and capacity to improve it.

Run a small workflow test before changing the team plan

Test the workflow on recent documentation work rather than a generic automation demo.

Select five to ten recent product changes and recurring support questions that led to documentation work.
Ask the current docs owner to mark where each item required audience judgment, source validation, drafting, or approval, and which steps repeated across items.
Keep audience decisions, ambiguity resolution, structure, and approval with the writer.
Test automation on detection, context gathering, first-draft preparation, and repeatable checks.
Record the affected pages found, factual corrections made during review, reviewer time, and elapsed time from signal to approved change. Compare those results with the current process.

The result should tell you what the requisition needs to accomplish. If the test reveals both missing ownership and a repeatable maintenance bottleneck, hire the writer and automate the bottleneck. If only one is missing, solve that problem first.

Make the requisition match the bottleneck

Open the requisition if the team lacks an accountable documentation owner with authority to set priorities, structure, and standards. Add automation if that owner is spending too much time finding changes, collecting source context, preparing routine updates, or running repeatable checks. If both conditions are true, fund the role and the workflow together.

Keep publication approval with the writer. Evaluate the combined system by documentation coverage, factual corrections during review, reviewer effort, and user outcomes.

To see how this workflow would handle your recent product changes and support questions, book an EkLine walkthrough.

FAQ

Should we hire a technical writer or automate documentation?

Hire a technical writer when the company lacks clear documentation ownership, audience judgment, information architecture, or editorial governance. Automate when an existing owner spends too much time detecting changes, gathering context, drafting routine updates, and checking repeatable rules. Fast-moving technical companies often need both: a writer who owns the documentation program and an agent that handles repeatable work.

Does EkLine replace technical writers?

No. EkLine gives technical writers leverage. It helps detect documentation work, gather source material, draft updates, run quality checks, and route changes for review. The writer still decides what users need, resolves ambiguity, shapes the information architecture, and approves publication.

What work should a technical writer own?

A technical writer should own audience understanding, documentation strategy, information architecture, editorial standards, cross-functional decisions, high-risk explanations, and final approval. These jobs depend on audience judgment, cross-functional trust, and clear accountability.

What documentation work should be automated?

Good candidates include detecting documentation impact from product changes, collecting relevant source context, drafting routine updates, checking style and terminology, finding broken links, and routing a reviewable change to the right owner.

How did Socure combine a technical writer with EkLine?

Socure paired one technical writer with EkLine across more than 25 products. Peter Schwarck reviewed and published the updates while EkLine detected changes and prepared source-grounded drafts. Socure reported 348 merged documentation updates in seven weeks, the estimated equivalent of more than 1,000 hours of documentation work.