Authsome

Authsome Documentation Audit

The docs are unusually well-structured for an alpha-stage tool — five concept pages, full CLI reference, eight integration guides, a threat model — but they're undermined by numerical contradictions across surfaces, an architecture page that documents layers that don't exist yet, and a sitemap that points to a different domain than the rest of the documentation.

1. Provider count contradicts itself across four surfaces (critical)

Location: Homepage (authsome.ai), /llms.txt, /docs/reference/bundled-providers, GitHub README

Problem: Four authoritative surfaces disagree on the headline number.

• Homepage: "45 bundled providers (14 OAuth2, 31 API-key)"
• /llms.txt: "44 bundled OAuth2 and API key providers"
• /docs/reference/bundled-providers: "45 total bundled providers: 14 OAuth2 and 31 API-key" — and the enumerated OAuth list contains both Notion and Notion (DCR), plus Klaviyo appears in both the OAuth2 list (Klaviyo (OAuth)) and the API-key list (Klaviyo).
• GitHub README: "44 bundled providers: 13 OAuth2 and 31 API key"

Consequence: A developer comparing the brochure number against uvx authsome list will find a discrepancy and have to reverse-engineer whether Notion-with-DCR and Klaviyo-with-OAuth are the same provider with two flows or two separate provider records. Agents indexing llms.txt will commit to "44" while the docs site insists "45." This is the single most-quoted number for this product and no two pages agree.

The fix: Decide on the canonical counting rule (one row per provider entry vs. one row per service), then unify it across the homepage, llms.txt, the bundled-providers page, and the GitHub README. Spell out explicitly that Notion has two entries (one OAuth + one DCR) and that Klaviyo has both an OAuth2 and an API-key entry.

2. Master key location contradicts itself between concept and reference docs (critical)

Location: /docs/concepts/credential-storage, /docs/security/threat-model, /docs/troubleshooting/doctor vs /docs/reference/file-layout

Problem: Three pages put the master key at ~/.authsome/master.key:

• Credential storage: master.key (mode 0600) directly inside ~/.authsome/
• Threat model: "Master key kept in ~/.authsome/master.key"
• Doctor: "Insecure permissions: chmod 0600 ~/.authsome/master.key"

But the file-layout reference puts it under a server/ subdirectory: "server/master.key — 256-bit vault encryption key, base64-encoded (mode 0600)".

Consequence: A developer hardening their machine, writing a backup script, or following the doctor's chmod instruction will touch a path that doesn't exist on their disk. For an open-source credential vault, the file path of the master key is the most security-sensitive piece of information in the docs.

The fix: Audit the source layout, pick the real path, and rewrite every page to match. If the layout changed between releases, add a "key location" note to the changelog.

3. Sitemap.xml is empty of docs and points at a different domain (critical)

Location: /sitemap.xml

Problem: The sitemap on authsome.ai contains exactly three URLs — and all three point at authsome.agentr.dev, not authsome.ai:

https://authsome.agentr.dev/
https://authsome.agentr.dev/blog
https://authsome.agentr.dev/blog/running-agents-without-losing-my-keys

None of the /docs/... pages, none of the integration guides, no CLI reference, no llms.txt. The Docs → link in the site header also goes to authsome.agentr.dev/docs, while every page in this audit was reachable at authsome.ai/docs. Two domains, no canonical declaration.

Consequence: Search engines and AI agents indexing the sitemap will discover three blog-ish pages and zero documentation. The two-domain split also means inbound links may scatter — some pointing at .ai, some at .agentr.dev — and there is no rel=canonical evidence either way. For a tool whose primary buyer is an AI coding agent that needs to find your docs, this is the worst-case discoverability state.

The fix: Pick one canonical docs domain, set rel=canonical on the other, and regenerate the sitemap to enumerate every /docs/... page plus llms.txt, llms-full.txt, and the changelog.

4. Architecture page advertises layers that don't exist yet, but other pages assume they do (significant)

Location: /docs/concepts/architecture, /docs/changelog, /docs/file-layout, blog post

Problem: The architecture page lists five layers (Identity, Policy, Vault, Auth, Audit) and then concedes: "Identity, Policy, and Audit are part of the long-term architecture. The current alpha implementation focuses on Vault and Auth." But:

• Changelog 0.2.2 ships "Audit logging" with structured JSON events at ~/.authsome/audit.log — i.e. Audit is implemented.
• The CLI reference exposes log to "view audit trail entries."
• The doctor page checks audit.log is writable.
• The file-layout reference documents identities/<handle>.key (Ed25519 PoP signing) and server/identity_registry.json — i.e. Identity is at least partially on disk.
• The blog says "five conceptual layers, though only three are fully implemented in v1."

