DEV Community: Alisa Hester

OpenAI Prompt Caching: When Is the New 12-Hour Cache Cheaper?

Alisa Hester — Tue, 27 Oct 2026 21:55:27 +0000

Your prompt caching dashboard shows a healthy read hit rate. The inference bill stays high anyway. Then OpenAI ships 12-hour prompt caching, and someone on the team asks whether you should switch.

On GPT-5.6 and later, a 12-hour (12h) cache write costs 2.5x the input price, while a write at the default 30-minute (30m) lifetime costs 1.25x. So 12h only pays when the same unchanged prefix comes back after two or more gaps longer than 30 minutes inside a 12-hour window. Otherwise 30m is cheaper, even when 12h shows a higher hit rate.

Hit rate counts reads. It says nothing about what you paid to write the prefix, and that write price now depends on the retention you pick. You can price each prefix from your own request logs with one rule and about 30 lines of Python.

TL;DR

On GPT-5.6 and later in the Responses API, you choose a 30-minute or 12-hour minimum lifetime, and the 12-hour write costs twice as much.
Count the gaps longer than 30 minutes after which the same prefix is reused inside one 12-hour window. With zero or one, 30m is cheaper. From two, 12h is cheaper.
A higher hit rate can come with a higher bill. In the modeled scenarios, 12h lifts the hit rate by five points and still costs more in one case, and ties on hit rate while costing 36% more in another.
Decide from cost per prefix per window, calibrated with your own usage fields.

What changed on October 20, 2026

OpenAI's changelog entry reads: "You can now choose 12-hour prompt caching in the API. 12-hour prompt caching keeps shared instructions, tools, and context cached longer to benefit from lower cached-input pricing, even when requests are hours apart. 12-hour cache writes cost 2.5x the input token price." The entry is tagged for the Responses API, and the two model generations now follow different rules.

Models	Setting	Values	Write charge	What the lifetime means
GPT-5.6 and later	`prompt_cache_options.ttl` (Responses API)	`30m` (default) or `12h`	1.25x input for 30m, 2.5x for 12h	A minimum lifetime for read-price eligibility
Earlier models	`prompt_cache_retention`	`in_memory` or `24h`	None	A best-effort maximum

The prompt caching guide says the older 24h setting "typically keeps entries available for around 30 minutes and can retain them for up to 24 hours." Twenty-four hours is the ceiling. The new 12 hours is a floor: for that long, a matching prefix is eligible for the cached-input price. Since May 29, 2026, 24h has been the default for organizations without zero data retention (ZDR), with no write charge.

The guide adds: "The minimum lifetime governs eligibility for cache-read pricing. It does not guarantee that every request reuses stored KV tensors or has lower latency."

How OpenAI prompt caching bills a prefix

The cache stores key-value (KV) tensors for a reusable prefix, the unchanged tokens at the start of the prompt. It does not store the tokens themselves, and caching "does not change how the model generates output tokens." On GPT-5.6 and later, the minimum cacheable prompt is 1,024 tokens. Caching is on by default for supported models, and the guide documents no way to turn it off.

You control where the prefix ends. With mode set to implicit, OpenAI places a breakpoint at the end of the latest eligible message. With explicit, you place your own breakpoints, and each request can create up to four cache writes. Tokens after the last breakpoint are billed at the uncached input rate with no write charge.

Each prefix then meets three prices:

The write: 1.25x the input rate for 30m, 2.5x for 12h.
The read: 0.1x the input rate on most of these models, and 0.05x on gpt-6.1-sol.
The rewrite: a full new write when a request arrives after coverage has ended.

The guide works one example: "At the 0.1× read rate with 30-minute writes, writing a prefix once and fully reusing it once costs 1.35× its ordinary input cost, compared with 2× for processing it twice without caching."

Reads also extend coverage. In the guide's words, "A 30-minute read refreshes coverage to at least 30 minutes after that read. If it uses an entry with valid 12-hour coverage, it preserves the later of the existing expiry and 30 minutes after the read. It does not restart a 12-hour clock or incur another write charge." Upgrading valid 30-minute coverage to 12 hours charges a new 12-hour write, with no credit for the earlier write.

The prefix must also stay identical. Changes to tools, text.format, reasoning.effort, and text.verbosity affect the cached prefix, so keep stable instructions and shared reference material first and variable content at the end.

The break-even rule

The guide frames the choice in one line: "Compare the higher 12-hour write rate with the cost of rewriting the prefix after 30-minute coverage expires."

With 30m, every long gap costs a fresh write at 1.25x. With 12h, you pay 2.5x once and every long gap costs only a read, so from the second long gap 12h costs less.

Write the cost of one prefix over one 12-hour window as a multiple of its ordinary input cost:

30m: 1.25 × (1 + G)
12h: 2.5 + (r × G)

The inputs:

G (measured, from your trace): the number of gaps longer than 30 minutes after which the same unchanged prefix is reused inside one 12-hour window.
r (from the guide and the price list): the read rate, 0.1 on most GPT-5.6 and later models or 0.05 on gpt-6.1-sol.
1.25 and 2.5 (from the guide): the write multipliers.

Reads inside a burst cost the same under both options, so they drop out. At G = 0, it is 1.25 against 2.5. At G = 1, it is 2.5 against 2.55 (r = 0.05) or 2.6 (r = 0.1), so 30m still wins. At G = 2, it is 3.75 against 2.6 or 2.7, so 12h wins.

A service that runs longer than 12 hours needs a new 12h write in each window, because reads do not restart the 12-hour clock. The openclaw maintainers merged 12h support the day after launch as an opt-in, with write-price accounting, in their pull request to opt into 12-hour prompt caching.

Five modeled scenarios: an illustration with list prices, not a benchmark

The numbers in this section come from a replay model run on OpenAI list prices. They are not results from production traffic, and the replay model makes no API calls. Every scenario uses these assumptions:

Prices for gpt-6.1-sol, Standard tier, short context, per 1M tokens, from OpenAI's pricing page: input $2.00, cached input $0.10, cache write 30m $2.50, cache write 12h $5.00, output $10.00.
One stable 20,000-token prefix (system prompt, tool definitions, reference material) with an explicit breakpoint at its end.
1,000 variable input tokens after the breakpoint per request, at the uncached input rate with no write charge.
500 output tokens per request.
Every request inside coverage is a read.
A read extends coverage to at least 30 minutes after it and never restarts the 12-hour clock.
A request after coverage ends is a fresh write.
"No cache" is a reference line only, with every prefix token at the input rate. It is not a setting OpenAI documents.
Hit rate is the share of requests that read the prefix.

Modeled illustration with OpenAI list prices (gpt-6.1-sol, Standard tier). Not a benchmark.

Scenario	Requests	No-cache reference	30m cost and hit rate	12h cost and hit rate	Cheaper option
A. Steady: one request every 2 minutes for 8 hours (G = 0)	240	$11.2800	$2.2080, 239/240 (99.6%)	$2.2580, 239/240 (99.6%)	30m, by $0.05
B. Bursty: six bursts of 10 requests 30 seconds apart, bursts start 90 minutes apart (G = 5)	60	$2.8200	$0.8280, 54/60 (90.0%)	$0.6380, 59/60 (98.3%)	12h, 23% cheaper
C. Sparse: four requests three hours apart (G = 3)	4	$0.1880	$0.2280, 0/4 (0%)	$0.1340, 3/4 (75.0%)	12h
D. Same bursts as B, but the prefix changes before each burst (G = 0 for every prefix)	60	$2.8200	$0.8280, 54/60 (90.0%)	$1.1280, 54/60 (90.0%)	30m (12h costs 36% more)
E. Two bursts of 10 requests, two hours apart (G = 1)	20	$0.9400	$0.2760, 18/20 (90.0%)	$0.2780, 19/20 (95.0%)	30m, by $0.002

In every row, the cheaper option is the one the break-even rule predicts from G. In A and D the hit rates tie while the costs differ, and in E the higher hit rate belongs to the more expensive option.

In C, every 30m request is a write at 1.25x, so 30m costs more than the no-cache line. D is the deploy case: a release edits tool definitions, or a timestamp sits in the system prompt, so each burst starts with a new prefix and the 12-hour coverage on the old one goes unused.

The replay model behind the table

The script replays request times and prefix versions against the billing rules and prices in the assumptions. The trace at the end is Scenario E.

# Replay a request trace against OpenAI's documented cache billing for GPT-5.6+.
# Prices: USD per 1M tokens, gpt-6.1-sol, Standard tier, checked 2026-10-22.
PRICES = {"input": 2.00, "cached_input": 0.10,
          "write_30m": 2.50, "write_12h": 5.00, "output": 10.00}

def replay(trace, ttl, prefix_tokens, tail_tokens, output_tokens, p=PRICES):
    """trace: list of (minute, prefix_version). ttl: "30m", "12h" or None."""
    life = {"30m": 30, "12h": 720}.get(ttl)
    expiry = {}  # prefix_version -> minute the coverage ends
    cost, hits = 0.0, 0
    for minute, version in trace:
        if ttl is None:  # reference only: every prefix token at the input rate
            cost += prefix_tokens * p["input"]
        elif expiry.get(version, -1) >= minute:  # read
            hits += 1
            cost += prefix_tokens * p["cached_input"]
            expiry[version] = max(expiry[version], minute + 30)
        else:  # write
            cost += prefix_tokens * p["write_" + ttl]
            expiry[version] = minute + life
        cost += tail_tokens * p["input"] + output_tokens * p["output"]
    return round(cost / 1_000_000, 4), hits

# Two bursts of 10 requests, two hours apart, same 20,000-token prefix.
trace = [(start + i * 0.5, "v1") for start in (0, 120) for i in range(10)]
for ttl in (None, "30m", "12h"):
    print(ttl, replay(trace, ttl, 20_000, 1_000, 500))

Running it prints:

None (0.94, 0)
30m (0.276, 18)
12h (0.278, 19)

To reproduce the other rows, change the trace; for D, give each burst its own prefix version. For your own workload, use timestamps and a prefix hash from your logs, and the current prices for your model.

