Intuned

Intuned Documentation Audit

The docs are well-structured with an llms.txt sitemap and an OpenAPI-backed API reference, but a cluster of contradictions across pricing, configuration filenames, auth-session naming, and stub reference pages will cause agents and developers to copy code and facts that don't hold up.

1. Signup AI credit contradicts itself: $10 vs $5 (critical)

Location: /docs/main/05-references/plans-and-billing.md and /docs/main/02-features/usage-pricing-monitoring-alerting.md

Problem: The Plans and Billing reference page states: "Eligible accounts receive a one-time $10 AI credit at signup." The comparison table on the same page reinforces this with "Monthly AI credit … Free Plan … $10 (one-time credit)*". But the Usage and billing page states: "Eligible accounts receive a one-time $5 AI credit at signup to explore Agent and SDK features."

Consequence: Two canonical pricing references disagree on the free-tier credit by 2x. Developers evaluating Intuned will trust whichever page they hit first, and an LLM agent answering "how much free AI credit do I get?" will return either answer depending on which page got indexed. This is the worst kind of contradiction — it's in two authoritative reference pages, not a stale blog post.

The fix: Pick the correct value, update both pages, and ideally introduce a single canonical fragment for pricing numbers (e.g., a shared snippet) so the two pages can't drift again.

2. AuthSession parameter has three different casings across the same product surface (critical)

Location: /docs/main/02-features/jobs-batched-executions.md, /docs/main/02-features/runs-single-executions.md, /docs/main/05-references/cli/dev.md

Problem: The same concept is named three different ways in three places:

• Runs API (TypeScript/Python SDK and REST): authSession (camelCase) — confirmed in the Runs single-executions page and the OpenAPI spec.
• Jobs API/CLI: auth_session (snake_case) — the docs even add a Note: "Jobs use auth_session (snake_case) in all languages and the CLI. This is different from runs, which use authSession (camelCase)."
• intuned dev run api CLI flag: --auth-session (kebab-case).

Consequence: This is documented as a deliberate design choice, but documenting an inconsistency doesn't make it less harmful. AI coding agents are particularly vulnerable here — they will confidently transpose a working Runs example into a Jobs call and silently fail, or vice versa. A human reader can reread the note; an agent that has loaded only the Runs page will hallucinate authSession into a Jobs payload and the API will reject it.

The fix: Pick one casing across the surface and migrate. If backward compatibility forces both to stay, accept both spellings server-side (alias authSession to auth_session) and document one canonical form everywhere. At minimum, put a structured "parameter name by surface" table at the top of both Jobs and Runs pages so agents can find it without prose-parsing.

3. Config filename has three spellings across docs (significant)

Location: /docs/main/05-references/intuned-json.md, /docs/main/02-features/local-development-cli.md, /docs/main/02-features/stealth-mode-captcha-solving-proxies.md

Problem: The reference page is titled "Intuned.json" and exclusively refers to Intuned.json. The Local development page shows the scaffolded project structure containing Intuned.jsonc (Intuned settings file) and calls it "Intuned settings file (Intuned.jsonc)". The Stealth/CAPTCHA/Proxy page tells users to "Add the headful key to your intuned.json" — lowercase. The CLI page mentions support for .json, .jsonc, .yaml/.yml, and .toml, but the reference page for the config file documents none of these alternatives.

Consequence: A developer following the local quickstart gets Intuned.jsonc, then clicks through to the reference page and sees only Intuned.json — is .jsonc deprecated? Supported? An LLM agent generating setup instructions will pick whichever spelling appears closest in its context window. Lowercase intuned.json will fail on case-sensitive filesystems if the actual file is capitalized.

The fix: Standardize on one canonical filename (likely Intuned.json with .jsonc as a supported variant). Update the reference page to enumerate every supported extension (.json, .jsonc, .yaml, .yml, .toml) since the CLI page already promises these. Replace intuned.json with the canonical capitalization everywhere.

4. Runtime SDK reference pages for extendTimeout / extend_timeout are stubs (critical)

Location: /docs/main/05-references/runtime-sdk-typescript/extend-timeout.md and /docs/main/05-references/runtime-sdk-python/extend-timeout.md

