Town Documentation Audit

Town's docs (~45 pages under /docs) are polished, user-friendly prose with a real webhook reference and admin guides — but they contradict themselves on the product's central trust claim, ship the only API example with an unusable placeholder URL, have zero machine-readable surface for AI agents, document tool tables for only 7 of the 40+ integrations they list, and reference a programmatic routine-management API that is documented nowhere.

1. Safety FAQ flatly contradicts the documented autonomy modes (critical)

Location: /docs/safety vs /docs/safety/modes-approvals and /docs/how-it-works

Problem: The Trust & Security page answers "Will Town email, schedule meetings, or message people without my permission?" with "No — never. Town will not send any email, message, or calendar invite, or schedule any event, without your express permission. It always asks first and waits for your go-ahead before anything goes out... nothing is ever sent or scheduled until you review and approve it." Meanwhile /docs/safety/modes-approvals documents an "Allow all actions" session setting ("Full autonomous mode for this session. No approvals required for any action.") and an Autonomous routine mode where "Actions that make changes also run immediately" with "No approval requests sent." /docs/how-it-works confirms: "Autonomous — Actions execute immediately without asking."

Consequence: This is the product's core trust promise, and it is false as written. A user (or a compliance reviewer, or an AI agent summarizing the docs) reading /docs/safety concludes nothing is ever sent without approval; the modes reference says the opposite. Agents parsing both pages get an unresolvable contradiction on the highest-stakes behavior in the product.

The fix: Rewrite the safety FAQ answer to state the actual default ("Ask before any changes") and explicitly note that users can opt into autonomous modes where actions execute without per-action approval, linking to Modes & Approvals for the precise rules.

2. The only HTTP API example uses a placeholder base URL that is never defined (critical)

Location: /docs/routines/webhooks

Problem: The webhook trigger page — the only HTTP-API-style reference in the entire docs — gives a curl example against https://your-town-url/workflow-webhooks/whk_.... No page anywhere states what the actual webhook host is, whether it's a per-account subdomain, api.town.com, or something copied from the routine settings UI.

Consequence: The one endpoint developers are invited to call cannot be called as documented. A developer (or coding agent) copying the example must guess the host; the documented behavior of returning the same 404 for "unknown endpoint, disabled endpoint, or invalid secret" means every wrong guess is indistinguishable from a bad token, making the failure mode undiagnosable.

The fix: State the real base URL (or explicitly say "copy the full webhook URL from the routine's settings page — it includes the host") directly above the curl example, and use a realistic host in the example.

3. llms.txt and sitemap probes soft-200 with homepage HTML — and no machine-readable docs index exists at all (critical)

Location: https://town.com/llms.txt, /llms-full.txt, /sitemap.xml, /docs/llms.txt, /docs/sitemap.xml

Problem: /llms.txt, /llms-full.txt, and /sitemap.xml all return HTTP 200 but serve the marketing homepage HTML (a ~40 KB Next.js page) — a tool requesting the docs index gets a 200 "success" stuffed with the wrong content instead of a clean 404. The /docs/llms.txt, /docs/llms-full.txt, and /docs/sitemap.xml variants return 404. There is no machine-readable index of the docs of any kind, and no OpenAPI spec (api.town.com/openapi.json is 404).

Consequence: The soft-200 responses actively mislead: a crawler or agent requesting llms.txt may cache 40 KB of homepage HTML as if it were the docs index rather than falling back to crawling. And with no llms.txt, sitemap, or spec anywhere, AI coding agents and crawlers cannot efficiently discover or index the docs at all.

The fix: Serve a real llms.txt (and ideally llms-full.txt) enumerating the ~45 docs pages, add a sitemap covering /docs, and return proper 404s for paths that don't exist instead of rewriting them to the homepage.

4. Dead /docs/features link baked into the sidebar of every docs page (significant)

Location: Every page under /docs (sidebar/prefetch link set)

Problem: The rendered HTML of every docs page includes href="/docs/features", which returns 404 — while its child pages (/docs/features/tasks, /docs/features/routines, /docs/features/profiles, /docs/features/recordings) and sibling section indexes (/docs/admin-setup, /docs/using-town) all return 200.

Consequence: Every reader who clicks the "Features" section header hits a 404 from anywhere in the docs. Crawlers and agents following sidebar links hit the same dead end on every single page, and link-checking tools will flag the entire site.

The fix: Add an index page at /docs/features (matching /docs/admin-setup and /docs/using-town) or make the sidebar section header non-clickable.

5. The docs overview page's HTML links to api.town.com, which serves only a bare Convex banner (significant)

Location: /docs (overview page HTML) → https://api.town.com

Problem: The raw HTML of the docs overview page contains an outbound link to https://api.town.com, which returns only: "This Convex deployment is running. See https://docs.convex.dev/." No documentation, and /docs, /openapi.json, /openapi.yaml, /v1, and /swagger on that host all 404.

Consequence: Anyone who follows the link — including crawlers and agents extracting hrefs from the page — expecting an API lands on an infrastructure banner that points them to a third party's docs (Convex). It also leaks the backend platform while providing zero value — there is no public REST API reference anywhere in Town's docs to back the link up.

