Trovu Documentation Audit

Trovu's user-facing pages are clear and friendly, but the developer/editor docs have undeniable rot: a half-edited migration page, an empty section in the URL reference, contradicting domains for the data file, schema mismatches between the shortcut docs and the include docs, and zero machine-readable surfaces (no llms.txt, no OpenAPI, no JSON Schema for the YAML files that are the entire product).

1. Migration page contains a visible half-applied edit and is years stale (significant)

Location: /docs/legacy/migrate/

Problem: The first sentence reads literally "FindFind.it will end its service in October December 2023, with the end of life of Drupal 7." Both "October" and "December" are present in the text, indicating an edit was started and not finished. The entire page is also written in future tense for an event that — per the document's own date — happened over two years before today (2026-05-08).

Consequence: Anyone arriving from a stale FindFind.it bookmark hits a page that looks abandoned. The contradictory date undermines trust in the rest of the docs and signals to AI agents indexing the site that the migration content is unreliable. A skim-reader cannot tell whether the shutdown is upcoming, in progress, or long over.

The fix: Pick one month, switch to past tense ("FindFind.it ended its service in December 2023"), and add a short "this migration is now historical" banner. If the FindFind.it export form referenced in step 7 ("My account ➡️ Edit ➡️ Export to Trovu") no longer exists, say so and remove the now-impossible steps.

2. No llms.txt or llms-full.txt — agents have no entry point (significant)

Location: https://trovu.net/llms.txt and https://trovu.net/llms-full.txt

Problem: Both /llms.txt and /llms-full.txt return HTTP 404. Trovu's whole value proposition is mapping natural-language keywords to URLs, which is exactly the kind of dataset an AI coding agent would want to discover programmatically.

Consequence: AI agents (Claude Code, Cursor, ChatGPT browsing) cannot find a curated index of Trovu's docs and have to crawl the site blindly. Given that the docs are split across /docs/users/, /docs/shortcuts/, /docs/editors/, /docs/developers/, /docs/legacy/, agent retrieval is much weaker than it would be with a one-file index.

The fix: Publish /llms.txt listing the major doc sections and the URL of the compiled data.json (which is itself the most agent-useful artifact on the site). Optionally publish /llms-full.txt with concatenated Markdown of all the /docs/ pages.

3. Two different domains given for the compiled shortcut data (critical)

Location: /docs/users/troubleshooting/ (FAQ "I Edited a Shortcut, but It Has No Effect"), /docs/editors/, /docs/privacy/

Problem: Within a single FAQ entry, the troubleshooting page tells users to first check https://trovu.net/data.json and then says reload "will cause your browser to reload the shortcut files from data.trovu.net" — two different hostnames in two adjacent paragraphs. The editors page reinforces trovu.net/data.json ("shortcuts and other contents from the /data directory get compiled into trovu.net/data.json"). The privacy page describes the fetch but names no URL at all ("a precompiled JSON file (based on the data in the GitHub repo)").

Consequence: A contributor who pushes a shortcut and wants to verify it landed has to guess which URL is canonical. If data.trovu.net is a CDN/origin and trovu.net/data.json is a redirect or proxy, that's not stated anywhere. An AI agent told to "verify your shortcut got built" has a coin-flip chance of fetching the wrong host. This is the kind of contradiction that humans paper over with a refresh and agents fail silently on.

The fix: Pick one canonical URL, document the relationship between trovu.net/data.json and data.trovu.net (origin vs. CDN, cache behavior), and use the same string everywhere — privacy page, editors page, troubleshooting FAQ.

4. examples: schema is documented two incompatible ways (significant)

Location: /docs/shortcuts/ and /docs/shortcuts/include/

Problem: The shortcut reference (/docs/shortcuts/) defines examples: as a list of objects each with arguments: and description: keys:

examples:
- arguments: foo, bar
  description: Search example.com for "foo" and "bar"

The include reference (/docs/shortcuts/include/), in its very first example for dcm, uses a completely different shape — a YAML mapping of input → description:

examples:
    baum: English translation of "baum"
    tree: German translation of "tree"

Consequence: A new editor (or an agent generating a shortcut PR) will copy whichever syntax they hit first. If only one is supported by the parser, the other silently produces broken examples in the shortcut listing. If both are supported, that needs to be said. As written, the two pages directly contradict each other on the schema of a core attribute.