So the architecture page says 2 implemented, the blog says 3, the changelog and file layout imply 3–4, and a reader cannot tell which features are real.

Consequence: A developer evaluating Authsome for production can't tell whether Audit is a shipped feature (it is) or a future plan (page says it is). Anyone reasoning about the Ed25519 identity files will be surprised when the docs claim Identity isn't implemented yet.

The fix: Replace the "long-term architecture" paragraph with a per-layer status table (implemented / partial / planned, with the version each shipped), and link each layer to the page or reference that documents it today.

5. llms-full.txt is 404 and llms.txt has broken link syntax (significant)

Location: /llms-full.txt, /llms.txt

Problem: https://authsome.ai/llms-full.txt returns 404. Inside llms.txt, the entire agent-integrations section is written as bracketed names with no URLs:

## Agent integrations
- [Claude Code], [Codex], [Cursor], [OpenCode], [LangChain], [LlamaIndex], [OpenAI Agents SDK], [Anthropic SDK]

Markdown link brackets with no (href) targets render as plain text — agents parsing this file cannot follow them.

Consequence: Authsome is targeted at AI coding agents, and the llms.txt convention exists precisely so those agents can pull a full corpus in one request. The "full" file doesn't exist, and the partial file's most important section (which integration page do I read for my agent?) has zero usable links. The cohort most likely to onboard via llms.txt hits a wall.

The fix: Serve a real llms-full.txt containing the concatenated docs (the existing site already contains the source). Inside llms.txt, replace each bracketed name with a real Markdown link to its integration page.

6. Profiles are documented as a feature but the CLI has no flag to use them (significant)

Location: /docs/concepts/credential-storage, /docs/reference/cli, blog post

Problem: Credential storage says profiles are first-class: ~/.authsome/profiles/<profile>/store.db, namespace profile:<profile>:<provider>:..., "credentials in work are invisible to personal." The threat model leans on profile isolation as a feature. But the CLI reference lists no --profile flag among either per-command options or the global flags (--json, --quiet, --no-color, --verbose). The blog confirms: "No CLI --profile flag; switching profiles requires editing config files." The blog's own workflow uses AUTHSOME_HOME=/home/me/.authsome-digest to fake the equivalent.

Consequence: A reader who learns about profiles from the concepts page will go looking for authsome login github --profile work and find nothing. The workaround (separate AUTHSOME_HOME per profile) is documented only in the blog, not in either the concepts page or the CLI reference.

The fix: Until a real --profile flag exists, the credential-storage page should explicitly say "profiles are accessible today only via the AUTHSOME_HOME environment variable" and link the changelog entry for AUTHSOME_HOME (0.2.4). When the flag ships, add it to the global flags table.

7. Hosted daemon is a shipped feature that the threat model explicitly does not recommend (significant)

Location: /docs/changelog (0.2.4) vs /docs/security/threat-model

Problem: Changelog 0.2.4 (2026-05-08) announces "Hosted daemon deployment support via AUTHSOME_DAEMON_URL and AUTHSOME_SERVER_BASE_URL." The threat model, under "Deployment Recommendations," says hosted daemons are "Not recommended" because they "have no per-user authentication or tenant isolation." No page documents how to actually deploy a hosted daemon, what the wire protocol is, what authentication exists, or what happens when two clients connect.

Consequence: A developer who sees the new env vars in the changelog will assume they're production-ready (changelogs ship features) and configure a shared daemon. The threat model warning is on a different page and may not be read. The two documents are giving opposite signals about the same feature.

The fix: Mark the hosted-daemon env vars as "experimental — single-user only" in the changelog and in a dedicated section of the daemon docs. If the feature is intended only for personal cloud-VM use, say so explicitly with an example deployment.

8. mitmproxy CA trust is acknowledged as the #1 friction but has no install procedure anywhere in the docs (significant)