The fix: Remove the api.town.com link from the docs page's HTML, or stand up an actual API landing page there. If a public API exists, document it; if not, don't link the host.

6. Three different trigger lists that don't agree (significant)

Location: /docs/how-it-works, /docs/custom-routines/manual, /docs/custom-routines/triggers

Problem: The trigger reference at /docs/custom-routines/triggers documents Outgoing email, Calendar RSVP, Calendar changed, and Webhook triggers. The trigger table on /docs/how-it-works omits all four. The manual-configuration page (/docs/custom-routines/manual) omits Outgoing email and Webhook, and collapses Calendar RSVP/Calendar changed into a single "Calendar events" entry.

Consequence: A developer deciding whether Town can react to sent mail or an external webhook — reading the overview or the manual-config page — concludes those triggers don't exist. An agent asked "what triggers does Town support?" gives different answers depending on which page it retrieved.

The fix: Make /docs/custom-routines/triggers the single source of truth and have the other two pages either show the complete list or explicitly link to it as the canonical reference.

7. "Connect multiple Slacks" vs "One Slack workspace per account" (significant)

Location: /docs/integrations vs /docs/integrations/slack

Problem: The integrations overview says: "If you've got more than one account for the same tool — say you're a consultant working across multiple client Slacks — you can connect them all and name each one." The Slack integration page's Limitations section says: "Single workspace — One Slack workspace per account."

Consequence: The overview's own worked example (multiple client Slacks) is exactly the case the Slack page rules out. A consultant evaluating Town on this basis buys into a capability the product's own reference says doesn't exist.

The fix: Determine which is true; either scope the overview's multi-account claim to tools where it holds (e.g., Gmail accounts), or update the Slack limitation.

8. Is Google required or not? Getting-started, the Google page, and the Entra guide disagree (significant)

Location: /docs/integrations/google vs /docs/getting-started vs /docs/admin-setup/microsoft-entra

Problem: /docs/integrations/google states Google "is required for your assistant to function." /docs/getting-started says "link your Google or Outlook account and Gmail, Calendar, and Drive all connect in one step." A full Microsoft Entra admin-consent guide exists at /docs/admin-setup/microsoft-entra — yet there is no Outlook/Microsoft 365 integration page under /docs/integrations at all.

Consequence: A Microsoft-shop admin can complete the entire Entra setup guide and still not know whether their users can actually use Town without a Google account, because one page says Google is mandatory and no page documents what the Microsoft integration covers.

The fix: Reconcile the requirement statement, and add a Microsoft/Outlook integration page documenting exactly what connects (mail, calendar, files) and what, if anything, still requires Google.

9. MCP servers page documents no authentication, no transports, and no setup location (significant)

Location: /docs/integrations/mcp-servers

Problem: The Custom Integrations (MCP) page walks through "Add a server" (Name, URL, Description) and "Enable for a routine," but never says where in the product to add a server — there is no navigation path. It says nothing about authentication (tokens, OAuth, headers), nothing about supported transports (SSE vs. HTTP), and nothing about whether local servers are supported or only remote URLs.

Consequence: MCP pipes third-party tools into an assistant that already has email and calendar access, and the page for it omits the entire security surface. A developer with a token-protected MCP server cannot tell from the docs whether Town can connect to it at all, and can't even find the screen to try.

The fix: Document the navigation path to the MCP settings, the supported transports, whether local servers work, and — above all — how authentication is configured (or state explicitly that only unauthenticated servers are supported).

10. Tools reference covers only 7 of the "over 40" integrations (significant)

Location: /docs/custom-routines/tools vs /docs/integrations (integration directory)

Problem: The integrations directory says "Town connects to over 40 tools" and lists them by category — Airtable, Salesforce, Jira, Supabase, Monday.com, QuickBooks, Xero, and dozens more. But integration tool tables exist only for GitHub, Slack, Linear, Notion, HubSpot, Dropbox, and Asana. The remaining 33+ listed integrations have zero tool documentation.

Consequence: Users can't know what enabling those integrations actually lets the assistant do — which actions it can take in their Salesforce or their accounting system — and can't audit routine tool checkboxes for any of them. The directory promises breadth the reference doesn't back up.

The fix: Publish tool tables (or at least capability summaries) for every integration in the directory, or clearly mark which integrations have documented tool sets and which don't.

11. "Calling Agents" page references a routine-management API documented nowhere (significant)

Location: /docs/custom-routines/concepts/calling-agents

Problem: The page instructs: configure "callable_routine_ids when creating a routine or callable_routines.add/remove/replace when updating one. When discovering candidates through tooling, use list_routines({ callable_only: true })." These identifiers — invoke_routine, callable_routine_ids, callable_routines.add/remove/replace, list_routines({ callable_only: true }) — appear nowhere else in the docs. There is no reference page for the "routine management tools" they belong to, no schema, no parameter list.

Consequence: This is the docs' only glimpse of a programmatic interface for managing routines, and it's unusable: a developer can't discover the full tool set, the calling convention, or where these calls even run. It reads like an internal reference pasted into a user guide.