Problem: The "Extend API timeout" recipe centers on calling extendTimeout() (TypeScript) and extend_timeout() (Python), and links readers to the SDK reference pages for these functions as the authoritative source. Those reference pages, as published, contain only the function name as a heading — no signature, no parameters, no return type, no constraints, no examples, no notes about which execution contexts (Run vs. Job) the function applies to.

Consequence: The recipe asserts behavior — "Each call resets the countdown to the original requestTimeout value … up to a 6-hour maximum total duration per Run" — but the reference pages it links to don't confirm or refute any of it. A developer or agent following the link from the recipe lands on an empty page and has no way to verify the recipe's claims, learn the function signature, or discover edge cases. For a function the docs themselves describe as central to running long automations, shipping reference pages this thin is a contract failure.

The fix: Flesh out both SDK reference pages with the full function signature, parameters, return type, the 6-hour cap and per-attempt timer behavior, examples mirroring the recipe, and an explicit "Works in: Runs / Jobs / Both" callout so the constraint is structured rather than implied.

5. Duplicate error code definitions in the canonical error reference (significant)

Location: /docs/main/05-references/error-codes.md

Problem: The error reference defines insufficient-resource-credits twice with different descriptions:

• "Insufficient resource-specific credits available for the operation."
• "Insufficient resource credits to execute the job run."

Consequence: Error codes are a contract. An agent or SDK consumer building a retry/alert routing rule keyed on code === "insufficient-resource-credits" cannot tell from the docs whether the two cases are the same error or whether one is a duplicate that will be removed. The page explicitly bills these codes as "Stable, machine-readable error identifier[s]" — duplication breaks that contract.

The fix: Remove the duplicate, or if both meanings genuinely exist, rename one to a distinct code (e.g., insufficient-job-run-credits). Add a CI lint over error-codes.md to fail on duplicate ### headings.

6. Intra-doc links inconsistently include the main prefix — broken navigation (significant)

Location: /docs/main/00-getting-started/quickstarts/scraper.md, /docs/main/00-getting-started/quickstarts/rpa.md, /docs/client-apis/overview.md, /docs/main/05-references/error-codes.md

Problem: Multiple prominent intra-doc links omit the main segment that actual URLs require, while other pages use the prefixed form for the same target:

• Scraper quickstart links to /docs/00-getting-started/quickstarts/intuned-agent (actual path lives under /docs/main/00-getting-started/...).
• RPA quickstart links to /docs/00-getting-started/quickstarts/build-an-rpa-with-intuned-agent.
• Client APIs overview links to /docs/03-how-to/manage/manage-workspace#how-to-get-your-workspace-id, /docs/03-how-to/manage/manage-api-keys, and /docs/06-resources/help-and-support — all missing the main prefix.
• Meanwhile, the error reference links to the same Help & Support page via /main/06-resources/help-and-support — the same target rendered two different ways across the site.

Consequence: The "if you'd rather skip the manual steps, see the Agent quickstart" link in the very first quickstart a new developer reads is broken. The API overview's "Manage API keys" CTA — the single most important link for a first-time API caller — is broken. The inconsistency also implies that further links across the rest of the docs likely drift in both directions.

The fix: Audit all /docs/... internal links and rewrite them to a single canonical form. Add a build-time link checker (most Mintlify-style docs have one available) so broken intra-doc links fail CI.

7. Sink terminology drifts between "AWS S3 Sink" and "S3-compatible" (significant)

Location: /docs/llms.txt, /docs/client-apis/api-reference/sinks/s3.md, /docs/client-apis/api-reference/sinks/overview.md

Problem: The llms.txt sitemap and the per-page title call this feature "AWS S3 Sink." The sinks overview page describes the same feature as an "S3-compatible storage" sink and lists Cloudflare R2, Tigris, Supabase Storage, and AWS S3 as supported destinations. The sink retry reference also uses "S3-Compatible Sinks."

Consequence: A developer searching the sitemap or scanning section titles will reasonably assume the integration is AWS-only and rule it out for R2/Tigris/Supabase workloads. An agent answering "does Intuned support Cloudflare R2?" hitting only the llms.txt entry will say no; hitting the overview will say yes. The discrepancy is exactly the kind of agent-hostile terminology drift the platform should avoid.