What the replay model does not show

The replay model is optimistic. It assumes every request inside coverage is a read, and real traffic can miss. In a small test of gpt-5.5 (a model from before GPT-5.6) in the Responses API, Jangwook Kim found that on a prompt of about 3,700 tokens "roughly 1 in 4 calls still paid full price" (3 of 12 warm calls). The sample is small and predates GPT-5.6, so calibrate the replay model with the cached_tokens and cache_write_tokens your own responses report.

The replay model has other limits:

No latency numbers. OpenAI's prompt caching guide does not quantify latency gains, and a minimum lifetime does not guarantee lower latency.
Standard tier only. This replay uses the Standard-tier prices listed above. Recalculate with the current price table before using another tier.
Responses API only. OpenAI documents the 12-hour option there, so do not plan on it for Chat Completions.

Testing the counterargument: more hits can only help

The case for switching: longer retention means more requests find the prefix warm, every extra hit is a read at a tenth of the input price or less, so turning 12h on can only help. On models before GPT-5.6, that holds. The longer 24h setting has no write charge, so extra retention costs nothing.

On GPT-5.6 and later it holds only when a prefix returns after two or more long gaps, because the longer option doubles the write price. Scenario E shows the small case: 12h raises the hit rate from 90.0% to 95.0%, and the bill rises by $0.002, under 1% of that trace. Scenario D shows the large case: the hit rates tie at 90.0%, and 12h costs 36% more.

Tian Pan described this pattern before the 12-hour option existed, writing about Anthropic prices: teams who "monitor the cache hit rate counter going up, and assume they're saving money. Some of them are paying more than if they hadn't cached anything."

What to log per request

Your dashboard gives you hit rate. The decision needs cost per prefix per window. To get it, log these fields for every request:

Timestamp.
Model and region.
A hash or version label of the prefix.
Billed input: total input tokens, from usage.input_tokens.
cached_tokens, from usage.input_tokens_details.
cache_write_tokens, with its cache_write_tokens_details split into ttl_30m_tokens and ttl_12h_tokens.
Output tokens.
Latency to first token, measured on your side.

Compute cost per request by pricing each bucket separately: uncached input, cached reads, 30-minute writes, 12-hour writes, and output. If you already track what each agent attempt costs, this is the caching line inside that number. Then group requests by prefix hash and 12-hour window, count G for each group, and compare the two formulas.

When a prefix misses unexpectedly, Prompt Cache Diagnostics compares a response with an earlier one through prompt_cache_options.comparison_response_id and returns a miss reason such as tools_changed or model_changed. It works on GPT-5.6 and later in the Responses API.

Know the limits of what you collect:

Sample size: a few hours of traffic will not show a full week's gap pattern.
Diagnostics records expire after a short period, so investigate misses soon.
Caches cannot be reused across regional processing boundaries or shared across organizations, so one prefix served from two regions counts twice.
List prices change, so store the price you used next to each calculation.

Workload audit checklist

List every prefix your service sends that meets the minimum cacheable length (1,024 tokens on GPT-5.6 and later), with its model and API.
Confirm which prefixes run on GPT-5.6 and later in the Responses API. Only those can use 12h.
Move variable content, such as a timestamp, after the last breakpoint, and keep tools and output settings stable between requests.
Record how often each prefix changes. A prefix that changes before each burst stays on 30m.
Count G for each prefix in each 12-hour window from your logs.
Check misses in your own cached_tokens and cache_write_tokens, and run Diagnostics on unexpected ones.
Set 12h only on prefixes with G of 2 or more, and leave the rest on 30m.
Replay or model a representative request trace with current prices before changing retention.

FAQ

Does OpenAI prompt caching store responses?

No. The cache stores KV tensors for the reusable prefix at the start of the prompt, not the prompt tokens themselves. Caching does not change how the model generates output tokens.

Is 12-hour prompt caching available in Chat Completions?

OpenAI documents the 12-hour option for GPT-5.6 and later in the Responses API, through prompt_cache_options.ttl. Plan on the Responses API if you want 12h.

Does a higher cache hit rate mean lower cost?

Not always on GPT-5.6 and later, because the 12h write costs 2.5x input instead of 1.25x. In modeled Scenario D, both options read the prefix on 90.0% of requests and 12h costs 36% more. In Scenario E, 12h raises the hit rate from 90.0% to 95.0% and still costs slightly more. Compare cost per prefix per window instead.

Should we set 12h on every request?

No. Set it only on stable prefixes that come back after two or more gaps longer than 30 minutes inside a 12-hour window. For steady traffic, or a prefix that changes often, the default 30m costs less.

Before you change retention on any prefix, pull a representative trace from your request logs, run it through the replay model with current prices, and check the result against the billing rules in OpenAI's prompt caching guide.

What Are GitHub Actions Lockfiles, and Do They Replace SHA Pinning?

Alisa Hester — Fri, 23 Oct 2026 23:52:51 +0000

Your SDK release workflow runs when someone pushes a version tag. Its steps read actions/checkout@v4, actions/setup-node@v4, and actions/attest-build-provenance@v1. Each @v4 or @v1 is a git ref in another team's repository. The commit it points to can change after your team reviewed the workflow, and nothing in your repository records which commit was reviewed.

The usual fix is to pin every action to a full commit SHA, as the Lullabot architecture decision record requires. Teams keep those pins current with Renovate, Dependabot, pinact, or ratchet, and frizbee converts tags to SHAs. That fixes the lines you can see. Andrew Nesbitt pointed out the gap: a SHA pin locks only the outer action, and a helper action it calls by tag can still change.

GitHub's workflow dependency lockfile moves pinning into one machine-generated file per repository. For each onboarded workflow, it records the ref, the resolved commit, and the source repository's identity, transitive actions included. For repositories that adopt it, GitHub says SHA pinning in workflow files is no longer necessary. The guarantee stops at known edges: the dependencies inside reusable workflows you call, container images pulled by tag, and the safety of the pinned code. Reviewers still read every lock diff. For one release workflow on github.com, a bounded pilot is a reasonable next step, unless you run GitHub Enterprise Server or depend mostly on reusable workflows you do not control.

TL;DR

A lockfile at .github/workflows/actions.lock records each onboarded workflow's dependencies, their commits, and their source repositories' IDs, transitive actions included.
For repositories that adopt a lockfile, GitHub says inline SHA pinning is no longer necessary. Keep SHAs wherever no lockfile reaches.
Generating the file, onboarding a workflow, running --verify in CI, and the Require lockfile policy are four separate controls. Only the policy blocks runs of workflows nobody onboarded.
Your lockfile does not control the dependencies inside a reusable workflow you call, and container images pulled by tag are not locked.
The feature and its pre-1.0 CLI are in preview, and GHES is not supported. Pilot one workflow before you require locking.

What changed, and what is still preview

On October 14, 2026, GitHub put workflow lockfiles into public preview for GitHub Enterprise Cloud (including data residency), Team, and Free plans. Each of GitHub's lockfile pages, starting with the concept page, says the feature is in public preview and subject to change.

The announcement now explicitly lists Team and Free, with an editor's note correcting plan availability. The setup guide still labels the feature GitHub Enterprise Cloud. Use the updated announcement for preview eligibility, and confirm which policy controls are available for your target repository.

The gh-actions-lock README says the tool is pre-1.0, that its file format, flags, and behavior may change between releases, and that GitHub Enterprise Server is not supported. The test examples below describe v0.2.0, published October 12, 2026, as tested on October 15, 2026. As of October 23, 2026, the latest published release is v0.3.0, released October 22 at 16:08 UTC. It changes local-action handling, adds container-image warnings, and tightens verification. The historical examples are retained unchanged; we have not rerun them with v0.3.0.

What the lockfile records

Each repository gets one lockfile at .github/workflows/actions.lock. You can onboard workflows to it individually or all at once. The concept page says the file should never be edited by hand. The gh actions-lock extension generates it, which requires write access.

The file has two sections. workflows lists the dependencies each onboarded workflow uses. dependencies holds one entry per dependency, with three kinds of field:

ref is the tag or branch the workflow names.
commit is the code that will run, written sha1-....
owner_id and repo_id let GitHub confirm at run time that the repository behind the name is still the one you locked.

Transitive actions appear as a uses: list under the parent entry, as in the lockfile in the extension's own repository. That file has no integrity or content hash field, only the commit (our reading; GitHub does not state it).

Once a workflow is onboarded, every action it uses must be in the lockfile. The README describes job-start checks of source-repository identity, the pinned commit, and full-version tags. The released CLI distinguishes a rename or transfer that preserves the repository ID, which produces a warning, from a different repository behind the name, which produces a blocking finding. Its v0.2.0 README says a failed check blocks the run. This describes the documented checks; malformed files and CLI/runtime differences need the separate caveats below.

A test run on one release workflow

We onboarded the release workflow from the opening in a test run with gh-actions-lock v0.2.0 (gh 2.102.0, Linux). We ran the release binary directly. We did not exercise hosted run-time enforcement, the Require lockfile policy, or Dependabot. The original release.yml:

name: release
on:
  push:
    tags: ['v*']
permissions:
  contents: read
  id-token: write
  attestations: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci && npm pack
      - uses: actions/attest-build-provenance@v1
        with:
          subject-path: '*.tgz'

GitHub's how-to installs the extension with gh extension install github/gh-actions-lock. Onboarding one workflow takes its path:

gh actions-lock .github/workflows/release.yml

It exited 0 and printed:

Scanning 1 workflow
Planning pins
Pinned 3 actions (+ 2 transitive) across 1 workflow
  actions/checkout@v4.4.0 (11d5960)
    └─ .github/workflows/release.yml
  actions/setup-node@v4.4.0 (49933ea)
    └─ .github/workflows/release.yml
  actions/attest-build-provenance@v1.4.4 (ef24412)
    └─ .github/workflows/release.yml
Transitive dependencies (from composite actions):
  actions/attest-build-provenance@36fa7d0 via actions/attest-build-provenance@v1.4.4
  actions/attest@67422f5 via actions/attest-build-provenance@v1.4.4