Location: /docs/quickstart, /docs/concepts/proxy-injection, /docs/integrations/agents/*, blog post

Problem: The blog says plainly: "The mitmproxy CA install is the #1 onboarding friction... This critical step was relegated to troubleshooting docs rather than installation guides." Reviewing the docs:

• Quickstart: "requires trusting the mitmproxy CA certificate" — no instructions.
• Proxy injection: "HTTPS interception requires the mitmproxy CA certificate to be trusted on your machine" — no instructions.
• Claude Code, OpenCode, etc.: "Requires mitmproxy CA installation for HTTPS interception" — no link, no command.
• Doctor: doesn't even check whether the CA is trusted.

The Cursor page does mention REQUESTS_CA_BUNDLE and SSL_CERT_FILE env vars for pinned-TLS clients, but never tells you how to install the CA into the OS trust store on macOS, Linux, or Windows.

Consequence: The single most common cause of authsome run failing silently has no documented fix on Authsome's own site. Users have to follow the upstream mitmproxy docs themselves.

The fix: Add a "Trust the mitmproxy CA" section to the quickstart with the three-OS commands (and mitmproxy --listen-port first-run instructions if needed), and have doctor check the trust store and emit a remediation hint.

9. uvx authsome run syntax disagrees between the README and the docs (significant)

Location: GitHub README vs every page under /docs/

Problem: GitHub README's Quick Start:

uvx authsome run python my_agent.py

Every documentation page (quickstart, all eight integration guides, CLI reference):

uvx authsome run -- python my_agent.py

The CLI reference defines the form with -- as the canonical syntax. There is no way to tell from the README whether the -- separator is required, optional, or simply a stylistic choice.

Consequence: A developer copy-pasting from the README will, depending on how authsome run's argument parser is built, either get unexpected flag-parsing behavior (if python is interpreted as a positional arg) or a hidden subprocess invocation that silently differs from what the docs assume. Agents will copy whichever form they saw last.

The fix: Fix the README to match the docs (uvx authsome run -- python my_agent.py), or formally document that -- is optional. Either way, pick one form.

10. Anthropic is documented as a setup task, not a bundled provider, for an AI-agent product (significant)

Location: /docs/integrations/agents/anthropic-sdk, /docs/reference/bundled-providers

Problem: The Anthropic SDK integration page begins with a six-line custom-provider JSON the user must hand-author and register:

First, register Anthropic as a custom provider:
{ "schema_version": 1, "name": "anthropic", ... "host_url": "api.anthropic.com" ... }

Meanwhile, OpenAI ships bundled. The product positions itself as a credential broker for AI agents, but the two largest agent-LLM API keys an agent will hold (OpenAI and Anthropic) are treated asymmetrically.

Consequence: Every Anthropic user pays a setup tax that OpenAI users don't. Worse, the JSON example uses host_url: "api.anthropic.com" only — so Anthropic's console.anthropic.com admin endpoints, Bedrock proxies, and any future host won't match the proxy host rule, and a developer following the snippet will silently bypass the proxy for non-matching hosts.

The fix: Ship Anthropic in the bundled-providers JSON set. While that's pending, the integration page should ship a copy-paste curl https://.../anthropic.json | uvx authsome register - one-liner rather than asking the reader to author JSON.

11. whoami has an undocumented side effect of creating the master key (minor)

Location: /docs/troubleshooting/doctor, /docs/reference/cli

Problem: Doctor docs say: "Master key not found: run uvx authsome whoami to auto-create." The CLI reference describes whoami only under "Administrative" — there is no indication that it has a write side effect of provisioning a 256-bit AES master key.

Consequence: whoami is, in every other CLI tradition, a read-only diagnostic. A developer running it in a CI debug step, or copy-pasting it into a shared shell, will silently provision a master key they didn't intend to create.

The fix: Document the side effect on the CLI reference's whoami entry, and add an explicit authsome init (or vault init) command whose only job is master-key provisioning.

12. --force flag used in examples but not documented (minor)

Location: /docs/integrations/agents/codex, /docs/integrations/agents/opencode, /docs/reference/cli

Problem: Both integration pages use uvx authsome login github --connection work --force (Codex) and "Switch default connections using the --force flag during login" (OpenCode). The CLI reference's login entry lists "options for flow type (pkce, device_code, dcr_pkce, api_key), custom connection names, scopes, and base URLs" — no --force.

Consequence: A reader hitting an existing-connection error and consulting the CLI reference for the right flag will not find it. They'll either grep the source or repeat the connection error.

The fix: Add --force to the login command's flag table, with a one-line description of what state it overrides.

What they do well

• The threat model is honest and concrete (memory-readable plaintext, no certificate pinning, profile isolation caveats). That kind of upfront limits-list is rare in alpha credential tools.
• The CLI reference has structured exit codes (0/1/3/4/5/8) — agents calling authsome can branch on them.
• The integration matrix covers eight named agent platforms with consistent shape, which is well above average for a v0.2.x project.

Top 3 recommendations

1. Pick one number for "bundled providers" and propagate it (homepage, llms.txt, GitHub, bundled-providers page) — and clarify how Notion-DCR and Klaviyo-OAuth are counted.
2. Fix the master-key path contradiction and regenerate /docs/reference/file-layout from the running binary so the disk layout matches reality.
3. Regenerate sitemap.xml to enumerate every docs URL on a single canonical domain, and ship a real llms-full.txt with embedded links for the agent-integrations section in llms.txt.