The fix: Publish a reference page for the routine management tools (names, parameters, examples), or rewrite this section in terms of the settings UI only.

12. "Code routines" are introduced, then never explained (significant)

Location: /docs/custom-routines → /docs/custom-routines/concepts (Advanced Topics)

Problem: /docs/custom-routines introduces "Code routines" ("For routines that need to follow exact steps every time... Learn more in Advanced Topics"). Advanced Topics contains only two deep-dives — Steps & Caching and Combining Routines — neither of which explains how to create, view, or edit a code routine.

Consequence: The docs promise a second routine type for "complex multi-step processes" and then dead-end the reader. Anyone trying to adopt code routines has no path from the concept to a working routine.

The fix: Add a code-routines page under Advanced Topics covering creation (via assistant and manually, if possible), inspection, and editing — or remove the "Learn more" pointer until it exists.

13. Security page uses internal snake_case tool IDs with no mapping to the Tools reference (minor)

Location: /docs/safety/security vs /docs/custom-routines/tools

Problem: The security page lists flagged tools by internal ID — slack_send_message_as_user, run_code, update_sheet_data, github_create_pull_request, etc. The Tools reference uses only human-readable names ("Create pull request", "Send email to you"). No page maps one naming scheme to the other, and tools like run_code (a code-execution sandbox with optional internet access) appear only in the security table with no documentation of their own.

Consequence: A user auditing which of their routines' tools count as "external communication" can't reliably match the security page's IDs to the checkboxes they actually see; run_code — arguably the most powerful tool listed — is otherwise invisible in the docs.

The fix: Use one naming scheme across both pages (or show both columns), and document run_code and its internet-access toggle in the Tools reference.

14. Plan tiers, credits, and caps are scattered and never defined (minor)

Location: /docs/accounts vs /docs/admin-setup/billing-and-usage

Problem: The Multiple Accounts page is the only place naming plan tiers ("Starter includes 2 email accounts, Pro 5, Power 10, and Power Plus unlimited"). The billing page explains everything in "credits" but never says what a credit costs, how many each plan includes, which actions consume how many, or which plans "cap how many custom routines you can have" at what number. There is no pricing/plans page in the docs.

Consequence: Users can't budget or compare plans from the docs; the billing page's core advice ("upgrade if you're consistently over") is unactionable without numbers.

The fix: Add a plans/limits reference table (tiers, included credits, account limits, custom-routine caps) or link to a canonical pricing page from both docs pages.

15. Docs link readers to sign-in-walled URLs, small rendering defects ship on key pages, and the macOS app has no docs page (minor)

Location: /docs/teams, /docs/getting-started, /docs/features/context-and-memory, /docs/custom-routines/concepts/steps-and-caching, /docs/getting-started/reaching-your-townie

Problem: /docs/teams tells readers "Teams lives at town.com/teams" and "Skills are available... at town.com/powers?tab=skills" — both 307-redirect logged-out readers to /sign-in, as does town.com/trust. The getting-started page's numbered list renders a stray "5." before the safety bullet points. /docs/features/context-and-memory renders bare relative paths into prose with a missing space ("Disconnect anything anytime at/integrations" — twice). Steps & Caching has a "## A visual walkthrough" heading with no content under it. And /docs/getting-started/reaching-your-townie advertises a macOS desktop app that "unlocks desktop-only abilities like accessing your iMessage conversations" — a sensitive capability — yet the using-town section has no macOS page at all (it covers web-app, iOS, email, tasks, assistant, town-document, and Apple Mail drafts only).

Consequence: Prospective users evaluating Teams before signing up hit a login wall from the docs; the broken list, missing-space paths, and empty section make copy-pasted or agent-extracted content garbled exactly on the onboarding and safety-adjacent pages; and the app with iMessage access — the kind of capability users most want documented — has nowhere in the docs explaining what it can read or how to control it.

The fix: Link the docs' own /docs/teams content instead of authed app URLs (or note sign-in is required), fix the list markup and the at /integrations spacing, fill or remove the empty walkthrough section, and add a macOS-app page under /docs/using-town covering the iMessage capability.

What they do well

• The webhook trigger page is a genuine API reference: bearer auth, content types, idempotency header, and a full response-code table (202/400/404/413/415/429).
• The security page is unusually candid — it names its "not zero-knowledge" limitation, enumerates blocked prompt-injection patterns, and lists concrete email validation limits.
• Pages carry "Last updated" dates, and much of the content is recent (many pages updated July 2026).

Top 3 recommendations

1. Reconcile the safety FAQ with the Modes & Approvals reference — the "never acts without permission" claim must accurately describe the autonomous modes the docs themselves document.
2. Make the webhook example runnable and close the reference gaps: state the real base URL (or exactly where to copy it from), publish the routine-management tool reference that Calling Agents alludes to, document MCP server authentication and setup, and cover the 33+ integrations missing from the Tools reference.
3. Add machine-readable surface: a real llms.txt and docs sitemap (with hard 404s instead of soft-200 homepage rewrites), fix the site-wide /docs/features dead link, and unify the three conflicting trigger lists.