It also rewrote the workflow: @v4 became @v4.4.0, and @v1 became @v1.4.4. The two transitive entries come from inside the composite actions/attest-build-provenance; no workflow line names them. The excerpt below is machine-generated output from the test run, copied verbatim. Each # … marks lines we cut.

# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
    '.github/workflows/release.yml':
        - 'actions/attest-build-provenance@v1.4.4'
        - 'actions/checkout@v4.4.0'
        - 'actions/setup-node@v4.4.0'
dependencies:
    # …
    'actions/attest-build-provenance@v1.4.4':
        ref: 'v1.4.4'
        commit: 'sha1-ef244123eb79f2f7a7e75d99086184180e6d0018'
        owner_id: 44036562
        repo_id: 760702757
        uses:
            - 'actions/attest-build-provenance@36fa7d009e22618ca7cd599486979b8150596c74'
            - 'actions/attest@67422f5511b7ff725f4dbd6fb9bd2cd925c65a8d'
    'actions/attest@67422f5511b7ff725f4dbd6fb9bd2cd925c65a8d':
        ref: 'v1.4.1'
        commit: 'sha1-67422f5511b7ff725f4dbd6fb9bd2cd925c65a8d'
        owner_id: 44036562
        repo_id: 760701061
    # …

With the lockfile committed, gh actions-lock --verify printed "All 1 workflow valid" and exited 0. We then appended - uses: actions/upload-artifact@v4 without relocking, and --verify exited 1:

Scanning 1 workflow
1 of 1 workflow failed
✗ Not pinned actions/upload-artifact@v4
  used in workflow but not pinned in lockfile (actions/upload-artifact@v4)
  see: https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions
  ↳ .github/workflows/release.yml
Re-run without --verify to apply fixes.

The offline --verify-local also exited 1, with "1 of 1 workflow failed: 1 not-pinned." Its flag help says it only checks that every action has an entry, not that the entries are trustworthy. That makes it a fit for a pre-commit hook, while GitHub's docs use --verify in CI.

Direct, transitive, and reusable workflows: where the boundary sits

The concept page draws the boundary at the repository: its lockfile covers its onboarded workflows and transitive actions, but the actions inside a called reusable workflow belong to the defining repository's lockfile.

Your release workflow's direct steps land in your file, and so do the actions inside its composite actions. The dependencies inside a reusable workflow it calls do not. The lockfile of the repository that defines that reusable workflow covers them, if that repository has one.

Our test matched the dependency boundary but recorded less than the concept page describes. That page says the lockfile pins the reusable workflows your workflows depend on, too. We onboarded a workflow whose only dependency was a call to slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.1.0. The tool reported "All 1 workflow valid" and left the file unchanged, and the caller's lockfile recorded '.github/workflows/release.yml': [], with no entry for the call. The how-to recommends onboarding repositories that hold shared workflows first.

In v0.2.0, resolvable same-repository local uses: ./… actions are rewritten to uses: $/…, which always resolves to the running commit, though that release's README also lists local-path actions as a short-term gap. The v0.3.0 README says local ./ actions are never followed or locked. A local action that uses remote actions now blocks fix and verify by default: explicitly migrate it with --migrate-local-actions, or accept warning-only treatment with --ignore-local-actions. The latter leaves that local-action dependency path unlocked. The linked concept and setup pages do not explain container-image coverage. The CLI source warns that a docker://image:tag step falls outside lockfile coverage because image tags can move.

Do lockfiles replace inline SHA pinning?

For repositories that adopt one, GitHub says yes. The concept page says SHA pinning in workflow files "is no longer necessary." The secure use reference keeps full-length SHA pinning as the guidance for repositories that cannot adopt a lockfile.

The condition applies per workflow. Keep full-length SHA pins on workflows you have not onboarded and on remote job-level reusable-workflow calls in v0.2.0, even when the callee repository has its own lockfile. That callee lockfile governs the actions inside the called workflow, not the caller's job-level ref. A GitHub maintainer confirms that job-level calls are not pinned. Keep separate image-digest pins on docker:// dependencies.

The SHA policy keeps working. GitHub's page on governing workflow execution says you can leave "Require actions to be pinned to a full-length commit SHA" enabled. For locked dependencies, GitHub checks the locked commit. During a staged rollout, the policy still enforces SHA pinning for workflows that have not adopted the lockfile.

Onboarding does change existing pins. In our test, actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 became actions/checkout@v4.4.0 on a default run, with the commit moved into the lockfile. With --no-narrow, the SHA stayed in the workflow file, which is the fix a maintainer gave in issue #130. If your organization allows only selected actions, the how-to warns that allowlist entries pinned to a tag stop matching. Use a wildcard or the full commit SHA instead.

Inline SHA pinning and a lockfile, side by side

Criterion	Inline full-length SHA pinning	Lockfile (onboarded workflow)
Where the pin lives	Each `uses:` line in each workflow file	One `actions.lock` per repository; workflow lines carry a version tag unless you use `--no-narrow`
Transitive actions	Whatever the composite action's author wrote	Recorded under the parent entry, except inside reusable workflow calls
Repository identity	Not recorded	`owner_id` and `repo_id`, checked at job start
What a reviewer sees	A changed SHA on each edited line	One diff with ref, commit, IDs, and transitive edges
Enforcement	Full-length SHA policy	Job-start checks, `--verify` as a required check, Require lockfile policy, SHA policy on the locked commit
Update automation	Renovate, Dependabot, pinact, or ratchet	Dependabot regenerates lock entries; Renovate documents experimental regeneration of an existing lockfile. Neither onboards new workflows
Container images by tag	Not covered by action pins	Not locked
Availability	GitHub's guidance for repositories that cannot adopt a lockfile	Public preview on Enterprise Cloud (including data residency), Team, and Free per the updated announcement; no GHES. Confirm target-repository policy availability

File, onboarding, CI check, and policy are four different controls

A lockfile in the repository does not prove that every workflow is governed.

Control	What it does	Availability	On failure
Generating the file	Pins each resolvable action and writes the lockfile	People with write access, through the gh extension	All or nothing: if it hits an error it cannot fix, it changes no workflow and no lockfile entry
Onboarding a workflow	Adds it to `workflows`; every dependency must then be locked	Individually or all at once	Documented job-start checks block failures; malformed-file fail-closed behavior requires the Require lockfile policy. We did not test hosted enforcement
`--verify` in CI	Read-only CLI validation for coverage and pin checks; use it as a required check, not as proof of identical hosted enforcement	Any CI job that runs the CLI	Exits 1 (our test); blocks merges only as a required check
Require lockfile policy	Blocks runs of targeted workflows that use actions but are not onboarded	Public repositories, and private repositories on Team or Enterprise; Evaluate mode only on GitHub Enterprise	Blocks runs in Active mode; Evaluate reports to Policy insights; we did not test this

Until the policy targets it, a workflow nobody onboarded runs with whatever refs its file contains. The enforcement guide covers both the policy rollout and the verify job. The workflow-policy page lists public repositories and private repositories on Team or Enterprise; private Free repositories are not listed.

Malformed lockfiles are a separate case. A GitHub maintainer says the Require lockfile policy supplies fail-closed behavior when the file cannot be reliably read. Onboarding and a CLI check alone are not equivalent to an active runtime policy.

CLI/runtime parity also needs a version boundary. In issue #174, the maintainer reported a backend bypass repair on October 16. On October 21, the maintainer said the CLI fix was on main and planned for the next release. The historical v0.2.0 verification code has the full-SHA ancestry-check limitation. That repair has now shipped: v0.3.0 rejects fork-only impostor commits and checks locked commits against the history of their recorded tag or branch. Its release notes also describe incomplete-lockfile failures for older lock graphs, exact-tag/commit mismatch errors, failures when GitHub cannot answer a pin check, and refusal to write cyclic or incomplete lock graphs. Follow the release-specific repair instructions and review the resulting diff before adopting it. We checked the release notes and v0.3.0 verification source; we did not reproduce hosted enforcement or rerun the CLI with this version.

What a reviewer approves on a lock update

The enforcement guide sets the condition: "A lockfile is only a security control if someone reads the diff." On each lock pull request, check:

Each changed commit, which is the code your release will run. The how-to treats it like any dependency version bump.
Each changed owner_id or repo_id, which the how-to calls rare and worth investigating before you merge.
New entries in a uses: list, which are transitive actions nobody typed into a workflow.
The workflows section, to see whether a workflow dropped out.

A normal run trusts refs such as main or v3 from the lockfile and does not re-resolve them. If upstream force-pushed or deleted a locked commit, --relock errors. Accepting the new commit takes gh actions-lock --relock --accept-moved, and that change deserves its own review.

For onboarded workflows, Dependabot regenerates the matching lockfile entry in the same pull request as the version update. It does not onboard workflows; it reports that onboarding is required. Beyond having Dependabot manage GitHub Actions dependencies, no configuration is needed. GitHub notes that this maintains coverage rather than extending it. Renovate also documents experimental regeneration of an existing actions.lock after action updates; workflows not yet onboarded are skipped. Neither tool onboards new workflows automatically. The cited guides do not specify a minimum Dependabot version.

The case for staying with SHA pins and Dependabot

The objection: "We already pin to SHAs and have Dependabot; this is a preview that adds another file and another failure mode." SHA pins plus Dependabot already fix and update every direct reference. The preview adds a pre-1.0 CLI, workflow rewrites, allowlist changes, CodeQL alerts, and early policy bugs. In the proposal thread, one commenter wrote in May 2026 that they would not use it instead of SHA pinning until it worked with Dependabot or Renovate.

For direct references the objection holds, because an inline SHA and a lock entry fix the same commit. Our inference from the documented behavior is that lockfiles address three gaps left by inline SHAs, within the coverage and enforcement limits above:

Transitive actions.
Repository-name reuse that points to a different repository identity.
A run-time check that covered dependencies are locked, with the active Require lockfile policy supplying fail-closed behavior for malformed files.