The fix: Decide whether examples: accepts only the long form, only the mapping form, or both. Update the include page (or the shortcut page) so the syntax matches, and add a note like "two equivalent forms are accepted" if that's actually true. A JSON Schema for shortcuts.yml would prevent this class of drift entirely.

5. URL reference page has an empty "Input encoding" section (significant)

Location: /docs/shortcuts/url/

Problem: The page lists <foobar: {encoding: iso-8859-1}> in the placeholder table with the description "... with encoding specified. See Input encoding below." The "Input encoding" heading exists further down, but its body is empty (rendered as just ... in the scraped content). The page also ends mid-sentence: "Filling and submitting with userscripts — If a website does not all" and then stops.

Consequence: A shortcut author who needs non-UTF-8 encoding for a legacy site (a real concern when targeting older European or Japanese sites) is told to scroll down for the spec, scrolls down, and finds nothing. The truncated final section leaves the userscript handoff dangling.

The fix: Either write the Input encoding section (which encodings are supported, where the conversion happens, what happens on failure) or remove the inline reference to it. Finish the trailing sentence about userscripts or link to /docs/shortcuts/userscripts/.

6. Content policy contradicts the namespaces example (significant)

Location: /docs/editors/policy/ ("2-letter keywords: Language codes have priority") vs. /docs/shortcuts/namespaces/

Problem: The content policy states: "A keyword with 2 letters shall be used for a dictionary of that language, using its ISO-639-1 language code (e.g. en, fr, be) … If the shortcut is not about a dictionary, then it should not use a ISO-639-1 language code." But the namespaces page's own example for the language namespace type is "Merriam-Webster dictionary: en.mw tree (from en)" — mw is a 2-letter keyword inside the en namespace pointing to Merriam-Webster, which is a dictionary but mw is not an ISO-639-1 code (and Merriam-Webster's own namespace would be 3 letters under the dictionary rule).

Consequence: Editors trying to follow the policy cannot tell whether the canonical example is conformant or whether the policy is aspirational. The policy itself admits "many curated shortcuts at this moment don't match the listed criteria" — but the docs should not actively use the worst-case examples to teach the schema.

The fix: Either swap the namespaces page example for one that is policy-conformant (e.g., a 3-letter dictionary keyword), or add a note on the policy page explicitly grandfathering keywords like mw and clarifying that the 2-letter rule applies only to new shortcuts.

7. Deprecated-shortcut example uses a placeholder name not introduced anywhere else (minor)

Location: /docs/shortcuts/deprecated/

Problem: The example shortcut url is http://www.example.com/?q=<query>, but the canonical short-notation example on /docs/shortcuts/ uses <param1> for the first positional argument: examplekeyword 1: http://www.example.com/?q=<param1>. The deprecated page also uses <1> inside the alternative.query field, a third spelling of the same idea.

Consequence: Three different placeholder names (<query>, <param1>, <1>) appear across docs for what may or may not be the same thing. A reader cannot tell whether <query>, <param1>, and <1> are aliases, distinct features, or context-dependent. If they are not interchangeable, copy-pasted examples break silently.

The fix: Add a single "placeholder names" section to /docs/shortcuts/url/ that enumerates <query>, <param1>, <param2>, ..., <1>, <2>, ... and <$variable>, says exactly where each is valid, and use one consistent style across pages.

8. Developer page never states the actual Node version, lacks any test/lint/troubleshooting docs (significant)

Location: /docs/developers/

Problem: The Prerequisites section says "NodeJS version as stated here (node-version:)" with a link to .nvmrc. The actual version number is never written in the docs. There is no documentation of npm test, lint commands, the test harness for shortcuts (the docs elsewhere claim "Tests are run regularly in the background"), env vars, or what to do when npm run build fails. The "Code documentation" section just says "An auto-created documentation of the code by JSDoc is also available" with no link or path.

Consequence: A new contributor running npm clean-install on the wrong Node major version gets cryptic native-module errors and has nothing in the docs to diagnose them. AI agents asked to "set up a Trovu dev environment" cannot pin the Node version without an additional GitHub fetch. The shortcut test infrastructure — arguably the most distinctive part of Trovu's data model — has no developer-facing entry point.

The fix: Inline the current Node version in the Prerequisites section (with a note that .nvmrc is the source of truth). Add sections for: running tests, running lint, the npm run script catalog, where the JSDoc output is hosted, and a "common build failures" appendix. Link to the JSDoc URL.

