Ren Documentation Audit

Ren's docs are well-structured (Diátaxis-style tutorials/guides/deep-dives/reference, static HTML, llms.txt + llms-full.txt, an OpenAPI-backed Scalar reference), but the surface hides real contradictions: the pricing page sells a feature the docs declare unavailable, the same scope word means three different things on three pages, the SDK README and SDK docs disagree on resource names, and the agent-facing "append .md" affordance 404s as documented.

1. Pricing sells webhook triggers; the docs say they don't exist; the API ships them (critical)

Location: https://useren.ai/docs/guides/automate/trigger-from-webhook/ vs https://useren.ai/pricing/ vs https://useren.ai/openapi.public.json

Problem: The webhook guide's entire body is a stub: "Coming soon — Webhook triggers are not yet available… Watch the changelog for updates." Meanwhile the pricing page lists "Webhook triggers | 3 active | Unlimited | Flexible" as a quantified feature of the $100 Pro and $200 Max plans, and the live OpenAPI spec (version 0.1.23) exposes /api/webhook-triggers (POST/GET), /api/webhook-triggers/{triggerId} (GET/PATCH), and /api/webhook-triggers/{triggerId}/archive (POST).

Consequence: A team buying Pro specifically for the advertised "3 active webhook triggers" hits a docs page that says the feature doesn't exist; a developer who finds the endpoints in the spec has zero documentation on payload shape, auth, or firing semantics. Humans get confused; agents reading llms-full.txt will confidently report the feature as unavailable even though the API serves it.

The fix: Pick one truth. If webhook triggers are live, replace the stub with a real guide covering the three endpoints; if they aren't, remove or footnote the pricing row and mark the endpoints as beta/hidden in the public spec.

2. "Private" scope is defined three contradictory ways, including who the default is (significant)

Location: https://useren.ai/docs/guides/build-and-run/create-a-skill/ vs https://useren.ai/docs/deep-dives/concepts/sharing/scopes/ vs https://useren.ai/docs/deep-dives/concepts/agents/skills/

Problem: The Create-a-skill guide says: "Skill scope determines visibility: private (default, only your org), org (all org members), or public." The Scopes concept page says the opposite on both axes: "Private: belongs to one user. Only that user can see or use it… Org: … This is the default." The Skills concept page agrees with Scopes ("private (just you), org (your organization)"), leaving the guide contradicting both its siblings.