Dependabot now regenerates lock entries, and Renovate documents experimental regeneration for existing lockfiles, which addresses the update-integration objection. --no-narrow keeps SHAs in the workflow file. The pre-1.0 CLI, allowlist changes, and CodeQL alerts still argue for testing on one workflow first.

Early-adopter reports

These come from the issue tracker, not from GitHub's documented behavior.

Issue #130 (closed): fix mode rewrote commit pins into tags. The maintainer pointed to --no-narrow.
Issue #131 (open): after a lockfile rewrite, CodeQL flags the new tag references as unpinned.
Issue #168 (closed October 21): the report describes how a locked Docker container action, or a docker:// step inside a locked composite action, still pulls the image its action.yml names, usually by tag. Moving that tag changes the image without a lockfile diff. v0.3.0 now emits non-blocking container-image warnings for docker:// steps, job containers and services, and remote Docker actions when images lack a SHA-256 digest, including expression-selected images. Those warnings do not pin images. The no-warning observation is the issue author's historical report, not a description of the latest release.
Issue #169 (closed): with the SHA-pinning policy on, version-tagged actions run through a reusable workflow were rejected despite a valid lockfile. A GitHub maintainer said a backend fix should address it, and the issue is closed.

What a lockfile does not establish

The changelog says locking "does not determine whether the dependency itself is safe," so review dependencies before you lock them. The secure use reference still says to audit the source code of every action you use.

The remaining boundaries combine the CLI's documented limits with our inference about what a commit lock can govern. The lock records commits without a content hash, while the earlier third-party gh-actions-lockfile records integrity hashes. Code an action downloads at run time is outside the lock, a point raised in the proposal thread. So are images pulled by tag, the runner image, workflow permissions, and secret handling.

Checklist: pilot one SDK or API release workflow

Inventory every uses: line: direct and composite actions, reusable workflows and their repositories, local ./ actions, and image-based actions.
Onboard the repositories that hold reusable workflows you control first. Keep the caller's remote job-level reusable-workflow refs pinned to full-length SHAs even when those repositories have lockfiles. Record repositories you do not control as out of scope.
Onboard only the release workflow. Add --no-narrow if you want SHAs kept in the file. We expect that to make the pilot easier to back out, but we did not test a rollback.
Review every commit, owner_id, repo_id, and transitive entry in the generated lockfile.
Move tag-based allowlist entries to a wildcard or full SHA, and decide how to triage CodeQL alerts.
Require CODEOWNERS review of .github/workflows/actions.lock, with a named owner.
Make a gh actions-lock --verify CI job a required check. For pre-commit, the enforcement guide uses gh actions-lock --verify-local --no-fix.
Keep Dependabot on GitHub Actions dependencies, and keep the full-length SHA policy enabled.
On GitHub Enterprise, run the Require lockfile policy in Evaluate mode, scoped to this workflow. GitHub advises switching to Active only after you have dependable lockfile-maintenance processes for every targeted workflow.
Exit test over the next few releases: each release ran onboarded, --verify failed only on real drift, every lock diff had a named reviewer, and a Dependabot update arrived with its lock entry.

Defer the pilot if any of these apply:

You run GitHub Enterprise Server.
You depend mostly on reusable workflows you do not control.
You rely on Docker-image-based actions that you need pinned.
Nobody owns lock diffs.

If you defer, keep SHA pins with Dependabot and revisit after the CLI reaches 1.0.

To start, follow GitHub's guide to locking action dependencies in a repository's workflows, then the guide to enforcing lockfiles when you are ready for the policy.

FAQ

Will a lockfile break my existing SHA-pinned actions?

The commit you pinned stays. A default run rewrites the line to its version tag and moves the commit into the lockfile; --no-narrow keeps the SHA in the workflow. Tag-based allowlist entries stop matching, and CodeQL may flag the rewritten tags.

Can I keep the full-length commit SHA policy enabled?

Yes. For locked dependencies, GitHub evaluates the policy against the locked commit. Workflows that are not onboarded still need full-length SHAs in the workflow file.

Will Dependabot continue to update my actions?

For onboarded workflows, Dependabot regenerates the matching lockfile entry in its version-update pull request. It does not onboard new workflows.

Does my lockfile cover the reusable workflows I call?

Not their dependencies. The actions inside a reusable workflow are covered by the lockfile of the repository where it is defined, so GitHub recommends onboarding shared-workflow repositories first. GitHub's concept page says reusable workflows themselves are pinned, but in our v0.2.0 test the caller's lockfile recorded no entry for the call. Keep remote job-level calls SHA-pinned even when the called repository has its own lockfile.

Claude Code for technical writers: what works and what breaks

Alisa Hester — Fri, 23 Oct 2026 23:52:45 +0000

Claude Code can turn a Git diff, or your description of a change, into a first draft. Without setup, though, nothing holds that draft to your style guide or term list, and it writes from instructions built for engineering work. Then engineering merges an API change while you are on vacation or deep in another project, and without a maintenance workflow the docs can wait until you get back. EkLine connects repository-change detection, scheduled maintenance, and reviewable docs updates for a team-owned accuracy process.

Most of that is fixable today. Claude Code reads project instructions, path-scoped rules, skills, a custom output style, and hooks. Set up together, they give Claude your reader, your terms, and a lint check after matching successful Write or Edit calls while the hook is enabled. Features such as scheduled tasks (formerly routines), Code Review, and shared project instructions partly close each of the old capability gaps. What they leave in place is a dependency on one person: auto-memory corrections stay on one machine unless promoted into shared files, scheduled tasks run as one person's account, and Claude's own review never blocks a merge.

The full claim review used first-party documentation checked on October 21, 2026. Selected setup instructions were checked again on October 23, 2026. The Claude Code changelog tracks CLI releases; cloud-service behavior is documented separately. These are documentation-based examples, not an end-to-end test in a production repository.

TL;DR

Name your reader and terms in a short CLAUDE.md; scope docs rules to docs files.
Add an output style for user-facing pages and an enabled lint hook for successful Write or Edit calls.
Scheduled tasks run as one person, and Code Review never blocks a merge.
Stop building your own pipeline when the docs must keep running while you are away.

Why Claude Code writes like an engineer

The engineer voice is the default by design. With no output style selected, Claude uses Claude Code's default software-engineering instructions. Unless you tell it who the reader is, it works from instructions written for engineering work, not for your reader.

Your instructions also compete for attention. Discovered project and ancestor instruction files load at session start, along with the auto-memory index (up to its first 200 lines or 25 KB), but Claude treats them as "context, not enforced configuration." The same page advises keeping each CLAUDE.md under 200 lines, because longer files reduce adherence. Pasting your full style guide in works against you.

So split the work: judgment calls (who the reader is, what a page is for) go in short instructions, and mechanical rules go to something deterministic. Mintlify's Ethan Palm makes the same recommendation in his technical-writing workflow: put checkable conventions in a linter or lifecycle hook rather than spending instruction-file space on them.

Before you start

Claude Code running in the repository that holds your docs.
A written style guide and term list.
Vale configured for your style guide, plus jq, which the hooks guide uses to read the edited file's path.

Each example below is adapted from a documented snippet. Test it in your repository before you rely on it.

Instructions guide Claude. In the diagram, "always runs" means an enabled hook on a matching successful Write or Edit call. It does not include edits made through Bash, disabled hooks, or failed tool calls.

Set up Claude Code for documentation in five steps

1. Write a short CLAUDE.md that names the reader

A project CLAUDE.md lives at ./CLAUDE.md or ./.claude/CLAUDE.md, and its instructions are "shared with your team through version control." Lead with the reader, then terminology, then a pointer to the full guide. Illustrative example: replace the reader, terms, and style-guide path with your own:

# Documentation conventions

## Reader
Write for backend developers who already know HTTP and want to integrate an API.

## Terminology
- Use "API key" and never "API token"

## Style
- Follow docs/style-guide.md for anything not covered here.

2. Scope docs rules to docs files

Rules in .claude/rules/ with a paths field load only when Claude reads or edits a matching file, according to the memory documentation. This keeps unrelated file rules out of the initial context; matching rules still consume context when loaded. Example, adapted from the documented format:

---
paths:
  - "docs/**/*.md"
---

# Docs page rules

- One instruction per numbered step
- Start each step with a verb

3. Package repeat checks as a skill

A skill lives at .claude/skills/terminology-check/SKILL.md. Claude loads it when relevant based on the description, or you run this example with /terminology-check. Commit it so your team gets it too. Example, using the documented minimal format:

---
name: terminology-check
description: Checks a docs page against the term list. Use when a docs page is created or edited.
---

Compare every product term on the page with the Terminology section of CLAUDE.md and list each mismatch with its line.

Plugins are the packaging layer for reusing the same setup across multiple repositories. In an October 8, 2026 Reddit post, u/the-ai-scientist described an ASD-STE100-inspired writing plugin. This is its author's report, not an audit of standards compliance. EkLine's open-source ekline-docs-skills plugin includes style-guide and terminology skills. For more options, see the 10 best Claude skills for documentation, ranked.

4. Add an output style for user-facing docs

A custom output style can put Claude in a writing-assistant role. Save it in .claude/output-styles/. Leave out keep-coding-instructions when Claude won't be doing software engineering in that session. After creating or editing the style file, restart the terminal Claude Code session so it loads the change, then switch with /output-style. Example, using the documented frontmatter:

---
name: User docs
description: Writes and edits pages for the reader named in CLAUDE.md
---

You are editing user-facing documentation. Lead every page with the reader's task.
Explain what a feature changes for the reader before how it is built.

5. Put mechanical rules in a lint hook

Hooks give you "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them." Palm's Vale hook matches successful Write or Edit tool calls. Merge its PostToolUse section into .claude/settings.json; the file must already have valid settings JSON or be created with this object. This baseline does not feed lint failures back to Claude:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "vale \"$(jq -r '.tool_input.file_path // empty')\""
          }
        ]
      }
    ]
  }
}