9. Support page has no GitHub Issues link for an open-source project (minor)

Location: /docs/users/support/

Problem: The Support page lists only Telegram and email as channels: "Ask any Trovu-related question in the Telegram group … Or send an email: info@trovu.net". The repo (github.com/trovu/trovu) is the project's source of truth, but the support page never points users at GitHub Issues for bug reports or feature requests.

Consequence: Bugs that should become tracked issues end up in a Telegram chat or in info@trovu.net and never become public, searchable, or actionable. New contributors looking for "good first issue" labels never get there from the docs.

The fix: Add a "Report a bug" entry pointing at https://github.com/trovu/trovu/issues, and make clear which channel is for which kind of question (chat = how-to, email = private, issues = bugs/features).

10. /docs/alternatives/ lists only Yubnub; omits the comparison the README itself makes (minor)

Location: /docs/alternatives/

Problem: The Alternatives page lists exactly one alternative — Yubnub — yet the GitHub README's tagline is literally "It's like DuckDuckGo bangs, but on steroids." DuckDuckGo bangs are not mentioned anywhere on the alternatives page. Kagi quick-bangs and browser-native custom search engines (which the integration page itself shows are first-class config targets) are also missing.

Consequence: The page that should help a developer decide whether Trovu is the right tool fails to address the most obvious comparison the project makes about itself. Search engines and AI agents asked "trovu vs duckduckgo bangs" find no first-party answer.

The fix: Add at minimum a DuckDuckGo bangs comparison (privacy model, custom shortcuts, multi-arg/typed args). Mention browser-native custom search engines and Kagi bangs. Sync the README's "DuckDuckGo bangs but on steroids" framing into this page.

11. Presentations page is three bare list items with no descriptions or working context (minor)

Location: /docs/presentations/

Problem: The whole page contents: "FOSSASIA: pdf / Polyglot Gathering / BHNT". No dates, no descriptions, no abstracts, no transcripts; "BHNT" is not even expanded.

Consequence: A page in the docs nav that contributes nothing and looks abandoned. Worse, this is the page a journalist or sponsor lands on when looking for prior talks.

The fix: Either delete the page from the docs nav or add a one-line description and date for each item, with the venue name expanded.

12. No machine-readable schema for config.yml or shortcuts.yml (significant)

Location: /docs/users/advanced/, /docs/shortcuts/, /docs/shortcuts/url/, /docs/shortcuts/include/

Problem: Trovu's entire user/editor surface is "edit a YAML file." The docs describe the schema in prose across at least four pages (advanced settings, shortcuts, url placeholders, include), and as findings #4 and #7 demonstrate, the prose drifts. There is no JSON Schema, no yaml-language-server modeline reference, no example with a # yaml-language-server: $schema=... line, and no link to a published schema URL.

Consequence: Editors get no IDE validation, agents have no formal contract to generate against, and contradictions like the examples: shape (finding #4) never get caught at edit time. A JSON Schema would also let GitHub Actions reject malformed PRs to /data/.

The fix: Publish a JSON Schema for config.yml and for shortcuts.yml (including the url, include, deprecated, examples, tests, tags sub-schemas). Reference it in the docs and in the YAML files themselves via the # yaml-language-server: $schema= modeline so editors get validation for free.

What they do well

• Privacy page is honest and concrete. It walks through query processing step-by-step (keyword parse → namespace lookup → placeholder substitution → redirect) — most products promise privacy without showing the mechanics.
• The namespace concept is well-taught. The /docs/shortcuts/namespaces/ table cleanly maps namespace types to ISO codes, even if the example choice (finding #6) is unfortunate.
• Include semantics are explained with a real, non-trivial example (the Arabic dictionary fallback chain through ard → dcm → bab → ...), which is the kind of example most docs hand-wave.

Top 3 recommendations

1. Fix the data-domain contradiction (finding #3) and the migration page rot (finding #1) — both are visible to anyone landing from search and they are cheap to fix.
2. Publish a JSON Schema for the YAML files and add an llms.txt (findings #2, #4, #12). One file unlocks IDE validation for editors and structured discovery for AI agents simultaneously.
3. Reconcile the schema docs across /docs/shortcuts/, /docs/shortcuts/include/, /docs/shortcuts/url/, and /docs/editors/policy/ so examples:, placeholder names, and the 2-letter-keyword rule mean exactly one thing each (findings #4, #6, #7).