Migrate to 2.0 ​

Two things change for your readers: the panel's default shape and its motion. It opens from a question bar at the bottom centre of the page, not from a button in the corner — see The panel is a bar by default — and it moves for a reader whose OS asks for reduced motion — see Motion is on by default. Its features and its client config keys are the same, and every other change in 2.0 is under the hood or in your own tooling. What you must check depends on your install:

The full list of changes has the engine specs behind each one.

Upgrade ​

npm i @cloflin/docpilot@2
npx docpilot update
npx docpilot index --yes

• update refreshes the skills and slash commands you installed, and installs the docpilot-tuner and docpilot-writer agents into .claude/agents/ if you chose the Claude Code target. A file you edited is kept beside the new one as .bak.
• index rebuilds the index with the new file names. An index built by 1.x still loads, without the integrity check, so you can upgrade first and rebuild when you deploy.

Run npx docpilot status afterwards. It shows whether the index is fresh and what to run next.

The panel is a bar by default ​

In 1.x, ui.panel: 'auto' with the floating button opened the popup above a button in the corner. In 2.0 it opens the bar: the composer sits at the bottom centre of every page, and the conversation rises in a window above it when the reader types. Below 960px the bar is a button that opens the same full-screen sheet as every other shape.

To keep the 1.x panel, name the shape:

ui: { panel: 'popup' }

ui.fabLabel and ui.fabIcon dress the corner button, so under the bar they do nothing. ui.side does not move the bar: it is centred.

Motion is on by default ​

1.x replaced every movement with a fade for a reader whose OS reports prefers-reduced-motion: reduce, and nothing could change that. 2.0 plays the motion for everyone by default and makes the 1.x behaviour a setting:

ui: { motion: 'auto' }     // 1.x: fades while the reader's OS asks for reduced motion
ui: { motion: 'reduce' }   // fades for everyone

A VitePress default-theme site removes all motion for that reader from its own base.css, with !important, whatever this says. See ui.motion.

The panel's CSS is in a cascade layer ​

In 1.x only web.css was in @layer docpilot. In 2.0 all five stylesheets are, so any unlayered CSS on your page outranks the panel's whatever its specificity.

Details and the layer order to write yourself: Appearance.

Index files are named by their bytes ​

In 1.x the shards, the document-frequency file, the vectors and the openers carried the corpus hash in their names. The corpus hash covers chunk ids and text only, so a change of tokenizer, config or embedder could rewrite a file under a name that a returning reader's immutable cache already held.

In 2.0 every one of those files is named by a hash of its own bytes. manifest.json stays the one file served without a long cache, and it carries integrity: the sha256-… digest of each file. The panel fetches each file with that digest, so a file that is not the one you built fails the load.

What this means for you:

• Deploy the whole index directory: the new files and the manifest together.
• A host that rewrites /rag/* in flight now breaks the load. Minifiers, HTML or JSON rewriters, and proxies that re-compress or inject into responses change the bytes. Turn that off for the index path, or the load fails.
• docpilot index prints the size on the wire (brotli) beside the size on disk, so you see what a reader downloads.

New defaults on the server install ​

Skip this section if you run the static install.

Every setting and its default is on Server operations.

docpilot serve now reads server.* ​

docpilot serve handed the server the resolved settings, and the resolved object carried server.endpoint alone. It dropped every other server.* key. In 2.0 the server gets the settings you wrote.

If you had server.* keys in your config that never seemed to do anything, they do now. Read them again before you deploy. The usual surprise is a server.limits or a server.allowedOrigins you wrote months ago and forgot.

What you gain, and need not use ​

None of the following is required.

• npx docpilot init asks which install you want and prints the block to paste. See Choose your install.
• Measuring: eval --runtime=server, --split=dev|test, --set=adversarial and --quiet, plus new metrics: see Measure.
• Improving: docpilot improve, and the Claude Code agents that run it.
• The terminal: the home screen, status and monitor — see The terminal.
• Security probes: Attack probes.

What did not change ​

• The client config keys, themeConfig, and every panel feature. Only ui.panel: 'auto' resolves to a different shape.
• The golden-set format. A record without split is assigned one by a hash of its id, so an existing set works with no edit.
• The turn log. It keeps docpilot.turn/1 and gains fields: timing, rankedIds, historySigned, leakBlocked and cached.
• The /ai/v1/* proxy contract of the static install.
• The default runtime: 'browser'.

If something breaks ​

1. Run npx docpilot status and npx docpilot doctor.
2. On the server install, a surprise 429 is the new limits. Read docpilot_refused_requests_total in the metrics, then change server.limits.
3. A panel that cannot load the index after the upgrade points at a host that rewrites the files. Compare the bytes you deploy with the bytes the host serves.
4. To go back, pin the 1.x version you came from and redeploy the index you built with it.