For a PostToolUse hook, exit code 2 "Shows stderr to Claude; the tool already ran." As published, the hook prints Vale's results to stdout, which Claude does not see. To hand failures to Claude, make the hook command send Vale's diagnostics to stderr and exit 2 only when lint fails; successful lint should exit 0. Either way, the edit is already saved. This matcher does not lint edits made through Bash or another tool, and it is not a CI merge gate.

Four gaps, checked against the current docs

Gap	What the docs show now	What still holds
No lasting style or terminology memory	Project CLAUDE.md shared through git; managed CLAUDE.md deployed by IT/DevOps; path-scoped rules	Memory is advisory; auto memory stays on one machine
No sense of the reader	A custom output style can make Claude a writing assistant	Nothing enforces the style
No review gate	Code Review comments on pull requests; a GitHub Action can run on pull requests	Code Review never blocks a merge
Nothing watching the repo	Scheduled tasks run on a schedule or on merged pull requests	Research preview; each scheduled task belongs to one person's account

What remains is about ownership.

Shared instructions are covered, but what Claude learns from your corrections stays with you. Auto memory, the notes Claude saves from your corrections, "is machine-local," so a term you fix on your laptop is unknown to a teammate's session. A subagent (a helper Claude starts with its own instructions) with memory: project keeps its notes in a folder that is "shareable via version control." That works when someone reviews and commits those notes.

The output style gives Claude a reader, but "nothing enforces it," and subagents other than a fork run their own system prompt, so the style does not reach them. You write the reader in by hand.

Code Review "never approves or blocks the pull request," and is available on Team and Enterprise plans for GitHub only. A REVIEW.md file can add team rules, and /code-review runs locally on any plan. The Claude Code GitHub Action costs GitHub Actions minutes plus API tokens per run (or subscription usage with an OAuth token), and its docs don't describe it as a merge gate.

Scheduled tasks, formerly routines, can trigger on merged pull requests, and Anthropic's own example is a weekly docs-drift task that opens update pull requests. They are in research preview and belong to the individual account that creates them. Their pull requests carry that person's connected GitHub identity.

Where the setup fails, and how to recover

Instructions fade. Trim CLAUDE.md and move page rules into a path-scoped rule.
Voice slips inside a subagent. Write the reader into its prompt.
Lint errors land after the page is saved. To block an action first, the memory docs point to a PreToolUse hook.
A scheduled task shows green but did nothing useful. The scheduled-tasks page says green reports a session without an infrastructure error, not that the requested work succeeded; GitHub webhook events beyond hourly caps are dropped. Read what it opened.
A draft reads well and fails when followed. A technical writer posting as cryzinger on Hacker News on August 29, 2026 describes Claude-generated writeups that "fall apart when you actually try to follow the instructions they lay out." Have a developer walk every procedure before it ships.

When Claude Code alone is enough

Claude Code now has project memory, skills, hooks, subagents, a GitHub Action, scheduled tasks, and Code Review, so a writer willing to maintain the setup can build much of a docs workflow themselves. Claude Code alone is a good fit when:

One writer owns the docs and is around to drive most sessions.
The docs live in one repository, or a plugin carries the setup across a few.
Your team already runs a CI linter that can fail a pull request, so you don't need Claude to be the gate.
You accept research-preview scheduled tasks acting as your account.

If that describes your team, the five steps are a starting setup. Confirm the hook loads, test a clean page and an intentional lint failure, and review its feedback before you rely on it.

The test: does the docs process run without you?

Palm wants to "take a vacation without blocking docs ships for a week and a half." Ask four questions about your setup:

If an API change merges while you are out for two weeks, does a docs pull request appear under an identity your team owns?
When a teammate corrects a term, does the next session on someone else's machine know about it?
Can a docs problem fail a check and block the merge?
Who maintains the hooks, rules, and scheduled tasks when you move to another project?

With Claude Code alone, the answers are "with scheduled tasks it runs as you; with the GitHub Action it uses the app and credentials your workflow configures," "only if someone commits it," "not through Code Review," and "you." When two or more of those answers worry you, look at tooling built for shared ownership.

Where EkLine fits

EkLine answers the same four questions for a team, and the writer still decides what ships.

Instructions and skills the whole team edits

In Docs Agent, custom instructions apply to every new session your organization starts after saving them, including new sessions started from GitHub, GitLab, or Slack, and any member can edit them. You set the reader there too. Custom skills are authored once and copied into every new session, run with the slash command shown for the saved skill. According to the EkLine changelog, Docs Agent "remembers context about your repositories and conventions across sessions, so your whole team benefits from shared knowledge."

Watching the repository as a team

With automatic PR review, when a non-draft pull request opens or becomes ready on a selected GitHub repository, EkLine stays silent at low confidence, posts a suggestion at medium, and starts a docs-update flow at high confidence that can create a reviewable docs pull request. Scheduled Agents run templates such as Docs Drift Review and Code Sample Review hourly, daily, weekly, or monthly, and deliver a pull request, a Slack message, or both. According to the changelog, any organization member can create and manage them.

A check that can block the merge

Docs Reviewer runs in CI on GitHub Actions, GitLab CI, and Bitbucket Pipelines. For GitHub Actions, the style-guide enforcement guide describes fail_on_error: true plus a required branch-protection check. There is a current implementation discrepancy: the v6 manifest declares that input, but the v6 entrypoint does not pass it to reviewdog. Do not assume the setting alone blocks merges. In the version you deploy, verify that an intentional finding fails the job, then require that exact status check. GitLab and Bitbucket need their own CI configuration.

Before: an API change merges during your vacation, and the docs wait for you. After: when automatic PR review detects clear impact on a monitored GitHub repository and the update flow completes, a docs pull request is available for your review when you get back. In an EkLine case study, Socure's one technical writer merged 348 documentation updates in seven weeks.

Know the limits: the automatic PR review assessment runs once per pull request, its confidence thresholds are fixed, and linked Jira or Linear tickets are not included.

FAQ

What's the difference between CLAUDE.md and AGENTS.md?

Claude Code v2.1.277 or later can read AGENTS.md as project instructions when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or its ancestors. When those instruction files exist, the default loads them instead. Import AGENTS.md from CLAUDE.md, or use the Project instructions setting to load both. Direct AGENTS.md support also requires its built-in plugin to remain enabled; the first session after some older-version upgrades can still require an import or a new session.

How do I stop Claude Code from flattening my writing voice?

Name your reader and voice in a short CLAUDE.md, use a custom output style for user-facing pages, and let a lint hook catch mechanical rules. Nothing enforces the style, so review diffs for voice before you merge.

Which Claude Code skills help with docs?

Start with one skill per repeat task, such as a terminology check, in .claude/skills/. Shared options include an ASD-STE100 rule set and EkLine's open-source ekline-docs-skills plugin.

Try it on one repository

To check whether your docs process keeps running without you, request Docs Agent access and test EkLine with one repository and one human reviewer. Docs Agent is on all plans, with access on request through support@ekline.io.

What Is Poppy? When Should Your API Support Customer Agents?

Alisa Hester — Tue, 13 Oct 2026 01:00:10 +0000

Poppy is the short name for the Personal Agent Protocol, which its overview defines as "an open protocol for how personal agents and companies work together." Sierra and Meta are developing it with industry partners, and the specification is draft 0.1, updated October 9, 2026. As of October 12, 2026, the right call for most consumer-facing API platforms is a small, disposable experiment with no production rollout, while you build the pieces any customer-agent channel needs.

By Sierra's account, most personal agents already use company websites and apps the way people do, loading pages and clicking through forms, and when that can't finish the job they may call the support line or open web chat. The protocol's overview calls this "all or nothing": either the agent "passes as the user, signing in with their password and clicking through pages built for people," or the company blocks it, and "the company can't tell an agent from a person or offer it a better path." Neither source publishes a measurement. Where it matches your traffic, you can't tell an agent from your customer, and your customer can't limit what the agent does once it is in. On a platform that moves money, holds health records, or changes bookings, that is a question for your fraud and privacy owners as much as for your API team.

Poppy's draft names the pieces that close that gap: agent identity by client_id, signed-out Sessions under User IDs that carry no personal data, short-lived key-bound Session Tokens, revocation, and human handoff. That work is likely to carry over whichever customer-agent protocol wins, since PACT, the A2A-based parallel design, also asks for scopes, consent, and discovery. Draft 0.1 defines no audit log, so you design that part.

TL;DR

Poppy is a consent and session layer between a customer's personal agent and a company. It reuses the company's APIs, MCP server, website, or company agent as channels.
As of October 12, 2026, the spec is draft 0.1 with breaking changes allowed, no official reference implementation is public, and we found no public evidence of production adoption.
An OAuth API plus an MCP server already provides scoped delegated authorization. Draft 0.1 adds signed-out Sessions, per-User agent attribution with allow and block lists, key-bound tokens, human handoff, and revocation back to signed out.

What a customer's agent needs from your platform

The spec's term for a customer's agent is personal agent. It is a new kind of client, and it needs six things: discovery (where your channels are and how to sign in), authorization (what the customer allowed), scoped Sessions tied to one agent and one customer, a route to a human, privacy for a customer who has not signed in, and somewhere to act. The status quo covers only the last. A browser agent holding the customer's password looks like the customer to you. MCP's authorization spec gives you scoped OAuth for tools, but it defines no signed-out session, no per-company User ID with no personal data, no human handoff, and no session shared across channels. Poppy puts all six behind one documented interface.

How a Poppy request flows, end to end

The draft spec walks one agent from discovery to sign-out, in this order (draft 0.1, so any step can change):

The draft 0.1 Session lifecycle, condensed.

