One-line state: Clean, well-organized Mintlify docs with genuinely useful robotics content — undermined by two contradictory on-disk locations for the product's signature feature spread across three pages, a simulator-support story that changes between the homepage, the config metadata, and the docs, a changelog frozen ~9 releases behind reality, and an llms.txt that hides roughly a third of the site from the agents it exists to serve.
1. Skills live in two contradictory on-disk locations across three pages (critical)
Problem: Skills are Drift's headline differentiator ("Your team's expertise becomes the agent's"), but the docs name two different native directories for them. The Introduction says: "Drop it in .claude/skills/<name>/SKILL.md (per-workspace) or ~/.claude/skills/<name>/SKILL.md." The FAQ ("Where do skills live on disk?") lists only.claude/skills/ paths and states "/skill add <path> copies your file to the right location for you." The canonical Custom Skills guide (/guides/skills) instead gives the native location as .drift/skills/<name>/SKILL.md and says /skill add "always copies into .drift/skills/." So the on-disk home is .claude/skills/ on two pages and .drift/skills/ on the third. (The ~/.claude home path is a machine-wide scope, not a third conflicting location — the real conflict is .claude vs .drift.)
Consequence: A developer who hand-places a skill under .claude/skills/ per the Introduction or FAQ may have it ignored if the engine actually reads .drift/skills/ per the canonical guide — and vice versa. The feature silently does nothing, with no error to debug. AI coding agents are hit hardest: they can't apply human judgment to reconcile ".claude vs .drift," so an agent scaffolding a skill picks one path and fails silently.
The fix: Pick one canonical on-disk location, state it once, and make every other page link to that single source. If both .claude/skills/ (compatibility) and .drift/skills/ (native) are genuinely read, say so explicitly on all three pages and document the precedence — don't let each page assert a different sole location.
2. MuJoCo is a documented "first-class target" but the site metadata and README sell Gazebo-only (significant)
Problem: The docs.json description and OG/Twitter metadata describe Drift as "the AI copilot built for robotics development. Build, test, and debug ROS2 simulations in Gazebo through plain English prompts — no manual URDF editing, no hand-written launch files." The README "About Drift" section repeats this verbatim. Neither mentions MuJoCo. Yet /guides/mujoco-scene states "Drift treats MuJoCo as a first-class target," the Introduction leads with three MuJoCo Menagerie examples (Go2, Aloha, H1), and the entire Robot Showcase is built on MuJoCo.
Consequence: Search engines, social cards, and the README — the surfaces a new developer or an agent sees first — advertise a Gazebo/ROS2-only tool and omit half the product. A MuJoCo/RL researcher evaluating Drift from its metadata or GitHub README would reasonably conclude it isn't for them and bounce, despite MuJoCo being a primary supported path. This is a discoverability and positioning failure rather than a functional break — no one following the docs hits a wall — which is why it's significant rather than critical.
The fix: Rewrite the docs.json description, OG/Twitter metadata, and README "About" section to name both simulators ("ROS2 + Gazebo Harmonic and native MuJoCo"). The product positioning should match the documented feature set.
3. Homepage markets Isaac Sim + USD; docs explicitly say Isaac Sim is unsupported (critical)
Problem: The homepage says Drift "launches the simulation in Gazebo, MuJoCo, or Isaac Sim" and "generates the matching world and robot description files (URDF, SDF, MJCF, or USD)," listing "three major simulators: Gazebo, MuJoCo, and Isaac Sim (coming soon)." The docs (llms-full.txt) state the opposite: "Drift targets Gazebo Harmonic, not Isaac Sim... Isaac Sim integration is not currently supported." USD is never mentioned anywhere in the docs.
Consequence: A developer who buys in from the homepage's Isaac Sim/USD pitch and then tries to generate a USD scene or launch Isaac Sim will fail, and the docs will tell them the feature doesn't exist. The "(coming soon)" qualifier appears only on the homepage, not where engineers actually look. This is the kind of marketing-vs-docs gap that erodes trust on day one.
The fix: Make the homepage and docs state the same support matrix. If Isaac Sim/USD are roadmap-only, label them consistently as "planned / not yet available" on the homepage, and add a one-line roadmap note to the docs so the two never contradict.
4. Mandatory Google Sign-In is invisible in the Quickstart — documented only under Troubleshooting (critical)
Location: /getting-started/quickstart vs /reference/troubleshooting
Problem: The Quickstart's "Launch Drift" step shows the welcome screen ("🚀 Welcome to Drift CLI ... drift>") and proceeds straight to prompting and simulator setup. It never mentions that Drift requires a Google Sign-In before it will process anything. The login flow ("Run drift - it shows a Google Sign-In URL... Complete Google Sign-In") appears only on the Troubleshooting page, under "Authentication Issues."
Consequence: A new user follows the Quickstart, expects the drift> prompt to accept a prompt immediately, and instead is blocked by an auth gate they were never told about — then has to discover it's mandatory by digging into a Troubleshooting page. Sign-in is a required onboarding step, not an error condition. Agents automating setup will stall on an undocumented interactive browser step.
The fix: Add an explicit "Sign in" step to the Quickstart before the first prompt, describing the Google Sign-In URL flow and the 5-minute login timeout. Keep the Troubleshooting entry for failures, but the happy path must document the gate.
5. Ubuntu 20.04 is listed as supported, but it has no supported ROS2 path (significant)
Problem: Both the System Requirements ("Ubuntu 20.04+ (Debian-based distributions)") and the Quickstart ("Ubuntu 20.04 (Focal)") list 20.04 as a supported OS. But the same docs state only "ROS2 Humble (LTS) or Jazzy" are supported, and "Foxy is EOL and unsupported." ROS2 Humble targets Ubuntu 22.04 and Jazzy targets 24.04; the 20.04-era distro is Foxy, which is unsupported. So a 20.04 user has an OS marked "supported" with no supported ROS2 distribution.
Consequence: A developer on Ubuntu 20.04 installs Drift believing they're on a supported platform, then discovers the ROS2/Gazebo path is effectively unavailable (only the MuJoCo path works). The OS support claim and the ROS2 support claim quietly contradict each other.
The fix: Either drop Ubuntu 20.04 from the supported OS list, or annotate it clearly: "Ubuntu 20.04 — MuJoCo path only; no supported ROS2 distribution (Humble requires 22.04, Jazzy requires 24.04)."
6. The docs changelog is ~9 releases and ~3 months stale, and every entry is empty (significant)
Problem: The docs changelog lists "v1.0.15 (Latest)" released March 12, 2026, and every single entry reads "Release notes coming soon." The live GitHub releases page shows the actual latest is v1.0.24 (June 6, 2026) — roughly nine versions and three months newer. The live changelog URL even redirects to GitHub, where the release notes are themselves essentially empty ("Full Changelog: 1.0.23...1.0.24").
Consequence: A user who runs /update (which the docs tell them to do "to stay on the latest release") ends up on a version the changelog has never heard of, with zero notes explaining what changed. There is no functioning record of what any release did — on the docs site or GitHub. Debugging a regression or checking whether a fix landed is impossible.
The fix: Automate changelog generation from releases so the docs version pin never drifts, and replace "Release notes coming soon" with actual per-release notes (even one line each). At minimum, update the pinned "Latest" version.
7. llms-full.txt omits the entire Robot Showcase and three guides — agents can't discover ~a third of the site (significant)
Location: /llms-full.txt vs docs.json navigation
Problem: The docs.json navigation defines 16 pages, but llms-full.txt's "Documentation Pages" index lists only 10. The six missing pages are the entire Robot Showcase group (showcase/quadruped-go2, showcase/dual-arm-aloha, showcase/humanoid-h1) plus three guides (guides/mujoco-scene, guides/project-context, guides/skills). That's roughly 37% of the navigation absent from the agent index. Worse, the /guides/first-simulation "Next Steps" cards link to "Building a MuJoCo Scene" (guides/mujoco-scene) and "Project Context" (guides/project-context) — both omitted from llms.txt/llms-full.txt, so those two cards are dangling references an agent can't resolve. (The third card, "Manipulator in RViz," does resolve — llms-full.txt lists "Launch Manipulator Arm in RViz" — so it is not a dangling reference.)
Consequence: llms.txt/llms-full.txt exist specifically so AI coding agents can index the docs efficiently. An agent relying on llms-full.txt will never find the Robot Showcase (the product's best end-to-end walkthroughs), the canonical skills guide, or the project-context guide — and will hit two dangling "Next Steps" cards it can't resolve. The agent-facing index silently hides the content agents most need.
The fix: Regenerate llms.txt/llms-full.txt from docs.json so the page index is complete and stays in sync. Every page in the navigation — including all three showcase pages and the mujoco-scene, project-context, and skills guides — should appear in the agent index.
8. llms-full.txt lists only 6 of 13 slash commands and mislabels them (significant)
Location: /llms-full.txt vs /reference/commands
Problem: The authoritative Commands Reference documents 13 slash commands (/help, /init, /skill add|list|remove, /ps, /version, /update, /login, /logout, /profile, /clear, /exit). The llms-full.txt "Slash commands" bullet lists only six — /ps, /help, /update, /clear, /exit, /version — and describes them as "executed directly, not processed by the AI." It omits /init, /skill, /login, /logout, and /profile entirely.
Consequence: An agent reading llms-full.txt (the machine-readable surface) concludes Drift has no skills management, no project bootstrap, and no auth commands — exactly the commands needed to onboard. The mischaracterization ("executed directly") also implies the omitted commands don't exist.
The fix: Sync the llms-full.txt command summary with the Commands Reference, or have it link to the full table rather than partially duplicating it.
9. The --repo flag for /skill add is documented only in the guide, not in the authoritative Commands Reference (significant)
Location: /guides/skills vs /reference/commands
Problem: The Custom Skills guide documents a --repo flag for /skill add. The Commands Reference — which is the docs' authoritative command list and documents /skill add <path>, /skill list, and /skill remove <name> — does not mention --repo at all (verifiable directly from the reference table, which lists no flags on the /skill rows).
Consequence: A developer or agent consulting the canonical command reference (the expected place to learn flags) never learns the flag exists; one consulting only the guide may not realize it's an undocumented extension. Either way, the two command surfaces disagree about the actual CLI grammar of a core feature.
The fix: Add --repo (with its argument and behavior) to the /skill add row in the Commands Reference, and make the reference the single source of truth for command syntax.
10. Two conflicting primary CTAs point to two different destinations, one with no docs (minor)
Problem: The docs chrome ships two competing calls to action: the topbar button "Get Early Access" → https://godrift.ai (marketing site), and the navbar primary button "Get Started" → https://platform.godrift.ai/ (the platform dashboard). The platform dashboard has no docs page, and the docs never explain what platform.godrift.ai is beyond hosting per-query cost tracking and usage limits.
Consequence: A reader sees two prominent buttons with different verbs and different destinations and can't tell which is the real entry point. "Get Started" routing to a bare dashboard (rather than the Quickstart) is a dead-end for someone who hasn't installed the CLI yet.
The fix: Use one primary CTA. Point "Get Started" at the Quickstart, and add one line to the docs explaining what platform.godrift.ai is and when to use it (cost tracking, budgets, usage limits).
11. macOS/Apple Silicon workarounds differ between docs and homepage (minor)
Location: /getting-started/introduction, /getting-started/faq vs https://godrift.ai/
Problem: The Introduction says Apple Silicon users "run Drift via a VMware Fusion x86_64 Ubuntu image," and the FAQ says macOS users "can run Drift inside a Ubuntu virtual machine using VMware Fusion." The homepage says macOS engineers "typically run Drift inside an Ubuntu VM, a container, or a remote dev box" — two options (container, remote dev box) the docs never mention.
Consequence: A macOS developer reading the docs believes VMware Fusion is the only supported workaround, when the vendor's own homepage suggests containers and remote dev boxes are viable. Conversely, a homepage reader who tries a container finds zero guidance in the docs. The supported-workaround story isn't consistent.
The fix: Pick the set of officially-supported macOS workarounds and document the same list in both places. If only VMware Fusion is tested, say so on the homepage too.
12. README repo-structure block is stale and omits real directories (minor)
Location: README.md
Problem: The README "Repo Structure" comment describes guides/ as "Built your first robot simulation" (a stale, ungrammatical label that names a single page), lists reference/ as only "Commands, System requirements, Changelog" (omitting Troubleshooting), and never mentions the showcase/ directory or the multiple guides that exist in docs.json.
Consequence: A contributor using the README to navigate the repo gets an inaccurate map — they won't know the Robot Showcase or Troubleshooting pages live there. Minor, but it signals the README isn't maintained alongside the content.
The fix: Regenerate the repo-structure block from the actual directory tree, including showcase/ and the full guides/reference page list.
13. Homepage's "50+ institutes/companies" claim is unsupported and at odds with the product's stated stage (minor)
Problem: The marketing homepage closes with "Used by engineers at 50+ institutes/companies, notably at" — and the sentence trails off with no names, logos, or links. Meanwhile the docs' own llms-full.txt labels the product "v1.0.15 (open beta)," and the public releases repo has only 5 stars.
Consequence: A developer evaluating Drift who cross-checks the GitHub footprint finds a five-star repo and an open-beta version pin that are hard to reconcile with "50+ institutes/companies." An adoption claim with nothing behind it ("notably at" with no names) reads as filler at exactly the moment a buyer is deciding whether the tool is real, and undercuts the credibility of the genuinely good technical content elsewhere.
The fix: Either substantiate the "50+ institutes/companies" claim with named references or logos, or soften it to match the product's open-beta stage. Don't leave "notably at" dangling with no examples.
What they do well
Honest scope sections — the Go2 showcase's "Honest scope" (no learned locomotion, no real-robot deployment, no footstep planning) and the quadruped guide's explicit caveats set realistic expectations instead of overpromising.
Concrete, failure-mode-specific content — debugging guidance names real MuJoCo failures ("NaN in qacc," "cylinder vs hinge axis mismatch," contact tuning) rather than vague "it might not work" hand-waving.
Clear health-check tooling — the Troubleshooting quick-health-check table (drift --version, echo $ROS_DISTRO, gz sim --version) gives developers exact commands and expected outputs to self-diagnose.
Top 3 recommendations
Resolve the skills-location contradiction immediately (Issue 1) — settle on one canonical path (.claude/skills/ vs .drift/skills/), state it once, and have the Introduction, FAQ, and guide all reference it. This is the product's signature feature and it currently fails silently.
Make the simulator-support story consistent across homepage, metadata, README, and docs (Issues 2 & 3) — name MuJoCo everywhere it's actually supported, and align the Isaac Sim/USD claims so marketing and docs agree on what exists today.
Fix the agent-facing surfaces: changelog and llms.txt (Issues 6, 7, 8) — automate the changelog from releases, and regenerate llms.txt/llms-full.txt from docs.json so the complete page list and command set are discoverable by the AI agents these files exist to serve.