The fix: Rename the page/title and llms.txt entry to "S3-compatible Sink" to match the overview. If "AWS S3" needs to stay for SEO, keep it as a sub-heading or alias on the page, not as the canonical title.

8. Retry timeline table rows are out of order (minor)

Location: /docs/main/05-references/sink-retry-behavior.md

Problem: In the "Retry Timeline Example" table, attempt 8 (8m 30s) is listed before attempt 7 (6m 30s):

| 6 (+2m)     | 4m 30s | ✓ | ✓ |
| 8 (+2m)     | 8m 30s | ✓ | ✓ |
| 7 (+2m)     | 6m 30s | ✓ | ✓ |
| 9 (+2m)     | 10m 30s | ✓ | Stops (10m limit) |

Consequence: A developer scanning the table to estimate when their webhook will stop retrying will misread the cadence. Worse, an agent extracting this as structured data for a retry visualizer or code-generated retry behavior will emit nonsense — attempt 8 cannot precede attempt 7.

The fix: Swap rows 7 and 8 to restore ascending order.

9. Typos and broken capitalization in the error reference (minor)

Location: /docs/main/05-references/error-codes.md

Problem: The reference contains visible defects:

• script-execution-exception: "this usually happen when the automation throw an un-handled exception." (lowercase sentence start, subject/verb agreement, hyphenation).
• script-no-valid-output-received: "the automation returned an invalid output.t" (stray "t" appended).
• Section heading "Billing Related error codes" is inconsistently cased vs. neighbors like "Script Execution Error Codes" and "Server Error Codes".

Consequence: These are on the page developers reach when something is on fire in production. The typos look unmaintained and undermine trust in the rest of the contract on the page (which, as Issue 5 shows, is in fact unmaintained).

The fix: Copy-edit pass; standardize heading casing across the file.

10. Agent FAQ ships a "coming soon" feature without a date or tracking link (minor)

Location: /docs/main/02-intuned-agent/overview.md

Problem: The FAQ answers "Does the agent support CLAUDE.md and custom skills?" with: "Not yet, but coming soon. The agent will load your project's CLAUDE.md and custom skills…" — with no target date, no changelog/roadmap link, and no way to subscribe.

Consequence: "Coming soon" without a commitment is a smell that compounds over time — six months from now, this answer will read as abandoned. Developers evaluating the agent against alternatives need to know whether to wait or move on.

The fix: Either link to a public roadmap/changelog entry with a quarter target, or remove the answer entirely and replace it with "Not currently supported — [request it here]".

11. BYOK link inside the BYOK section is self-referential (minor)

Location: /docs/main/05-references/plans-and-billing.md and /docs/main/02-features/usage-pricing-monitoring-alerting.md

Problem: Both pages include the sentence "If your account is not eligible, you can bring your own API key to use AI features without interruption." On the Usage page, that link points back to a section on the same page; the Plans page links to the same anchor rather than to its own BYOK guidance.

Consequence: Users following the prompt land on the section they just bounced off of, with no additional setup guidance. The actual configuration entry point (app.intuned.io/settings/own-keys) is mentioned elsewhere on the page but is not what the inline CTA links to.

The fix: Point the inline link to a setup-oriented destination — either the app.intuned.io/settings/own-keys URL or a dedicated BYOK how-to — not back to the section the reader is already inside.

What they do well

• llms.txt exists and looks complete — agents have a discoverable sitemap covering the SDKs, REST API reference, features, and recipes.
• OpenAPI-backed REST reference — endpoints like Run/Job/AuthSession create/get/delete are machine-readable, not buried prose.
• Explicit casing/contract notes when contradictions exist — the team is at least aware of the authSession vs auth_session split and calls it out inline; the fix is to resolve the split, not just to document it.

Top 3 recommendations

1. Resolve the AuthSession casing split (Issue 2) and flesh out the runtime SDK reference stubs (Issue 4) — these are the two findings most likely to cause an agent to emit broken code or copy unverified claims from a recipe.
2. Fix the $5/$10 free-credit contradiction (Issue 1) and audit for other duplicated pricing facts across the Plans page and the Usage page — introduce a single source of truth for numbers.
3. Add a CI link checker and a duplicate-heading lint to catch the /docs/... vs /docs/main/... drift (Issue 6) and duplicate error-code definitions (Issue 5) at build time, not in audits.