Discover. "A Company MUST publish its poppy.json document at https://{domain}/.well-known/poppy.json over HTTPS." It lists your sign-in options (auth) and channels (agent, apis, web).
Identify the agent. "A Personal Agent's client_id MUST be an HTTPS URL that returns its metadata document." You may require registration ahead of time and keep allowlists or blocklists by client_id.
Start signed out. The agent sends a signed assertion (a JWT bearer grant) to your token_endpoint, naming itself (iss) and the User (sub). "A Session starts signed out": you can recognize the same User over time, but not who the User is. The User ID "MUST NOT contain or be derived from personal information, such as an email address, phone number, or name, even with a keyed hash."
Sign in and grant scope. Sign-in is Direct ("the OAuth 2.0 authorization code flow with PKCE"), Device ("the OAuth 2.0 device authorization grant"), or Mediated, which "is not an OAuth flow." Base scopes are poppy:read and poppy:write, plus any you define. Sign-in returns an Account Token, "A long-lived credential from sign-in."
Get a key-bound Session Token. The Account Token yields signed-in Session Tokens, "bound to a key the Personal Agent holds, so a copied token is useless without it," which "SHOULD last hours, not days."
Act. The agent calls your APIs ("DPoP for OpenAPI, and Bearer for MCP"), gets a website cookie through web.browser_session_endpoint, or talks to your company agent through the conversation API.
Hand off. The agent sends "an empty JSON object" to POST {endpoint}/{id}/handoff; the conversation's responder is agent or human, and its status is working, idle, queued, or closed.
Close. An empty JSON object to POST {endpoint}/{id}/close ends the conversation.
Revoke or fail. The agent revokes its Account Token at your revocation_endpoint, and you sign out every Session signed in with it: "Usually those Sessions continue signed out, so a cart or an open conversation carries on." Failures return invalid_token (401), sign_in_required (403), insufficient_scope (403), invalid_session (400), or account_mismatch (400).

Poppy vs MCP vs A2A

The last column is today's browser agent. Versions: Poppy draft 0.1, MCP schema 2026-07-28, and A2A 1.0.0, as of October 12, 2026.

Criterion	Poppy	MCP	A2A	Status quo: agent passes as the user
Job it owns	Consent and sessions between a personal agent and a company	Connecting LLM applications to external tools and data	Communication between independent, "potentially opaque" agent systems	Finishing a task through pages built for people
Where state lives	A company-side Session per agent and User, signed out or in, shared by API, website, and conversation	Stateless, self-contained JSON-RPC 2.0 requests between host, client, and server; the authorization spec defines no signed-out or cross-channel session	In tasks, with states such as `TASK_STATE_COMPLETED`	The customer's web session
Who acts for whom	A personal agent for one User, toward one Company	A host's client calling a server, optionally for an OAuth-authorized user	One agent delegating to another	The agent, indistinguishable from the customer
Execution context	Your OpenAPI endpoints, MCP server, website, or company agent	The MCP server's tools	Inside the remote agent	Your website, in a browser
Authorization and control boundary	Direct, Device, or Mediated sign-in; base and custom scopes; key-bound tokens; `client_id` allow and block lists	Optional; when used, an OAuth 2.1 resource server with RFC 9728 metadata and scope step-up	Agent Card at `/.well-known/agent-card.json`; a `TASK_STATE_AUTH_REQUIRED` state	The customer's password
Interoperability	Lists OpenAPI and MCP servers as channels; the spec does not mention A2A	Founding project of the Agentic AI Foundation (December 9, 2025)	Agentic AI Foundation project since August 17, 2026; PACT builds on it	None defined
Fallback path	`handoff` to a person; revocation drops Sessions to signed out	None in the authorization spec	`TASK_STATE_INPUT_REQUIRED` marks a task that needs input	The support line or web chat

The layers stack: Poppy decides which agent is asking and what the customer allowed; an MCP server is one channel it can route that agent through.

A2A's relationship to Poppy is unsettled. Neither the Poppy spec nor Sierra's posts mention A2A, so no primary source defines it; the independent tracker poppy.md calls the two "Mostly complementary, with one overlap to watch: the 'company agent' route." The A2A-based design is Decagon's PACT (Personal Agent Consent & Trust Protocol), released October 6, 2026, the same day Sierra announced the Personal Agent Protocol, and "Built on the Agent2Agent protocol and OAuth 2.0." Decagon says PACT joins "the Personal Agent Protocol working group announced by the team behind Meta's Muse," though no Poppy spec text mentions PACT. For A2A's own production gaps, read A2A production readiness: what it takes beyond protocol support.

Where Poppy stands on October 12, 2026

Maturity, implementations, and adoption are separate claims.

Draft maturity. The spec's status line marks it Draft 0.1, updated October 9, 2026, under the Apache License 2.0, and warns that "Any part of it can change before a stable version, including in ways that aren't backward compatible." No editors, governance body, or standards organization appear on the spec, overview, or home page.

Implementations. On October 9, Sierra wrote, "Over the next month we will host design workshops and publish a reference implementation to help developers get started." As of October 12, the independent tracker poppy.md says of the official reference implementation, "none is public yet." It lists only community and partner-demo work, such as a Cloudflare Workers demo, a demo of Meta's Muse shown only in an X video, and the independent Datalayer SDK, which implements "draft 0.1 (2026-10-09)."

Production adoption. We found no public evidence of it. On October 9 the orka project reported, "No company publishes a PAP file," after checking about 40 sites, including the launch partners: "Some sites blocked the check, and none of the rest had one." Sierra's October 9 post adds 35 design partners, including OpenAI, Visa, Mastercard, PayPal, Okta, and Bank of America, to the launch partners Meta, Genesys, Instinct, NiCE, Rocket, Shopify, Stripe, and Walmart. Design-partner status is not an implementation, and poppy.md lists no design-partner implementation beyond demos as of October 12. A go/no-go review in the fillthemat project's GitHub issues said of OpenAI's listing as a design partner, "This does not establish ChatGPT support or merchant traffic."

What your API team would need to build

The minimum is small: a company implements "one of agent, apis, or web," and sign-in is optional: "With none, it offers only signed-out Sessions."

An OAuth API plus an MCP server already covers:

Scoped delegated authorization: under MCP's authorization spec, a protected server "acts as an OAuth 2.1 resource server," publishes RFC 9728 metadata that tells clients how to authorize, and can step up scope on insufficient_scope.
Direct and Device sign-in, if your OAuth server runs PKCE and the device grant. The OpenAgents team found this overlap: "We already have RFC 8414/9728 metadata, PKCE, a device flow (coder login) and an MCP resource server."
An API channel: an MCP server listed in apis is a valid Poppy channel with Bearer tokens.
Agent identity by URL: MCP's authorization spec says authorization servers and MCP clients "SHOULD support OAuth Client ID Metadata Documents," where the client uses an HTTPS URL as its client_id.

Draft 0.1 adds:

A poppy.json discovery file pointing at your existing endpoints.
Agent and User attribution on every token, plus allow and block lists by client_id.
Signed-out Sessions started from the agent's signed assertion, with User IDs never derived from personal data.
Key-bound Session Tokens that last hours, checked on OpenAPI calls with DPoP (RFC 9449), which proves the caller holds the agent's key.
One Session across channels, including a browser_session_endpoint whose cookie follows sign-in and sign-out.
Handoff and close endpoints, if you offer a company agent, wired to a staffed queue.
A revocation_endpoint that signs out every Session tied to an Account Token.
Audit records you design. The spec gives attribution ("the Company always knows a request comes from a Personal Agent, which one, and for which User") and defines no audit log.

For delegated OAuth in more depth, read OAuth for AI agents: why general-purpose agents strain the integration model.

The case against adding Poppy now, and where it holds

The strongest objection is that an OAuth API, and maybe an MCP server, is enough, and a new draft protocol is premature. The evidence supports much of it. The spec can change incompatibly, and fillthemat found that "Datalayer shipped 11 non-stage npm versions Oct 10–11, including breaking changes." We found no adoption to serve, and PACT is a parallel design, though poppy.md notes it is "now an input to the Poppy working group rather than a rival, at least on paper." Three of the four public GitHub issues we found from October 9 to 12 stopped short of production: orka wrote, "We should not build anything yet," OpenAgents closed its issue as "Not on the V1 launch path," and fillthemat's review said "NO-GO for production rollout or substantial investment yet." The fourth is fillthemat's own follow-up spec: "The owner chose (2026-10-11) to build full support anyway, as a deliberate bet." That is a planned build, not adoption.

On Hacker News, in a thread with two comments, one commenter asked, "As a human directing my personal agent, why does it need a protocol?"

On scoped authorization, the objection is right, and a large investment in a draft would be a poor trade. It falls short on the rest. MCP's authorization spec defines no signed-out session, per-company User ID, human handoff, or session shared across channels, and those gaps remain whatever protocol your customers' agents speak. PACT on A2A also asks for scopes, consent, and discovery of its own, so identity and session work is likely to carry over, whichever design wins.

Adopt, experiment, or wait

For any draft standard, production work waits for stability and a counterpart; cheap, reversible work can start now.

Adopt now when all of these hold

The spec is stable.
An official reference implementation is public.
A personal agent your customers use sends Poppy traffic to services like yours.
Audit records, fraud review, and a staffed queue are ready for poppy:write actions and handoffs.

As of October 12, 2026, the spec is not stable, no official reference implementation is public, and we found no public evidence of the third.

Run a bounded experiment when these hold

You already run OAuth with PKCE or a device flow, an MCP server, or a public OpenAPI.
You see customer agents in your web or support traffic.
You can cap the work and throw it away, as fillthemat's review capped a proposed spike at one engineer-day or less.
The scope stays at poppy.json over existing endpoints, signed-out read access, and no new write paths.

Wait when any of these hold

You have no OAuth-scoped public API yet; build that first.
No customer agents appear in your web or support traffic.
Your write actions move money or change accounts, and you have no audit trail for agent actions.

Waiting still leaves protocol-neutral work open: per-agent attribution, short token lifetimes, revocation, and an escalation route to a person.

Risks and open questions