Consequence: This is an access-control primitive. A developer following the guide believes a freshly created skill is already visible to the whole org ("private … only your org") — or believes the default is private when it's actually org — and either over-shares or can't explain why teammates see (or don't see) a resource. Agents parsing the two pages extract mutually exclusive facts about the same enum.

The fix: Correct the Create-a-skill guide to match the Scopes page: private = single user, org = organization-wide and the default. Audit other guides for the same copy.

3. SDK docs and the SDK's own GitHub README disagree on resource groups (significant)

Location: https://useren.ai/docs/developers/typescript-client/ vs https://github.com/renai-labs/sdk README

Problem: The docs list the client's resource groups as including client.trigger and client.blueprint. The README for the same package (@renai-labs/sdk, latest 0.1.24 on npm) instead lists client.routines and includes neither client.trigger nor client.blueprint. The README's quick start also uses the placeholder base URL https://api.ren.example where the docs use the real https://api.useren.ai, with no note that it's a placeholder.

Consequence: routines appears nowhere in the documentation site, and trigger/blueprint appear nowhere in the README — a developer (or coding agent) starting from GitHub writes client.routines.* calls against a client that may not expose them, and copy-pasting the README quick start sends requests to a non-existent host. Silent divergence between generated SDK surface and its two descriptions means at least one is stale.

The fix: Regenerate the README from the same source as the docs page (or vice versa), name the real resource groups in both, and use the actual API base URL in every example.

4. The documented "append .md to any docs URL" pattern returns 404 (significant)

Location: https://useren.ai/docs/developers/llms-txt/

Problem: The page — explicitly written for feeding docs to agents — instructs: "For a single page, append .md to any docs URL … to get just that page's Markdown." Tested: https://useren.ai/docs/tutorials/quickstart.md → 404, …/quickstart/.md → 404, …/developers/cli.md → 404. The pattern that actually works (and that the pages' own "Open Markdown" button uses) is a /raw/ prefix: https://useren.ai/raw/docs/tutorials/quickstart.md → 200.

Consequence: The one page whose whole job is telling machines how to fetch machine-readable docs gives a fetch recipe that fails on every URL. Agents follow instructions literally: they'll try .md, get 404s, and fall back to scraping HTML or give up — precisely the failure llms.txt exists to prevent.

The fix: Document the real pattern (/raw/docs/<path>.md) or add a rewrite so appending .md actually works as written.

5. Quickstart promises Homebrew and manual-binary installs that are documented nowhere (significant)

Location: https://useren.ai/docs/tutorials/quickstart/ (step 1) → https://useren.ai/docs/developers/cli/

Problem: The quickstart says "For full install options (including Homebrew and manual binary), see Install the CLI," linking to the CLI reference. That page's Install section offers exactly two tabs — "npm" and "npx (no install)" — and contains no mention of Homebrew or a binary anywhere (grep for homebrew/brew/binary: 0 matches).

Consequence: Developers who don't want a global npm install (common on locked-down machines, or for Homebrew-first Mac users) chase a link to install options that don't exist, and are left guessing whether the methods were removed, are unreleased, or live on some other page.

The fix: Either add the Homebrew/binary instructions to the CLI page or delete the claim from the quickstart until they ship.

6. A tutorial's first step is "install the Ren plugin" — with no plugin name, package, or link (significant)

Location: https://useren.ai/docs/tutorials/give-agent-access-to-ren/

Problem: Step 1 reads, in full: "Install the Ren plugin into your coding agent… Install the Ren plugin for your coding agent." There is no package name, no install command, no marketplace link, and no per-agent instructions (the page names Claude Code as an example but never says how to install anything into it). Step 2 ("Deploy your agent stack to Ren") is likewise three prose bullets with no commands, on a site where every other guide shows exact CLI invocations.

Consequence: The tutorial is not completable as written. A reader reaches the first actionable step and has to leave the docs to search for an unnamed artifact; an agent asked to follow the tutorial has literally nothing to execute.

The fix: Name the plugin, show the install command per supported client (Claude Code, Codex, opencode, Hermes — the tabs already exist on Run an agent), and give step 2 concrete CLI commands.

7. Changelog has zero entries, yet two stub pages point readers at it (significant)

Location: https://useren.ai/docs/developers/changelog/

Problem: The complete changelog is one "Unreleased" bullet about the docs themselves ("Notable, user-facing changes to Ren. Maintained manually; newest first. ## Unreleased …"). Meanwhile the webhook-trigger stub and the Gangprompting stub both instruct: "Watch the changelog for updates" — and the API is already at version 0.1.23 with 203 paths, the CLI at 0.2.6, the SDK at 0.1.24.

Consequence: The only mechanism the docs offer for learning when missing features ship is empty. Developers watching it will never see the webhook or multi-agent announcements arrive; nobody can tell what changed between CLI 0.x releases or API spec versions.

The fix: Backfill dated entries keyed to CLI/SDK/API versions, or wire the changelog to the release pipeline; until then, stop pointing stub pages at it.

8. The waiting session status means something different on each of three pages (minor)

Location: https://useren.ai/docs/deep-dives/concepts/agents/sessions/ vs https://useren.ai/docs/guides/build-and-run/run-an-agent/ vs https://useren.ai/docs/deep-dives/how-ren-works/

Problem: Sessions concept: "waiting | An agent has paused and needs human input to continue." Run an agent: "waiting (agent needs a permission decision)." How Ren works: "waiting (the agent needs your approval or input)." One says any input, one says specifically a permission approval, one hedges both.

Consequence: Code that polls GET /api/sessions/{id} and branches on waiting needs to know whether the correct response is "send a message" or "resolve a permission request" — the docs give three answers. Automations built from the run-an-agent definition will mishandle sessions that are merely waiting on a question.

The fix: Define waiting once (enumerating what can cause it) in the sessions reference and link the other two pages to it.

9. Two competing CLI command families for browsing the registry (minor)

Location: https://useren.ai/docs/deep-dives/concepts/sharing/registry/ vs https://useren.ai/docs/developers/cli/ and https://useren.ai/docs/deep-dives/concepts/agents/skills/

Problem: The Registry page browses with ren registry agents list, ren registry skills list, ren registry mcps list. The CLI reference and Skills page do the same job with ren agents list --published, ren skills list --published, and ren mcps search. No page mentions the other form or says whether both work.

Consequence: Developers and agents can't tell which is canonical; if one family is stale, copied commands fail with unknown-command errors in scripts and CI.

The fix: Standardize on one command family in the CLI reference and update the concept pages to match (or explicitly document the alias).

10. ren skills create shown with incompatible argument shapes on sibling pages (minor)

Location: https://useren.ai/docs/deep-dives/concepts/agents/skills/ vs https://useren.ai/docs/guides/build-and-run/create-a-skill/

Problem: The Skills concept page creates a skill from a folder: ren skills create ./my-skill --name "My skill" # upload a folder containing SKILL.md. The Create-a-skill guide creates it bare (ren skills create --name "summarize-commits") and uploads the folder only later via ren skills versions create … --archive ./skill-folder/. The two pages also split on frontmatter conventions: the concept page lists hyphen-case allowed-tools while the guide's example uses camelCase requiredCredentials — a field the concept page's frontmatter list omits entirely.

Consequence: One of the two create invocations is presumably wrong or outdated; a copied command either errors on an unexpected positional argument or silently creates a skill with no version. Mixed key conventions make hand-authored SKILL.md files a guessing game.

The fix: Show the single correct ren skills create signature on both pages, and document the full SKILL.md frontmatter schema (with casing) in one canonical place.

11. Public OpenAPI spec declares no server URL (minor)

Location: https://useren.ai/openapi.public.json (rendered at https://useren.ai/docs/developers/api/)

Problem: The 1.3 MB spec (OpenAPI 3.1.1, "Ren API" 0.1.23, 203 paths) contains no servers entry. The base URL https://api.useren.ai is only discoverable in prose on the CLI page and in one SDK snippet.

Consequence: Tooling that consumes the spec directly — codegen, Postman import, agents constructing requests from the Scalar reference — has no host to send requests to; every path like /api/sessions is unrooted.

The fix: Add "servers": [{"url": "https://api.useren.ai"}] to the published spec.

What they do well

• First-class machine readability: static HTML, llms.txt/llms-small.txt/llms-full.txt on every build, and a real 203-path OpenAPI spec behind the reference.
• Guides consistently show UI + CLI + API + TypeScript tabs with concrete, ID-annotated commands (skl_abc123, prj_def456), and honest "Current state" caveats (Environments).
• Security-relevant behavior is unusually well specified: config file modes (0600/0700), PAT format and scope groups, vault credential types, and permission precedence (deny beats ask beats allow).

Top 3 recommendations

1. Reconcile feature truth across pricing, docs, and the API spec — starting with webhook triggers — so no surface sells or denies a feature the others contradict.
2. Fix the access-control contradictions first (scope defaults and meanings, waiting semantics): they're small edits with outsized blast radius for both humans and agents.
3. Make the agent-facing plumbing actually work as documented: correct the .md fetch pattern, add servers to the OpenAPI spec, and regenerate the SDK README from the same source as the SDK docs.