Protocol churn: draft 0.1 allows breaking changes, so record the protocol_version you implement and budget for rework.
Identity and authorization: Mediated sign-in uses "credentials the User has given it for this Company." The agent still holds the customer's credentials, though you can now see it is an agent; decide whether to offer it.
Consent: poppy:write covers "Make changes, such as exchanging an item or updating a booking," so your custom scopes carry the consent design.
Privacy: check that analytics and fraud tooling never join a signed-out User ID to an identity before sign-in.
Auditability: the spec defines no audit log, so record agent, User, scope, Session, and action yourself.
Abuse and fraud: registration, allow and block lists, client_id revocation, and per-client_id rate limits are among the spec's optional controls, so decide what fraud review applies to agent writes.
Observability and versioning: tag logs and metrics by client_id, and pin community SDK versions in any spike.
Operational ownership: name owners for the token endpoints, the handoff queue, and poppy.json.
Fallback to people: customers whose agent fails still need your existing support workflow.

Evaluation checklist

Mark each yes or no for your own API:

Your OAuth server supports the authorization code flow with PKCE and the device authorization grant.
Your MCP server, if any, acts as an OAuth 2.1 resource server with RFC 9728 metadata.
Your API can validate DPoP-bound tokens, or you have sized that work.
Your token endpoint can issue a signed-out Session for an agent and a User ID with no personal data.
You can identify agents by HTTPS client_id and keep allow and block lists.
One revocation signs out every Session tied to an account while carts and conversations continue.
A staffed human queue sits behind any agent handoff.
Your logs record agent, User, scope, and action for every request.
You see customer agents in your traffic today.
One named person owns the experiment and tracks the spec.

Yes on 1 or 2, plus 9 and 10, points to an experiment. No on both 1 and 2 points to waiting. Yes across the list, plus a stable spec and an agent counterpart, points to adoption.

FAQ

Is Poppy the same as the Personal Agent Protocol?

Yes. The overview says "Personal Agent Protocol (Poppy for short)." Sierra's October 6, 2026 announcement used only the full name; its October 9 post added "known as Poppy."

Who maintains it?

Sierra and Meta develop it with industry partners under the Apache License 2.0. As of October 12, 2026, no editors, governance body, or standards organization appear on the spec site.

Is the spec final?

No. It is draft 0.1, updated October 9, 2026, and any part can change before a stable version, including in ways that are not backward compatible.

Does Poppy replace MCP or A2A?

No. Poppy lists MCP servers and OpenAPI endpoints as channels, so it sits on top of an MCP server you already run. The spec does not mention A2A, and no primary source defines that relationship.

How is it different from PACT?

Decagon's PACT is "Built on the Agent2Agent protocol and OAuth 2.0," and its agents find a business through an A2A Agent Card. Poppy uses poppy.json and routes agents to OpenAPI, MCP, the website, or a company agent. Decagon's PACT is a different document from the IETF individual draft also named PACT (Private Agent Consent and Trust Profile, April 2026); neither references the other.

Is there a reference implementation?

Not an official one as of October 12, 2026. Sierra said on October 9 it would publish one "Over the next month." Independent community SDKs and demos exist.

Should our API support Poppy now?

For most consumer-facing platforms, as of October 12, 2026, run a bounded experiment with signed-out read access and no new write paths, and hold production rollout until the adopt conditions are met.

Run the evaluation checklist against your own API with the draft 0.1 specification open beside it, and record your adopt, experiment, or wait decision with its reasons.

How do you evaluate AI support quality beyond deflection rate?

Alisa Hester — Tue, 13 Oct 2026 00:30:05 +0000

Leadership asks whether the AI is working, and the number you can defend is deflection or containment. What you cannot say is whether the customers behind it got a correct answer, finished the task, trusted the experience, or came back with the same problem. A deflected conversation can hide a customer who retried, reopened a ticket, escalated by email, churned, or acted on an incorrect answer.

Deflection records where the work went. Whether the customer got a correct answer is a separate question, and your vendor's "resolution" figure does not settle it: each vendor sets its own window, judge, and stance on accuracy, and for some it is the unit you pay for.

Our recommendation: keep deflection as an efficiency line and build your own scorecard around it. Rank answer correctness and verified resolution above efficiency, check each resolution against repeat contact in a fixed window per issue type, and segment by issue risk. Then run one bounded 30-day experiment with a decision rule you write before the data comes in.

TL;DR

Deflection and containment are cheap, real-time efficiency metrics and weak quality metrics.
Vendor "resolution" numbers differ in window, judge, and accuracy criterion, and Intercom and Zendesk bill on them.
Grade a small, stratified sample with reviewers who do not configure the bot; correctness and safety fails override other scores.
Joining conversations to later outcomes shows association; only a holdout or staggered rollout shows cause.

What deflection can and cannot tell you

Salesforce's Agentforce module defines Deflection Rate as the "Share of sessions that ended without escalation to a support representative or another agent." Decagon, which sells an AI support agent, calls deflection "a routing statistic" and resolution "an outcome statistic," and says "they can move in opposite directions from the same change to an AI agent." The mechanism holds without the vendor: hiding the handoff raises deflection whether or not more customers get answers.

The denominator decides the number

Deflection over all AI-touched sessions = sessions with no handoff ÷ all sessions where the AI replied.
Deflection over real questions = sessions with no handoff ÷ (AI sessions minus greetings, test traffic, and sessions abandoned at the first message).

The first counts a customer who typed "hi" and left as a success. The second still counts everyone who left after a wrong answer. Vendors choose too: Intercom's Fin resolution count leaves out greetings, unanswered clarifying questions, and explicit requests for a human. Write your denominator down and keep it fixed.

A session without a handoff has three explanations

The customer was solved, gave up, or switched channels, and session data cannot tell which. SQM Group's survey method for phone first-call resolution counts a call only with "yes" to "Was your call resolved?", one call, and "no" to using another channel (SQM, Jan 19, 2021, phone contact centers). Your AI data needs the same check: join sessions to later contacts.

Vendor "resolution" is several different metrics

Definition	What counts	Window	Who judges	Accuracy a criterion?	Billing
Intercom Fin resolution	Customer confirms, or "exits the conversation without requesting further assistance (assumed resolution)"	None stated; Fin can follow up after 4 minutes of inactivity	Customer behavior	Not stated	$0.99 per resolution, "one outcome per conversation"
Zendesk Verified Resolution	An LLM reads the conversation "to confirm that the customer's request was satisfactorily resolved"	Messaging 2 hours, up to 72; email 72 hours; voice on hangup	The vendor's LLM	Not named	Draws from the resolution allowance
Ada automated resolution	"Relevant," "Accurate," and "Safe," on an LLM-graded sample of closed conversations	Not stated	The vendor's LLM	Yes	Not stated

None of these can be compared across tools, and two are billing units. Sources, for the definitions only: Intercom Help, Zendesk's tiers, "introduced on May 18, 2026", and Ada's guide (June 17, 2026).

Drag, an inbox vendor that competes with these tools, gives an example (Aug 8, 2026) without saying whether the numbers come from a real queue: "A single support queue, measured all four ways, produces four numbers that can span thirty points."

Confirmed resolution: 46%
Assumed resolution: 68%
Deflection: 80%
Satisfaction: 74%

CSAT does not close the gap. Intercom's CX Score scores closed chat or email conversations that include "at least two customer replies and two agent/chatbot replies," and Intercom says shorter conversations may now be rated when there is "a clear signal to evaluate." By our reading, a customer who leaves Fin after one exchange can count as an assumed resolution and still get no quality score, which is where silent failures are likely to sit.

The objection: deflection and CSAT are good enough

Deflection is cheap and real-time, sampling is slow and noisy, and vendors already report resolution, so keep deflection as the efficiency line. Vendor resolution follows rules each vendor sets. Zendesk's billable Verified Resolution is graded by Zendesk's own LLM, and Intercom also bills for assumed resolutions, which it infers from customer silence. CSAT and conversation scores can miss the short exchanges where silent failures sit. The only QA price we found is for Lorikeet's automated QA product, Coach: "about $0.27–$0.30 per ticket." We found no measured cost for human sampling. NIST's voluntary Generative AI Profile, which abbreviates generative AI as GAI, advises: "Avoid extrapolating GAI system performance or capabilities from narrow, non-systematic, and anecdotal assessments" (MS-2.5-001), which favors a small systematic sample over ad hoc spot checks.

A measurement hierarchy

Rank metrics so a gain lower down never excuses a loss higher up:

Safety and answer correctness.
Task or issue resolution, verified against repeat contact.
Escalation quality and context preservation.
Customer effort, confidence, and trust.
Operational efficiency and cost.
Product, customer, and business outcomes.

Correctness comes first because a confident wrong answer looks like a success in every routing metric. NIST AI 600-1 (July 2024) defines confabulation as "The production of confidently stated but erroneous or false content ... by which users may be misled or deceived."

The concrete case is Moffatt v. Air Canada (2024 BCCRT 149). Air Canada argued it could not be held liable for what its chatbot said. The tribunal found the airline "did not take reasonable care to ensure its chatbot was accurate," a "negligent misrepresentation," and awarded "$650.88 CAD" plus interest and fees, according to Manatt's summary (Feb 28, 2024). It is a decision of British Columbia's Civil Resolution Tribunal, a small-claims body. A deflection count cannot separate that conversation from a correct one.

Efficiency sits fifth because speed and quality can move apart. In measured research on "5,172 customer support agents" (arXiv v2, Nov 6, 2024; an assistant for human agents, not a customer-facing bot), Brynjolfsson, Li and Raymond found AI assistance raised issues resolved per hour "by 15% on average," while the "most experienced and highest-skilled workers see small gains in speed and small declines in quality."

Metric definitions, formulas, and gaming risks

The formulas are our recommendation; keep each definition fixed for any comparison.

Metric	Definition or formula	What it indicates	How to instrument	Main failure mode or gaming risk
Deflection	Sessions with no handoff ÷ eligible AI sessions, denominator stated	Where the work went	Handoff event	Rises when the handoff is hidden; counts give-ups as wins
Containment	AI sessions completed with no request for more help ÷ eligible AI sessions	The AI kept the conversation	Session-end event and "no further request" flag	Counts silent exits; the customer may return by email
Assumed vs confirmed resolution	Assumed: no further request after the last AI answer. Confirmed: the customer said it worked	How much of "resolved" rests on silence	Exit and confirmation events	Assumed rises with abandonment
Verified resolution	Resolutions passing the correctness check with no repeat contact in the window ÷ eligible sessions	A correct answer that held	QA sample and repeat-contact join	Vendor versions are graded by the vendor
First-contact resolution	Issues resolved on the first contact in any channel ÷ issues	One contact was enough	Issue ID across channels; SQM uses "within 1 to 30 days" by call reason	A short window hides failures
Repeat contact in window	Customers contacting again on the same issue within its window ÷ resolved issues	The answer did not hold	Join on customer ID, issue category, timestamp	Loose issue tags hide repeats; one window for all issues
Reopen	Tickets reopened ÷ tickets closed after AI involvement	Closure was premature	Ticket status history	Lorikeet warns a 24-hour window can "close before the customer has noticed the problem is still there"
Escalation rate	AI sessions handed to a person ÷ eligible AI sessions	How often the AI needs help	Handoff event	Lowered by hiding the handoff
Escalation quality	Handoffs where context arrived and the customer did not repeat themselves ÷ handoffs	Context survived the transfer	QA sample of handoffs	Measuring transfer speed instead
Customer effort	Reported effort, plus contacts and channels per issue	How hard help was to get	Survey after resolution; contacts per issue	In-session surveys miss customers who left
Time to resolution	First contact to verified resolution, across channels	Speed of an answer that held	Issue timestamps	Measured to session end instead
Answer correctness and groundedness	Sampled answers passing the gated check ÷ sampled answers	Right and backed by your sources	QA rubric and citation check; Salesforce's "Answer Faithfulness" is one vendor version	Unreviewed vendor auto-scores; convenience samples
Business outcomes	Churn, feature activation, expansion, or refunds in a fixed window for AI-served accounts, against a baseline	Downstream association	Account ID joined to billing and product events	Read as causation; groups differ before the AI touches them

Each efficiency metric can rise without helping a customer; pair it with a quality metric.

A QA rubric for sampled AI conversations

Correctness and policy or safety are gating: a fail on either fails the conversation, whatever the other scores say.

Criterion	Scale	Fails when	Gating
Correctness and groundedness	Pass or fail	A claim contradicts the product, a policy, or the source, or rests on no source you can find	Yes
Policy and safety	Pass or fail	Promises a refund, exception, or commitment policy does not allow; exposes account data	Yes
Completeness	0 to 2	Answers part of the question or stops a step short	No
Actionability	0 to 2	The customer cannot act without asking again	No
Cited documentation was current	Current, stale, missing, or no citation	Cites an article that no longer matches the product, or needed one that does not exist	No; route to the docs owner
Tone, only where relevant	0 to 2	In a billing dispute, outage, or complaint, ignores the stated problem	No

How to sample

Stratify by risk segment and oversample high-risk ones. Include assumed resolutions and short conversations your quality score may not rate.
Use reviewers who do not configure the bot. NIST MS-1.3-003: "Verify those conducting structured human feedback exercises are not directly involved in system development tasks for the same GAI model."
Calibrate weekly: two reviewers grade a shared subset, and each disagreement becomes a rubric note.
Open every cited article. NIST MS-2.5-003: "Review and verify sources and citations in GAI system outputs during pre-deployment risk measurement and ongoing monitoring activities."
Size per segment: if you would act on a failure that occurs once in N conversations, reading about 3N from that segment gives roughly a 95% chance of seeing it at least once (our arithmetic: 1 minus (1 minus 1/N) to the power 3N is close to 95%). Twig, which sells AI support, suggests "typically 50-100 interactions per week" (vendor guidance).

When the failure is the article

The rubric line "cited documentation was current" separates two fixes. When sampled failures trace to a missing or stale article, route them to the documentation owner: the fix is a new or corrected article. Gartner's measured figure, reported by destinationCRM (Sep 12, 2024), covers self-service in general, not AI accuracy: "in 43 percent of cases, customers couldn't find content relevant to their issues."

EkLine works on that layer: Docs Agent drafts and edits articles in a Confluence or Pylon knowledge base from sources such as support threads. A person reviews the diff under View All Changes and clicks Update KB, which "overwrites the live page immediately," so nothing goes live without that approval. Two scheduled agents help: "Improve Pylon knowledge base" reviews recent Pylon tickets for questions the knowledge base should have answered and drafts articles for your review, and "Confluence Knowledge Base Drift Review" detects Confluence pages that recent documentation changes made stale and drafts corrections. Knowledge base management is available on request.

Before, a stale-article cluster from your sample waits in a backlog; after, a drafted correction waits for a reviewer. EkLine drafts the article fix; your scorecard still decides whether anything improved. Start with the tutorial on turning recurring support questions into a knowledge base article, whose last step includes "Watch whether the question returns."

Join conversations to what happened next

Fix each signal's key and window before you look at results.

Signal	Example join key	Window
Repeat contact or later escalation	Customer or account ID plus issue category, any channel	Per issue type
Reopen	Ticket ID	Until auto-close
Task completion	Account ID plus the product event the answer described	Per issue type
Feature activation	Account ID plus feature event	Fixed in advance
Refund or churn risk	Account ID plus billing events	Fixed in advance
Support-assisted revenue	Account ID plus expansion records	Fixed in advance

Set each window by how long a customer takes to discover a wrong answer. SQM sets phone windows by call reason: a claim "might need 30 days" and a status inquiry "might only need 5 days." Vendor guidance runs shorter: Decagon says "Recontact rate within 48 or 72 hours is the cheapest check on an inflated resolution figure," and Zendesk's blog uses 24 to 72 hours. One practitioner, Tian Pan, recommends "Repeat-contact rate at 7, 30, and 90 days."

These joins measure association. Customers who stay with the AI can differ from those who ask for a person first, so lower churn among them can reflect who they were. To show cause, use a holdout (eligible conversations in a segment randomly routed to the AI or the human path) or a staggered rollout (segments switched on in an order fixed in advance, compared with segments still waiting). Both need the same definitions on each side, a primary metric and window chosen before launch, and time for lagging outcomes to appear.

Segment before you average

Report every metric by issue type, customer tier, product area, risk (money, account access, security, and policy commitments in the high tier), and channel. Averages hide harmful failures in small high-risk segments: if password resets dominate your volume, the blended rate can rise while answers about a changed API endpoint or a refund policy get worse. NIST says organizations "may additionally wish to allocate risk management resources relative to the severity and likelihood of negative impacts" (AI 600-1, p. 3), and SQM's per-reason windows apply the same logic to time. No source we found measures how often this happens; it follows from how averages work.

An example balanced scorecard

Illustrative layout, fields and formulas only. Values come from your own human and AI baselines. The only published averages we found are vendor figures on the vendor's own definition.

Line	Metric	Formula	Segment by	Review cadence
Guardrail	Gated correctness pass rate	Sampled conversations passing ÷ sampled conversations	Risk tier, issue type	Weekly
Guardrail	Policy and safety fails	Count of gated policy fails in the sample	Risk tier	Weekly; high-risk fails reviewed that week
Leading	Verified resolution rate	As in the matrix	Issue type, channel	Weekly
Leading	Repeat contact in window	Repeat contacts on the same issue ÷ resolved issues	Issue type	Weekly, as windows close
Leading	Escalation quality	Handoffs with context preserved ÷ handoffs	Product area	Weekly
Leading	Documentation currency	Answers citing a current article ÷ answers with a citation	Product area	Weekly, to the knowledge base owner
Efficiency	Deflection, denominator stated	Sessions with no handoff ÷ eligible AI sessions	Channel	Real time
Lagging	Refund or churn in window	Accounts with the event ÷ accounts in the group, AI beside human baseline	Customer tier	Monthly

A 30-day plan

Owners: the support leader (decision rule), Support Ops (definitions and instrumentation), reviewers outside the bot team (sample), and the knowledge base owner (documentation failures).

Week	Do	Checkpoint
1	Establish definitions, denominators, segments, and per-issue windows. Write the decision rule (expand, hold, or pull back) before any data comes in.	Signed definitions; dated decision rule
2	Instrument handoff, exit, confirmation, and reopen events and build the joins. Create the sample and audit process.	Events firing; first calibration session
3	Baseline human and AI flows on the same definitions and windows. Grade the weekly sample.	Side-by-side baseline per segment
4	Review failure clusters: wrong answers, stale articles, lost context. Apply the decision rule as written.	Expand, hold, or pull back, per segment

A rule might read: expand in a segment when its sample shows no gated fails and repeat contact is no worse than the human baseline; pull back on any high-risk safety fail or repeat contact worse than the baseline; hold otherwise.

Replace the deflection target with one experiment

An illustrative bounded experiment:

Hypothesis: AI answers to refund-policy questions are correct and hold as well as human answers.
Segment: refund-policy questions in chat, all tiers (high risk).
Primary signal: repeat contact on the same issue within 30 days, a claim-type window.
Guardrail: gated correctness and policy pass rate in a weekly stratified sample.
Window: 30 days of conversations, plus 30 days for the last window to close.
Decision rule: written in week 1 and applied as written.

Bring that segment to your next leadership review, with deflection beside it as the efficiency line.

FAQ

Is a high deflection rate a good thing?

It means the AI kept the conversation, which lowers cost if the answers were right. It cannot separate solved customers from those who gave up or switched channels, so read it beside verified resolution and repeat contact.

What resolution rate should an AI support agent achieve?

We found no cross-vendor benchmark for resolution, repeat contact, or accuracy. Vendor averages, such as the one Ada publishes for its own automated resolution rate, use that vendor's definition and do not compare across tools. Set targets from your own human baseline, segment by segment.

How can false deflection negatively impact customers?

A customer counted as deflected may have acted on a wrong answer, retried elsewhere, or left. In Moffatt v. Air Canada, a ruling by British Columbia's Civil Resolution Tribunal, a small-claims body, a chatbot's inaccurate answer led to a finding of negligent misrepresentation.

How should deflection and resolution metrics be reported to leadership?

As separate lines on one scorecard: guardrails first, then verified resolution and repeat contact, then efficiency, each by segment. State every denominator and window, and label downstream outcomes as association.

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.